Skip to content

feat: lumectl, a command-line tool that reproduces stream problems headlessly - #53

Merged
bilipp merged 4 commits into
mainfrom
feat/lumectl
Oct 13, 2026
Merged

bilipp merged 4 commits into
mainfrom
feat/lumectl

Conversation

@bilipp

@bilipp bilipp commented Oct 12, 2026

Copy link
Copy Markdown
Owner

Stacked on #46.

Summary

lumectl is a macOS command-line tool that reproduces stream problems without the app. It drives a PlayerSession headlessly (muted) against a URL and prints what the engine reports, so startup stalls, reconnects, replays, seams, decoder downgrades and HTTP errors from a provider can be triaged from a terminal.

  • lumectl probe <url>: container, duration, start time, live/seekable, bitrate, and every track (codec, language, size, fps, bit depth, pixel format, HDR transfer, primaries/matrix/transfer tags, channels, sample rate, default/forced), plus chapters and metadata.
  • lumectl play <url>: every PlayerEvent with a timestamp, a Diagnostics heartbeat (--interval, default 2 s) with the delivery rate in Mbit/s, the StartupTimeline once the first frame shows, lastStallReason on every .stalled, the EngineError with its httpFailure class, a final diagnostics line and a summary.
    • Options: --duration, --start (resume path), --seek (mid-stream, after the first frame), --software, --audio-lang de,en, --no-audio / --no-video (isolate a lane), --stall-threshold.
    • Source options (both commands): --header 'K: V' (repeatable), --user-agent, --referer, --no-reconnect, --io-timeout, --open-timeout.
  • Output: text by default. --json writes JSON Lines with ordered keys (t, type first). --record-events FILE keeps a JSON Lines copy next to the readable output.
  • Exit status: 0 ok, 1 tool failure, 2 usage, 3 open failed, 4 playback failed, 5 stalled (without failing), 130 Ctrl-C before the open finished. A failure outranks a stall. Ctrl-C is how a live run ends, so it is not a verdict of its own.
  • Credentials are redacted by default. URLs are printed as scheme://host[:port]/[redacted].ext, so the extension still tells HLS from TS. URLs inside error messages and metadata are redacted the same way, and header values are never printed (names only). --show-urls opts out. The scrubber is small and private to the tool, and it does not depend on the engine.
  • Ctrl-C: the first one ends the run like --duration would. A pending open is cancelled, which aborts the FFmpeg I/O, the session is shut down (bounded at 5 s) and the summary is printed. A second Ctrl-C exits immediately.

Layout:

  • Sources/LumeCtlCore: the testable logic (argument parser, URL scrubber, JSON encoder, reporter, run control, exit codes, the probe/play runs).
  • Sources/lumectl: only process plumbing (argv, SIGINT via a dispatch signal source, unbuffered stdout).
  • Hand-rolled argument parser, with no new package dependencies.
  • The executable follows the demo's #if os(macOS) pattern, so the LumeEngine-Package scheme still builds for other platforms. I compile-checked lumectl for tvOS.

API

Additive only, and Lume compiles unchanged. There are no engine source changes: no new PlayerEvent cases, no public API touched. Package.swift adds:

  • a lumectl executable product,
  • an internal LumeCtlCore target and the lumectl executable target,
  • LumeCtlCore and lumectl as dependencies of the existing test target.

The CFFmpeg binary target, its conditionals, the evolution-flag logic and the dynamic LumeEngine product are untouched.

Tests

Tests/LumeEngineCoreTests/LumeCtlTests.swift, 20 tests in 4 suites. They live in the existing test target rather than a new one because the end-to-end runs need the generated fixtures and TortureHTTPServer, which live there. A separate target would have to duplicate both.

  • Arguments: every option in both spellings (--x v, --x=v), -- terminator, help/version, the defaults keep engine defaults, the mapping onto PlayerConfiguration (seconds to µs for --io-timeout, last value wins for a repeated header), and 18 malformed command lines. These include CRLF injection in --header, NaN/inf/negative numbers, empty language tags, and --no-audio --no-video together.
  • URL redaction:
    • credentials in Xtream-style paths, get.php queries and userinfo (including an unescaped @ in a password) are withheld;
    • ports, extensions, local paths and file:// are kept;
    • URLs inside quoted error messages are redacted where they stand.
  • Output: JSON key order and escaping, non-finite numbers become null, the exit-code policy, and the error rendering (HTTP class shown, URL hidden).
  • End-to-end, in process:
    • probe on multitrack.mkv;
    • 2 s play of basic.mp4 (startup, heartbeats, summary);
    • a 403 via the torture server gives exit 3, with no credential substring anywhere in the output;
    • a source that goes silent gives exit 5 with stage source;
    • a live HLS channel that ends gives exit 4 with sourceEnded;
    • an injected interrupt ends a 10 s file early with a clean summary.
  • End-to-end, real binary: SIGINT to the built lumectl gives exit 0 with "interrupted, shutting down" and a summary.

