diff --git a/CHANGELOG.md b/CHANGELOG.md index a7caf63..94d92b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.3.0 - unreleased + +- README: a summary of what the collection contains, a "What you can build" + table, the functions grouped by role with hardware needs and licenses, and + release badges instead of version numbers that went stale. +- Added mxl-avsync (now released) and more complementary projects (MXL + docs and awesome-mxl, EASY MXL, mxl-k8s, BCP-007-03). +- States that this is an independent community project. +- The Compose examples are unchanged (same pinned images as 0.2.0). + ## 0.2.0 - 2026-10-24 - FlowXer vision mixer (19.26.68) as a media function: README table, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a15c06b..081cff7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,10 @@ - Here: corrections to the requirements, the Compose examples and the Kubernetes notes. Keep them in line with the function READMEs, which are the source of truth. -- When a function releases, update its version in `README.md` and the image - tags in `compose/`, and add a line to `CHANGELOG.md`. +- The README shows each function's latest release as a badge, so a function + release needs no change here. Update the image tags in `compose/` only after + running the new set together, and add a line to `CHANGELOG.md`. +- A new function: add a row to its category table in `README.md`. - Check before a pull request: ```bash diff --git a/README.md b/README.md index 4db6978..2ea106b 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,24 @@ # mxl-stack -An umbrella for a set of open-source media functions built on -[MXL](https://github.com/dmf-mxl/mxl) (Media eXchange Layer, part of the EBU -Dynamic Media Facility). This repository holds no media code. It links the -function repositories, lists what a host needs, and gives Docker Compose -examples to run them together. +**Open-source broadcast media functions for [MXL](https://github.com/dmf-mxl/mxl) +(Media eXchange Layer), the shared-memory media exchange of the EBU Dynamic +Media Facility (DMF).** Gateways (SMPTE ST 2110, SRT, SDI), a vision mixer, +an audio mixer, replay, graphics, a multiviewer, scopes, monitoring, AV sync +measurement and multi-host replication over MXL Fabrics. Every function is a +container with AMWA NMOS IS-04/IS-05 (BCP-007-03) control, a web UI and +Prometheus metrics. + +This repository is the entry point. It holds no media code: it lists the +function repositories, explains what a host needs, and gives Docker Compose +examples and Kubernetes notes to run them together. Each function repository stays the source of truth: its README and SPECIFICATION document every setting, port, metric and API. If this page and a function's README disagree, the README wins. +This is an independent community project. It is not part of, or endorsed by, +the MXL project, the EBU or the Linux Foundation. + ## What MXL is MXL lets media functions on one host exchange uncompressed video, audio and @@ -58,35 +67,76 @@ flowchart LR - Browser previews are low-rate H.264 published to MediaMTX and played over WebRTC (WHEP). +## What you can build + +Examples of chains made from these functions. Each arrow is an IS-05 +connection made in an NMOS controller. + +| Workflow | Chain | Start from | +| --- | --- | --- | +| A studio on one host | test-player or DeckLink → FlowXer (vision mixer) and audio-mixer → multiviewer, webrtc-monitor | [compose/single-host](compose/single-host/) | +| ST 2110 facility edge | ST 2110 sources → st2110-gateway → MXL functions → st2110-gateway → ST 2110 | [mxl-st2110-gateway](https://github.com/LeeO86/mxl-st2110-gateway) (needs an Intel E810) | +| Remote contribution | SRT in → srt-gateway → replay, browser-source graphics, audio-mixer → srt-gateway → SRT out | [compose/single-host](compose/single-host/) with `--profile extras` | +| Two hosts | functions on host-b read host-a's flows; the fabrics agent mirrors them over RDMA | [compose/multi-host-rdma](compose/multi-host-rdma/) | +| Measure a chain | avsync generator → chain under test → avsync analyzer (AV offset, latency); scopes for levels | [mxl-avsync](https://github.com/LeeO86/mxl-avsync) | + ## Media functions -FlowXer lives in its own GitHub account and has its own license (see its -repository). Images are on GitHub Container Registry. Release tags are `X.Y.Z`, `X.Y` and -`X`; there is no `latest` on most repos, so pin a version. - -| Function | Purpose | Image | Version | -| --- | --- | --- | --- | -| [mxl-st2110-gateway](https://github.com/LeeO86/mxl-st2110-gateway) | SMPTE ST 2110 <-> MXL gateway on Intel E810 with MTL/DPDK, two NMOS nodes | `ghcr.io/leeo86/mxl-st2110-gateway` | 1.0.20 | -| [mxl-srt-gateway](https://github.com/LeeO86/mxl-srt-gateway) | SRT (MPEG-TS) ingest and egress to and from MXL, NVDEC/NVENC optional | `ghcr.io/leeo86/mxl-srt-gateway` | 1.4.4 | -| [mxl-decklink](https://github.com/LeeO86/mxl-decklink) | Blackmagic DeckLink SDI input and output as MXL flows | `ghcr.io/leeo86/mxl-decklink` | 1.0.7 | -| [mxl-test-player](https://github.com/LeeO86/mxl-test-player) | TAI-locked test source: video, audio, timecode, fill/key | `ghcr.io/leeo86/mxl-test-player` | 1.2.4 | -| [mxl-multiviewer](https://github.com/LeeO86/mxl-multiviewer) | Multiviewer with up to 32 inputs, tally (TSL), CPU or CUDA | `ghcr.io/leeo86/mxl-multiviewer` | 1.4.6 | -| [mxl-webrtc-monitor](https://github.com/LeeO86/mxl-webrtc-monitor) | Watch and listen to any MXL flow in a browser (WebRTC/HLS) | `ghcr.io/leeo86/mxl-webrtc-monitor` | 1.4.2 | -| [mxl-color-corrector](https://github.com/LeeO86/mxl-color-corrector) | Colour correction (gain, pedestal, saturation, gamut clip), AVX2/AVX-512 | `ghcr.io/leeo86/mxl-color-corrector` | 1.2.3 | -| [mxl-scopes](https://github.com/LeeO86/mxl-scopes) | Video scopes (waveform, parades) as an MXL flow and a WebRTC widget | `ghcr.io/leeo86/mxl-scopes` | 1.1.0 | -| [mxl-replay](https://github.com/LeeO86/mxl-replay) | Live slow-motion replay, clip player, shotbox and playlists | `ghcr.io/leeo86/mxl-replay` | 1.8.1 | -| [mxl-browser-source](https://github.com/LeeO86/mxl-browser-source) | Offscreen Chromium (CEF) web page as MXL video, key and audio; OGraf graphics | `ghcr.io/leeo86/mxl-browser-source` | 1.3.3 | -| [mxl-audio-mixer](https://github.com/LeeO86/mxl-audio-mixer) | Broadcast audio engine: matrix, channel strips, DSP, loudness, control room | `ghcr.io/leeo86/mxl-audio-mixer` | 1.4.3 | -| [mxl-fabrics-agent](https://github.com/LeeO86/mxl-fabrics-agent) | Per-host agent that mirrors flows between hosts over RDMA (MXL Fabrics) | `ghcr.io/leeo86/mxl-fabrics-agent` | 1.7.3 | -| [FlowXer](https://github.com/firesh0ot/FlowXer) | Vision mixer: up to 4 MEs, keyers and DME boxes, clip players, stingers, tally (TSL), WebRTC preview, widgets. Needs an NVIDIA GPU | `ghcr.io/firesh0ot/flowxer-vision-mixer`, `ghcr.io/firesh0ot/flowxer-gui` | 19.26.68 | - -Work in progress (no image yet): [mxl-avsync](https://github.com/LeeO86/mxl-avsync), -AV sync and latency measurement (specification). - -Library: [mxl-nmos](https://github.com/LeeO86/mxl-nmos) (0.1.1), a Rust NMOS -node crate (IS-04, IS-05, BCP-007-03). - -### Infrastructure +Images are on GitHub Container Registry (`ghcr.io/leeo86/`). Release +tags are `X.Y.Z`, `X.Y` and `X`; most repos have no `latest`, so pin a version. +The badges show each repository's latest release. The Compose examples pin a +set that was run together; see [CHANGELOG.md](CHANGELOG.md). + +**Status.** All functions below have tagged releases, a container image and a +changelog, are tested on real hardware, and several run continuously on a +multi-host Kubernetes test platform. They are proofs of concept for MXL-based +production, not certified products. Features a README marks as planned are not +in the image yet. + +### Gateways and I/O + +| Function | What it does | Needs | License | Release | +| --- | --- | --- | --- | --- | +| [mxl-st2110-gateway](https://github.com/LeeO86/mxl-st2110-gateway) | SMPTE ST 2110 (-20, -30, -40, 2022-7) ↔ MXL with MTL/DPDK; two NMOS nodes | Intel E810, DPDK, hugepages, PTP | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-st2110-gateway?label=) | +| [mxl-srt-gateway](https://github.com/LeeO86/mxl-srt-gateway) | SRT (MPEG-TS) ingest and egress to and from MXL | CPU; NVDEC/NVENC optional | MIT (image GPL-2.0+, x264/x265) | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-srt-gateway?label=) | +| [mxl-decklink](https://github.com/LeeO86/mxl-decklink) | Blackmagic DeckLink SDI input and output as MXL flows | DeckLink card, Desktop Video driver | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-decklink?label=) | + +### Sources and graphics + +| Function | What it does | Needs | License | Release | +| --- | --- | --- | --- | --- | +| [mxl-test-player](https://github.com/LeeO86/mxl-test-player) | TAI-locked test source: video, audio, timecode, fill/key | CPU | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-test-player?label=) | +| [mxl-browser-source](https://github.com/LeeO86/mxl-browser-source) | Offscreen Chromium (CEF) web page as MXL video, key and audio, frame-locked to TAI; OGraf graphics | CPU; NVIDIA GPU optional | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-browser-source?label=) | + +### Production + +| Function | What it does | Needs | License | Release | +| --- | --- | --- | --- | --- | +| [FlowXer](https://github.com/firesh0ot/FlowXer) | Vision mixer: up to 4 MEs, keyers and DME boxes, clip players, stingers, tally (TSL), WebRTC preview, widgets | NVIDIA GPU | Apache-2.0 | tag `19.26.68` | +| [mxl-audio-mixer](https://github.com/LeeO86/mxl-audio-mixer) | Broadcast audio engine: routable matrix, channel strips, DSP, loudness, control room, VCAs | CPU | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-audio-mixer?label=) | +| [mxl-replay](https://github.com/LeeO86/mxl-replay) | Live slow-motion replay, clip player, shotbox and playlists | NVIDIA GPU recommended; records and plays clips without one | GPL-3.0 | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-replay?label=) | +| [mxl-color-corrector](https://github.com/LeeO86/mxl-color-corrector) | Colour correction (gain, pedestal, saturation, gamut clip), AVX2/AVX-512 | CPU | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-color-corrector?label=) | + +FlowXer is developed in its own GitHub account; see its repository for +releases and licensing. + +### Monitoring and measurement + +| Function | What it does | Needs | License | Release | +| --- | --- | --- | --- | --- | +| [mxl-multiviewer](https://github.com/LeeO86/mxl-multiviewer) | Multiviewer with up to 32 inputs, tally (TSL), as an MXL flow | CPU; CUDA optional | Apache-2.0 | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-multiviewer?label=) | +| [mxl-webrtc-monitor](https://github.com/LeeO86/mxl-webrtc-monitor) | Watch and listen to any MXL flow in a browser (WebRTC/HLS) | CPU; NVENC optional | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-webrtc-monitor?label=) | +| [mxl-scopes](https://github.com/LeeO86/mxl-scopes) | Video scopes (waveform, parades) as an MXL flow and a WebRTC widget | CPU (AVX2/AVX-512) | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-scopes?label=) | +| [mxl-avsync](https://github.com/LeeO86/mxl-avsync) | AV sync and latency measurement: test signal generator and analyzer; phone apps in testing | CPU | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-avsync?label=) | + +### Infrastructure and libraries + +| Project | What it does | Needs | License | Release | +| --- | --- | --- | --- | --- | +| [mxl-fabrics-agent](https://github.com/LeeO86/mxl-fabrics-agent) | Per-host agent that mirrors flows between hosts over MXL Fabrics, following NMOS connections | RDMA NIC (or TCP) | MIT | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-fabrics-agent?label=) | +| [mxl-nmos](https://github.com/LeeO86/mxl-nmos) | Rust crate: NMOS node (IS-04, IS-05, BCP-007-03) for MXL media functions. Early, 0.x | — | Apache-2.0 | ![release](https://img.shields.io/github/v/release/LeeO86/mxl-nmos?label=) | + +### Infrastructure used by the examples (third party) | Component | Purpose | Image | | --- | --- | --- | @@ -94,25 +144,47 @@ node crate (IS-04, IS-05, BCP-007-03). | [dmf-app-nmos-crosspoint](https://github.com/qvest-digital/dmf-app-nmos-crosspoint) | NMOS controller with a crosspoint view; connects ST 2110 and BCP-007-03 MXL senders and receivers over IS-05. Fork of [nmos-crosspoint_v3](https://github.com/Gemini2350/nmos-crosspoint_v3); see upstream for licensing | `ghcr.io/qvest-digital/dmf-app-nmos-crosspoint:4.36` | | [MediaMTX](https://github.com/bluenviron/mediamtx) | RTSP/WebRTC/HLS server for the browser previews | `bluenviron/mediamtx:1.20.1` | -### Related projects (third party) - -- [obs-mxl-plugin](https://github.com/JohannesItten/obs-mxl-plugin): OBS Studio input and output plugins for MXL. -- [Media Transport Library](https://github.com/OpenVisualCloud/Media-Transport-Library): ST 2110 over DPDK, used by the ST 2110 gateway. -- [mxl-hands-on](https://github.com/cbcrc/mxl-hands-on): MXL tutorial; the `/Volumes/mxl` tmpfs convention comes from there. - ## Getting started 1. Prepare the host: [docs/requirements.md](docs/requirements.md) (tmpfs MXL root, TAI time, inotify limit, optional GPU). 2. Run the single-host example: [compose/single-host](compose/single-host/). + It needs no special hardware: a Linux x86-64 host with Docker is enough + for the test player, multiviewer, scopes, audio mixer, replay, browser + source and WebRTC monitor. 3. Two hosts over RDMA: [compose/multi-host-rdma](compose/multi-host-rdma/). 4. Kubernetes notes: [docs/kubernetes.md](docs/kubernetes.md). -## Status - -These functions are proofs of concept for MXL-based production. They are -tested on real hardware, but APIs are unauthenticated by design: run them on a -protected network only. +New to MXL itself? Start with the SDK documentation and the CBC/Radio-Canada +hands-on workshop (below), then come back here. + +## Related projects + +Complementary open-source work around MXL, maintained by others: + +- [dmf-mxl/mxl](https://github.com/dmf-mxl/mxl): the MXL SDK, with + [documentation](https://dmf-mxl.github.io/mxl/) and the community list + [awesome-mxl](https://github.com/dmf-mxl/mxl/wiki/awesome%E2%80%90mxl). +- [cbcrc/mxl-hands-on](https://github.com/cbcrc/mxl-hands-on): MXL workshop + with example media functions; the `/Volumes/mxl` tmpfs convention comes from + there. CBC/Radio-Canada also maintain an + [FFmpeg with MXL](https://github.com/cbcrc/guidance-for-building-ffmpeg-with-mxl) + guide and a [CSI driver](https://github.com/cbcrc/mxl-csi) for MXL on Kubernetes. +- [EASY MXL](https://github.com/CLOUDflex-broadcast/easy-mxl): a web UI that + creates MXL domains and launches media functions from a catalog on a Docker host. +- [qvest-digital/mxl-k8s](https://github.com/qvest-digital/mxl-k8s): a + Kubernetes control plane for MXL, including Fabrics across nodes. +- [AMWA BCP-007-03](https://specs.amwa.tv/bcp-007-03): NMOS with MXL, the + IS-04/IS-05 transport the functions here implement. +- [obs-mxl-plugin](https://github.com/samisb/obs-mxl-plugin): OBS Studio input + and output plugins for MXL. +- [Media Transport Library](https://github.com/OpenVisualCloud/Media-Transport-Library): + ST 2110 over DPDK, used by the ST 2110 gateway. + +## Security + +The function APIs are unauthenticated by design: run them on a protected +network only. ## Contributing @@ -122,5 +194,4 @@ that function's repository. ## License MIT, see [LICENSE](LICENSE). Each function repository and image has its own -license and third-party notices (for example, the SRT gateway image is -GPL-2.0-or-later because it links x264 and x265). +license and third-party notices (see the License column above).