Skip to content
PhramePhrame

VDI — Local Frame Bus

VDI — Local Frame Bus

Section titled “VDI — Local Frame Bus”

VDI (Virtual Digital Interface) is how stages on the same host hand frames to each other with almost no overhead — shared memory, zero copies, futex signalling. Most pipelines are wired together over VDI.

VDI — zero-copy shared-memory frame bus producerinput-processor /vision-mixer consumerdownstream stage shared memory (/dev/shm) setup region — media format data regioncircular grain buffers (frames in place) control region — futex signalling write read one stream = three regions · frames exchanged in place · grain slots returned via plugin_free_frame

  • Library: libvdi.so · Implementation: C++
  • Addressing: vdi://<uuid>:<suffix> — the suffix selects a sub-stream (e.g. video/audio, or :0/:1).

How it works

Section titled “How it works”

VDI uses three shared-memory regions per stream (setup, data, control), circular grain buffers, and futex-based signalling between producer and consumer. It is lower-latency than MXL and intended for intra-host hops. For NMOS-style flows other tooling can discover, use MXL.

Configuration

Section titled “Configuration”

The JSON passed to plugin_open describes the stream’s media format (packages), with is_write selecting producer (true) vs consumer (false). Hosts usually build this JSON for you from their own config — e.g. input-processor’s stream_id and output settings. Indicative shape:

{
  "packages": {
    "video:0": {
      "video": {
        "width": 1920, "height": 1080,
        "frame_rate": { "numerator": 25, "denominator": 1 },
        "pixel_format": "yuv422p16le", "bit_depth": 16,
        "codec": "uncompressed"
      },
      "prefix": "vdi", "suffix": "0", "id": "<uuid>:video",
      "is_write": true, "loop": false
    }
  },
  "prefix": "vdi", "id": "<uuid>:video", "is_write": true
}

Build & notes

Section titled “Build & notes”

Built by plugins/phrame-make.sh (CMake); libvdi.so is staged into plugins/ and copied into every consumer image. Implements all ABI functions; frames are exchanged in place in the shared data region, and plugin_free_frame returns ownership of a grain slot. See Frame Bus & Plugins for the ABI.