[Used by] KSKPix

[ksktech-dev]

App name

KSKPix

Repository or website URL

https://ksktech.dev/kskpix

One-line description

KSKPix is a premium IPTV player for Live TV, Movies & Series

Platforms

Multiple

Confirmation

• This app actually ships AetherEngine as a dependency.
• The name, URL, and description above are correct and ready to publish.

[ksktech-dev]

Hi — KSKPix (an IPTV player for Apple TV and iOS) has shipped AetherEngine as its primary playback engine since v2.0.0, and I'd rather show you how we credit it.

We name it in four places (screenshots attached):

• the player's engine switcher — "AetherEngine", with a logo, alongside VLC
• Settings → playback backend — "AetherEngine + VLC"
• Stats for Nerds — the active decoder and the version we vendored, e.g. "AetherEngine 6.25.2"
• one line of Settings copy explaining what each engine can and can't do (AirPlay, PiP)

There's one non-UI place too: our User-Agent appends an engine token, so requests reach providers as KSKPix/ … Aether/. Happy to drop that or if you'd rather your engine's name not appear in traffic to third-party CDNs.

The intent is just credit — it's your engine doing the work and we'd rather say so than hide it behind a generic label. But it's your name, so if the wording, the placement, or the logo isn't how you'd want it represented, tell me what you'd prefer and I'll change it. If you'd rather we didn't use the name at all, that's fine too.

[superuser404notfound]

Thanks for writing this up, and for the screenshots. The credit is more than fine and nothing needs to change on your side.

Name and logo. Use both as they are. The switcher entry, the "AetherEngine + VLC" line and the vendored version in Stats for Nerds all read exactly the way I would want them to read, and the mark in the screenshots is the repo's own asset, so there is nothing to approve separately. Two small preferences, neither worth a build of its own:

• The name is one word with two capitals, AetherEngine. The short form "Aether" in body copy once the full name has appeared is fine, which is what the Player engine screen already does.
• If you ever need the mark bigger, .github/aetherengine-logo.png is the source at 1024px. Ask if you need another size or a transparent variant.

User-Agent. Keep it. The engine sets no User-Agent of its own anywhere: it forwards whatever the host hands it in LoadOptions.httpHeaders and otherwise leaves AVFoundation's default alone, so that token is yours to carry and nothing about it bothers me.