Full suite: 161 tests in 24 suites pass (swift test).

Verification

Builds:

  • swift build: no new warnings.
  • xcodebuild build -scheme LumeEngine for generic/platform=tvOS and generic/platform=iOS: succeeds. The only warnings are the two existing ones in SystemRenderer.swift:87-88, which are untouched here.
  • -scheme lumectl for tvOS also builds.

Manual runs, with this branch's freshly generated fixtures.

lumectl probe TestStreams/generated/basic.mp4:

[   0.003] lumectl probe TestStreams/generated/basic.mp4
[   0.405] format    mov,mp4,m4a,3gp,3g2,mj2
           duration  10.000 s
           start     0.000 s
           live      no   seekable yes
           bitrate   2.07 Mbit/s
           tracks
             #0 video h264 und 640x360 30 fps 8-bit yuv420p SDR untagged limited 1997 kbit/s [default]
             #1 audio aac und 1 ch 44100 Hz 69 kbit/s [default]
           metadata
             compatible_brands: isomiso2avc1mp41
             encoder: Lavf63.1.102
             major_brand: isom
             minor_version: 512
[   0.405] summary ok (exit 0), stalls 0, errors 0, downgrades 0
exit=0

lumectl play TestStreams/generated/basic.mp4 --duration 2 --interval 1:

[   0.000] lumectl play TestStreams/generated/basic.mp4
[   0.100] state opening
[   0.106] state ready
[   0.106] opened
           format    mov,mp4,m4a,3gp,3g2,mj2
           duration  10.000 s
           start     0.000 s
           live      no   seekable yes
           bitrate   2.07 Mbit/s
           tracks
             #0 video h264 und 640x360 30 fps 8-bit yuv420p SDR untagged limited 1997 kbit/s [default]
             #1 audio aac und 1 ch 44100 Hz 69 kbit/s [default]
           metadata
             compatible_brands: isomiso2avc1mp41
             encoder: Lavf63.1.102
             major_brand: isom
             minor_version: 512
[   0.106] selected video #0, audio #1, subtitles none
[   0.106] state buffering
[   0.325] state playing
[   0.326] startup open 0.01 pkt 0.01 v 0.14 a 0.03 shown 0.23
[   1.115] heartbeat state=playing playhead=0.71s vq=7/0.23s+0.06s@0.00 vp=267/8.90s aq=48/1.11s+0.32s@0.00 ap=338/7.84s renderers=v1 a1 demuxEOF=yes read=2.5MB seams=0 dup=0 startup=[open 0.01 pkt 0.01 v 0.14 a 0.03 shown 0.23] in=19.92Mbit/s
[   2.117] heartbeat state=playing playhead=1.71s vq=8/0.27s+0.06s@0.00 vp=237/7.90s aq=48/1.11s+0.06s@0.00 ap=306/7.10s renderers=v1 a1 demuxEOF=yes read=2.5MB seams=0 dup=0 startup=[open 0.01 pkt 0.01 v 0.14 a 0.03 shown 0.23] in=0.00Mbit/s
[   2.117] final state=playing playhead=1.71s vq=7/0.23s+0.09s@0.00 vp=237/7.90s aq=48/1.11s+0.06s@0.00 ap=306/7.10s renderers=v1 a1 demuxEOF=yes read=2.5MB seams=0 dup=0 startup=[open 0.01 pkt 0.01 v 0.14 a 0.03 shown 0.23]
[   2.184] state idle
[   2.184] summary ok (exit 0), position 1.708 s, stalls 0, errors 0, downgrades 0
exit=0

hls-live as a file (the playlist carries its end marker, so it opens as VOD):

[   0.002] lumectl probe TestStreams/generated/hls-live/index.m3u8
[   0.225] format    hls
           duration  12.000 s
           start     1.400 s
           live      no   seekable yes
           bitrate   162 bit/s
           tracks
             #0 video h264 320x180 25 fps 8-bit yuv420p SDR untagged limited
             #1 audio aac 1 ch 44100 Hz
[   0.226] summary ok (exit 0), stalls 0, errors 0, downgrades 0
exit=0
[   0.000] lumectl play TestStreams/generated/hls-live/index.m3u8
[   0.103] state opening
[   0.108] state ready
[   0.108] opened
           format    hls
           ...
