NDIPlayer

NDIPlayer is a small Linux tool that discovers NDI video sources on your network, plays one source as live video using GStreamer + GTK3, and can also send your desktop as an NDI source.

Key features:

• Live playback of an NDI source (GStreamer ndisrc)
• Desktop capture and streaming: send your desktop (or specific monitor) as an NDI source
• Source switching
  • Up/Down: cycle sources
  • Right click: show a list of sources and select one
• Fullscreen toggle
  • Ctrl+F
  • Double left-click
• Reconnect handling: if a source stops streaming (EOS / error), the player keeps trying to reconnect to that same source and shows a reconnect overlay.
• Last used source: persisted to the user cache dir (defaults to $XDG_CACHE_HOME/ndiplayer or ~/.cache/ndiplayer)

---

Requirements (Ubuntu / Debian)

This project relies on system packages for GTK/GStreamer and the NDI GStreamer plugin.

System packages

Install the GTK3 + GStreamer runtime and tools:

sudo apt update
sudo apt install -y \
  python3-gi python3-gi-cairo \
  gir1.2-gtk-3.0 libgtk-3-0 \
  gstreamer1.0-tools \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-base-apps \
  gstreamer1.0-gtk3

Notes:

• gstreamer1.0-plugins-base-apps provides gst-device-monitor-1.0, which is useful to verify what NDI sources your system can see.
• For desktop capture, you also need gstreamer1.0-plugins-good (provides ximagesrc).
• Depending on your NDI encoding / pipeline needs you may also want: gstreamer1.0-libav, gstreamer1.0-plugins-good, gstreamer1.0-plugins-bad, gstreamer1.0-plugins-ugly.

NDI SDK + gst-plugin-ndi

You need the NewTek/NDI SDK installed and the GStreamer NDI plugin available so GStreamer provides ndisrc / ndideviceprovider.

• NDI plugin docs: https://gstreamer.freedesktop.org/documentation/ndi/index.html?gi-language=python
• Plugin source: https://github.com/teltek/gst-plugin-ndi

Quick verification:

gst-inspect-1.0 ndi
gst-device-monitor-1.0 -f Source/Network:application/x-ndi

---

Install (uv)

This repo uses uv as the project manager.

uv sync

Run:

uv run ndiplayer --help
uv run ndiplayer list
uv run ndiplayer play
uv run ndiplayer send

---

Usage

List sources (with resolution probe)

uv run ndiplayer list

Play

uv run ndiplayer play

Controls:

• Up/Down: cycle sources
• Right click: open the source list
• Ctrl+F / Double-click: toggle fullscreen
• Esc: close

Send Desktop as NDI Source

Capture your desktop and send it as an NDI source on the network.

# Capture entire display (all monitors) at default 60 FPS
uv run ndiplayer send

# Capture specific monitor (index 0) at default 60 FPS
uv run ndiplayer send --monitor 0

# Capture monitor 1 at 30 FPS
uv run ndiplayer send --monitor 1 --fps 30

# Capture entire display with custom NDI source name
uv run ndiplayer send --ndi-name "My Desktop"

# Capture monitor 0 at 24 FPS with custom name
uv run ndiplayer send --monitor 0 --fps 24 --ndi-name "Main Monitor"

Options:

• --monitor <int>: Monitor/display index to capture (0-based). If omitted, captures entire display (all monitors combined).
• --ndi-name <string>: Name for the NDI source. If not provided, uses format: NDI_PLAYER {hostname} [{monitor}] or NDI_PLAYER {hostname} for full display.
• --fps <int>: Frames per second for the video stream. Default is 60, can be lowered (e.g., 30, 24).

The process runs until interrupted (Ctrl+C).

Environment variables

• NDI_SOURCE_NAME: initial source name
• NDI_FULLSCREEN: 1/true/yes to start fullscreen
• NDI_REFRESH_INTERVAL_S: refresh interval for NDI source list
• NDI_PLAYER_CACHE_PATH: override cache path (otherwise XDG cache is used)

---

Docker (experimental)

There is a Docker + Docker Compose setup in this repo, including installing the NDI SDK and building gst-plugin-ndi inside the image.

However, NDI discovery inside the container is currently not working reliably (the container does not see NDI sources even when the host does). The Docker setup should therefore be considered work in progress.