SkadiLabs/vizionStreamer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a2d2f256cf494b3692085a3ce0dd8ace74888de5
vizionStreamer/README.md
Maik Jurischka a2d2f256cf add license information
2025-12-19 09:57:28 +01:00

9.8 KiB
Raw Blame History

VizionStreamer

High-performance video streaming application for Technexion cameras with GStreamer integration and Unix Domain Socket control interface.

Depends on: https://github.com/TechNexion-Vision/vizionsdk

Features

  • Continuous Frame Acquisition: Dedicated thread for frame capture from VizionSDK
  • GStreamer Integration: Flexible video processing and output
  • Socket Control API: Runtime configuration via JSON commands over Unix Domain Socket
  • Camera Parameter Control: Exposure, white balance, brightness, contrast, etc.
  • Multiple Output Options: Display, UDP/TCP streaming, file recording, RTSP, MJPEG
  • Performance Monitoring: Real-time FPS statistics
  • Thread-Safe: Mutex-protected operations

Quick Start

Build

cmake -B build -S .
cmake --build build

Run

# Start VizionStreamer
./build/vizionStreamer

Start Streaming (Default Pipeline)

In another terminal:

# Start streaming with default pipeline (local display)
./scripts/start_stream.sh

# Stop streaming
./scripts/stop_stream.sh

That's it! The default pipeline videoconvert ! autovideosink is already configured.

Architecture

┌─────────────────┐
│  VizionSDK      │
│  Camera         │
└────────┬────────┘
         │ VxGetImage()
         ▼
┌─────────────────┐
│  Acquisition    │
│  Loop Thread    │  (StreamingEngine)
└────────┬────────┘
         │ Push frames
         ▼
┌─────────────────┐
│  GStreamer      │
│  Pipeline       │  (appsrc → processing → output)
└────────┬────────┘
         │
         ▼
    Display/Stream/File

┌─────────────────┐
│  Socket Server  │  ← JSON commands
│  (Control API)  │
└─────────────────┘

Control Scripts

Located in scripts/ directory:

Script Description
start_stream.sh Start streaming (use default or configured pipeline)
stop_stream.sh Stop streaming
get_status.sh Show streaming status and current pipeline
get_formats.sh List available camera formats
set_pipeline_display.sh Set pipeline for local display
set_pipeline_udp.sh [host] [port] Set pipeline for UDP streaming
set_pipeline_file.sh [path] Set pipeline for file recording
set_pipeline_mjpeg.sh [port] Set pipeline for MJPEG HTTP streaming

See scripts/README.md for detailed usage.

Common Use Cases

Local Display

./build/vizionStreamer
# In another terminal:
./scripts/start_stream.sh

UDP Streaming to Remote Host

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_udp.sh 192.168.1.100 5000
./scripts/start_stream.sh

# On receiving machine:
gst-launch-1.0 udpsrc port=5000 ! application/x-rtp,encoding-name=H264 ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! autovideosink

Record to File

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_file.sh /tmp/recording.mp4
./scripts/start_stream.sh
# Let it run, then:
./scripts/stop_stream.sh

MJPEG HTTP Streaming

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_mjpeg.sh 8080
./scripts/start_stream.sh

# View in browser:
firefox http://localhost:8080

Socket Control API

Full API documentation: SOCKET_API.md

Socket Path: /tmp/vizion_control.sock

Available Commands

  • get_formats - List camera formats
  • set_format - Change resolution/framerate/format
  • start_stream - Start streaming
  • stop_stream - Stop streaming
  • get_status - Get streaming status
  • set_pipeline - Configure GStreamer pipeline
  • set_exposure - Configure exposure
  • set_whitebalance - Configure white balance
  • set_brightness - Adjust brightness
  • set_contrast - Adjust contrast
  • set_saturation - Adjust saturation
  • set_sharpness - Adjust sharpness
  • set_gamma - Adjust gamma
  • set_gain - Adjust gain
  • set_ehdr_mode - Enable/disable eHDR (compatible cameras only)
  • set_ehdr_exposure_min - Set eHDR minimum exposure frames
  • set_ehdr_exposure_max - Set eHDR maximum exposure frames
  • set_ehdr_ratio_min - Set eHDR minimum exposure ratio
  • set_ehdr_ratio_max - Set eHDR maximum exposure ratio
  • get_ehdr_status - Get current eHDR settings