[   0.108] selected video #0, audio #1, subtitles none
[   0.108] state buffering
[   0.328] state playing
[   0.539] startup open 0.00 pkt 0.00 v 0.11 a 0.03 shown 0.44
[   1.138] heartbeat state=playing playhead=2.10s vq=7/0.28s+0.12s@1.42 vp=271/10.84s aq=48/1.11s+0.32s@1.40 ap=425/9.86s renderers=v1 a1 demuxEOF=yes read=1.0MB seams=0 dup=0 startup=[open 0.00 pkt 0.00 v 0.11 a 0.03 shown 0.44] in=8.24Mbit/s
[   2.116] final state=playing playhead=3.08s vq=8/0.32s+0.10s@1.42 vp=246/9.84s aq=48/1.11s+0.06s@1.40 ap=394/9.15s renderers=v1 a1 demuxEOF=yes read=1.0MB seams=0 dup=0 startup=[open 0.00 pkt 0.00 v 0.11 a 0.03 shown 0.44]
[   2.172] state idle
[   2.172] summary ok (exit 0), position 1.684 s, stalls 0, errors 0, downgrades 0
exit=0

hls-live served live: the playlist has its end marker stripped and is served over local HTTP under an Xtream-shaped path with credentials and a token. The URL comes out redacted and the Cookie value is hidden:

$ lumectl play 'http://127.0.0.1:48731/live/someuser/s3cretpass/index.m3u8?token=abc' --duration 2 --interval 1 --user-agent 'Lume/1.0' --header 'Cookie: session=secret'
[   0.000] lumectl play http://127.0.0.1:48731/[redacted].m3u8
             headers: Cookie (values hidden)
[   0.106] state opening
[   0.112] state ready
[   0.113] opened
           format    hls
           duration  unknown (live)
           start     7.423 s
           live      yes   seekable no
           tracks
             #0 video h264 320x180 25 fps 8-bit yuv420p SDR untagged limited
             #1 audio aac 1 ch 44100 Hz
[   0.113] selected video #0, audio #1, subtitles none
[   0.113] state buffering
[   0.325] state playing
[   0.325] startup open 0.01 pkt 0.01 v 0.13 a 0.03 shown 0.22
[   1.137] heartbeat state=playing playhead=8.15s vq=8/0.32s+0.08s@7.42 vp=118/4.72s aq=48/1.11s+0.31s@7.44 ap=165/3.83s renderers=v1 a1 demuxEOF=no read=0.5MB seams=0 dup=0 startup=[open 0.01 pkt 0.01 v 0.13 a 0.03 shown 0.22] in=3.73Mbit/s
[   2.138] final state=playing playhead=9.15s vq=8/0.32s+0.08s@7.42 vp=93/3.72s aq=29/0.67s+0.43s@7.44 ap=134/3.11s renderers=v1 a1 demuxEOF=no read=0.5MB seams=0 dup=0 startup=[open 0.01 pkt 0.01 v 0.13 a 0.03 shown 0.22]
[   2.198] state idle
[   2.198] summary ok (exit 0), position 1.724 s, stalls 0, errors 0, downgrades 0
exit=0

The same live channel run for 20 s. No new segments ever appear, so the source stops and the stalls show their stage:

[   4.564] STALLED at 4.391 s, stage: source
[   6.275] state buffering
[   8.568] STALLED at 6.065 s, stage: source
...
[  20.270] summary stalled (exit 5), position 6.065 s, stalls 4 [source, source, source, source], errors 0, downgrades 0

A refused open and a missing file:

$ lumectl probe 'http://user:pw@127.0.0.1:1/get.php?username=u&password=p'
[   0.000] lumectl probe http://127.0.0.1:1/[redacted].php
[   0.112] open failed: openFailed (ffmpeg -61): avformat_open_input: Connection refused
[   0.112] summary open-failed (exit 3), ...
$ lumectl play /nonexistent.ts
...
[   0.124] FAILED openFailed (ffmpeg -2): avformat_open_input: No such file or directory
[   0.124] summary open-failed (exit 3), stalls 0, errors 1, downgrades 0

Ctrl-C with --json --record-events run.jsonl, kill -INT after 1.5 s: exit 0, and 13 records were written to both stdout and the file. Excerpt:

{"t":1.488,"type":"note","note":"interrupted"}
{"t":1.586,"type":"state","state":"idle"}
{"t":1.586,"type":"summary","outcome":"ok","exitCode":0,"position":0.996,"stalls":[],"errors":0,"downgrades":0,"failure":null}

Probe of an HDR10 sample: #0 video hevc und 640x360 25 fps 10-bit yuv420p10le HDR PQ bt2020/bt2020nc/pq limited 556 kbit/s [default].

