add GStreamer helper scripts
This commit is contained in:
Maik Jurischka
290
README.md
Normal file
290
README.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# VizionStreamer
|
||||
|
||||
High-performance video streaming application for Vizion cameras with GStreamer integration and Unix Domain Socket control interface.
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
cmake -B build -S .
|
||||
cmake --build build
|
||||
```
|
||||
|
||||
### Run
|
||||
|
||||
```bash
|
||||
# Start VizionStreamer
|
||||
./build/vizionStreamer
|
||||
```
|
||||
|
||||
### Start Streaming (Default Pipeline)
|
||||
|
||||
In another terminal:
|
||||
|
||||
```bash
|
||||
# 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](scripts/README.md) for detailed usage.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Local Display
|
||||
```bash
|
||||
./build/vizionStreamer
|
||||
# In another terminal:
|
||||
./scripts/start_stream.sh
|
||||
```
|
||||
|
||||
### UDP Streaming to Remote Host
|
||||
```bash
|
||||
./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
|
||||
```bash
|
||||
./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
|
||||
```bash
|
||||
./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_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
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
See VizionSDK license terms.
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions, refer to:
|
||||
- [SOCKET_API.md](SOCKET_API.md) - Complete API reference
|
||||
- [scripts/README.md](scripts/README.md) - Script usage guide
|
||||
- VizionSDK documentation at `/opt/vizionsdk/`
|
||||
Reference in New Issue
Block a user