Die Sicherheitsleine — der teure Weg, mit engen Regeln

Wenn der billige Hebel nichts ausrichtet, weil die Playlist nur eine
Stufe hat oder schon die unterste läuft, bleibt nur der Neuaufbau mit
kleinerer Bitrate: Transcoder anhalten, Motor abreißen, neu aushandeln,
zurückspringen. Sekunden mit schwarzem Bild.

**Ein Notnagel, keine Regelschleife.** Zu oft ausgelöst erzeugt er genau
das Ruckeln, das er beheben soll. `DowngradeRule` ist deshalb eine Liste
von Bedingungen, die alle gelten müssen, und keine Schwelle: nur bei
„automatisch", nur wenn der billige Weg erschöpft ist, nur ab drei
Rücklern in anderthalb Minuten oder einem einzelnen über fünfzehn
Sekunden, nicht in den ersten zehn Sekunden, nicht binnen zehn Sekunden
nach einem Sprung, höchstens alle drei Minuten, höchstens zweimal.

Ein Sprung leert den Puffer **immer**. Ihn als Beleg für eine schlechte
Leitung zu nehmen hieße, sich für das eigene Tun zu bestrafen.

Das Urteil ist eine Aufzählung und kein `Bool`: „es hakt, aber wir tun
nichts" ist ohne Grund von einem Fehler nicht zu unterscheiden. Vierzehn
Tests schreiben jede Bedingung einzeln hin.

Ist das Budget verbraucht, **wird es gesagt** statt lautlos weiter
abgesenkt. Still bis zur untersten Sprosse zu gehen ist schlimmer, als
einmal zuzugeben, dass die Leitung es nicht trägt.

**Live-TV ist dabei**, wie gewünscht — aber mit Tuner-Abbau vorweg und
Budget eins statt zwei. Er ist ein Stück Hardware, vier Stück gibt es,
und ein doppelt belegter ist schlimmer als ein Stottern. Bekannte
Grenze: `endLiveSession` meldet nicht, **ob** die Freigabe geklappt hat
— das Protokoll gibt nichts zurück. Deshalb der eine Versuch und jeder
Schritt im Protokoll, damit ein verlorener Tuner nachvollziehbar bleibt.

Nebenbei aufgeräumt: die Wahl von Hand und die Sicherheitsleine teilen
sich jetzt denselben Neuaufbau. Was sie unterscheidet, steht in
`effectivePolicy` — die Wahl setzt `quality`, die Automatik
`automaticCeiling`, und beides fließt dort zusammen. Die Automatik
schreibt dabei nie `rememberedQuality` fort: eine schlechte Zugfahrt
soll nicht dauerhaft das Wohnzimmer verschlechtern.

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

Flixy/Views/Player/PlayerModel.swift

