Cameras¶

Flex Video supports V4L2 (Video4Linux2) cameras for direct capture from USB and integrated cameras.

Supported Cameras¶

Any V4L2-compatible camera works with Flex Video:

USB webcams (Logitech, Microsoft, etc.)
MIPI CSI cameras (Raspberry Pi Camera, Jetson cameras)
HDMI/SDI capture cards (Magewell, Blackmagic)
IP cameras with V4L2 bridge

Listing Cameras¶

Web Interface¶

Connected cameras appear in the Cameras section of the web interface.

REST API¶

curl -k https://<encoder-ip>:3539/flex/cameras

Response:

{
  "cameras": [
    {
      "path": "/dev/video0",
      "name": "HD Pro Webcam C920",
      "driver": "uvcvideo",
      "format_count": 4
    }
  ]
}

Camera Capabilities¶

Query detailed capabilities for a specific camera:

curl -k "https://<encoder-ip>:3539/flex/camera?path=/dev/video0"

Response includes:

capabilities - Simplified list of resolution/fps options (best format auto-selected)
formats - Raw format data for advanced use
best_capability - Single highest-quality option

Capabilities¶

The capabilities array provides a simplified list with one entry per resolution/fps combination. The best pixel format is automatically selected based on resolution and USB bandwidth constraints.

"capabilities": [
  {
    "format": "YUYV",
    "width": 1920,
    "height": 1080,
    "fps": 30.0,
    "gstreamer_caps": "video/x-raw,format=YUY2,width=1920,height=1080,framerate=30/1",
    "quality_score": 1944000
  },
  {
    "format": "YUYV",
    "width": 1280,
    "height": 720,
    "fps": 30.0,
    "gstreamer_caps": "video/x-raw,format=YUY2,width=1280,height=720,framerate=30/1",
    "quality_score": 921600
  }
]

Best Capability¶

The best_capability field contains the single highest-quality option based on:

Resolution (higher is better)
Framerate (higher is better, capped at 60fps for scoring)
Format preference (raw formats preferred at ≤1080p, MJPEG at higher resolutions)

Using Cameras in Pipelines¶

GStreamer Source URI¶

Use the V4L2 device path as the source:

{
  "id": "webcam-stream",
  "mode": "simple",
  "source": {
    "uri": "file:///dev/video0"
  },
  "encoding": {
    "codec": "h264",
    "bitrate": 750,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "quality": 5
  },
  "output": {
    "uri": "rtsp://0.0.0.0:8731/webcam"
  }
}

Specifying Format and Resolution¶

To use a specific format/resolution instead of auto-detection:

"source": {
  "uri": "file:///dev/video0",
  "caps": "video/x-raw,format=YUY2,width=1280,height=720,framerate=30/1"
}

Hot-Plug Monitoring¶

Flex Video monitors for camera connection/disconnection events.

Web Interface¶

The camera list updates automatically when cameras are plugged or unplugged.

REST API (SSE)¶

Subscribe to camera events:

curl -k -N https://<encoder-ip>:3539/flex/cameras/events

Events:

event: camera_added
data: {"device_path":"/dev/video0","device_name":"HD Pro Webcam C920"}

event: camera_removed
data: {"device_path":"/dev/video0","device_name":"HD Pro Webcam C920"}

Linux Camera Setup¶

udev Rules¶

The Flex Video installer configures udev rules for camera hot-plug support:

# /etc/udev/rules.d/99-flex-video.rules
SUBSYSTEM=="video4linux", ACTION=="add", RUN+="/usr/bin/systemctl restart flex-video"
SUBSYSTEM=="video4linux", ACTION=="remove", RUN+="/usr/bin/systemctl restart flex-video"

Permissions¶

Ensure the container has access to video devices:

# docker-compose.yml
volumes:
  - /dev:/dev
group_add:
  - video
device_cgroup_rules:
  - 'c 81:* rmw'  # Video4Linux devices

Multiple Cameras¶

When using multiple cameras:

Identify each camera by its unique path or serial number
Use udev rules to create stable symlinks:

# /etc/udev/rules.d/99-cameras.rules
SUBSYSTEM=="video4linux", ATTRS{serial}=="ABC123", SYMLINK+="camera-entrance"
SUBSYSTEM=="video4linux", ATTRS{serial}=="DEF456", SYMLINK+="camera-lobby"

Then reference by symlink: file:///dev/camera-entrance

Troubleshooting¶

Camera Not Detected¶

Check device exists: ls -la /dev/video*
Verify permissions: groups should include video
Check driver loaded: lsmod | grep uvcvideo
Test with v4l2-ctl: v4l2-ctl --list-devices

Poor Video Quality¶

Check lighting conditions
Verify resolution matches camera capability
Try a different pixel format
Update camera firmware

Camera Disconnects¶

Check USB cable quality
Use a powered USB hub
Check dmesg for USB errors
Try a different USB port

Format Not Supported¶

If a format isn't working:

# List supported formats
v4l2-ctl -d /dev/video0 --list-formats-ext

Use a supported format in your pipeline configuration.