# thatdavidbelll/ndi-to-whip architecture

> Architecture diagram of the GitHub repository thatdavidbelll/ndi-to-whip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thatdavidbelll/ndi-to-whip
- Repository: https://github.com/thatdavidbelll/ndi-to-whip

## Overview

1. **What this repo is**
   - This is a small deployment-focused bridge from an NDI source to a WHIP ingest endpoint.
   - The application itself is the Python script `ndi_to_whip.py`; the rest of the repo is packaging, service wiring, validation, and an optional local WHIP server config.

2. **Core runtime boundary**
   - The actual media pipeline runs in GStreamer, not in Python.
   - Python’s role is orchestration: read config, probe/select the NDI source, build the GStreamer pipeline, and keep it running under foreground or systemd supervision.

3. **Main media data path**
   - Input comes from the NDI network via `ndisrc`.
   - The stream is split by `ndisrcdemux` into separate raw video and raw audio branches.
   - Video is normalized with `videoconvert`, `videoscale`, and `videorate`; audio with `audioconvert` and `audioresample`.
   - Both branches feed a single `whipclientsink`, which publishes to the WHIP endpoint over WebRTC.

4. **Encoding boundary**
   - Encoding is intentionally handled inside `whipclientsink` / `GstBaseWebRTCSink`, not pre-encoded in Python or in the pipeline before the sink.
   - The design constrains video to H.264 for compatibility, and audio is Opus.
   - Hardware encoders can be selected by GStreamer automatically when available; the repo treats this as an environment capability, not app logic.

5. **Key external dependencies**
   - NDI SDK is proprietary and must be installed on the host before the app can run.
   - `gst-plugins-rs` must be built locally to provide `libgstndi.so` and `libgstrswebrtc.so`; these are not shipped in the repo.
   - Standard Ubuntu GStreamer, libnice, and libsrtp2 provide the WebRTC transport layer.

6. **Configuration boundary**
   - Runtime settings live in `/etc/ndi_to_whip/config.toml`.
   - The config separates source selection (`[ndi]`), WHIP connection settings (`[whip]`), and media parameters (`[video]`, `[audio]`).
   - The README shows that some fields are advisory rather than strict controls because the sink negotiates final codec/bitrate details.

7. **Service and process management**
   - `ndi-to-whip.service` runs the bridge as a systemd service under a dedicated `ndi-whip` user.
   - The service setup relies on access to `video` and `audio` groups, writable GStreamer registry cache, and environment variables that expose the custom plugin path and NDI library path.
   - This repo expects the process to be long-lived and restarted on failure, not used as a short-lived CLI tool.

8. **Installation/bootstrap boundary**
   - `install.sh` is the provisioning path for the host.
   - It installs OS packages, sets up the Rust toolchain, assumes the NDI SDK has already been manually installed, builds the required GStreamer plugins, and places app files into `/opt/ndi_to_whip` and `/etc/ndi_to_whip`.
   - So the repository splits “bootstrap the machine” from “run the bridge.”

9. **Validation and operational checks**
   - `validate.sh` is a pre-flight checklist for host readiness.
   - The README positions it as the way to verify plugin discovery, environment, NDI visibility, and WHIP reachability before troubleshooting runtime failures.
   - This is an operational safety layer, not part of the media path.

10. **Optional local WHIP server**
   - `mediamtx.yml` configures MediaMTX as a local WHIP endpoint for testing or on-prem deployment.
   - In that mode, the bridge publishes to MediaMTX over WHIP, and MediaMTX republishes the stream via WebRTC, HLS, and RTSP.
   - This makes MediaMTX an external but common deployment companion, not a dependency of the core app.

11. **Control and observability**
   - The repo is designed for both interactive runs and systemd-managed runs.
   - Logs are expected to go to journald in service mode, with diagnostic output around NDI discovery, WHIP connection, and encoder selection.
   - The `--probe`, `--print-pipeline`, and `--validate` modes indicate the app is built around inspectable startup behavior.

12. **Architectural constraints worth diagramming**
   - Discovery and signaling are separate from media transport: NDI discovery happens on the LAN, WHIP signaling happens over HTTP, and actual media flows over ICE/DTLS-SRTP WebRTC.
   - The `gst-plugins-rs` version must match the system GStreamer version; that version coupling is a real deployment boundary.
   - The repo assumes Linux/Ubuntu as the execution environment and is effectively a single-host bridge with external ingress and egress points.

