vizionStreamer/README.md

# 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/`