Example

# Manual command
echo '{"command":"start_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Set custom pipeline
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! x264enc ! rtph264pay ! udpsink host=192.168.1.100 port=5000"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Get status
echo '{"command":"get_status"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

GStreamer Pipeline Examples

Display

videoconvert ! autovideosink

UDP H.264 Streaming

videoconvert ! x264enc tune=zerolatency bitrate=2000 ! rtph264pay ! udpsink host=192.168.1.100 port=5000

File Recording

videoconvert ! x264enc ! mp4mux ! filesink location=/tmp/output.mp4

TCP Streaming

videoconvert ! x264enc ! h264parse ! mpegtsmux ! tcpserversink host=0.0.0.0 port=5000

MJPEG HTTP

videoconvert ! jpegenc ! multipartmux ! tcpserversink host=0.0.0.0 port=8080

Tee (Display + Record)

tee name=t ! queue ! videoconvert ! autovideosink t. ! queue ! x264enc ! mp4mux ! filesink location=out.mp4

Dependencies

  • VizionSDK: Camera interface (located at /opt/vizionsdk)
  • GStreamer 1.0: Video processing (gstreamer-1.0, gstreamer-app-1.0)
  • CMake: Build system (>= 3.20)
  • C++23: Compiler support
  • socat: For socket communication (control scripts)

Install Dependencies (Debian/Ubuntu)

sudo apt install build-essential cmake pkg-config socat \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly gstreamer1.0-x

Project Structure

vizionStreamer/
├── main.cpp                    # Main application
├── SocketServer.{h,cpp}        # Unix domain socket server
├── CameraController.{h,cpp}    # Command processing & camera control
├── StreamingEngine.{h,cpp}     # Acquisition loop & streaming
├── GStreamerPipeline.{h,cpp}   # GStreamer pipeline wrapper
├── CMakeLists.txt              # Build configuration
├── config/
│   └── VxConfig.conf           # VizionSDK configuration
├── scripts/                    # Control scripts
│   ├── README.md
│   ├── start_stream.sh
│   ├── stop_stream.sh
│   ├── get_status.sh
│   ├── set_pipeline_*.sh
│   └── get_formats.sh
├── SOCKET_API.md               # Complete API documentation
└── README.md                   # This file

Configuration Files

VxConfig.conf

Automatically copied to build directory during build. Contains VizionSDK camera configuration.

Performance

The acquisition loop displays statistics every second:

FPS: 30 | Total frames: 1234 | Frame size: 4147200 bytes

Typical performance:

  • Local Display: 30 FPS @ 1080p
  • UDP Streaming: 30 FPS @ 1080p with H.264 encoding
  • File Recording: Limited by disk I/O

Troubleshooting

No cameras found

  • Check camera connection
  • Run /opt/vizionsdk/init_driver.sh if needed
  • Check dmesg for USB errors

Pipeline fails to start

  • Verify GStreamer plugins are installed
  • Test pipeline manually: gst-launch-1.0 videotestsrc ! YOUR_PIPELINE
  • Check pipeline syntax

Socket connection refused

  • Ensure VizionStreamer is running
  • Check socket exists: ls -l /tmp/vizion_control.sock
  • Verify permissions

Low FPS

  • Reduce resolution or framerate
  • Use hardware encoding if available (vaapih264enc instead of x264enc)
  • Check CPU usage

License

VizionStreamer Copyright (c) 2025 Maik Jurischka

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).

You are free to:

  • Share — copy and redistribute the material in any medium or format
  • Adapt — remix, transform, and build upon the material

Under the following terms:

  • Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
  • NonCommercial — You may not use the material for commercial purposes.
  • ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

Full license text: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Third-Party Dependencies

This software uses the following dependencies:

Support

For issues and questions, refer to:

Reference in New Issue View Git Blame Copy Permalink