How to Stream MPEG-TS with KLV over UDP using FFmpeg

This article provides a practical guide on how to construct and run an FFmpeg command to stream an MPEG-TS (MPEG Transport Stream) containing synchronized Key-Length-Value (KLV) metadata over a UDP network. You will learn how to map both video and data streams correctly, ensure real-time transmission, and configure the stream output to preserve the KLV packet structure.

Streaming an Existing File with Video and KLV Metadata

If you already have a file (such as an .ts or .mpg file) that contains both a video track and a KLV metadata track, you can stream it over UDP using the following FFmpeg command:

ffmpeg -re -i input.ts -map 0:v -map 0:d -c copy -f mpegts "udp://239.0.0.1:1234?pkt_size=1316"

Here is a breakdown of the critical parameters used in this command:

• -re: Reads the input file at the native frame rate. This is required for real-time live streaming; omitting this will cause FFmpeg to stream the file as fast as CPU/bandwidth allows.
• -i input.ts: Specifies the input file containing the video and KLV data.
• -map 0:v: Explicitly selects the video stream from the first input file.
• -map 0:d: Explicitly selects the data stream (which contains the KLV metadata) from the first input. By default, FFmpeg does not always map data streams, so this flag is mandatory.
• -c copy: Copies both the video and data streams without transcoding them, saving CPU cycles and preserving the exact metadata payload.
• -f mpegts: Forces the output format to be MPEG Transport Stream, which natively supports KLV metadata tracks (often registered as SMPTE 336M).
• "udp://239.0.0.1:1234?pkt_size=1316": Defines the target UDP destination (multicast or unicast IP and port). The parameter pkt_size=1316 limits the packet size to exactly 7 MPEG-TS packets (188 bytes each), preventing network packet fragmentation.

Multiplexing and Streaming Separate Video and KLV Files

If your video stream and KLV metadata are in separate sources (for example, an MP4 video file and a raw binary KLV stream), you can multiplex them into a single MPEG-TS stream on the fly:

ffmpeg -re -i video.mp4 -re -i klv_data.bin -map 0:v -map 1:d -c:v libx264 -c:d copy -f mpegts "udp://192.168.1.50:5000?pkt_size=1316"

Key differences for this configuration include:

• -i video.mp4 -i klv_data.bin: Takes two separate files as inputs.
• -map 0:v -map 1:d: Maps the video stream from the first input (index 0) and the data stream from the second input (index 1).
• -c:v libx264: Encodes the video to H.264 (necessary if the source video format is not native to MPEG-TS, like MP4).
• -c:d copy: Copies the raw KLV binary data directly into the transport stream without alteration.