One caution rather than an objection: origins that gate on User-Agent are common enough in IPTV that per-stream header forwarding exists for them (#119), and aetherctl's HLS fixture has a --deny-user-agent flag so that shape can be reproduced offline (#363). The day a provider decides it dislikes an unfamiliar token, the failure will present as a playback bug rather than a header problem. A per-stream override, or a switch that drops the token, is cheap insurance against spending an evening on it.

Version. Surfacing the vendored version is genuinely useful on my end, a version in a bug report saves a round. Worth knowing that 6.25.2 has been overtaken: 6.25.3 and 6.25.4 are both drop-in with no API change (a PGS subtitle end that could not be corrected once taken, and a Matroska HEVC config record whose SEI made the Apple TV track builder refuse the file). The IPTV-relevant one of the recent batch is 6.24.0, live playlists routed through the path that carries their headers, and you already have that.

One licensing note, since KSKPix ships through the App Store and you vendored the engine. AetherEngine is LGPL-3.0 with an App Store / DRM exception, and FFmpeg reaches you through FFmpegBuild as dynamically linked LGPL-2.1 frameworks. Practically that means embedding them dynamically rather than linking them in, shipping the license texts, and pointing at the build's source. The concrete adopter steps are in README > License and in FFmpegBuild's README. Not a complaint, just easier to get right before a submission than after one.

KSKPix is in the used-by list as of #375 and on the docs site landing page. Bug reports welcome, IPTV-shaped ones especially.

[superuser404notfound]

One question I should have put in that comment, because a dual-engine host sits in a position nobody else does: what does VLC still cover for you that Aether does not?

Your settings copy says VLC plays the widest range of streams, so there is a list behind that sentence, and whatever makes your fallback fire in practice is effectively a gap list for the engine. A useful shape of an answer:

• what trips it (container, codec, live against VOD, a particular provider's playlist), and whether the fallback is automatic on failure or something a user picks by hand
• whether it fails outright or plays badly (no picture, no audio, stalls, a timeline that does not match the stream)
• anything that has quietly turned into "just switch to VLC for those" in your support replies. That class is the interesting one, because it never gets filed as a bug by anyone

A playlist URL or a sample is ideal, but the shape alone is enough to start on. The bug template in this repo is the right place if you would rather file them one at a time, and IPTV-shaped reports go to the front of the queue.

[kskchaitanya1993]

Thanks — all four points taken, and the VLC question is a fair one to put to us. Answering it honestly means separating what we can measure from what we can only guess at, so I'll do that explicitly.

What VLC covers today: on our own test bed, nothing

We run a deterministic fixture set (34 entries: progressive MP4/MKV/WebM/TS VOD, HLS fMP4 and TS, endless sliding-window live in H.264/HEVC/HDR10/HLG/4K50, plus injected faults — 403 playlist, periodic 404/403 segments, 20s playlist stalls, corrupt segments, throughput starvation, mid-segment disconnects). Current numbers on 6.25.2:

• Apple TV, real device: 13/13 on rung aether, avg TUNE→picture 0s, max 1s
• iOS simulator soak/zap: 6/6, every channel starting and staying on aether, no demotions

Both harnesses now treat a row landing on VLC as the regression condition. The comment in our own soak script reads: "VLC is a rung nothing in the test bed falls to — the only way to verify the VLC path still carries the whole player is to force it." So we keep a --force-vlc lever purely to exercise that path.

That is a statement about our fixtures, not about the world. It does mean we have no reproducible case in hand to hand you.

What actually triggers the fallback

Automatic, and deliberately narrow. The ladder demotes on:

• the engine failing to initialise
• load() throwing
• our host-side TS-ingest retry throwing
• never producing a first frame inside a budget — 20s live, 15s VOD, 35s once a session is on the loopback path

Explicitly not a mid-stream stall. Once a real video frame has rendered we latch a flag and never demote after that, because we had the opposite behaviour once and it produced "plays in Aether fine, then switches to VLC a few seconds later." A stall after first frame is yours to recover and it does.

On top of that there are two manual routes: a per-stream engine switch in the player's ⋮ menu, and a global default in Settings (AetherEngine is the default; VLC is opt-in).

What used to trip it, and no longer does

The honest historical answer, since it's the closest thing we have to a gap list:

• HEVC-in-MPEG-TS live was the big one — AVFoundation builds no video track and the session played audio over black. That was a constant fallback trigger for us and the HDR10 4K HEVC 50fps live HLS via nativeRemoteHLS: AVPlayer exposes no video track (audio-only, black); no HDR display-criteria negotiation. VLC + Android decode it fine #168 carriage reroute closed it. It is the single largest change in how often VLC gets reached in this app.
• 4K50 HDR HEVC-in-TS specifically, same shape, previously our worst channel; now first frame in about a second on the device.
• A .ts URL served as an HLS playlist used to error on the raw live path and drop to VLC; we carried a host-side retry for it, and 6.24.0 made the engine route it itself.

The class you actually asked about

"Things that quietly became just switch to VLC for those in support replies" — there is no such class, and the reason is timing rather than tidiness. The dual-engine build only reached users on iPhone and iPad this afternoon; 2.0.0 is its first public release. Apple TV has shipped AetherEngine since 1.x, but there is no body of support correspondence of that kind behind it either. So there is nothing to mine yet, in either direction, and any list offered here would be invention rather than recollection.

What we can do instead: we already have the demotion reason at the point it happens, so emitting it as an analytics event with container/codec/live-vs-VOD attached would turn this into counts rather than impressions. Given 2.0.0 has hours of field time, that instrumentation is the only route to a real answer, and it is the one worth taking. If it would be useful to you I'll wire it and report back with numbers.

The other three

Naming — checked both codebases: zero instances of the spaced form. Full name on the control, short "Aether" in body copy, as you described.

User-Agent — the insurance you suggested already exists, which I should have said in the first comment. Our UA helper only appends the engine token when the User-Agent starts with our own KSKPix/ prefix; an explicit per-source or MAG User-Agent is passed to the origin verbatim and token-free. So a provider that dislikes the token can be worked around per stream without a build. There's no global "drop the token but keep our UA" switch — worth adding, and cheap.

Version — moving to 6.25.4 now.

Licensing — checked against the adopter steps rather than assuming. The FFmpeg side is nine dynamic frameworks in KSKPix.app/Frameworks/, not merged into the app binary. AetherEngine's own code we link statically, which your exception covers explicitly ("end-user re-linking of the installed binary against modified versions"). What was genuinely stale was our published licence page: it still described AetherEngine as Apple-TV-only at 6.6.0 and the mobile FFmpeg as our own static MediaBridge build, both true up to 1.x and neither true since 2.0. Corrected, with the linkage shape spelled out: https://ksktech.dev/kskpix/oss — happy to adjust anything there that reads wrong to you.

---

🤖 This comment was written and posted by Claude Code on behalf of @ksktech-dev. The measurements quoted are from our own harness runs against a synthetic test bed, not from the field.

Edited shortly after posting: the first version implied we had a history of support replies steering users to VLC. We don't — 2.0.0 reached users the same afternoon this was written, so there is no field history to draw on yet. Corrected rather than left standing, since it read as evidence we do not have.

[superuser404notfound]

That is the answer I wanted, and "no reproducible case in hand" is a result rather than a non-answer. A fixture set that no longer falls to the second engine is worth more than a list assembled from memory would have been, and 13/13 on a real device with a one second worst case is a number I have from nowhere else.

Wire the instrumentation. One extra field turns it from a counter into the gap list.

A demotion count says how often, not where. The engine publishes where, as of 6.23.0: player.$startupProgress is a nine step ladder (checkpoint, completed of total, fraction, stage), and every step is recorded by the code that finishes the work it names, never by a timer and never from an estimate. Sample the furthest checkpoint at the moment of demotion, attach it to the container / codec / live-vs-VOD you already have, and the histogram reads straight back as engine work:

• .sourceOpened / .containerOpened never reached: the origin, before any media question is asked
• stuck at .streamsProbed: avformat_find_stream_info, the longest single stretch on a slow origin and the one nothing else exposes
• .displayPrepared: the display criteria handshake, so the panel rather than the stream
• .routed / .sessionConstructed: route picked, backend building
• .ready reached but never .presenting: the session calls itself ready and no picture follows. That is the shape your HEVC-in-TS channels used to have.

Two notes on measuring against it:

• Whatever marks "first frame" for the budget should not be state == .playing. On the native path that is an intent, published before the item is ready (automaticallyWaitsToMinimizeStalling), so a budget that stops there can stop over a black screen. $hasFirstFrameReadyForDisplay is the edge, and .presenting is that same edge inside the ladder, which is why the ladder deliberately does not end at .playing.
• The 20 s live budget sits under the bypass's own 45 s readiness ceiling (nativeRemoteHLS: a session that never reaches readyToPlay has no terminal state, and a settled carriage verdict sits unused #334, 6.15.1), whose failure text names the cause rather than the symptom: "AVFoundation built no track for it within 45s and the source's carriage could not be identified". Demoting before that is a product call I would make too, but then the engine's own sentence never reaches your logs. The checkpoint at demotion is what preserves it.

The latch after first frame is right for timers, and it must not swallow the two terminal signals.

Not demoting on a mid-stream stall is the correct call and worth keeping. What it should not also suppress is the case where the engine has stopped claiming it can recover, because that is precisely where a second engine is the right answer:

• state = .error(String). Worth knowing while you are still on 6.25.2: three arms in the VOD reopen path used to end on a bare return once their budget was spent, which left a session a host cannot tell apart from a slow one, which is the exact failure mode a first-frame latch is exposed to. 6.25.0 closed the muxer-failure arm (muxerFailed / permanent black screen: first-segment audio prime scan gives up when the selected audio track is sparsely interleaved (UHD remux) #366), 6.25.1 the gate-starvation re-anchor and a pump that reached EOF having written nothing (Unknown-length HTTP MP4 enters streaming mode and returns ready with zero packets; the same URL plays in VLC #126). 6.25.4 carries all three, so that contract now has a signal behind it instead of an assumption.
• liveSourceReset, and this is the one to check you subscribe to. On live, exhaustion arrives as a retune request rather than an error state: a source restarted from byte 0, a playlist still frozen after the stall ladder's last reload rung, or an in-engine reopen transport whose budget is spent all halt production first and then publish it, because the only thing that can revive such a session is a URL the engine has no way to obtain. Unsubscribed, it costs a channel that stops while the engine still reports a session. The machinery behind it is familiar territory over there, Rerouted live-ingest session death relands on the known-bad native path: #168 verdict not remembered, no in-engine revive #199 was traced from your field logs.

Some of that is on the README: it lists every @Published surface and named neither PassthroughSubject, so a host reading it came away without the live retune contract at all. Fixed in f4e5305, together with systemCaptionRequest.

The three that no longer trip it match the record on my side, and between them they are the only real gap list either of us has. HEVC-in-MPEG-TS live is #168, with #293 covering a media playlist that has no master to judge and #199 remembering the verdict so a retune after an ingest death does not re-pay the mount plus grace window. The .ts served as a playlist is #363, which also routes a live m3u8 that lands on the raw live path and hands a 401/403 bypass refusal to the ingest instead of failing the load. If the instrumentation turns up a fourth, that is the interesting one.

The license page reads correct. Unmodified sources, engine linked statically under the exception clause, FFmpeg dynamic in Frameworks/, LGPL-only build, and FFmpegBuild 2.4.2 is exactly what 6.25.4 resolves to, so the version pairing is right as well. Nothing there I would change. The one piece worth confirming on your side is that the license texts themselves travel with the app or are reachable from inside it rather than only being named; the source offer is satisfied by the page either way.

Naming, User-Agent and version are all clear, and the UA helper's prefix rule is a better answer than the global switch I suggested.

Send the histogram once it has enough field time behind it, even if it turns out boring. A quarter with no demotions outside the known three is itself a measurement, and it is one I currently cannot make.

[kskchaitanya1993]

Both corrections land, and one of them is a bug on our side.

liveSourceReset — not subscribed. Neither platform. That was the right thing to single out. We handle state = .error and demote on it, and we deliberately don't demote on a mid-stream stall, but the retune request we simply never wired, so the case it exists for — source restarted from byte 0, playlist still frozen after the last reload rung, reopen transport spent — ends with the engine parked and our UI still showing a live session. A channel that stops and stays stopped, with nothing in our logs to say why. It reads as a freeze, which is why it would never have been filed as an engine bug. Subscribing on both hosts, per session, and routing it into the same retune path a manual channel change uses.

Two things I can confirm rather than promise:

• The first-frame budget is not measured on state == .playing. It reads hasFirstFrameReadyForDisplay, and our own comment beside it says the native path fires .playing as an intent; there's a separate guard withholding first-frame for an audio-only native .playing, which we added after a black HEVC channel passed as healthy. So the edge you describe is the one we're on.
• The latch after first frame only suppresses the timer. .error still demotes through it. Your note that 6.25.0/6.25.1 gave those three VOD arms a real signal instead of a bare return is the part that makes that contract worth relying on — we're moving to 6.25.4 for exactly that.

Instrumentation: agreed, with the checkpoint. Sampling the furthest startupProgress checkpoint at the moment of demotion and attaching it to container / codec / live-vs-VOD is a better design than the counter I proposed, and the mapping you gave — .ready reached but never .presenting being the old HEVC-in-TS shape — is what makes the histogram readable without a human interpreting each row. I'll also record the engine's own error string where there is one, since your point about our 20 s budget sitting under the 45 s ceiling is well taken: we'd otherwise demote before the sentence that names the cause is ever written.

Licence texts. Checked rather than assumed, and you were right to ask: they are currently only named in the app. The in-app screen is a plain text block that mentions the URL in prose — not a link, and the texts themselves aren't bundled. The page satisfies the source offer, but "reachable from inside it" it is not. Making the URL an actual link and bundling the LGPL texts with the app so they travel with it.

Histogram will come when there's enough field time behind it to mean anything, boring or not.

---

🤖 Written and posted by Claude Code on behalf of @ksktech-dev.

[superuser404notfound]

Both corrections are worth having on the thread, and the unsubscribed liveSourceReset is the one that changes something in the field rather than on paper. A channel that stops and stays stopped, with the UI still showing a live session, is the exact shape that never gets filed, so finding it by reading the contract rather than from a report is the better way round.

The retune needs its own guard, because the manual path will not carry one. Routing it into the channel-change path is the right shape, but that path is user-paced by construction: it never needed a spacing rule because a human supplies one. Driven by the engine it does. What the reference host settles on (PlayerViewModel+Live.handleLiveSourceReset, public source):

• one retune in flight, a second reset arriving during it is dropped and logged rather than queued, so a hung reload is visible instead of silently eating all further recovery
• a minimum spacing of 20 s, and at most three per session
• the exhausted case surfaced to the viewer, not swallowed. A ladder that ends on a silent return leaves the same dead channel with a counter behind it, which is what the subject exists to prevent in the first place

On the engine side a reset from a session a zap has superseded is dropped before it is published (identity check against the current session; the stall ladder's own sinks die with the load), so the in-flight latch only has to cover the host's path, not duplicates from mine.

What a retune costs an IPTV host, since it is not the Jellyfin shape. That reference answers a reset by re-negotiating: fresh PlaybackInfo, new PlaySessionId, transcode anchored at the live edge. A channel URL that never changes has nothing to negotiate, so the answer is loading the same URL again, and that is the cheap case rather than a no-op. The #168 carriage verdict is remembered per exact absolute URL, 32 entries, six hours, so the retune routes straight onto the live ingest and skips the native mount plus watchdog grace the first load already paid. Pair that with the budget: a URL carrying a rotated per-session token is a cache miss and re-pays the one-time discovery per retune, which is where a 20 s live budget covering the retune would feel it. The README says this now as well (e139249), because "negotiate a fresh URL" reads as "nothing to do here" to exactly your class of host, and that was my wording rather than your reading.

Where the first-frame latch and the retune bound meet. Not demoting on a mid-stream stall stays right. An exhausted retune ladder is a different animal: the engine has said it cannot revive the session, the host has tried and given up, and the channel is dead with a picture already behind it. That is the one post-first-frame case where a second engine is the honest answer, and today it is invisible to the instrumentation you are about to wire, because it presents as neither .error nor a slow start. Recording it with the checkpoint and the engine's last message attached is what would make a fourth gap-list entry findable at all.

The audio-only guard: the flag agrees with it, so it is not covering for me. hasFirstFrameReadyForDisplay folds the host's video-display level only, latched for the load, and a session with no video-display signal never arms it, including through the readiness path that exists because a local layer never rises while an external screen holds the picture (#315). Guard and flag say the same thing, which is the useful outcome: the black-channel case cannot come back in through a route the guard does not watch.

One implementation nit, if the engine instance outlives a session over there: the subscription is per session by intent. A long-lived engine that gains a fresh sink per load accumulates handlers, and then one reset retunes several times, which the in-flight latch will hide rather than fix.