Abspielen am Fernseher — mit Apples Player und unseren Spuren

Schritt sieben. Wiedergabe, Spurwahl, Titelzeile, „Intro überspringen".

**Die schwierige Stelle war die Spurwahl.** Unsere Ton- und Untertitelwahl
geht als `audioStreamIndex` an Jellyfin und verlangt bei einem Transcode
einen **neuen Stream**. Apples eingebauter Spurwähler zeigt dagegen die
Auswahlgruppen des **laufenden** Streams — beim Transcode genau eine. Er
ist die richtige Oberfläche für die falsche Liste. Unsere Menüs sitzen
deshalb über `transportBarCustomMenuItems` daneben; `customInfoViewControllers`
wäre falsch, denn die Tonspur ist ein Bedienelement der Wiedergabe und kein
Begleitmaterial.

**Der Neuaufbau wird angesagt, nicht erklärt.** Jeder Eintrag, der Sekunden
mit schwarzem Bild kostet, trägt das als Untertitel — vorher, nicht
hinterher. Wer drückt, sieht den Haken sofort wandern, weil das Menü sich
schliesst und darin kein Platz für einen Kreisel ist. Das schwarze Bild
deckt eine Überlagerung in `contentOverlayView` zu, die hinter den
Bedienelementen liegt und keinen Fokus nimmt — `customOverlayViewController`
täte beides nicht und machte die Fernbedienung währenddessen tot. Und
solange umgebaut wird, sind alle Einträge gesperrt: sonst räumt `restart()`
eine Engine ab, die eine andere gerade baut.

**Die Regel dahinter ist jetzt prüfbar.** „Wann kostet ein Spurwechsel einen
Neuaufbau" lag bisher mitten im Vollzug von `selectAudioStream` und liess
sich nur an einem echten Server mit mehreren Tonspuren auslösen. Als
`TrackMenu` steht sie neben den übrigen Entscheidungsregeln, mit sieben
Tests — darunter der Fall, auf den der Kommentar dort seit jeher hinweist:
stimmt die Spurzahl nicht überein, ist die Zuordnung über die Reihenfolge
falsch, und es muss neu aufgebaut werden.

**Zwei stille Fehler nebenbei.** Die Tonsitzung stand hinter `#if os(iOS)`
und wäre auf tvOS nie gesetzt worden — verfügbar ist sie dort seit 9.0, man
hätte es nur daran gemerkt, dass sich die Wiedergabe gegen anderen Ton
nicht durchsetzt. Und `PlayerModel.downloads` ist jetzt optional statt
eines leeren Koordinators: ein leerer bräuchte einen `ModelContainer`, und
der ist das Einzige, wofür diese App SwiftData benutzt.

