Pipelines¶

Pipelines are the core of Flex Video, defining how video is ingested, processed, and delivered.

Pipeline Types¶

SimplePipeline¶

SimplePipeline provides a high-level configuration interface:

{
  "id": "camera-1",
  "mode": "simple",
  "source": { ... },
  "encoding": { ... },
  "output": { ... }
}

Best for:

• Standard transcoding workflows
• Users who don't need GStreamer knowledge
• Consistent, maintainable configurations

MultiViewPipeline¶

MultiViewPipeline composes 1-4 video inputs into a single output stream:

{
  "id": "quad-view",
  "mode": "multiview",
  "inputs": [
    {
      "label": "North Gate",
      "source": { "uri": "rtsp://192.168.1.100:8554/live" }
    },
    {
      "label": "South Gate",
      "source": { "uri": "rtsp://192.168.1.101:8554/live" }
    }
  ],
  "encoding": {
    "codec": "av1",
    "bitrate": 750,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "quality": 5
  },
  "output": {
    "uri": "rtsp://0.0.0.0:8731/quad-view"
  }
}

Best for:

• Multi-camera monitoring (compose up to 4 feeds into one stream)
• Side-by-side or quad-view layouts
• Reducing the number of output streams while monitoring multiple sources

Input Sources¶

Each input accepts the same source types as SimplePipeline (RTSP, UDP, file, test pattern), plus direct V4L2 camera paths. The web interface provides a camera picker for selecting connected cameras.

Layout¶

Layout is computed automatically based on the number of inputs:

Per-Input Controls¶

Each input supports independent configuration:

Global Controls¶

These apply to the composed output:

AdvancedPipeline¶

AdvancedPipeline accepts raw GStreamer pipeline strings:

{
  "id": "custom-pipeline",
  "mode": "advanced",
  "raw_pipeline": "videotestsrc ! videoconvert ! <flex:h264 /> ! rtph264pay ! udpsink host=239.1.1.1 port=5004"
}

Best for:

• Custom processing requirements
• Unusual source/sink combinations
• GStreamer experts

Encoder Macros¶

Advanced pipelines support encoder macro tags that expand to optimized encoder configurations. Use these instead of typing full encoder element strings:

Set bitrate in kbps (default: 500, range: 5–5,000):

{
  "id": "macro-pipeline",
  "mode": "advanced",
  "raw_pipeline": "videotestsrc ! queue ! videoconvert ! <flex:av1 bitrate=500 /> ! fakesink"
}

Source Configuration¶

Supported Sources¶

RTSP Sources¶

"source": {
  "uri": "rtsp://192.168.1.100:8554/live",
  "latency_ms": 200
}

Latency tuning:

UDP Multicast Sources¶

"source": {
  "uri": "udp://239.1.1.1:5004",
  "network_interface": "eth0"
}

The network interface can also be embedded directly in the URI:

"source": {
  "uri": "udp://eth0@239.1.1.1:5004"
}

Both formats are equivalent. If both are provided, the network_interface field takes priority.

Test Patterns¶

Available patterns for testing without a real source:

Video Decoding¶

Flex Video automatically selects the best available decoder for incoming video streams. On supported hardware, hardware-accelerated decoders are used when available, reducing CPU load and improving performance. If no hardware decoder is available for a given codec, Flex Video falls back to software decoding.

The installer automatically enables hardware decoding on supported platforms. On x86_64 systems with VAAPI, hardware-accelerated encoding is also available. To force software-only decoding (for example, to troubleshoot playback issues), set the following in /opt/flex/.env:

FLEX_FORCE_SW_DECODERS=true

Restart services after changing this value. See Hardware Acceleration for platform-specific setup details.

Encoding Configuration¶

"encoding": {
  "codec": "h264",
  "bitrate": 750,
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "quality": 5
}

Codecs¶

Bitrate Guidelines¶

AV1 is significantly more efficient than H.264/H.265. The following guidelines are for AV1 encoding:

For H.264 and H.265, use approximately 2-3x the AV1 values above.

Quality Preset¶

The quality setting (1-10) controls the encoder speed/quality tradeoff. Default is 5.

Output Configuration¶

RTSP Output (Recommended)¶

"output": {
  "uri": "rtsp://0.0.0.0:8731/stream-name",
  "mtu": 1400
}

Outputs to the built-in RTSP server. Clients connect to rtsp://server-ip:8731/stream-name. See Receiving & Playback for compatible players and plugin requirements.

UDP Multicast Output¶

"output": {
  "uri": "udp://239.1.1.1:5004",
  "network_interface": "eth0",
  "mtu": 1400
}

The network interface can also be embedded in the URI:

"output": {
  "uri": "udp://eth0@239.1.1.1:5004",
  "mtu": 1400
}

MTU Settings¶

Optional Features¶

Overlays¶

Add text or timestamp overlays:

"overlay": {
  "show_timestamp": true,
  "text": "Camera 1 - Main Entrance"
}

Transform¶

Apply video transformations:

"transform": {
  "mirror": false,
  "rotate": 90,
  "grayscale": false
}

Rotation values: 0, 90, 180, 270

Crop¶

Crop the video frame:

"crop": {
  "top": 100,
  "right": 0,
  "bottom": 100,
  "left": 0
}

Geolocation¶

Set static or dynamic position using latitude/longitude or MGRS coordinates:

"geolocation": {
  "latitude": 38.8977,
  "longitude": -77.0365,
  "altitude": 100.0,
  "heading": 45.0,
  "is_dynamic": false
}

Alternatively, provide an MGRS coordinate instead of latitude/longitude:

"geolocation": {
  "mgrs": "18SUJ2337006519",
  "altitude": 100.0,
  "is_dynamic": false
}

When both are provided, latitude/longitude take precedence. Responses include latitude, longitude, and computed mgrs.

Set is_dynamic: true when position will be updated from KLV metadata.

Pipeline Lifecycle¶

stateDiagram-v2
    ready --> playing : play
    playing --> ready : stop

Runtime Editing¶

You can adjust encoding settings on a running pipeline without deleting and recreating it. This is supported for SimplePipeline and MultiViewPipeline.

Editable while playing:

In the web interface, click Edit on a running Simple or Multiview pipeline to enter live edit mode. Encoding fields are editable while the stream plays. Click Apply Encoding Update to send the changes. If the update fails, the pipeline automatically rolls back to its previous settings.

AdvancedPipeline must be stopped before editing.

Automatic Recovery¶

Pipelines are automatically restored if the video processing backend restarts unexpectedly. Running streams will experience a brief interruption but resume without user intervention.

On-Demand vs Auto-Start¶

Pipeline Limits¶

Pipeline limits are controlled by your license:

• Check limits: GET /flex/licensed
• Exceeding limits returns HTTP 402

Best Practices¶

1. Use descriptive IDs: entrance-cam-h264 not pipe1
2. Match resolution to source: Don't upscale unnecessarily
3. Set appropriate latency: Higher for unreliable networks
4. Use RTSP output: Better client compatibility than UDP
5. Monitor pipeline state: Use SSE for real-time updates