Phase 0: Projektgerüst, Design-Tokens und Navigation

Legt das Fundament für den Plex-Client an: - XcodeGen-Projekt nach dem Muster von Onyx (com.scarriffleservices, strict concurrency, Projektdatei nicht eingecheckt) - FlixyKit mit vier Modulen: PlexKit, FlixyDesign, FlixyPlayback, FlixyDownloads. macOS steht als Plattform mit drin, damit die Logik-Tests ohne Simulator laufen. - FlixyDesign: dunkle Farb-Tokens, Schriftskala, Poster- und Querformat-Kacheln, Aufmacher-Bild. Die Akzentfarbe fließt über die Umgebung und wird per WCAG-Rechnung lesbar gehalten. - PlexKit: Kopfzeilen-Identität, Transport-Protokoll, Fehlerarten und die Medienmodelle samt nachsichtigem Decoder. - FlixyPlayback: VideoPlayerEngine-Protokoll und PlaybackDecider — die eine Funktion, an der Phase 2 das Transcoding andockt. - Ausfahrbare Seitenleiste auf dem iPhone, Split-View auf dem iPad. - 45 Tests, alle grün. VLCKit 4.0.0-a24 ist vorab geprüft: baut über SPM unter Swift 6 mit strict concurrency. Die iOS-Slice ist mit 239 MB allerdings gewichtig, deshalb bekommt sie in Phase 1 ein eigenes Target. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-11 16:04:40 +02:00
commit 1ed64bf166
54 changed files with 3584 additions and 0 deletions
@@ -0,0 +1,71 @@
+import Foundation
+import PlexKit
+
+/// Eine wählbare Ton- oder Untertitelspur.
+///
+/// Bewusst getrennt von `PlexStream`: VLCKit und AVPlayer nummerieren ihre
+/// Spuren selbst, und die Nummern stimmen nicht mit denen von Plex überein.
+/// `engineIdentifier` hält deshalb fest, wie der jeweilige Motor die Spur
+/// nennt, während `plexStreamID` für den Server gedacht ist.
+public struct MediaTrack: Sendable, Equatable, Identifiable {
+    public enum Kind: Sendable, Equatable { case audio, subtitle }
+
+    public let id: String
+    public let kind: Kind
+    public let displayName: String
+    public let languageCode: String?
+    public let plexStreamID: Int?
+    /// Die Nummer, unter der der laufende Motor die Spur führt.
+    public let engineIdentifier: Int?
+    public let isForced: Bool
+
+    public init(
+        id: String,
+        kind: Kind,
+        displayName: String,
+        languageCode: String? = nil,
+        plexStreamID: Int? = nil,
+        engineIdentifier: Int? = nil,
+        isForced: Bool = false
+    ) {
+        self.id = id
+        self.kind = kind
+        self.displayName = displayName
+        self.languageCode = languageCode
+        self.plexStreamID = plexStreamID
+        self.engineIdentifier = engineIdentifier
+        self.isForced = isForced
+    }
+}
+
+extension MediaTrack {
+    /// Baut eine Spur aus dem, was Plex gemeldet hat.
+    ///
+    /// `displayTitle` ist das, was Plex selbst in seinen Oberflächen zeigt
+    /// (etwa „Deutsch (AC3 5.1)"). Fehlt es, wird aus Sprache und Codec etwas
+    /// Brauchbares gebaut, statt „Spur 3" anzuzeigen.
+    public init?(stream: PlexStream) {
+        guard let kind = stream.kind else { return nil }
+        let trackKind: Kind
+        switch kind {
+        case .audio: trackKind = .audio
+        case .subtitle: trackKind = .subtitle
+        case .video: return nil
+        }
+
+        let name = stream.displayTitle
+            ?? stream.title
+            ?? [stream.language, stream.codec?.uppercased()]
+                .compactMap(\.self)
+                .joined(separator: " · ")
+
+        self.init(
+            id: "plex-\(stream.id)",
+            kind: trackKind,
+            displayName: name.isEmpty ? "—" : name,
+            languageCode: stream.languageCode,
+            plexStreamID: stream.id,
+            isForced: stream.isForced
+        )
+    }
+}
@@ -0,0 +1,46 @@
+import Foundation
+
+/// Der Zustand der Wiedergabe, unabhängig vom Motor.
+public enum PlaybackState: Sendable, Equatable {
+    case idle
+    /// Quelle wird geöffnet, es ist noch nichts zu sehen.
+    case loading
+    case playing
+    case paused
+    /// Läuft eigentlich, wartet aber auf Daten.
+    case buffering
+    case ended
+    case failed(PlaybackFailure)
+
+    public var isActive: Bool {
+        switch self {
+        case .playing, .buffering: true
+        case .idle, .loading, .paused, .ended, .failed: false
+        }
+    }
+}
+
+/// Ein Fehler bei der Wiedergabe, in der Sprache der App statt in der des
+/// jeweiligen Motors.
+public struct PlaybackFailure: Sendable, Equatable, Error {
+    public enum Kind: Sendable, Equatable {
+        /// Die Quelle war nicht erreichbar.
+        case sourceUnavailable
+        /// Der Motor kann das Format nicht — sollte nach einer korrekten
+        /// Entscheidung nicht vorkommen und ist deshalb ein Hinweis darauf,
+        /// dass die Fähigkeitenliste nachgezogen werden muss.
+        case formatUnsupported
+        case networkInterrupted
+        case unknown
+    }
+
+    public let kind: Kind
+    /// Der ursprüngliche Fehlertext. Wandert nicht in die Oberfläche, aber in
+    /// die Protokolle — sonst ist „geht nicht" alles, was man hat.
+    public let underlyingDescription: String?
+
+    public init(kind: Kind, underlyingDescription: String? = nil) {
+        self.kind = kind
+        self.underlyingDescription = underlyingDescription
+    }
+}
@@ -0,0 +1,72 @@
+import Foundation
+
+/// Woher das Bild kommt.
+public struct PlaybackSource: Sendable, Equatable {
+    public enum Origin: Sendable, Equatable {
+        /// Vom Server — per DirectPlay oder als HLS-Strom des Transcoders.
+        case remote
+        /// Aus dem Download-Ordner.
+        case local
+    }
+
+    public let url: URL
+    public let origin: Origin
+    /// Ab wo gestartet werden soll. Kommt aus dem zuletzt gemeldeten
+    /// Fortschritt; `.zero` heißt von vorn.
+    public let startTime: Duration
+
+    public init(url: URL, origin: Origin, startTime: Duration = .zero) {
+        self.url = url
+        self.origin = origin
+        self.startTime = startTime
+    }
+}
+
+/// Was ein Motor von sich aus meldet.
+///
+/// Ein Strom statt beobachtbarer Eigenschaften: AVPlayer meldet über KVO,
+/// VLCKit über Delegat-Rückrufe. Beide in dieselbe Ereignisfolge zu
+/// übersetzen hält den Unterschied an genau einer Stelle je Motor — statt in
+/// jeder View, die den Zustand anzeigt.
+public enum PlaybackEvent: Sendable, Equatable {
+    case stateChanged(PlaybackState)
+    case timeChanged(Duration)
+    case durationResolved(Duration)
+    case tracksResolved(audio: [MediaTrack], subtitle: [MediaTrack])
+    case reachedEnd
+}
+
+/// Der gemeinsame Nenner von AVPlayer und VLCKit.
+///
+/// Alles, was die Oberfläche zum Steuern braucht — und nichts darüber hinaus.
+/// Was hier nicht steht, gibt es für die Views nicht; dadurch bleibt der
+/// Austausch des Motors unsichtbar.
+@MainActor
+public protocol VideoPlayerEngine: AnyObject {
+    var events: AsyncStream<PlaybackEvent> { get }
+
+    var state: PlaybackState { get }
+    var currentTime: Duration { get }
+    var duration: Duration? { get }
+
+    /// Ob dieser Motor Bild-in-Bild kann. Steuert, ob der Knopf überhaupt
+    /// erscheint — ein Knopf, der bei manchen Dateien nichts tut, ist
+    /// schlimmer als keiner.
+    var supportsPictureInPicture: Bool { get }
+
+    func load(_ source: PlaybackSource) async throws(PlaybackFailure)
+    func play()
+    func pause()
+    func seek(to time: Duration) async
+    func setRate(_ rate: Double)
+
+    var audioTracks: [MediaTrack] { get }
+    var subtitleTracks: [MediaTrack] { get }
+    func selectAudioTrack(_ track: MediaTrack?)
+    /// `nil` schaltet die Untertitel ab.
+    func selectSubtitleTrack(_ track: MediaTrack?)
+
+    /// Gibt Puffer und Dekoder frei. Muss beim Verlassen des Players laufen,
+    /// sonst behält besonders VLCKit den Speicher.
+    func teardown()
+}