Repository navigation
feat: lumectl, a command-line tool that reproduces stream problems headlessly - #53
Merged
Merged
Conversation
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #46.
Summary
lumectlis a macOS command-line tool that reproduces stream problems without the app. It drives aPlayerSessionheadlessly (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>: everyPlayerEventwith a timestamp, aDiagnosticsheartbeat (--interval, default 2 s) with the delivery rate in Mbit/s, theStartupTimelineonce the first frame shows,lastStallReasonon every.stalled, theEngineErrorwith itshttpFailureclass, a final diagnostics line and a summary.--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.--header 'K: V'(repeatable),--user-agent,--referer,--no-reconnect,--io-timeout,--open-timeout.--jsonwrites JSON Lines with ordered keys (t,typefirst).--record-events FILEkeeps a JSON Lines copy next to the readable output.0ok,1tool failure,2usage,3open failed,4playback failed,5stalled (without failing),130Ctrl-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.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-urlsopts out. The scrubber is small and private to the tool, and it does not depend on the engine.--durationwould. A pendingopenis 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).#if os(macOS)pattern, so theLumeEngine-Packagescheme still builds for other platforms. I compile-checkedlumectlfor tvOS.API
Additive only, and Lume compiles unchanged. There are no engine source changes: no new
PlayerEventcases, no public API touched.Package.swiftadds:lumectlexecutable product,LumeCtlCoretarget and thelumectlexecutable target,LumeCtlCoreandlumectlas dependencies of the existing test target.The
CFFmpegbinary target, its conditionals, the evolution-flag logic and the dynamicLumeEngineproduct 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 andTortureHTTPServer, which live there. A separate target would have to duplicate both.--x v,--x=v),--terminator, help/version, the defaults keep engine defaults, the mapping ontoPlayerConfiguration(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-videotogether.get.phpqueries and userinfo (including an unescaped@in a password) are withheld;file://are kept;null, the exit-code policy, and the error rendering (HTTP class shown, URL hidden).probeonmultitrack.mkv;playofbasic.mp4(startup, heartbeats, summary);source;sourceEnded;lumectlgives 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 LumeEngineforgeneric/platform=tvOSandgeneric/platform=iOS: succeeds. The only warnings are the two existing ones inSystemRenderer.swift:87-88, which are untouched here.-scheme lumectlfor tvOS also builds.Manual runs, with this branch's freshly generated fixtures.
lumectl probe TestStreams/generated/basic.mp4:lumectl play TestStreams/generated/basic.mp4 --duration 2 --interval 1:hls-liveas a file (the playlist carries its end marker, so it opens as VOD):hls-liveserved 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 theCookievalue is hidden:The same live channel run for 20 s. No new segments ever appear, so the source stops and the stalls show their stage:
A refused open and a missing file:
Ctrl-C with
--json --record-events run.jsonl,kill -INTafter 1.5 s: exit 0, and 13 records were written to both stdout and the file. Excerpt: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
LumeEngineproduct are untouched.MediaInfo/TrackInfodo not expose the DV configuration record, so probe shows the colour tags, which revealipt-c2when the stream tags it. Adding something likeTrackInfo.Video.dolbyVisionProfilewould be a small additive engine change for a later PR.