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 http://localhost: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 "http://localhost:3539/flex/camera?path=/dev/video0"

Response includes:

Supported pixel formats (YUYV, MJPEG, H.264, etc.)
Available resolutions
Supported framerates
Recommended "best" capability

Best Capability¶

Flex Video automatically selects the best capability based on:

Highest resolution
Highest framerate
Preferred format (raw > compressed)

"best_capability": {
  "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
}

Using Cameras in Pipelines¶

GStreamer Source URI¶

Use the V4L2 device path as the source:

{
  "id": "webcam-stream",
  "mode": "simple",
  "source": {
    "uri": "v4l2:///dev/video0"
  },
  "encoding": {
    "codec": "h264",
    "bitrate": 2000,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "quality": 7
  },
  "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": "v4l2:///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 -N http://localhost: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: v4l2:///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.