**Belegt statt vermutet.** Im Simulator lief die Wiedergabe gegen die
Attrappe, und die Titelzeile zeigte „Unbekannt". Statt an AVKit zu drehen,
hat ein Protokolleintrag die Frage beantwortet: `externalMetadata` wird
gesetzt, der Wert stimmt, und „Unbekannt" ist wörtlich das, was die
Attrappe für unbekannte Kennungen liefert. Geblieben ist davon nur die
Erkenntnis, dass die Beschriftung auf das Item warten muss — beim
Austausch des Players gibt es noch keines.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Scarriffle
2026-09-29 19:55:02 +02:00
co-authored by Claude Opus 5
parent 87f23afe90
commit 12bfc9e530
17 changed files with 799 additions and 23 deletions
+10 -1
View File
@@ -13,6 +13,8 @@ struct TVLibraryView: View {
let libraryID: String
@Environment(FlixySession.self) private var session
@Environment(PlaybackCoordinator.self) private var playback
@Environment(QuickPlay.self) private var quickPlay
@State private var feed: LibraryFeed?
@FocusState private var fokus: String?
@@ -78,10 +80,17 @@ struct TVLibraryView: View {
),
progress: item.watchProgress
) {
// In Fassung eins führt die Karte zur Detailseite.
// **Über QuickPlay, nicht unmittelbar.** Steht im
// Raster eine Serie, hat die keine Fassungen; der
// direkte Weg schickte ihre eigene Kennung an den
// Player und scheiterte mit „keine abspielbare
// Datei". QuickPlay löst stattdessen die nächste
// ungesehene Folge auf.
//
// Ein Kontextmenü wie am Telefon gibt es hier
// nicht: langes Drücken ist auf der Fernbedienung
// keine verlässliche Geste.
quickPlay.start(item, backend: session.backend, coordinator: playback)
}
.focused($fokus, equals: item.id)
.onChange(of: fokus) { _, neu in
@@ -0,0 +1,199 @@
import AVKit
import UIKit
import FlixyPlayback
import MediaKit
/// Führt Apples Player — und hält ihn über einen Neuaufbau hinweg am Leben.
///
/// **Das Problem, um das es hier geht.** Unsere Ton- und Untertitelwahl geht
/// als `audioStreamIndex` an Jellyfin und verlangt bei einem Transcode einen
/// **neuen Stream**. Apples eingebauter Spurwähler zeigt dagegen die
/// `AVMediaSelectionGroup`s des **laufenden** Streams — beim Transcode genau
/// eine. Er ist also die richtige Oberfläche für die falsche Liste.
///
/// Deshalb bekommt die Transportleiste unsere eigenen Menüs über
/// `transportBarCustomMenuItems`. Nicht `customInfoViewControllers`: die Wahl
/// der Tonspur ist ein Bedienelement der Wiedergabe, kein Begleitmaterial —
/// Apples eigene Beispiele dafür sind Bonusinhalte und Verwandtes, und dort
/// erwartet niemand „Sprache".
@MainActor
final class TVPlayerCoordinator: NSObject, @MainActor AVPlayerViewControllerDelegate {
let controller = AVPlayerViewController()
private let onDismiss: () -> Void
private var letzteAufnahme: TVPlayerSnapshot?
/// Wacht darüber, wann es etwas zu beschriften gibt.
///
/// **Nicht beim Austausch des Players.** In dem Moment ist `currentItem`
/// noch `nil` — das Item entsteht erst, wenn das Asset geladen ist, und
/// bis dahin zeigt Apples Titelzeile, was es selbst aus der Datei liest:
/// „Unbekannt". Also wird gewartet, bis das Item wirklich da ist.
private var itemBeobachter: NSKeyValueObservation?
/// Was drinstehen soll, sobald es ein Item gibt.
private var beschriftung: (titel: String, untertitel: String?)?
/// Die Abdeckung für das schwarze Bild während eines Neuaufbaus.
private lazy var abdeckung = TVRebuildOverlay()
private var abdeckungsAufgabe: Task<Void, Never>?
init(onDismiss: @escaping () -> Void) {
self.onDismiss = onDismiss
super.init()
controller.delegate = self
controller.videoGravity = .resizeAspect
// Nie auf dem Fernseher — ein Apple TV hat kein zweites Fenster.
controller.allowsPictureInPicturePlayback = false
controller.transportBarIncludesTitleView = true
// **Hinter den Bedienelementen und ohne Fokus.** `contentOverlayView`
// liegt über dem Bild, aber unter Apples Leiste, und nimmt keine
// Eingaben an. `customOverlayViewController` täte beides nicht: der
// ersetzt die ganze Überlagerung und zieht den Fokus an sich — damit
// wäre die Fernbedienung während des Umschaltens tot.
if let ebene = controller.contentOverlayView {
abdeckung.translatesAutoresizingMaskIntoConstraints = false
ebene.addSubview(abdeckung)
NSLayoutConstraint.activate([
abdeckung.topAnchor.constraint(equalTo: ebene.topAnchor),
abdeckung.bottomAnchor.constraint(equalTo: ebene.bottomAnchor),
abdeckung.leadingAnchor.constraint(equalTo: ebene.leadingAnchor),
abdeckung.trailingAnchor.constraint(equalTo: ebene.trailingAnchor),
])
}
}
// MARK: - Nachführen
func apply(_ aufnahme: TVPlayerSnapshot, model: PlayerModel) {
defer { letzteAufnahme = aufnahme }
// **Den Player nur austauschen, wenn es ein anderer ist.** `restart()`
// baut eine neue Engine mit einem neuen `AVPlayer`; genau dann — und
// nur dann — wird das Bild schwarz.
if aufnahme.playerIdentity != letzteAufnahme?.playerIdentity {
controller.player = model.systemPlayer
beobachteItem()
}
beschriftung = (aufnahme.title, aufnahme.subtitle)
beschrifte()
zeigeAbdeckung(aufnahme.isRebuilding)
controller.transportBarCustomMenuItems = TVTrackMenuBuilder.items(
for: aufnahme,
onAudio: { [weak model] index in
guard let model, let stream = model.audioStreams.first(where: { $0.index == index })
else { return }
Task { await model.selectAudioStream(stream) }
},
onSubtitle: { [weak model] index in
guard let model else { return }
let stream = index.flatMap { i in
model.subtitleStreams.first { $0.index == i }
}
Task { await model.selectSubtitleStream(stream) }
}
)
controller.contextualActions = TVTrackMenuBuilder.contextualActions(
for: aufnahme,
onSkip: { [weak model] in model?.skipActiveMarker() }
)
}
private func beobachteItem() {
itemBeobachter = controller.player?.observe(\.currentItem, options: [.initial, .new]) {
[weak self] _, _ in
MainActor.assumeIsolated { self?.beschrifte() }
}
}
/// Titel und Untertitel in Apples Titelzeile.
///
/// Über `externalMetadata` am `AVPlayerItem`, weil die Transportleiste
/// genau dort nachsieht. Auf iOS zeichnet unsere eigene Kopfzeile das;
/// hier gäbe es sonst gar keine Auskunft darüber, was läuft — ausser dem,
/// was AVKit selbst aus der Datei liest, und das ist bei einem
/// Transcode-Stream „Unbekannt".
private func beschrifte() {
guard let item = controller.player?.currentItem,
let beschriftung
else { return }
var einträge: [AVMetadataItem] = [eintrag(.commonIdentifierTitle, beschriftung.titel)]
if let untertitel = beschriftung.untertitel {
einträge.append(eintrag(.iTunesMetadataTrackSubTitle, untertitel))
}
item.externalMetadata = einträge
}
private func eintrag(_ kennung: AVMetadataIdentifier, _ wert: String) -> AVMetadataItem {
let eintrag = AVMutableMetadataItem()
eintrag.identifier = kennung
eintrag.value = wert as NSString
eintrag.extendedLanguageTag = "und"
return eintrag
}
/// Blendet die Abdeckung ein — aber erst nach einer Viertelsekunde.
///
/// Der häufige Fall (unverändert gespielt, unter fünfzig Millisekunden)
/// soll nicht aufblitzen. Wer nur umschaltet, sieht dann gar nichts.
private func zeigeAbdeckung(_ sichtbar: Bool) {
abdeckungsAufgabe?.cancel()
guard sichtbar else {
abdeckung.setVisible(false)
return
}
abdeckungsAufgabe = Task { [weak self] in
try? await Task.sleep(for: .milliseconds(250))
guard !Task.isCancelled else { return }
self?.abdeckung.setVisible(true)
}
}
// MARK: - Der Menü-Knopf der Fernbedienung
/// Fängt den Menü-Knopf ab, statt in SwiftUI `onExitCommand` zu raten.
func playerViewControllerShouldDismiss(_ controller: AVPlayerViewController) -> Bool {
onDismiss()
return true
}
}
/// Die Abdeckung, die das schwarze Bild während eines Neuaufbaus zudeckt.
///
/// Ohne sie sieht man Sekunden lang nichts und hält es für einen Absturz —
/// dabei ist es die angekündigte Folge einer Spurwahl.
@MainActor
final class TVRebuildOverlay: UIView {
private let kreisel = UIActivityIndicatorView(style: .large)
private let zeile = UILabel()
override init(frame: CGRect) {
super.init(frame: frame)
backgroundColor = UIColor.black.withAlphaComponent(0.75)
isUserInteractionEnabled = false
alpha = 0
kreisel.color = .white
kreisel.startAnimating()
zeile.text = String(localized: "player.rebuilding")
zeile.textColor = .white
zeile.font = .preferredFont(forTextStyle: .headline)
let stapel = UIStackView(arrangedSubviews: [kreisel, zeile])
stapel.axis = .vertical
stapel.alignment = .center
stapel.spacing = 24
stapel.translatesAutoresizingMaskIntoConstraints = false
addSubview(stapel)
NSLayoutConstraint.activate([
stapel.centerXAnchor.constraint(equalTo: centerXAnchor),
stapel.centerYAnchor.constraint(equalTo: centerYAnchor),
])
}
@available(*, unavailable)
required init?(coder: NSCoder) { fatalError("nicht aus einem Storyboard") }
func setVisible(_ sichtbar: Bool) {
UIView.animate(withDuration: 0.2) { self.alpha = sichtbar ? 1 : 0 }
}
}
+79
View File
@@ -0,0 +1,79 @@
import AVKit
import SwiftUI
import FlixyPlayback
import MediaKit
/// Hängt Apples Player in den SwiftUI-Baum.
///
/// **Wem was gehört.** Der `AVPlayerViewController` gehört dem Coordinator,
/// nicht der SwiftUI-Struktur — die wird bei jedem Neuzeichnen neu gebaut —
/// und nicht dem `PlayerModel`, das frei von UIKit bleiben soll. Das Modell
/// gibt nur seinen `AVPlayer` heraus, und das ist AVFoundation.
@MainActor
struct TVPlayerHost: UIViewControllerRepresentable {
let model: PlayerModel
/// Eine Momentaufnahme dessen, was den Controller betrifft.
///
/// **Als Wert, nicht als Verweis.** SwiftUI ruft `updateUIViewController`
/// nur, wenn sich am Repräsentanten etwas geändert hat. Stünde hier allein
/// das Modell, änderte sich nie etwas: es ist eine Klasse, und ihre
/// Kennung bleibt über jeden Spurwechsel hinweg dieselbe. Der Wert wird im
/// Rumpf der umgebenden Ansicht gebildet — dort und nur dort entsteht die
/// Beobachtungsbeziehung zu `@Observable`.
let snapshot: TVPlayerSnapshot
let onDismiss: () -> Void
func makeUIViewController(context: Context) -> AVPlayerViewController {
context.coordinator.controller
}
func updateUIViewController(_ controller: AVPlayerViewController, context: Context) {
context.coordinator.apply(snapshot, model: model)
}
func makeCoordinator() -> TVPlayerCoordinator {
TVPlayerCoordinator(onDismiss: onDismiss)
}
}
/// Was der Controller von der Wiedergabe wissen muss — und mehr nicht.
struct TVPlayerSnapshot: Equatable {
/// Wechselt bei jedem Neuaufbau. Daran hängt der Austausch des Players.
let playerIdentity: ObjectIdentifier?
let audio: [TrackMenu.Entry]
let subtitles: [TrackMenu.Entry]
/// Läuft gerade ein Neuaufbau? Dann ist das Bild schwarz und das Menü
/// gesperrt.
let isRebuilding: Bool
let title: String
let subtitle: String?
/// Der Zeitbereich einer Marke — für „Intro überspringen".
let markerLabel: String?
/// `@MainActor`, weil das Modell es ist: gelesen wird hier zwölfmal aus
/// ihm, und zwar im Rumpf einer View — also ohnehin auf dem Hauptakteur.
@MainActor
init(_ model: PlayerModel, offLabel: String) {
playerIdentity = model.systemPlayer.map(ObjectIdentifier.init)
let direkt: Bool = if case .directPlay = model.decision?.method { true } else { false }
audio = TrackMenu.audio(
from: model.audioStreams,
selected: model.selectedAudioStream,
isDirectPlay: direkt,
playerTrackCount: model.audioTracks.count
)
subtitles = TrackMenu.subtitles(
from: model.subtitleStreams,
selected: model.selectedSubtitleStream,
isDirectPlay: direkt,
playerTrackLanguages: model.subtitleTracks.map(\.languageCode),
offLabel: offLabel
)
isRebuilding = model.isChangingQuality
title = model.title
subtitle = model.subtitle
markerLabel = model.activeMarker.map {
String(localized: $0.isIntro ? "player.skipIntro" : "player.skipCredits")
}
}
}
+70
View File
@@ -0,0 +1,70 @@
import SwiftUI
import FlixyDesign
import FlixyPlayback
import MediaKit
/// Der Player auf dem Fernseher.
///
/// **Das Modell lebt hier und stirbt hier.** Auf dem Telefon hält `RootView`
/// es fest, damit die Wiedergabe den Wechsel zwischen Kachel und Vollbild
/// überlebt. Ohne Mini-Player gibt es diesen Wechsel nicht, und ein
/// hochgehaltenes Modell hielte nur eine tote Engine, einen laufenden
/// Transcoder und eine offene Jellyfin-Sitzung am Leben, nachdem der Player
/// längst weg ist.
struct TVPlayerScreen: View {
let request: PlaybackRequest
@Environment(FlixySession.self) private var session
@Environment(PlaybackCoordinator.self) private var playback
@Environment(PlaybackSettings.self) private var settings
@Environment(LanguagePreferences.self) private var languages
@Environment(SubtitleAppearance.self) private var subtitleAppearance
@Environment(NetworkConditions.self) private var network
@Environment(PlaybackDiagnostics.self) private var diagnostics
@State private var model: PlayerModel?
var body: some View {
ZStack {
Color.black.ignoresSafeArea()
if let model {
// **Die Momentaufnahme entsteht hier, im Rumpf einer View.**
// Nur so entsteht die Beobachtungsbeziehung zu `@Observable`
// — ein Repräsentant, der bloss das Modell hält, bekäme nie
// ein `updateUIViewController`.
TVPlayerHost(
model: model,
snapshot: TVPlayerSnapshot(model, offLabel: String(localized: "player.subtitlesOff")),
onDismiss: { playback.close() }
)
.ignoresSafeArea()
} else {
ProgressView()
}
}
.task {
guard model == nil else { return }
let frisch = PlayerModel(
request: request,
backend: session.backend,
liveTV: nil, // Kein Live-TV in Fassung eins.
downloads: nil, // Nie auf dem Fernseher.
diagnostics: diagnostics,
policy: settings.policy(for: network),
settings: settings,
languages: languages,
subtitles: subtitleAppearance,
isLocalConnection: session.isLocalConnection,
connectionDescription: session.connectionDescription,
unavailableMessage: session.playbackUnavailableMessage
)
model = frisch
await frisch.start()
}
// Beim Verschwinden wirklich Schluss: Engine abräumen, Fortschritt
// melden, die Jellyfin-Sitzung schliessen. Ohne das liefe der
// Transcoder auf dem Server weiter, obwohl niemand mehr zusieht.
.onDisappear { [model] in Task { await model?.stop() } }
}
}
@@ -0,0 +1,85 @@
import AVKit
import UIKit
import FlixyPlayback
/// Baut aus unseren Spurlisten die Menüs für Apples Transportleiste.
///
/// Die reine Abbildung steht in `TrackMenu` und ist dort geprüft; hier geht es
/// nur noch um UIKit.
@MainActor
enum TVTrackMenuBuilder {
static func items(
for aufnahme: TVPlayerSnapshot,
onAudio: @escaping (Int?) -> Void,
onSubtitle: @escaping (Int?) -> Void
) -> [UIMenuElement] {
var menüs: [UIMenuElement] = []
if aufnahme.audio.count > 1 {
menüs.append(menü(
titel: String(localized: "player.audioTracks"),
symbol: "waveform",
einträge: aufnahme.audio,
gesperrt: aufnahme.isRebuilding,
aktion: onAudio
))
}
if aufnahme.subtitles.count > 1 {
menüs.append(menü(
titel: String(localized: "player.subtitleTracks"),
symbol: "captions.bubble",
einträge: aufnahme.subtitles,
gesperrt: aufnahme.isRebuilding,
aktion: onSubtitle
))
}
return menüs
}
private static func menü(
titel: String,
symbol: String,
einträge: [TrackMenu.Entry],
gesperrt: Bool,
aktion: @escaping (Int?) -> Void
) -> UIMenu {
UIMenu(
title: titel,
image: UIImage(systemName: symbol),
options: [.singleSelection],
children: einträge.map { eintrag in
UIAction(
title: eintrag.title,
// **Vorher ansagen, nicht hinterher erklären.** Steht hier
// nichts, ist die Sekundenpause danach eine Panne; steht
// es hier, ist sie eine angekündigte Folge. Das ist der
// billigste Teil dieser ganzen Sache und der wirksamste.
subtitle: eintrag.rebuilds
? String(localized: "player.rebuilds")
: nil,
// **Keine zweite Bestellung, solange die erste läuft.**
// Sonst räumt `restart()` eine Engine ab, die eine andere
// gerade baut.
attributes: gesperrt ? [.disabled] : [],
state: eintrag.isSelected ? .on : .off
) { auslöser in
// **Sofort quittieren.** Das Menü schliesst sich beim
// Drücken, und darin ist kein Platz für einen Kreisel.
// Der Haken wandert, bevor sich am Bild etwas tut.
auslöser.state = .on
aktion(eintrag.id)
}
}
)
}
/// „Intro überspringen" unten rechts, solange eine Marke läuft.
///
/// Die tvOS-Entsprechung zu dem Knopf, den der iOS-Player selbst zeichnet.
static func contextualActions(
for aufnahme: TVPlayerSnapshot,
onSkip: @escaping () -> Void
) -> [UIAction] {
guard let beschriftung = aufnahme.markerLabel else { return [] }
return [UIAction(title: beschriftung) { _ in onSkip() }]
}
}
+15
View File
@@ -11,6 +11,7 @@ import FlixyDesign
/// in derselben Datei.
struct TVRootView: View {
@Environment(FlixySession.self) private var session
@Environment(PlaybackCoordinator.self) private var playback
var body: some View {
ZStack {
@@ -38,6 +39,20 @@ struct TVRootView: View {
}
}
.task { await session.restore() }
// **Hier und nicht in der Startseite.** Von einer Kachel, aus dem
// Aufmacher und aus der Detailseite wird dasselbe gestartet; läge der
// Übergang weiter innen, gäbe es ihn dreimal.
//
// `fullScreenCover(item:)` gibt es auf tvOS seit 14, und
// `PlaybackRequest` ist bereits `Identifiable`.
.fullScreenCover(
item: Binding(
get: { playback.request },
set: { if $0 == nil { playback.close() } }
)
) { request in
TVPlayerScreen(request: request)
}
}
private func verbinden(mit name: String) -> some View {