Main entry points: [`ndi_to_whip.py`](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/ndi_to_whip.py) (Bridge app), [`install.sh`](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/install.sh) (Installer), [`validate.sh`](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/validate.sh) (Validator), [`mediamtx.yml`](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/mediamtx.yml) (MediaMTX)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_ndi_to_whip_py["Bridge app<br/>Python orchestrator<br/>[ndi_to_whip.py]"]
  node_ndi_source[("NDI source<br/>LAN input")]
  node_gstreamer_pipeline["GStreamer pipeline<br/>Media graph"]
  node_ndisrcdemux{{"Demux<br/>NDI splitter"}}
  node_video_branch["Video branch<br/>Normalize video"]
  node_audio_branch["Audio branch<br/>Normalize audio"]
  node_whip_sink[("WHIP sink<br/>WebRTC sink")]
  node_whip_endpoint[("WHIP endpoint<br/>HTTP ingest")]
end

subgraph group_deployment["Deployment"]
  node_config_toml["Config<br/>TOML runtime<br/>[config.toml]"]
  node_systemd_service["Service<br/>systemd unit"]
  node_install_sh["Installer<br/>Bootstrap script<br/>[install.sh]"]
  node_ndi_sdk[("NDI SDK<br/>Proprietary dependency")]
  node_gst_plugins_rs["gst-plugins-rs<br/>Custom plugins"]
  node_gst_stack[("GStreamer stack<br/>System media libs")]
  node_plugin_path["Plugin path<br/>Env setup"]
end

subgraph group_ops["Operations"]
  node_validate_sh["Validator<br/>Preflight script<br/>[validate.sh]"]
end

subgraph group_companion["Companion"]
  node_mediamtx_yml["MediaMTX<br/>WHIP server config<br/>[mediamtx.yml]"]
end

node_config_toml -->|"runtime settings"| node_ndi_to_whip_py
node_ndi_to_whip_py -->|"probe/select"| node_ndi_source
node_ndi_to_whip_py -->|"build pipeline"| node_gstreamer_pipeline
node_ndi_source -->|"raw NDI"| node_ndisrcdemux
node_ndisrcdemux -->|"video"| node_video_branch
node_ndisrcdemux -->|"audio"| node_audio_branch
node_video_branch -->|"H.264 path"| node_whip_sink
node_audio_branch -->|"Opus path"| node_whip_sink
node_whip_sink -->|"WHIP publish"| node_whip_endpoint
node_systemd_service -->|"run"| node_ndi_to_whip_py
node_install_sh -->|"install unit"| node_systemd_service
node_install_sh -->|"build plugins"| node_gst_plugins_rs
node_install_sh -->|"deps"| node_gst_stack
node_install_sh -->|"require host SDK"| node_ndi_sdk
node_plugin_path -->|"env"| node_ndi_to_whip_py
node_gst_plugins_rs -->|"plugins"| node_gstreamer_pipeline
node_gst_stack -->|"runtime libs"| node_gstreamer_pipeline
node_ndi_sdk -->|"discovery"| node_ndi_source
node_validate_sh -->|"check"| node_plugin_path
node_validate_sh -->|"check"| node_ndi_source
node_validate_sh -->|"check"| node_whip_endpoint
node_mediamtx_yml -->|"local ingest"| node_whip_endpoint
node_mediamtx_yml -->|"test target"| node_whip_sink