@@ -208,6 +208,42 @@ final class PlayerModel {
     /// Wann zuletzt eine Stufe höher gegangen wurde.
     @ObservationIgnored private var lastStepUp: Duration?
     @ObservationIgnored private var hasNotedMissingLadder = false
+    /// Wann zuletzt gesprungen wurde — ein Sprung leert den Puffer immer.
+    @ObservationIgnored private var lastSeekAt: Duration?
+    @ObservationIgnored private var lastDowngradeAt: Duration?
+    @ObservationIgnored private var downgradesUsed = 0
+
+    /// Ob die Automatik aufgegeben hat.
+    ///
+    /// Dann wird es gesagt statt lautlos weiter abgesenkt: still bis zur
+    /// untersten Sprosse zu gehen ist schlimmer, als einmal zuzugeben, dass
+    /// die Leitung es nicht trägt.
+    private(set) var hasGivenUp = false
+
+    /// Wie oft in **dieser** Wiedergabe der teure Weg gegangen werden darf.
+    ///
+    /// Bei Live-TV nur einmal. Jeder Neuaufbau stimmt dort den Tuner neu ab,
+    /// und davon gibt es vier Stück — ein Stottern ist der kleinere Schaden
+    /// als ein Sender, der gar nicht mehr angeht.
+    private var downgradeBudget: Int { isLive ? 1 : 2 }
+
+    /// Die Richtlinie, wie sie **jetzt** gilt.
+    ///
+    /// Die eingestellte Obergrenze, überschrieben von dem, was die Automatik
+    /// unterwegs gelernt hat. Getrennt von `quality`, damit eine schlechte
+    /// Zugfahrt nicht als gemerkte Stufe das Wohnzimmer verschlechtert.
+    private var effectivePolicy: PlaybackPolicy {
+        let base = quality.policy(basedOn: policy)
+        guard quality == .automatic, let ceiling = automaticCeiling else { return base }
+        return PlaybackPolicy(
+            allowsTranscoding: true,
+            // Ohne Ersatzmotor: sonst spielte VLC die Datei unverändert ab,
+            // und die abgesenkte Grenze bliebe wirkungslos.
+            allowsFallbackEngine: false,
+            maximumBitrate: min(ceiling, base.maximumBitrate ?? ceiling),
+            forcesTranscoding: true
+        )
+    }
 
     /// Die Obergrenze, die die Automatik gerade setzt — in Kilobit.
     ///
@@ -359,15 +395,33 @@ final class PlayerModel {
               let backend, let item, let media = currentMedia, let part = currentPart
         else { return }
 
+        quality = newQuality
+        // Von Hand gewählt: was die Automatik gelernt hatte, gilt nicht mehr.
+        automaticCeiling = nil
+        hasGivenUp = false
+        // Merken, wenn es gewünscht ist — sonst gilt die Wahl nur für diesen
+        // einen Film.
+        if settings.remembersQuality { settings.rememberedQuality = newQuality.storageValue }
+
+        await restart()
+    }
+
+    /// Baut den Strom mit der **aktuell geltenden** Richtlinie neu auf.
+    ///
+    /// Geteilt zwischen der Wahl von Hand und der Sicherheitsleine — der
+    /// Ablauf ist derselbe, nur der Anlass nicht. Was sich unterscheidet,
+    /// steht in `effectivePolicy`, nicht hier: die Wahl setzt `quality`, die
+    /// Automatik setzt `automaticCeiling`, und beides fließt dort zusammen.
+    private func restart() async {
+        guard !isOffline,
+              let backend, let item, let media = currentMedia, let part = currentPart
+        else { return }
+
         isChangingQuality = true
         defer { isChangingQuality = false }
 
         let resumeAt = currentTime
         resumeTarget = resumeAt
-        quality = newQuality
-        // Merken, wenn es gewünscht ist — sonst gilt die Wahl nur für diesen
-        // einen Film.
-        if settings.remembersQuality { settings.rememberedQuality = newQuality.storageValue }
 
         // Den alten Transcoder anhalten, bevor der neue anläuft. Sonst rechnet
         // der Server zwei Streams gleichzeitig für einen Zuschauer.
@@ -380,10 +434,9 @@ final class PlayerModel {
         engine = nil
         phase = .preparing
 
-        let newPolicy = newQuality.policy(basedOn: policy)
         let newDecision = PlaybackDecider().decide(
             profile: media.profile(file: part),
-            policy: newPolicy
+            policy: effectivePolicy
         )
         decision = newDecision
 
@@ -596,16 +649,150 @@ final class PlayerModel {
             indicatedBitrate: statistics.indicatedBitrate
         ))
 
-        // **Ohne Leiter greift der billige Hebel ins Leere.** AVPlayer spielt
-        // die eine Stufe auch dann, wenn sie über der Grenze liegt. Das ist
-        // kein Fehler, sondern der Fall, für den es die Sicherheitsleine gibt
-        // — und bis die steht, gehört er wenigstens ins Protokoll.
-        guard statistics.hasLadder else {
+        // Erst der billige Hebel — er kostet kein schwarzes Bild.
+        if statistics.hasLadder {
+            adjustCeiling(for: urteil, statistics: statistics, at: now)
+        } else {
             noteMissingLadder(urteil)
+        }
+
+        // Und dann die Frage, ob der teure Weg nötig ist.
+        considerTheHardWay(urteil, statistics: statistics, at: now)
+    }
+
+    // MARK: - Die Sicherheitsleine
+
+    /// Prüft, ob der Strom neu aufgebaut werden muss — und tut es.
+    private func considerTheHardWay(
+        _ condition: StreamCondition,
+        statistics: PlaybackStatistics,
+        at now: Duration
+    ) {
+        guard !hasGivenUp, !isChangingQuality, resumeTarget == nil else { return }
+
+        let unterste = statistics.variantBitrates.first
+        let facts = DowngradeRule.Facts(
+            isAutomatic: quality == .automatic,
+            hasLadder: statistics.hasLadder,
+            isAtLowestRung: unterste.map { (automaticCeiling ?? .max) <= $0 } ?? false,
+            condition: condition,
+            stallsInWindow: stallLedger.count(at: now),
+            longestStallInWindow: stallLedger.longest(at: now),
+            playedFor: now,
+            sinceLastSeek: lastSeekAt.map { now - $0 },
+            sinceLastDowngrade: lastDowngradeAt.map { now - $0 },
+            used: downgradesUsed,
+            budget: downgradeBudget
+        )
+
+        switch DowngradeRule.verdict(facts) {
+        case .downgrade:
+            Task { await downgradeTheHardWay(at: now) }
+        case .budgetSpent:
+            // **Hier hört es auf und wird gesagt.** Lautlos die ganze Leiter
+            // hinunterzugehen ist schlimmer, als einmal zuzugeben, dass die
+            // Leitung es gerade nicht trägt.
+            hasGivenUp = true
+            diagnostics.note("Automatik aufgegeben — die Leitung trägt es nicht")
+        case .notAutomatic, .cheaperPathRemains, .notBadEnough, .tooEarly, .cooling:
+            break
+        }
+    }
+
+    /// Baut den Strom mit kleinerer Bitrate neu auf.
+    private func downgradeTheHardWay(at now: Duration) async {
+        guard let ziel = nextLowerRung() else {
+            hasGivenUp = true
+            diagnostics.note("Keine kleinere Stufe mehr übrig")
             return
         }
 
-        adjustCeiling(for: urteil, statistics: statistics, at: now)
+        automaticCeiling = ziel
+        downgradesUsed += 1
+        lastDowngradeAt = now
+        diagnostics.note("Neuaufbau mit höchstens \(ziel) kbit — es hakte zu oft")
+
+        if isLive {
+            await retuneLive(to: ziel)
+        } else {
+            await restart()
+        }
+    }
+
+    /// Die nächste Sprosse unterhalb der aktuellen — aus **unserer** Leiter.
+    ///
+    /// Nicht aus der Playlist: die hat in diesem Fall gerade keine, sonst
+    /// wären wir hier nicht. Die Sprossen richten sich nach der Höhe der
+    /// Quelle — eine 720p-Datei auf 1080p „hochzurechnen" bringt kein Bild
+    /// dazu.
+    private func nextLowerRung() -> Int? {
+        let aktuell = automaticCeiling
+            ?? statistics?.indicatedBitrate
+            ?? policy.maximumBitrate
+            ?? 8_000
+
+        let sprossen = PlayerQuality.available(forSourceHeight: sourceHeight)
+            .compactMap { option -> Int? in
+                guard case .limited(let rung) = option else { return nil }
+                return rung.bitrate
+            }
+            .sorted()
+        return sprossen.last { $0 < aktuell }
+    }
+
+    /// Stimmt einen Sender mit kleinerer Bitrate neu ab.
+    ///
+    /// **Der Tuner wird zuerst freigegeben.** Er ist ein Stück Hardware, vier
+    /// Stück gibt es, und ein doppelt belegter ist im Alltag schlimmer als
+    /// ein Stottern. Erst danach wird neu abgestimmt.
+    ///
+    /// Bekannte Grenze: `endLiveSession` meldet nicht, **ob** die Freigabe
+    /// geklappt hat — das Protokoll gibt nichts zurück. Deshalb hier nur ein
+    /// Versuch je Wiedergabe und jeder Schritt im Protokoll, damit ein
+    /// verlorener Tuner wenigstens nachvollziehbar bleibt.
+    private func retuneLive(to bitrate: Int) async {
+        guard let liveTV, let subscription = request.liveSubscriptionKey else {
+            hasGivenUp = true
+            return
+        }
+
+        isChangingQuality = true
+        defer { isChangingQuality = false }
+
+        let stelle = currentTime
+        eventTask?.cancel()
+        engine?.teardown()
+        engine = nil
+        phase = .preparing
+
+        diagnostics.note("Tuner wird freigegeben")
+        await liveTV.endLiveSession(subscriptionKey: subscription)
+
+        let liste = await liveTV.liveChannels()
+        guard let sender = liste.channels.first(where: { $0.id == request.ratingKey }) else {
+            diagnostics.finish(outcome: "Sender nach dem Freigeben nicht mehr gefunden")
+            phase = .failed(message: String(localized: "player.stalled"))
+            return
+        }
+
+        let ergebnis = await liveTV.tune(
+            channel: sender,
+            program: nil,
+            maximumBitrate: bitrate
+        )
+        guard let url = ergebnis.url else {
+            diagnostics.finish(outcome: "Neues Abstimmen gescheitert")
+            phase = .failed(message: String(localized: "player.stalled"))
+            return
+        }
+
+        diagnostics.note("Neu abgestimmt mit höchstens \(bitrate) kbit")
+        let entscheidung = PlaybackDecision(method: .transcode(maximumBitrate: bitrate), rationale: [])
+        self.decision = entscheidung
+        await load(
+            PlaybackSource(url: url, origin: .remote, startTime: stelle),
+            decision: entscheidung
+        )
     }
 
     /// Setzt die Obergrenze eine Sprosse tiefer oder höher.
@@ -774,6 +961,7 @@ final class PlayerModel {
 
     func seek(to time: Duration) {
         guard let engine else { return }
+        if let startedAt = playbackStartedAt { lastSeekAt = ContinuousClock.now - startedAt }
         Task { await engine.seek(to: time) }
     }
 
@@ -833,6 +1021,10 @@ final class PlayerModel {
         automaticCeiling = nil
         lastStepUp = nil
         hasNotedMissingLadder = false
+        lastSeekAt = nil
+        lastDowngradeAt = nil
+        downgradesUsed = 0
+        hasGivenUp = false
         NowPlaying.shared.release(for: self)
     }