Not verified

  • Real IPTV providers. Every run here was against local fixtures and local HTTP servers.
  • Behaviour against a macOS audio route that refuses the (muted) audio renderer. I have seen no such case, but the tool's audio timing is the real renderer's.
  • Lume itself was not rebuilt against this branch. Nothing it links changed: the new product is an executable, and the engine targets and the LumeEngine product are untouched.
  • The Dolby Vision profile is not shown. MediaInfo/TrackInfo do not expose the DV configuration record, so probe shows the colour tags, which reveal ipt-c2 when the stream tags it. Adding something like TrackInfo.Video.dolbyVisionProfile would be a small additive engine change for a later PR.

Base automatically changed from feat/live-playout-and-startup-events to main October 12, 2026 22:14
The audio decoder read the negotiated output width once, at creation, so a
route change mid-playback (HDMI receiver to AirPlay, HomePods) kept feeding
the old width. AudioOutputRoute now follows the shared audio session's
negotiated width through route-change notifications (stereo on macOS); the
decoder refits per AudioLayoutPolicy at the next frame boundary, with an
explicit ITU-R BS.775 DownmixMatrix (centre and surrounds -3 dB, LFE
omitted) set into swresample, and mono goes out on both speakers. When the
route narrows, the renderer keeps audio decoded for the wider route away
from the renderer.

PlayerSession.audioHealth (also in Diagnostics) reports audio that died
while video plays on: decoder failed, renderer failed, or nothing reaching
the renderer at a running playhead (AudioLossDetector), the latter also as
.error with the new EngineError.Code.audioLost. Additive API only.
Cue lifecycle: decoders now hand the store display updates (start, end or
none, text, whether the track replaces the whole screen), and a pure
SubtitleTimeline decides how long each shows. Open cues (UINT32_MAX end:
PGS, DVB, captions) end at the next update of their track instead of
staying up for 49 days; the empty update replacing tracks send to clear
the screen now ends what is showing instead of being dropped; open cues
are capped at 16 s and ended by a seek; re-read ranges stay deduplicated;
the store is bounded at 8192 cues so a live session no longer grows
without limit. Subtitle decoders flush their state across seek serials.
SubtitleStore is now checked Sendable (Mutex) instead of @unchecked.

Closed captions: CEA-608 carried as A/53 side data on decoded video frames
is lifted off in VideoDecoder.receiveFrames by a ClosedCaptionTap, stamped
with the frame's PTS and trySend-ed to a SubtitleDecoder running ccaption
in real-time mode, anchored at the packet time. The video lane never
waits on it. A synthetic "CC1" subtitle track
(TrackInfo.embeddedClosedCaptionsIndex) appears in PlayerSession.mediaInfo
once caption content is seen, and selectSubtitleTrack accepts it.

Stacked on #46.
SUBTITLE_BITMAP rects from avcodec_decode_subtitle2 were dropped. They
now become SubtitleImages on the cue: a premultiplied sRGB CGImage
(palette ARGB -> premultiplied BGRA) and a rect normalized to the
subtitle's authoring canvas as the decoder reports it after decoding
(DVB display definition, PGS presentation size, DVD size:), with a 720x576
fallback grown to fit the rects. The DVB context's size is zeroed before
opening so the stream's display definition decides it.

SubtitleCue gains images (defaulted, empty for text cues); bitmap cues
carry empty text, so text-only consumers keep working and show nothing.
The timeline treats an update with images as content rather than a clear,
deduplicates re-decoded bitmaps by position and size, and bounds bitmap
memory at 64 MB on top of the cue count. LumePlayer exposes the active
cues' images as subtitleImages; LumePlayerView has no subtitle overlay, so
drawing stays with the host.

Stacked on #46.
…adlessly

`lumectl probe <url>` opens a source and prints what it carries; `lumectl
play <url>` drives a muted PlayerSession against it and prints every
PlayerEvent with a timestamp, the Diagnostics heartbeat with the delivery
rate, the StartupTimeline once the first frame shows, lastStallReason on
every stall and the typed EngineError (with its HTTP class) on failure.
Text or JSON Lines, optionally recorded to a file. Exit status separates
ok, open failure, playback failure and stall; Ctrl-C shuts the session
down (bounded) and prints the summary.

URLs are printed as scheme and host only unless --show-urls, and header
values never, because IPTV URLs and headers carry the account.

The logic lives in LumeCtlCore and is tested from LumeEngineCoreTests,
which already owns the fixtures and the torture server: argument parsing,
URL redaction, JSON output, exit codes, and end-to-end runs (probe, play,
refused open, silent source, live source that ends, interrupt, SIGINT on
the built binary).
@bilipp
bilipp merged commit f7f8358 into main Oct 13, 2026
8 of 10 checks passed
@bilipp
bilipp deleted the feat/lumectl branch October 13, 2026 06:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant