How thatdavidbelll/ndi-to-whip works
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 Bridge app · install.sh Installer · validate.sh Validator · mediamtx.yml MediaMTX
Components 17
Runtime
Application and media pipeline
- Bridge app · Reads config, probes NDI, builds and supervises the GStreamer pipeline
ndi_to_whip.py - NDI source · Discoverable NDI sender on the network
- GStreamer pipeline · Runtime media processing and transport boundary
- Demux · Splits incoming NDI into raw video and audio branches
- Video branch · videoconvert, videoscale, and videorate prepare video for sink negotiation
- Audio branch · audioconvert and audioresample prepare audio for sink negotiation
- WHIP sink · whipclientsink negotiates codec and publishes the stream
- WHIP endpoint · Remote ingest server receiving the published WebRTC stream
Deployment
Bootstrap and service wiring
- Config · Source selection, WHIP settings, and media parameters
config.toml - Service · Long-lived supervised runtime under the ndi-whip user
ndi-to-whip.service - Installer · Installs packages, builds plugins, and deploys files on the host
install.sh - NDI SDK · Host-installed NDI runtime required for source access
- gst-plugins-rs · Provides libgstndi.so and libgstrswebrtc.so built on the host
- GStreamer stack · System GStreamer plus libnice and libsrtp2 for WebRTC transport
- Plugin path · Custom plugin and library paths exposed to the service process
Operations
Validation and observability
- Validator · Checks host readiness, plugin discovery, and connectivity
validate.sh
Companion
Optional local WHIP server
- MediaMTX · Optional local WHIP endpoint and republishing setup
mediamtx.yml
Connections 23
- 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