click node_ndi_to_whip_py "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/ndi_to_whip.py"
click node_config_toml "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/config.toml"
click node_systemd_service "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/ndi-to-whip.service"
click node_install_sh "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/install.sh"
click node_validate_sh "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/validate.sh"
click node_mediamtx_yml "https://github.com/thatdavidbelll/ndi-to-whip/blob/main/mediamtx.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ndi_to_whip_py,node_ndi_source,node_gstreamer_pipeline,node_ndisrcdemux,node_video_branch,node_audio_branch,node_whip_sink,node_whip_endpoint toneBlue
class node_config_toml,node_systemd_service,node_install_sh,node_ndi_sdk,node_gst_plugins_rs,node_gst_stack,node_plugin_path toneAmber
class node_validate_sh toneMint
class node_mediamtx_yml toneRose
```

## Components

### Runtime

Application and media pipeline

- [Bridge app](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/ndi_to_whip.py): Python orchestrator · Reads config, probes NDI, builds and supervises the GStreamer pipeline · `ndi_to_whip.py`
- **NDI source**: LAN input · Discoverable NDI sender on the network
- **GStreamer pipeline**: Media graph · Runtime media processing and transport boundary
- **Demux**: NDI splitter · Splits incoming NDI into raw video and audio branches
- **Video branch**: Normalize video · videoconvert, videoscale, and videorate prepare video for sink negotiation
- **Audio branch**: Normalize audio · audioconvert and audioresample prepare audio for sink negotiation
- **WHIP sink**: WebRTC sink · whipclientsink negotiates codec and publishes the stream
- **WHIP endpoint**: HTTP ingest · Remote ingest server receiving the published WebRTC stream

### Deployment

Bootstrap and service wiring

- [Config](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/config.toml): TOML runtime · Source selection, WHIP settings, and media parameters · `config.toml`
- [Service](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/ndi-to-whip.service): systemd unit · Long-lived supervised runtime under the ndi-whip user · `ndi-to-whip.service`
- [Installer](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/install.sh): Bootstrap script · Installs packages, builds plugins, and deploys files on the host · `install.sh`
- **NDI SDK**: Proprietary dependency · Host-installed NDI runtime required for source access
- **gst-plugins-rs**: Custom plugins · Provides libgstndi.so and libgstrswebrtc.so built on the host
- **GStreamer stack**: System media libs · System GStreamer plus libnice and libsrtp2 for WebRTC transport
- **Plugin path**: Env setup · Custom plugin and library paths exposed to the service process

### Operations

Validation and observability

- [Validator](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/validate.sh): Preflight script · Checks host readiness, plugin discovery, and connectivity · `validate.sh`

### Companion

Optional local WHIP server

- [MediaMTX](https://github.com/thatdavidbelll/ndi-to-whip/blob/main/mediamtx.yml): WHIP server config · Optional local WHIP endpoint and republishing setup · `mediamtx.yml`

## Connections

- Config → Bridge app: runtime settings · Python reads source, WHIP, video, and audio configuration
- Bridge app → NDI source: probe/select · App discovers and selects the NDI sender on the LAN
- Bridge app → GStreamer pipeline: build pipeline · App assembles the media graph and keeps it running
- NDI source → Demux: raw NDI · Incoming NDI stream enters the split stage
- Demux → Video branch: video · Video pad feeds normalization and format shaping
- Demux → Audio branch: audio · Audio pad feeds normalization and resampling
- Video branch → WHIP sink: H.264 path · Video is constrained for sink-side encoding and negotiation
- Audio branch → WHIP sink: Opus path · Audio is prepared for sink-side WebRTC publication
- WHIP sink → WHIP endpoint: WHIP publish · Media is sent over WebRTC after WHIP signaling
- Service → Bridge app: run · Service supervises the bridge process under a dedicated user
- Installer → Service: install unit · Bootstrap places the service and app files on the host
- Installer → gst-plugins-rs: build plugins · Installer compiles the custom NDI and WebRTC plugins locally
- Installer → GStreamer stack: deps · Installer brings in system packages needed by the media stack
- Installer → NDI SDK: require host SDK · Provisioning assumes the proprietary NDI SDK is already installed
- Plugin path → Bridge app: env · Service environment exposes plugin and library locations
- gst-plugins-rs → GStreamer pipeline: plugins · Pipeline depends on locally built NDI and WebRTC elements
- GStreamer stack → GStreamer pipeline: runtime libs · Pipeline relies on system GStreamer and transport libraries
- NDI SDK → NDI source: discovery · NDI source access requires the host SDK and native libraries
- Validator → Plugin path: check · Validator verifies environment and plugin discovery
- Validator → NDI source: check · Validator confirms NDI visibility before runtime use
- Validator → WHIP endpoint: check · Validator tests WHIP reachability and ingest readiness
- MediaMTX → WHIP endpoint: local ingest · Optional MediaMTX endpoint can receive the bridge output
- MediaMTX → WHIP sink: test target · Used as a local WHIP destination during testing or on-prem deployment
