feat(cli): standalone aetherctl harness for offline HLSVideoEngine repro

Adds a small executable target that wraps `HLSVideoEngine` so we can
reproduce the host-side AVPlayer hang against a real source on macOS
without round-tripping through TestFlight + Apple TV. Argument is a
file:// or http(s):// source the engine demuxes; once it parks on a
loopback URL we can poke at the manifests + segments with curl,
mediastreamvalidator, mp4dump, ffprobe, or just `open` the URL in
QuickTime / macOS AVPlayer to see whether the desktop player
reproduces the same waitingToPlay-with-no-TCP behaviour.

`HLSVideoEngine`, its error enum, and `init` / `start` / `stop` are
now `public` so the CLI can drive them directly. No behaviour change
on existing call sites; the host's `AetherEngine.startNativeVideo
Session` still wraps them the same way.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: superuser404notfound

Package.swift

@@ -14,6 +14,11 @@ let package = Package(
             name: "AetherEngine",
             targets: ["AetherEngine"]
         ),
+        // Standalone CLI used for offline reproduction of the host-side
+        // HLSVideoEngine playback symptoms on macOS, without going
+        // through TestFlight + Apple TV. Builds only on macOS in
+        // practice (Apple platform reqs match the lib target).
+        .executable(name: "aetherctl", targets: ["aetherctl"]),
     ],
     dependencies: [
         // Minimal FFmpeg build (avcodec, avformat, avutil, swresample only).
@@ -36,5 +41,10 @@ let package = Package(
                 .linkedFramework("AudioToolbox"),
             ]
         ),
+        .executableTarget(
+            name: "aetherctl",
+            dependencies: ["AetherEngine"],
+            path: "Sources/aetherctl"
+        ),
     ]
 )

Sources/AetherEngine/Video/HLSVideoEngine.swift

@@ -19,11 +19,11 @@ import Libavutil
 /// Phase 4 of the rollout: video-only fragments. Audio routing into
 /// the same fMP4 stream lands in phase 6. AVPlayer will play silent
 /// video for now, which is enough to verify the DV signalling path.
-final class HLSVideoEngine: @unchecked Sendable {
+public final class HLSVideoEngine: @unchecked Sendable {
 
     // MARK: - Errors
 
-    enum HLSVideoEngineError: Error, CustomStringConvertible, LocalizedError {
+    public enum HLSVideoEngineError: Error, CustomStringConvertible, LocalizedError {
         case openFailed(reason: String)
         case noVideoStream
         case unsupportedCodec(rawCodecID: UInt32)
@@ -33,7 +33,7 @@ final class HLSVideoEngine: @unchecked Sendable {
         case alreadyStarted
         case notStarted
 
-        var description: String {
+        public var description: String {
             switch self {
             case .openFailed(let r):     return "HLSVideoEngine: open failed (\(r))"
             case .noVideoStream:         return "HLSVideoEngine: source has no video stream"
@@ -46,7 +46,7 @@ final class HLSVideoEngine: @unchecked Sendable {
             }
         }
 
-        var errorDescription: String? { description }
+        public var errorDescription: String? { description }
     }
 
     /// DV profile + base-layer compatibility classification per the
@@ -115,15 +115,15 @@ final class HLSVideoEngine: @unchecked Sendable {
     /// authoring recommendation.
     private static let targetSegmentDuration: Double = 6.0
 
-    init(url: URL) {
+    public init(url: URL) {
         self.sourceURL = url
     }
 
     // MARK: - Public API
 
     /// Open the source, build the segment plan, start the server,
     /// return the URL the host hands to AVPlayer.
-    func start() throws -> URL {
+    public func start() throws -> URL {
         guard demuxer == nil else { throw HLSVideoEngineError.alreadyStarted }
 
         // 1. Open the source. Reuses AetherEngine's existing AVIO +
@@ -389,7 +389,7 @@ final class HLSVideoEngine: @unchecked Sendable {
         return url
     }
 
-    func stop() {
+    public func stop() {
         server?.stop()
         server = nil
         provider?.close()

Sources/aetherctl/main.swift

@@ -0,0 +1,86 @@
+// aetherctl: standalone reproduction harness for HLSVideoEngine on macOS.
+//
+// Spins up the same engine the tvOS app uses, against any source URL
+// (file:// or http(s)://), and parks the loopback HLS-fMP4 server in
+// the foreground so curl / mediastreamvalidator / mp4dump / ffprobe
+// can poke at the manifests + segments without an Apple TV in the
+// loop. The build-122 spinner-and-back symptom on tvOS isn't
+// reproducible from the device side without TestFlight cycles; this
+// CLI lets us iterate locally.
+
+import Foundation
+import AetherEngine
+
+let args = CommandLine.arguments
+guard args.count >= 2 else {
+    print("usage: aetherctl <url>")
+    print("")
+    print("  url: file:// or http(s):// to a video source the engine demuxes")
+    print("       (typically a Dolby Vision MKV, same kind of source the")
+    print("       tvOS app's `.native` route would feed to AVPlayer).")
+    print("")
+    print("Once the engine is running it prints the loopback URL it served.")
+    print("Useful next steps from another terminal:")
+    print("  curl -i  http://127.0.0.1:<port>/master.m3u8")
+    print("  curl -o  /tmp/init.mp4   http://127.0.0.1:<port>/init.mp4")
+    print("  curl -o  /tmp/seg0.mp4   http://127.0.0.1:<port>/seg0.mp4")
+    print("  mediastreamvalidator http://127.0.0.1:<port>/master.m3u8")
+    print("  mp4dump --verbosity 1 /tmp/init.mp4")
+    print("  ffprobe -v debug /tmp/seg0.mp4")
+    print("  open 'http://127.0.0.1:<port>/master.m3u8'   # macOS QuickTime")
+    print("")
+    exit(64)
+}
+
+let raw = args[1]
+let sourceURL: URL = {
+    if let parsed = URL(string: raw), parsed.scheme != nil {
+        return parsed
+    }
+    return URL(fileURLWithPath: raw)
+}()
+
+// Mirror what the tvOS app does: route every engine log to stdout
+// instead of into a host overlay buffer, so the CLI session reads
+// linearly.
+EngineLog.handler = { line in
+    let timestamp = ISO8601DateFormatter.string(from: Date(),
+                                                timeZone: .current,
+                                                formatOptions: [.withTime, .withFractionalSeconds])
+    print("[\(timestamp)] \(line)")
+}
+
+print("aetherctl: opening \(sourceURL.absoluteString)")
+print("")
+
+let engine = HLSVideoEngine(url: sourceURL)
+let playbackURL: URL
+do {
+    playbackURL = try engine.start()
+} catch {
+    print("ERROR: \(error)")
+    exit(1)
+}
+
+print("")
+print("=== PLAYBACK URL ===")
+print(playbackURL.absoluteString)
+print("====================")
+print("")
+print("Engine is parked. Hit Ctrl-C to tear down.")
+print("")
+
+// Trap SIGINT to clean up so the next run can rebind the same
+// (ephemeral) port if needed and so the demuxer's HTTP session
+// doesn't leak.
+signal(SIGINT, SIG_IGN)
+let sigintSource = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+sigintSource.setEventHandler {
+    print("")
+    print("aetherctl: SIGINT, stopping engine")
+    engine.stop()
+    exit(0)
+}
+sigintSource.resume()
+
+RunLoop.main.run()