Feature request: generation-scoped startup progress checkpoints for host loading UI

[dlev02]

The use case

I'm adding an optional determinate loading indicator to the host app's pre-playback screen: a progress bar with a percentage instead of the usual indeterminate spinner, so the user can tell a slow open apart from a stuck one.

I want the number to be honest, so it's driven purely by real startup checkpoints (completed steps over total steps), never elapsed time, byte counts, or an ETA. A slow stage holds, a skipped stage jumps. That part works and I'm happy with the semantics.

What's possible host-side today

The host can already derive a coarse ladder from existing publishes, and that's what I shipped:

1. load dispatched
2. playbackPhase leaves .idle
3. first non-empty audioTracks (or a nonzero duration) lands, meaning the probe finished
4. isSessionReady
5. hasFirstFrameReadyForDisplay (nice addition in 6.13.0, this is its first use here)
6. first .playing

Six edges, so the bar moves in roughly 20% steps. Livable, but the real problem is where the edges sit: on a slow origin almost the entire wait is inside the open/probe window, between steps 2 and 3, and the host has zero visibility into it. The bar sits at 20% for ten seconds and then sprints to 100%, which reads worse than it should given how much real work the engine is progressing through in that window.

The ask

A published, generation-scoped startup progress snapshot the host can observe. Shape I'd find useful:

• a semantic current stage plus completed/total checkpoint counts (or a normalized fraction derived from them)
• monotonic within one load generation; steady republishes deduped
• a new load() starts a fresh generation at zero; publishes from a superseded generation are ignored
• an engine-internal reroute (the remote-HLS bypass decision, a backend correction) stays inside the same user-visible startup and never lowers the value; it can update the stage label
• error/stop ends the sequence without ever publishing the final checkpoint
• checkpoints emitted from the code that actually completes the work, roughly: connection opened, probe finished, route chosen, backend host constructed, ready, first frame, playing
• paths that legitimately skip work (audio-only, the AVPlayer-direct bypass) complete the skipped checkpoints immediately rather than stalling

The biggest single win would be any sub-steps inside the open/probe window itself (connected vs first bytes vs probe complete, or however the internals naturally divide), since that's the stretch the host can't see at all and it's where slow sources spend their time.

Explicitly not asking for time estimates, byte-based percentages, or anything driven by timers. Checkpoints only, and no extra work on the startup path beyond publishing them.

If there's already a better seam for this than a new published property, happy to adapt to whatever fits the engine's conventions.

[superuser404notfound]

Shipped in 6.23.0. Thanks for the writeup: the six-edge ladder and the measurement of where the wait actually sits made this straightforward to place, and the shape you asked for is close to what landed.

startupProgress publishes a StartupProgress? carrying completed / total, a normalized fraction, and a stage naming the work in flight:

dispatched -> sourceOpened -> containerOpened -> streamsProbed -> displayPrepared
           -> routed -> sessionConstructed -> ready -> presenting

Three of those sit inside the open, which was the ask: the connection coming up and delivering its first bytes, avformat_open_input identifying the container, and the stream-info pass after it. That is as fine-grained as it gets without reaching inside avformat_find_stream_info, which does not narrate itself. A fourth checkpoint covers the display-criteria handshake, which on a real SDR to HDR switch runs for seconds and was invisible from the outside for the same reason the open was.

The ladder is one ordered axis rather than a set, so a path that legitimately skips work records the checkpoint it does reach and the ones behind it are credited by that alone. A local file has no connection to bring up, the remote-HLS bypass demuxes nothing and runs no panel handshake, an audio session has no picture. Nothing stalls waiting for a checkpoint its path never emits, and there is no per-path total to reconcile.

Three notes on where the implementation diverges from the request, all three worth knowing before wiring a bar to it:

The generation is not the engine's internal load counter. That one counts teardowns, and the engine's own reroutes (an HLS playlist discovered on the loopback path, a carriage case rerouted onto ingest) tear down and re-enter load() underneath one uninterrupted wait. Scoping to it would have done exactly what you asked it not to. StartupProgress.generation counts the waits a user sat through; the reroutes mark the continuation explicitly. Measured on a rerouted load, the ladder reads 0,5,6,8 with the generation unchanged.

The last checkpoint is the first frame, not .playing. On the native path state becomes .playing before the item is ready, because automaticallyWaitsToMinimizeStalling handles play-before-ready, so a ladder ending at the first .playing reports 100% over a black screen. It also never completes on a paused mount. If your current ladder ends on .playing, that is worth checking against your own traces.

ready is often overtaken on the native path. AVPlayer's layer holds a picture before the item publishes readyToPlay, so the bar steps straight from sessionConstructed to presenting there. It is kept because the software and audio paths pass it in order, and because on a start where the picture lags readiness it is the only movement in that stretch.

Error and stop behave as requested: the sequence ends without the last checkpoint ever being published, and nothing fakes an ending. Steady republishes are deduped, so a sink fires once per real step.

Every checkpoint also emits a log line ([AetherEngine] #361 startup 3/8 streamsProbed (gen 1)), which is the cheapest way to sanity-check what your own sources do before building UI on it.

Verified with aetherctl play across the native, software, both audio and bypass paths, including against an origin throttled to 600 kbit/s with 400 ms of added latency, where the three open checkpoints land seconds apart. The full matrix is in the release notes. Leaving this open until you have had a chance to try it on your side.

[dlev02]

Thank you for shipping this and for the detailed explanation. This looks like exactly the kind of signal I was hoping for, especially the checkpoints inside the open and probe window and the display-preparation step.

I will take a look at 6.23.0, wire it up on my side, and test it against some slow sources (will try to report back within the next week, want to ensure I have proper time to test though).