Fünf Fehler auf einem Weg — warum nie ein Untertitel kam

Sechs Reparaturversuche haben nichts bewirkt, weil jeder an einer Stelle
ansetzte, die gar nicht die Ursache war. Eine systematische Untersuchung —
45 Hypothesen, jede von drei Skeptikern gegengeprüft — hat fünf voneinander
unabhängige Defekte auf demselben Weg gefunden. Jeder einzelne genügt.

**1. Es wurde eine Playlist bestellt, die keine Untertitelspur tragen kann.**
Jellyfins TranscodingUrl lautet `main.m3u8` — eine Media Playlist, also eine
Liste von Schnipseln. `#EXT-X-MEDIA`, die Zeile, mit der ein Server eine
Untertitelspur ankündigt, darf nach RFC 8216 nur in einer Master Playlist
stehen. Der Wechsel main→master hing aber an der Leiter, und die wird beim
Umpacken und bei jeder von Hand gewählten Stufe nicht bestellt. Ein Matroska
geht immer über das Umpacken — die halbe Sammlung konnte strukturell keine
Untertitel haben.

Der Kommentar daneben war überholt und hat den Fehler verdeckt: er stammte
aus der Zeit, als Umpacken eine fortlaufende MP4 war. Seit es über HLS läuft,
ist die Master-Liste genau richtig. Pfadwechsel und Leiter sind jetzt zwei
Fragen, nicht eine.

**2. Der lokale Server etikettierte jeden Schnipsel als video/mp4.** Auch die
WebVTT-Schnipsel der Untertitelspur. So angekündigt gehen sie bei
AVFoundation an den falschen Parser, finden keine Box, und es entsteht
lautlos keine Einblendung — die Spur steht im Blatt, ist ausgewählt, bleibt
leer. Der Vorrat behält jetzt die Sorte der Gegenstelle; die Endung ist nur
noch der Notnagel.

**3. Nach dem ersten Untertitel wählte niemand mehr etwas aus.**
`selectedSubtitleTrack` wurde beim Neuaufbau nie zurückgesetzt, und beide
Wähler prüfen genau darauf. Eine frische Engine hat aber nichts ausgewählt —
also blieb sie für den Rest des Films stumm, während das Symbol „ein" zeigte.
Auch das Nachfassen im Sekundentakt war damit stillgelegt. Die Bestellung
(`selectedSubtitleStream`) bleibt, die Merker fallen.

**4. Die Schutzmarke war nach 250 ms tot.** `restart()` setzte sie als
Allererstes — und wartete danach auf einen echten Netzaufruf mit fünf
Sekunden Zeitgrenze, bevor es den alten Ereignisstrom abbestellte. In diesem
Fenster meldete der alte Player weiter seine Stelle, und die Prüfung „sind
wir angekommen" traf sofort zu. Die Marke war gelöscht, bevor der neue Stream
bestellt war; danach setzte jede Meldung des anlaufenden Streams die Stelle
auf null, und der nächste Neuaufbau merkte sich den Filmanfang. Das war der
Sprung — und der Grund, warum mein Fix von 88ba1a5 wirkungslos blieb.

**5. Der Sprung wurde einmal versucht und nie geprüft.** Der Rückgabewert von
`seek` wurde verworfen, die gemerkte Stelle verbraucht, bevor gesprungen
wurde, und framegenaue Toleranz verlangt — in einen Stream, den der Server
gerade erst erzeugt. Jetzt bleibt die Stelle stehen, bis ein Sprung bestätigt
ist, die Toleranz liegt bei einer halben Sekunde, und jedes Wachsen des
springbaren Bereichs ist ein neuer Anlass.

Belegt statt vermutet: ein neuer Test startet den lokalen Server gegen einen
eigenen Herkunftsserver und liest die Antworten Byte für Byte — ohne Gerät,
ohne Simulator, in 0,03 Sekunden. Er hat Fehler 2 vor der Reparatur
reproduziert und danach bestätigt. Fünf weitere Tests halten Fehler 1 fest.

Zwei alte Tests hielten das fehlerhafte Verhalten fest und waren damit
mitschuldig; beide sind mitgeändert.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Packages/FlixyKit/Sources/FlixyPlayback/Prefetch/StreamCache.swift

