XC_VM/tools/test-stream-generator/README.md

Test stream generator

Generates a synthetic, ever-changing test pattern (no input file) and serves it as looping, HTTP-served streams you can paste into the panel as a live stream source — for end-to-end testing of the panel's streaming pipeline, including LLOD (the Low-Latency On-Demand processor in src/Cli/Commands/LlodCommand.php).

The picture is drawn live by ffmpeg from testsrc2 (a moving colour test pattern) with overlays: a large running stopwatch (elapsed), the real wall-clock time (compare it to your own clock to eyeball end-to-end latency), a frame counter, and two boxes sweeping across the frame. Audio is a low 1 kHz tone. Everything is paced in real time, so the panel sees a never-ending "live" channel.

Requirements

• Python 3.7+ (standard library only — no pip install)
• ffmpeg available in PATH (or pass --ffmpeg /path/to/ffmpeg)
• A TrueType font for the on-screen clock/labels — autodetected (DejaVu / Liberation / fc-match). If none is found it falls back to testsrc (v1), whose built-in timestamp still gives a running timer plus the moving boxes.

Usage

cd tools/test-stream-generator
./stream_server.py

On start it prints the URLs to paste into the panel, e.g.:

  TS (LLOD): http://192.168.1.50:8088/stream.ts
  HLS      : http://192.168.1.50:8088/stream.m3u8
  M3U list : http://192.168.1.50:8088/playlist.m3u
  Index    : http://192.168.1.50:8088/

Stop with Ctrl+C.

Options

Flag	Default	Description
--host	0.0.0.0	Bind address.
--port	8088	Bind port.
--advertise-host	autodetect	Host/IP printed in the URLs (set this if the panel is on another host).
--size	1280x720	Frame size WxH.
--fps	25	Frame rate.
--font	autodetect	Path to a .ttf for the on-screen clock/labels.
--max-clients	32	Max concurrent /stream.ts readers (all share the one TS encoder). Extra connections get 503.
--verbose	off	Log every HTTP request (off by default to keep long runs quiet).
--ffmpeg	ffmpeg	ffmpeg binary to use.

./stream_server.py --size 1920x1080 --fps 30
./stream_server.py --font /usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf

Endpoints

URL	Content-Type	Use
/stream.ts	video/mp2t	Continuous MPEG-TS — the endpoint for testing LLOD. Served from one shared, always-running encoder, so every open — including repeated on-demand pulls — attaches instantly with no new ffmpeg.
/stream.m3u8	application/vnd.apple.mpegurl	Live HLS (sliding-window playlist + .ts segments).
/playlist.m3u	audio/x-mpegurl	M3U channel list with both URLs, for bulk import.
/	text/html	Index page listing every URL.

Adding a stream in the panel

1. Admin → Streams → Add/Edit stream.
2. Paste a URL into the stream source field (stream_source[] in src/Public/Views/admin/stream.php). You can add several sources.
3. Save and start the stream.

Testing LLOD specifically

1. Use the /stream.ts URL as the stream source (LLOD requires an upstream that responds with Content-Type: video/mp2t, which this endpoint does).
2. Enable the LLOD flag on the stream (streams.llod = 1).
3. Start the stream and confirm the panel writes rolling 4-second segments to /home/xc_vm/content/streams/{id}_{segment}.ts and the client can play it.

Bulk import

Add http://HOST:8088/playlist.m3u as a playlist source to register both the TS and HLS test channels at once.

Notes

• Each /stream.ts client gets its own ffmpeg; the HLS output is shared by a single background ffmpeg that auto-restarts if it dies.
• HLS segments live in a temp directory (bounded by delete_segments) that is removed on exit.
• Long-run safety (fine to leave running for days): concurrent /stream.ts pulls are capped (--max-clients), each client socket has a write timeout + TCP keepalive so a stalled/half-open peer is dropped instead of pinning an ffmpeg, and per-request access logging is off unless --verbose. The only cosmetic quirk over multi-day runs is the MPEG-TS 33-bit timestamp wrap (~26.5 h), which ffmpeg handles.
• This is a development/testing tool. Do not expose it to the public internet.