@@ -22,6 +22,12 @@ import OSLog
 /// **Der Vorsprung ist begrenzt**, und zwar in Sekunden Film, nicht in
 /// Schnipseln: die Zahl soll dasselbe bedeuten, egal wie der Server schneidet.
 public actor StreamCache {
+    /// Ein Schnipsel — Daten **und** wofür sie sich ausgeben.
+    public struct Segment: Sendable {
+        public let data: Data
+        public let contentType: String
+    }
+
     /// Wie weit vorausgelaufen wird.
     public struct Policy: Sendable {
         /// Wie viel Film im Voraus geholt werden soll.
@@ -47,8 +53,14 @@ public actor StreamCache {
     private var segments: [String] = []
     private var targetDuration: Duration = .seconds(6)
 
-    /// Was schon auf der Platte liegt — Pfad auf Datei.
-    private var stored: [String: URL] = [:]
+    /// Was schon auf der Platte liegt — Adresse auf Datei **und Sorte**.
+    ///
+    /// **Die Sorte gehört dazu.** Ein Schnipsel ist nicht zwangsläufig Bild:
+    /// die Untertitelspur liefert WebVTT, der Ton kann AAC sein. Wer die
+    /// Sorte wegwirft und später etwas behauptet, liefert dem Player einen
+    /// Text als Video — der gibt ihn dem falschen Parser, findet keine Box,
+    /// und es entsteht lautlos gar nichts.
+    private var stored: [String: (ort: URL, type: String)] = [:]
     private var storedBytes = 0
     /// Welchen Schnipsel der Player zuletzt verlangt hat.
     private var lastRequested = 0
@@ -147,13 +159,15 @@ public actor StreamCache {
     // MARK: - Ausliefern
 
     /// Die Daten zu einer Adresse — aus dem Vorrat, sonst frisch geholt.
-    public func data(for address: String) async -> Data? {
+    public func data(for address: String) async -> Segment? {
         if let index = segments.firstIndex(of: address) {
             lastRequested = max(lastRequested, index)
             trimBehind()
         }
 
-        if let ort = stored[address], let daten = try? Data(contentsOf: ort) { return daten }
+        if let eintrag = stored[address], let daten = try? Data(contentsOf: eintrag.ort) {
+            return Segment(data: daten, contentType: eintrag.type)
+        }
 
         // **Der Player hat Vorrang.** Fehlt ihm etwas, wartet er darauf — und
         // der Vorrat darf ihm dabei nicht die Leitung wegnehmen. Rechnet der
@@ -218,23 +232,43 @@ public actor StreamCache {
     }
 
     @discardableResult
-    private func fetch(_ address: String) async -> Data? {
+    private func fetch(_ address: String) async -> Segment? {
         guard let ziel = URL(string: address) else { return nil }
 
         do {
-            let (daten, antwort) = try await session.data(from: ziel)
-            guard (antwort as? HTTPURLResponse)?.statusCode ?? 200 < 400 else { return nil }
-            store(daten, at: address)
-            return daten
+            var anfrage = URLRequest(url: ziel)
+            for (name, wert) in headers { anfrage.setValue(wert, forHTTPHeaderField: name) }
+            let (daten, antwort) = try await session.data(for: anfrage)
+            let http = antwort as? HTTPURLResponse
+            guard http?.statusCode ?? 200 < 400 else { return nil }
+
+            // **Die Sorte kommt von der Gegenstelle, nicht von uns.** Sie
+            // weiss, was sie geschickt hat; wir wüssten es nur aus der
+            // Endung, und die kann fehlen oder lügen. Erst wenn sie nichts
+            // sagt, raten wir anhand der Adresse.
+            let sorte = http?.value(forHTTPHeaderField: "Content-Type")
+                ?? Self.guessedType(for: address)
+            store(daten, type: sorte, at: address)
+            return Segment(data: daten, contentType: sorte)
         } catch {
             return nil
         }
     }
 
-    private func store(_ daten: Data, at path: String) {
+    /// Die Sorte aus der Endung — der Notnagel.
+    static func guessedType(for address: String) -> String {
+        let pfad = URL(string: address)?.path.lowercased() ?? address.lowercased()
+        if pfad.hasSuffix(".vtt") { return "text/vtt" }
+        if pfad.hasSuffix(".ts") { return "video/MP2T" }
+        if pfad.hasSuffix(".aac") { return "audio/aac" }
+        if pfad.hasSuffix(".m3u8") { return "application/vnd.apple.mpegurl" }
+        return "video/mp4"
+    }
+
+    private func store(_ daten: Data, type: String, at path: String) {
         let ort = directory.appending(path: UUID().uuidString)
         guard (try? daten.write(to: ort, options: .atomic)) != nil else { return }
-        stored[path] = ort
+        stored[path] = (ort, type)
         storedBytes += daten.count
     }
 
@@ -249,11 +283,11 @@ public actor StreamCache {
 
         for index in 0..<min(grenze, segments.count) {
             let pfad = segments[index]
-            guard let ort = stored.removeValue(forKey: pfad) else { continue }
-            let größe = (try? FileManager.default.attributesOfItem(atPath: ort.path))
+            guard let eintrag = stored.removeValue(forKey: pfad) else { continue }
+            let größe = (try? FileManager.default.attributesOfItem(atPath: eintrag.ort.path))
                 .flatMap { $0[.size] as? Int } ?? 0
             storedBytes = max(0, storedBytes - größe)
-            try? FileManager.default.removeItem(at: ort)
+            try? FileManager.default.removeItem(at: eintrag.ort)
         }
     }