AetherEngine

https://github.com/superuser404notfound/aetherengine
Admin
AetherEngine is a media player engine for Apple platforms that handles complex media formats (HDR,...
Tokens:59,988
Snippets:765
Trust Score:5.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start playback

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Initiates playback from the current position.

```swift
public func play()
```

--------------------------------

### Initialize and Load AetherEngine

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Demonstrates engine instantiation, view binding for UIKit/AppKit or SwiftUI, and starting media playback.

```swift
import AetherEngine

// Create engine
let engine = try AetherEngine()

// Bind to view (UIKit/AppKit)
let view = AetherPlayerView()
engine.bind(view: view)

// Or SwiftUI
var body: some View { AetherPlayerSurface(engine: engine) }

// Load and play
try await engine.load(url: videoURL)
engine.play()
```

--------------------------------

### load(url:options:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Loads and starts playback from a specified URL.

```APIDOC
## load(url: options:) async throws

### Description
Load and start playback from a URL.

### Parameters
- **url** (URL) - Required - Media source URL (http, https, file, etc.)
- **options** (LoadOptions) - Optional - Load configuration (Default: LoadOptions())

### Throws
AetherEngineError.noVideoStream, .noAudioStream, etc.
```

--------------------------------

### play()

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Starts playback from the current position.

```APIDOC
## play()

### Description
Start playback from current position.

### Method
`public func play()`
```

--------------------------------

### Load media from URL

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Loads and starts playback from a specified URL with optional configuration.

```swift
public func load(url: URL, options: LoadOptions = LoadOptions()) async throws
```

--------------------------------

### installAudioTap()

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Installs a decoded-audio tap to capture mono Float32 48 kHz PCM audio data.

```APIDOC
## installAudioTap()

### Description
Installs a decoded-audio tap (mono Float32 48 kHz PCM) off the render path. Useful for live transcription or ShazamKit integration.

### Signature
`public func installAudioTap() -> AsyncStream<AudioTapBuffer>`

### Returns
- **AsyncStream<AudioTapBuffer>** - An asynchronous stream of audio buffers.
```

--------------------------------

### Configure Engine Loading Options

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Provides examples for setting language preferences, configuring live streams with DVR, and passing custom HTTP headers.

```swift
// Language preferences
try await engine.load(
    url: url,
    options: LoadOptions(
        preferredAudioLanguages: ["en", "de"],
        preferredSubtitleLanguages: ["en", "es"]
    )
)

// Live with DVR
try await engine.load(
    url: liveURL,
    options: LoadOptions(
        isLive: true,
        dvrWindowSeconds: 1800,
        liveJoinProfile: .fastZap  // For channel zapping
    )
)

// Custom HTTP headers (IPTV tokens)
try await engine.load(
    url: iptvURL,
    options: LoadOptions(
        httpHeaders: ["Authorization": "Bearer \(token)"]
    )
)
```

--------------------------------

### Initialize ExternalSubtitleTrack

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Examples of creating ExternalSubtitleTrack instances for local or container-based subtitle sources.

```swift
ExternalSubtitleTrack(url: srtURL, name: "English", language: "en")
ExternalSubtitleTrack(url: mkvURL, name: "Spanish", language: "es", sourceStreamIndex: 3)
```

--------------------------------

### Install via Swift Package Manager

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Add the AetherEngine dependency to your Package.swift file.

```swift
.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "6.25.1")
```

--------------------------------

### Install Audio Tap

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Installs a decoded-audio tap for live transcription or ShazamKit integration.

```swift
public func installAudioTap() -> AsyncStream<AudioTapBuffer>
```

--------------------------------

### Expected harness output

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Tests/Integration/README.md

Example output from the integration harness when successfully validating the master playlist.

```text
[harness] opening http://127.0.0.1:58494/master.m3u8  (timeout 30s)
[harness] AVPlayerItem.status = .readyToPlay
[harness] legible media-selection options: 1
[harness]   [0] displayName="Subtitle 1" lang=nil mediaType=sbtl
[harness] PASS: readyToPlay + 1 legible option(s) against the loopback master
```

--------------------------------

### engine.installAudioTap()

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Installs an audio tap to decode playback audio for live transcription or external processing. The stream provides Mono Float32 48 kHz audio with source-PTS timestamps.

```APIDOC
## engine.installAudioTap()

### Description
Decodes playback audio for live transcription or ShazamKit. The stream is decoupled from the playback display and supports loopback, remote HLS, and software paths.

### Usage
```swift
let audioStream = engine.installAudioTap()

Task {
    for await buffer in audioStream {
        let pcm = buffer.buffer
        let sourceTime = buffer.sourceTime
        let isGap = buffer.discontinuity
        // Process buffer...
    }
}

// Clean up
engine.removeAudioTap()
```
```

--------------------------------

### Implement Archive Reader

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Example implementation of IOReader for a custom ZipArchive source.

```swift
final class MyArchiveReader: IOReader {
    private let archive: ZipArchive
    private var position: Int64 = 0
    
    func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
        guard let buffer = buffer else { return -1 }
        let bytesRead = archive.read(into: buffer, count: Int(size), at: position)
        if bytesRead > 0 {
            position += Int64(bytesRead)
        }
        return Int32(bytesRead)
    }
    
    func seek(offset: Int64, whence: Int32) -> Int64 {
        let newPos: Int64
        switch whence {
        case 0: newPos = offset
        case 1: newPos = position + offset
        case 2: newPos = Int64(archive.totalSize) + offset
        case 65536: return Int64(archive.totalSize)
        default: return -1
        }
        guard newPos >= 0, newPos <= archive.totalSize else { return -1 }
        position = newPos
        return newPos
    }
    
    func close() {
        archive.close()
    }
    
    func makeIndependentReader() -> IOReader? {
        MyArchiveReader(archive: archive.makeCopy())
    }
    
    var discImageProbeEnabled: Bool { false }  // Not a disc image
}

// Load
let reader = MyArchiveReader(archive: myZip)
let probe = try await AetherEngine.probe(source: .custom(reader, formatHint: "mp4"))
try await engine.load(source: .custom(reader, formatHint: "mp4"))
```

--------------------------------

### Verify HLS stream with curl and media tools

Source: https://github.com/superuser404notfound/aetherengine/blob/main/docs/cli.md

Use these commands to interact with the local HLS server started by the serve command.

```bash
curl -i  http://127.0.0.1:<port>/master.m3u8
curl -o  /tmp/init.mp4   http://127.0.0.1:<port>/init.mp4
mediastreamvalidator http://127.0.0.1:<port>/master.m3u8
mp4dump --verbosity 1 /tmp/init.mp4
ffprobe -v debug /tmp/seg0.mp4
open 'http://127.0.0.1:<port>/master.m3u8'   # macOS QuickTime
```

--------------------------------

### Convert Source Time to Item Time

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Example of converting subtitle cue start times from the source axis to the item axis for AVPlayer-based compositing.

```swift
// Subtitle cues are on source axis; convert to item-axis for AVPlayer-based compositing
let itemTime = engine.presentationAxisMap.itemSeconds(forSourceSeconds: cue.startTime)
```

--------------------------------

### Run the integration harness

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Tests/Integration/README.md

Commands to build the CLI, serve the media file, and execute the AVPlayer integration check.

```bash
# 1. Build the CLI
swift build

# 2. Serve the file with the native subtitle rendition requested (parks; note the printed URL).
#    --native-subs N requests the native track; the engine now auto-attaches one cue store per
#    embedded text track inside start(), so the master advertises the SUBTITLES rendition.
.build/debug/aetherctl serve --native-subs 0 /tmp/embedded-subs.mkv
#    -> "=== PLAYBACK URL ===" prints e.g. http://127.0.0.1:58494/media.m3u8
#       The master is always at the same host:port, path /master.m3u8.

# 3. In another shell, point the harness at /master.m3u8 (NOT media.m3u8; the rendition lives
#    only in the master).
swift Tests/Integration/avplayer-open-check.swift http://127.0.0.1:<port>/master.m3u8 30

# 4. Ctrl-C the aetherctl process when done.
```

--------------------------------

### Configure Live Stream with DVR Window

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

Initialize LoadOptions with live streaming enabled and a 30-minute DVR buffer.

```swift
LoadOptions(isLive: true, dvrWindowSeconds: 1800)  // 30 min DVR
```

--------------------------------

### Initialize and Play Media in SwiftUI

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/00-START-HERE.md

Demonstrates how to instantiate the AetherEngine, load media with language options, and handle playback state changes using SwiftUI views.

```swift
import AetherEngine
import SwiftUI

let engine = try AetherEngine()

var body: some View {
    VStack {
        AetherPlayerSurface(engine: engine)
            .onAppear {
                Task {
                    try await engine.load(
                        url: videoURL,
                        options: LoadOptions(
                            preferredAudioLanguages: ["en", "de"],
                            preferredSubtitleLanguages: ["en"]
                        )
                    )
                    engine.play()
                }
            }
        
        VStack {
            ForEach(engine.subtitleTracks, id: \.id) { track in
                Button(track.name) {
                    engine.selectSubtitleTrack(index: track.id)
                }
            }
        }
    }
    .onReceive(engine.$playbackPhase) { phase in
        switch phase {
        case .playing: hideSpinner()
        case .loading, .seeking: showSpinner()
        case .error(let msg): showError(msg)
        default: break
        }
    }
}
```

--------------------------------

### init()

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Initializes a new instance of the AetherEngine.

```APIDOC
## init()

### Description
Creates a new AetherEngine instance. Throws if initialization fails.

### Signature
`public init() throws`
```

--------------------------------

### Initialize and Control AetherEngine

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Demonstrates engine initialization, UI binding for SwiftUI and UIKit/AppKit, media loading options, and playback control methods.

```swift
import AetherEngine
import SwiftUI

let player = try AetherEngine()

// SwiftUI: drop AetherPlayerSurface anywhere in the view tree
var body: some View { AetherPlayerSurface(engine: player) }

// UIKit / AppKit: bind an AetherPlayerView directly
let surface = AetherPlayerView()
player.bind(view: surface)

try await player.load(url: videoURL)                            // or with a resume position
try await player.load(url: videoURL, startPosition: 347.5)
try await player.load(url: videoURL, options: .init(
    httpHeaders: headers,              // attached to every demux + segment fetch
    matchContentEnabled: matchContent  // tvOS Match Content master toggle
))
try await player.reloadAtCurrentPosition()                      // background reopen, preserves options
try await player.load(url: trackURL, options: .init(audioOnly: true))   // lean audio path

// Transport
player.play()
player.pause()
player.togglePlayPause()
player.setRate(1.5)                    // clamped to player.maxSupportedRate (2x video, 3x audio-only)
await player.seek(to: 120)
player.stop()
```

--------------------------------

### Run DemoPlayerMac from source

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Examples/DemoPlayerMac/README.md

Execute the application directly from the project directory using Swift Package Manager.

```bash
swift run
```

--------------------------------

### Use AetherPlayerSurface in SwiftUI

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Example implementation of the AetherPlayerSurface within a SwiftUI view body.

```swift
var body: some View {
    AetherPlayerSurface(engine: player)
}
```

--------------------------------

### Implement Aether Engine Playback

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Demonstrates engine initialization, media loading, transport control, state observation, and subtitle handling.

```swift
import AetherEngine
import SwiftUI

let engine = try AetherEngine()
let view = AetherPlayerView()
engine.bind(view: view)

// Load and play
try await engine.load(
    url: videoURL,
    options: LoadOptions(
        httpHeaders: ["Authorization": "Bearer token"],
        isLive: false,
        autoplay: true
    )
)

// Transport
engine.play()
engine.setRate(1.5)
await engine.seek(to: 120)

// State observation
engine.$state
    .sink { state in
        print("State: \(state)")
    }
    .store(in: &cancellables)

// Subtitles
engine.selectSubtitleTrack(index: engine.subtitleTracks.first!.id)

for cue in engine.subtitleCues {
    if case .richText(let runs) = cue.body {
        render(runs, at: cue.placement)
    }
}

// Cleanup
engine.stop()
```

--------------------------------

### Get or set volume

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Controls the playback volume within the range [0, 1].

```swift
@Published public internal(set) var volume: Float
```

--------------------------------

### Handle dolbyVisionUnplayableOnSoftwarePath Recovery

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/errors.md

Example of catching the Dolby Vision error and retrying with tone-mapping enabled.

```swift
do {
    try await engine.load(url: dvURL)
} catch AetherEngineError.dolbyVisionUnplayableOnSoftwarePath(let profile) {
    print("DV P\(profile) requires HW AV1; tone-mapping to SDR")
    try await engine.load(
        url: dvURL,
        options: LoadOptions(matchContentEnabled: false)
    )
}
```

--------------------------------

### AetherEngine Initialization and Playback

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Methods for initializing the engine, binding it to a view, and loading media content.

```APIDOC
## AetherEngine Initialization

### Description
Initializes the AetherEngine instance and binds it to a UI component for rendering.

### Method
`init()`

### Parameters
- None

## engine.bind(view:)

### Description
Binds the engine to a UIKit or AppKit view.

### Parameters
- **view** (AetherPlayerView) - Required - The view instance to bind.

## engine.load(url:)

### Description
Loads media content from a URL.

### Parameters
- **url** (URL) - Required - The media source URL.

### Method
`async`
```

--------------------------------

### probe(url: options:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Performs a one-shot container and stream metadata probe without starting playback.

```APIDOC
## probe(url: options:) async throws -> SourceProbe

### Description
One-shot container + stream metadata probe without starting playback.

### Parameters
- **url** (URL) - Required - Media source URL
- **options** (LoadOptions) - Optional (Default: LoadOptions()) - Probe options (httpHeaders, probesize, etc.)

### Returns
`SourceProbe` with duration, codec, tracks, metadata, live heuristic.

### Signature
`public static func probe(url: URL, options: LoadOptions = LoadOptions()) async throws -> SourceProbe`
```

--------------------------------

### Run DemoPlayerMac

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Examples/README.md

Commands to navigate to the DemoPlayerMac directory and execute the application.

```bash
cd Examples/DemoPlayerMac
swift run
```

--------------------------------

### Get maximum supported rate

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Returns the maximum playback rate, which varies based on media type.

```swift
@Published public internal(set) var maxSupportedRate: Float
```

--------------------------------

### Define ChapterInfo struct

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Represents chapter metadata for discs or containers, including start time and optional naming.

```swift
public struct ChapterInfo: Identifiable, Sendable, Equatable {
    public let id: Int
    public let name: String?
    public let startSeconds: Double
}
```

--------------------------------

### Build and Test AetherEngine

Source: https://github.com/superuser404notfound/aetherengine/blob/main/CONTRIBUTING.md

Use these commands to build and test the AetherEngine Swift package from the command line.

```bash
swift build
swift test
```

--------------------------------

### Access isSessionReady property

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Indicates if the playback session is constructed and ready; use this to gate PiP or AirPlay setup.

```swift
@Published public internal(set) var isSessionReady: Bool
```

--------------------------------

### Handle hlsPlaylistOnRawLivePath Recovery

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/errors.md

Examples for resolving HLS playlist errors by using an appropriate reader or direct URL loading.

```swift
let hlsReader = HLSLiveIngestReader(playlistURL: m3u8URL)
try await engine.load(
    source: .custom(hlsReader, formatHint: "mpegts"),
    options: LoadOptions(isLive: true)
)
```

```swift
try await engine.load(url: m3u8URL, options: LoadOptions(isLive: true))
```

--------------------------------

### setVideoNowPlayingInfo(_ info: [String: Any])

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Sets the video-path Now Playing information dictionary.

```APIDOC
## setVideoNowPlayingInfo(_ info: [String: Any])

### Description
Set video-path Now Playing info dictionary.

### Signature
`public func setVideoNowPlayingInfo(_ info: [String: Any])`
```

--------------------------------

### Load media with default settings

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

Loads a video using all default engine settings.

```swift
try await engine.load(url: videoURL)
```

--------------------------------

### Integrate Video Now Playing Session

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Configure video playback sessions and update system Now Playing metadata by setting ownsVideoNowPlayingSession to true.

```swift
engine.ownsVideoNowPlayingSession = true

engine.$videoNowPlayingSession
    .compactMap { $0 }
    .sink { session in
        // Register playback commands
        MPRemoteCommandCenter.shared().playCommand.addTarget { [weak self] in
            self?.engine.play()
            return .success
        }
        MPRemoteCommandCenter.shared().pauseCommand.addTarget { [weak self] in
            self?.engine.pause()
            return .success
        }
    }
    .store(in: &cancellables)

// Update Now Playing info
engine.setVideoNowPlayingInfo([
    MPMediaItemPropertyTitle: "Episode Title",
    MPMediaItemPropertyArtist: "Show Name",
    MPMediaItemPropertyArtwork: MPMediaItemArtwork(image: thumbnail),
    MPMediaItemPropertyPlaybackDuration: engine.duration
])
```

--------------------------------

### Load live DVR stream

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

Configures a live stream with a 30-minute timeshift window and fast-zap profile.

```swift
try await engine.load(
    url: liveStreamURL,
    options: LoadOptions(
        isLive: true,
        dvrWindowSeconds: 1800,
        liveJoinProfile: .fastZap
    )
)
```

--------------------------------

### Manage Subtitle Tracks and Cues

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Shows how to select subtitle tracks, iterate through cues for custom rendering, and enable native WebVTT for Picture-in-Picture.

```swift
// Select a track
engine.selectSubtitleTrack(index: engine.subtitleTracks[0].id)

// Render cues (on source PTS axis)
for cue in engine.$subtitleCues {
    if case .richText(let runs) = cue.body {
        renderStyledText(runs, placement: cue.placement)
    } else if case .image(let bitmap) = cue.body {
        renderBitmap(bitmap)
    }
}

// Native WebVTT for PiP
try await engine.load(
    url: url,
    options: LoadOptions(prepareNativeSubtitles: true)
)
```

--------------------------------

### Initialize AetherEngine

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Creates a new instance of the AetherEngine. Throws an error if initialization fails.

```swift
public init() throws
```

--------------------------------

### Initialize SourceProbe

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Initializer for the SourceProbe structure.

```swift
public init(
    url: URL,
    durationSeconds: Double,
    videoFormat: VideoFormat,
    videoCodecID: Int32,
    videoCodecName: String?,
    videoWidth: Int32,
    videoHeight: Int32,
    videoFrameRate: Double?,
    isDolbyVision: Bool,
    dvProfile: Int? = nil,
    audioTracks: [TrackInfo],
    subtitleTracks: [TrackInfo],
    metadata: MediaMetadata = MediaMetadata(title: nil, artist: nil, album: nil, artworkData: nil),
    isLive: Bool = false
)
```

--------------------------------

### Probe Media and Handle Errors

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Demonstrates inspecting media metadata before loading and implementing fallback logic for specific playback errors.

```swift
do {
    let probe = try await AetherEngine.probe(url: url)
    print("Video: \(probe.videoCodecName ?? "none") \(probe.videoWidth)x\(probe.videoHeight)")
    print("Duration: \(probe.durationSeconds)s")
    
    try await engine.load(url: url)
} catch AetherEngineError.dolbyVisionUnplayableOnSoftwarePath(let profile) {
    // Auto-tonemap for non-HW AV1 devices
    try await engine.load(
        url: url,
        options: LoadOptions(matchContentEnabled: false)
    )
} catch {
    print("Error: \(error)")
}
```

--------------------------------

### AetherEngine Initialization and View Binding

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Methods to initialize the AetherEngine and bind it to UI components in SwiftUI or UIKit/AppKit.

```APIDOC
## AetherEngine Initialization

### Description
Initializes the AetherEngine instance.

### Signature
`let player = try AetherEngine()`

## AetherPlayerSurface (SwiftUI)

### Description
Integrates the engine into a SwiftUI view tree.

### Signature
`AetherPlayerSurface(engine: player)`

## AetherPlayerView (UIKit/AppKit)

### Description
Binds the engine to a UIKit or AppKit view.

### Signature
`player.bind(view: surface)`
```

--------------------------------

### Configure HLS Fixture with Header Enforcement

Source: https://github.com/superuser404notfound/aetherengine/blob/main/docs/cli.md

Sets up a local HLS fixture that enforces specific request headers and handles redirects, followed by a playback test command.

```bash
# portal on 8099 answers /entry.m3u8 with a 302 to the "CDN edge" on 8100, both enforcing the header
aetherctl hlsfixture --segments-dir ./segs --master --codecs "avc1.4d401f,mp4a.40.2" \
  --resolution 1280x720 --require-header "User-Agent: Mozilla/5.0 (QtEmbedded; TestSTB)" \
  --redirect-entry --redirect-port 8100 --port 8099
aetherctl play --live --header "User-Agent: Mozilla/5.0 (QtEmbedded; TestSTB)" \
  --seconds 60 http://127.0.0.1:8099/entry.m3u8
```

--------------------------------

### LoadOptions Configuration Structure

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

The LoadOptions struct defines the configuration passed to the load(url:options:) method, containing all necessary settings for media playback initialization.

```swift
public struct LoadOptions: Sendable, Equatable {
    // Display & Criteria
    public var omitCriteriaColorExtensions: Bool
    public var suppressDisplayCriteria: Bool
    public var matchContentEnabled: Bool
    public var panelIsInHDRMode: Bool
    public var keepDvh1TagWithoutDV: Bool
    
    // HTTP & Network
    public var httpHeaders: [String: String]
    public var sequentialOrigin: Bool
    public var declaredDurationSeconds: Double?
    
    // Audio
    public var audioBridgeMode: AudioBridgeMode
    public var confirmAtmos: Bool
    public var preferredAudioLanguages: [String]
    
    // Video & Codec
    public var probesize: Int64?
    public var maxAnalyzeDuration: Int64?
    public var deinterlaceMode: DeinterlaceMode
    public var deinterlaceFieldRate: DeinterlaceFieldRate
    
    // Live Streaming
    public var isLive: Bool
    public var dvrWindowSeconds: Double?
    public var liveBlockingReload: Bool?
    public var liveJoinProfile: LiveJoinProfile
    
    // Remote HLS
    public var nativeRemoteHLS: Bool
    public var nativeRemoteHLSIngestFallback: Bool
    
    // Subtitles
    public var preserveASSMarkup: Bool
    public var prepareNativeSubtitles: Bool
    public var eagerNativeSubtitleReaders: Bool
    public var nativeSubtitlePreferredLanguages: [String]
    public var preferredSubtitleLanguages: [String]
    public var externalSubtitles: [ExternalSubtitleTrack]
    
    // Session Control
    public var audioOnly: Bool
    public var autoplay: Bool
    public var forwardBufferSegments: Int?
    public var teletextPage: Int?
}
```

--------------------------------

### Configure Live TV and DVR Playback

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Manage live streams, timeshifting, and channel zapping using LoadOptions. Access live-edge metadata via the player clock.

```swift
// Live-only (seek() is a no-op), or live + timeshift:
try await player.load(url: streamURL, options: LoadOptions(isLive: true))
try await player.load(url: streamURL, options: LoadOptions(isLive: true, dvrWindowSeconds: 1800))

// IPTV channel zapping: join in ~3-6s instead of 10-18s on strict-realtime origins by letting
// TARGETDURATION (and the live-edge holdback derived from it) track the source keyframe cadence:
try await player.load(url: streamURL, options: LoadOptions(isLive: true, liveJoinProfile: .fastZap))

// Drive a scrubber from the live-edge fields (they tick, so they live on player.clock):
player.clock.$seekableLiveRange   // ClosedRange<Double>?, session-relative; nil when DVR off
player.clock.$behindLiveSeconds   // seconds behind the edge; 0 at the edge
player.clock.$liveEdgeTime
await player.seekToLiveEdge()
await player.seek(to: player.liveEdgeTime - 300)   // 5 minutes back

// Ingest a live HLS upstream directly, no media server in the data path:
try await player.load(
    source: .custom(HLSLiveIngestReader(playlistURL: upstreamM3U8), formatHint: "mpegts"),
    options: LoadOptions(isLive: true, dvrWindowSeconds: 600)
)
```

--------------------------------

### engine.load(url:options:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

Loads a media stream with optional configuration for live streaming, language preferences, custom headers, and playback optimizations.

```APIDOC
## engine.load(url:options:)

### Description
Loads a media source into the AetherEngine. Supports various configurations including live DVR settings, language selection, and custom HTTP headers.

### Method
Async Function

### Parameters
- **url** (URL) - Required - The source URL of the media.
- **options** (LoadOptions) - Optional - Configuration object for the load request.
```

--------------------------------

### Configuration and Load Options

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Advanced configuration options for loading media, including language preferences, live stream settings, and custom headers.

```APIDOC
## LoadOptions

### Description
Configuration object passed to the load method.

### Parameters
- **preferredAudioLanguages** ([String]) - Optional - List of preferred audio language codes.
- **preferredSubtitleLanguages** ([String]) - Optional - List of preferred subtitle language codes.
- **isLive** (Bool) - Optional - Set to true for live streams.
- **dvrWindowSeconds** (Int) - Optional - DVR window duration in seconds.
- **httpHeaders** ([String: String]) - Optional - Custom HTTP headers for authentication or requests.
```

--------------------------------

### Build distribution DMG

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Examples/DemoPlayerMac/README.md

Run the build script with environment variables to generate a notarized universal binary DMG.

```bash
DEVELOPER_ID="Developer ID Application: Your Name (TEAMID)" \
NOTARY_PROFILE="NOTARY_PROFILE" \
./Scripts/build-dmg.sh
```

--------------------------------

### Integrate SMB Shares

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Connect to SMB shares using the AetherEngineSMB product.

```swift
import AetherEngineSMB

let smb = try await SMBConnection.connect(
    server: URL(string: "smb://nas.local")!,
    share: "media",
    path: "Movies/film.mkv",
    user: "alice",
    password: "s3cret"
)

try await engine.load(
    source: .custom(
        SMBIOReader(source: smb, discImageProbeEnabled: false),
        formatHint: "matroska"
    )
)
```

--------------------------------

### Generate test media with ffmpeg

Source: https://github.com/superuser404notfound/aetherengine/blob/main/Tests/Integration/README.md

Creates a test MKV file containing a subrip subtitle track for integration testing.

```bash
# 5s 1080p h264 test pattern + a subrip text subtitle track muxed into MKV
printf '1\n00:00:00,500 --> 00:00:02,000\nhello from a text subtitle\n\n2\n00:00:02,500 --> 00:00:04,500\nsecond cue\n' > /tmp/subs.srt
ffmpeg -y -f lavfi -i testsrc=duration=5:size=1920x1080:rate=24 \
       -i /tmp/subs.srt \
       -c:v libx264 -pix_fmt yuv420p -c:s srt \
       /tmp/embedded-subs.mkv
# sanity: stream[1] should be codec_type=subtitle codec_name=subrip
ffprobe -v error -show_entries stream=index,codec_type,codec_name /tmp/embedded-subs.mkv
```

--------------------------------

### Initialize LoadOptions

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

The initializer for LoadOptions defines all available configuration parameters with their default values.

```swift
public init(
    omitCriteriaColorExtensions: Bool = false,
    suppressDisplayCriteria: Bool = false,
    httpHeaders: [String: String] = [:],
    keepDvh1TagWithoutDV: Bool = false,
    matchContentEnabled: Bool = true,
    panelIsInHDRMode: Bool = false,
    audioBridgeMode: AudioBridgeMode = .surroundCompat,
    isLive: Bool = false,
    audioOnly: Bool = false,
    dvrWindowSeconds: Double? = nil,
    liveBlockingReload: Bool? = nil,
    liveJoinProfile: LiveJoinProfile = .standard,
    nativeRemoteHLS: Bool = false,
    nativeRemoteHLSIngestFallback: Bool = true,
    preserveASSMarkup: Bool = false,
    prepareNativeSubtitles: Bool = false,
    eagerNativeSubtitleReaders: Bool = false,
    confirmAtmos: Bool = false,
    nativeSubtitlePreferredLanguages: [String] = [],
    sequentialOrigin: Bool = false,
    declaredDurationSeconds: Double? = nil,
    probesize: Int64? = nil,
    maxAnalyzeDuration: Int64? = nil,
    preferredAudioLanguages: [String] = [],
    preferredSubtitleLanguages: [String] = [],
    externalSubtitles: [ExternalSubtitleTrack] = [],
    forwardBufferSegments: Int? = nil,
    autoplay: Bool = true,
    teletextPage: Int? = nil,
    deinterlaceMode: DeinterlaceMode = .auto,
    deinterlaceFieldRate: DeinterlaceFieldRate = .field
)
```

--------------------------------

### engine.load(source:options:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Loads a live HLS stream directly from an upstream source without requiring a media server.

```APIDOC
## engine.load(source:options:)

### Description
Direct ingest from live HLS upstream. Supports MPEG-TS muxing, inline AES-128 clear-key decryption, and SSAI ad-pod direct play.

### Parameters
- **source**: HLSLiveIngestReader with playlistURL and formatHint
- **options**: LoadOptions (isLive, dvrWindowSeconds)

### Usage
```swift
try await engine.load(
    source: .custom(
        HLSLiveIngestReader(playlistURL: upstreamM3U8),
        formatHint: "mpegts"
    ),
    options: LoadOptions(
        isLive: true,
        dvrWindowSeconds: 600
    )
)
```
```

--------------------------------

### Inspect Probe Before Load

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/errors.md

Retrieve media metadata and stream information before initiating playback.

```swift
let probe = try await AetherEngine.probe(url: sourceURL)
print("Video: \(probe.videoCodecName ?? "none")")
print("DV: \(probe.isDolbyVision ? "P\(probe.dvProfile ?? 0)" : "no")")
print("Streams: \(probe.audioTracks.count) audio, \(probe.subtitleTracks.count) subtitle")
```

--------------------------------

### LoadOptions Initialization

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

The LoadOptions struct is used to configure the behavior of AetherEngine when loading or probing media. It provides various options for audio, subtitles, live streaming, and playback settings.

```APIDOC
## LoadOptions Initialization

### Description
Initializes the configuration options for AetherEngine playback and loading operations.

### Parameters
- **omitCriteriaColorExtensions** (Bool) - Optional - Whether to omit criteria color extensions.
- **suppressDisplayCriteria** (Bool) - Optional - Whether to suppress display criteria.
- **httpHeaders** ([String: String]) - Optional - Custom HTTP headers for requests.
- **keepDvh1TagWithoutDV** (Bool) - Optional - Whether to keep dvh1 tag without DV.
- **matchContentEnabled** (Bool) - Optional - Whether match content is enabled.
- **panelIsInHDRMode** (Bool) - Optional - Whether the panel is in HDR mode.
- **audioBridgeMode** (AudioBridgeMode) - Optional - The audio bridge mode (default: .surroundCompat).
- **isLive** (Bool) - Optional - Whether the stream is live.
- **audioOnly** (Bool) - Optional - Whether to play audio only.
- **dvrWindowSeconds** (Double?) - Optional - The DVR window duration in seconds.
- **liveBlockingReload** (Bool?) - Optional - Whether to enable live blocking reload.
- **liveJoinProfile** (LiveJoinProfile) - Optional - The live join profile (default: .standard).
- **nativeRemoteHLS** (Bool) - Optional - Whether to use native remote HLS.
- **nativeRemoteHLSIngestFallback** (Bool) - Optional - Whether to use native remote HLS ingest fallback.
- **preserveASSMarkup** (Bool) - Optional - Whether to preserve ASS markup.
- **prepareNativeSubtitles** (Bool) - Optional - Whether to prepare native subtitles.
- **eagerNativeSubtitleReaders** (Bool) - Optional - Whether to use eager native subtitle readers.
- **confirmAtmos** (Bool) - Optional - Whether to confirm Atmos.
- **nativeSubtitlePreferredLanguages** ([String]) - Optional - List of preferred native subtitle languages.
- **sequentialOrigin** (Bool) - Optional - Whether to use sequential origin.
- **declaredDurationSeconds** (Double?) - Optional - The declared duration in seconds.
- **probesize** (Int64?) - Optional - The probe size.
- **maxAnalyzeDuration** (Int64?) - Optional - The maximum analyze duration.
- **preferredAudioLanguages** ([String]) - Optional - List of preferred audio languages.
- **preferredSubtitleLanguages** ([String]) - Optional - List of preferred subtitle languages.
- **externalSubtitles** ([ExternalSubtitleTrack]) - Optional - List of external subtitle tracks.
- **forwardBufferSegments** (Int?) - Optional - Number of forward buffer segments.
- **autoplay** (Bool) - Optional - Whether to enable autoplay.
- **teletextPage** (Int?) - Optional - The teletext page number.
- **deinterlaceMode** (DeinterlaceMode) - Optional - The deinterlace mode (default: .auto).
- **deinterlaceFieldRate** (DeinterlaceFieldRate) - Optional - The deinterlace field rate (default: .field)
```

--------------------------------

### Generate software-path test clip

Source: https://github.com/superuser404notfound/aetherengine/blob/main/docs/cli.md

Creates a test video file with audio for use with the bgaudio verification command.

```bash
ffmpeg -f lavfi -i testsrc2 -f lavfi -i sine -c:v libvpx-vp9 -c:a aac -shortest clip.mkv
```

--------------------------------

### Select disc chapter

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Seek to a specific chapter within a disc source.

```swift
public func selectChapter(id: Int)
```

--------------------------------

### Configuring Testing Hooks

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/advanced-usage.md

Methods for forcing software paths, throttling bandwidth, and enabling instrumentation during testing.

```swift
// Force software path (test AV1 decode)
AetherEngine.setForceSoftwarePathForTesting(true)

// Throttle bandwidth
AetherEngine.setSourceThrottleKbpsForTesting(500)  // 500 kbps limit

// Enable memory instrumentation
AetherEngine.setLargeAllocationCensusEnabled(true)

// Background audio testing (internal)
engine.setSoftwareBackgroundAudioOnlyForTesting(true)
```

--------------------------------

### Configuring Now-Playing Session

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Enables and configures the native Now-Playing session for custom-transport hosts.

```swift
player.ownsVideoNowPlayingSession = true
player.videoNowPlayingSession                  // MPNowPlayingSession?, nil unless opted in
player.setVideoNowPlayingInfo([ /* MPMediaItemProperty… */ ])
```

--------------------------------

### Run Playback Sessions with aetherctl

Source: https://github.com/superuser404notfound/aetherengine/blob/main/docs/cli.md

Executes various playback scenarios including VOD, live streams, subtitle testing, and host-call simulation.

```bash
swift run aetherctl play <url>                                  # VOD load, 30 s telemetry
swift run aetherctl play --seconds 60 <url>                     # longer window
swift run aetherctl play --live --dvr-window 1800 <url>         # live path with a DVR ring
swift run aetherctl play --subs teletext <url>                  # activate the first matching subtitle track, log every cue + trim
swift run aetherctl play --host-calls reloadlive,play,extractor,setrate <url>   # mimic a host's post-load call sequence
swift run aetherctl play --live --dvr-window 1800 --audio-stats <url>           # decoded-PCM continuity + per-second audio lead
swift run aetherctl play --live --native-hls <master.m3u8>      # nativeRemoteHLS bypass (carriage watchdog + #293 probe)
swift run aetherctl play --sidecar de=/tmp/de.srt --subs de <master.m3u8>   # declare a sidecar at load (#316)
```

--------------------------------

### Media Loading Methods

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Methods for loading media content into the AetherEngine with various configuration options.

```APIDOC
## load(url:)

### Description
Loads a video from a URL.

### Signature
`try await player.load(url: videoURL)`

## load(url:startPosition:)

### Description
Loads a video starting at a specific position.

### Signature
`try await player.load(url: videoURL, startPosition: 347.5)`

## load(url:options:)

### Description
Loads media with specific configuration options such as HTTP headers or audio-only mode.

### Signature
`try await player.load(url: videoURL, options: .init(...))`
```

--------------------------------

### selectAudioTrack(index:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Switch the active audio track.

```APIDOC
## selectAudioTrack(index:)

### Description
Switch active audio track.

### Signature
`public func selectAudioTrack(index: Int)`

### Parameters
- **index** (Int) - Required - Stream ID from audioTracks[].id
```

--------------------------------

### AetherEngine.probe(url:options:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/configuration.md

Probes a media source to retrieve metadata without initializing a display or playback session.

```APIDOC
## AetherEngine.probe(url:options:)

### Description
Retrieves stream information such as duration, codec details, and track counts for a given URL without starting playback.

### Method
Async Function

### Parameters
- **url** (URL) - Required - The source URL to probe.
- **options** (LoadOptions) - Optional - Configuration object for the probe request.
```

--------------------------------

### Initialize TrackInfo

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Initializer for creating a new TrackInfo instance with default values for optional fields.

```swift
public init(id: Int, name: String, codec: String, language: String?, 
            channels: Int = 0, bitrate: Int64 = 0, isDefault: Bool, 
            isForced: Bool = false, isHearingImpaired: Bool = false, 
            isCommentary: Bool = false, isAtmos: Bool = false, 
            assHeader: String? = nil, isExternal: Bool = false)
```

--------------------------------

### Access mediaChapters property

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Retrieves container chapters for formats like Matroska or MP4; remains empty for disc sources.

```swift
@Published public internal(set) var mediaChapters: [ChapterInfo]
```

--------------------------------

### Now Playing Integration

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Properties for managing MPNowPlayingSession instances and opting into video now-playing control.

```APIDOC
## Now Playing Integration

### audioNowPlayingSession
`@Published public internal(set) var audioNowPlayingSession: MPNowPlayingSession?`
Active MPNowPlayingSession for audio-only path (tvOS/iOS).

### videoNowPlayingSession
`@Published public internal(set) var videoNowPlayingSession: MPNowPlayingSession?`
Active MPNowPlayingSession for video. Nil unless opted in via `ownsVideoNowPlayingSession = true`.

### ownsVideoNowPlayingSession
`public var ownsVideoNowPlayingSession: Bool`
Set before load to opt into system Now-Playing for video path. Off by default.
```

--------------------------------

### Observe Playback State and Time

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/README.md

Uses Combine publishers to monitor playback phases and throttle time updates for UI synchronization.

```swift
// One-liner: unified playback state
engine.$playbackPhase
    .sink { phase in
        switch phase {
        case .playing: showFrame()
        case .paused: hideFrame()
        case .loading, .seeking, .rebuffering: showSpinner()
        case .stalled(let reconnecting): showStallUI(reconnecting)
        case .ended: showEndScreen()
        case .error(let msg): showError(msg)
        case .idle: break
        }
    }
    .store(in: &cancellables)

// Time ticks (separate ObservableObject, ~10 Hz)
engine.clock.$currentTime
    .throttle(to: 0.1, scheduler: RunLoop.main, latest: true)
    .sink { time in updateUI(time) }
    .store(in: &cancellables)
```

--------------------------------

### Initialize AetherPlayerSurface

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

Initializer for the SwiftUI wrapper requiring an AetherEngine instance.

```swift
public init(engine: AetherEngine)
```

--------------------------------

### Configuring Native WebVTT Renditions

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Manage native subtitle renditions for features like PiP or AirPlay.

```swift
player.$nativeSubtitleTracks                   // [NativeSubtitleTrack]: ordinal, language, displayName
player.setNativeSubtitleSelected(track: 2)     // engage a rendition (e.g. on PiP entry); nil deselects
```

--------------------------------

### Set Now Playing Info Dictionaries

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Configures Now Playing information for video or audio-only playback sessions.

```swift
public func setVideoNowPlayingInfo(_ info: [String: Any])
```

```swift
public func setAudioNowPlayingInfo(_ info: [String: Any])
```

--------------------------------

### Access startupProgress property

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Provides monotonic, deduped load progress checkpoints. Returns nil before the first load and after calling stop().

```swift
@Published public internal(set) var startupProgress: StartupProgress?
```

--------------------------------

### Navigating Disc Titles and Chapters

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Access disc-specific navigation structures for DVD or Blu-ray sources.

```swift
player.$discTitles                             // [TitleInfo]: id, name, durationSeconds, chapterCount (longest first, id 0 is the main feature)
player.$selectedDiscTitle                      // TitleInfo?
player.selectTitle(id: titleID)                // switch title (rebuilds from the new title's head)
player.$discChapters                           // [ChapterInfo] for the selected title
player.selectChapter(id: chapterID)            // seek to a chapter (disc chapters only)
```

--------------------------------

### Define StartupProgress struct

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/types.md

A monotonic, deduped snapshot of the current load progress, used by AetherEngine.startupProgress.

```swift
public struct StartupProgress: Sendable, Equatable {
    public let generation: UInt64
    public let checkpoint: StartupCheckpoint
    
    public var completed: Int
    public var total: Int
    public var fraction: Double
    public var stage: StartupStage
    public var isComplete: Bool
}
```

--------------------------------

### Generate a late-audio test file

Source: https://github.com/superuser404notfound/aetherengine/blob/main/docs/cli.md

Creates an MKV file with an offset audio track for testing audio switching scenarios.

```bash
ffmpeg -f lavfi -i testsrc2=size=1280x720:rate=30:duration=40 -f lavfi -i sine=frequency=440:duration=40 -itsoffset 12 -f lavfi -i sine=frequency=660:duration=28 -map 0:v -map 1:a -map 2:a -c:v libx264 -c:a libopus late-audio.mkv
```

--------------------------------

### selectChapter(id:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Seek to a disc chapter.

```APIDOC
## selectChapter(id:)

### Description
Seek to a disc chapter.

### Signature
`public func selectChapter(id: Int)`

### Parameters
- **id** (Int) - Required - Chapter ID from discChapters[].id
```

--------------------------------

### Implement graceful audio-only fallback

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/errors.md

Handle missing video or audio streams by adjusting load options or engine state.

```swift
func loadVideo(url: URL) async throws {
    do {
        try await engine.load(url: url)
    } catch AetherEngineError.noVideoStream {
        print("No video; loading audio-only")
        try await engine.load(
            url: url,
            options: LoadOptions(audioOnly: true)
        )
    } catch AetherEngineError.noAudioStream {
        print("No audio; muting")
        try await engine.load(url: url)
        engine.volume = 0
    }
}
```

--------------------------------

### Access Software Presentation Timebase and Observer

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Accesses the master clock and registers an observer for frames on the software path, where frames are reported in ascending presentation order.

```swift
player.softwarePresentationTimebase               // the master clock, on the source axis
player.setSoftwareVideoFrameTimeObserver { frame in
    frame.presentation; frame.generation
}
```

--------------------------------

### Access softwarePiPSource

Source: https://github.com/superuser404notfound/aetherengine/blob/main/_autodocs/api-reference/aether-engine.md

Provides the AVSampleBufferDisplayLayer and transport answers when on the software path with PiP active.

```swift
@Published public internal(set) var softwarePiPSource: SoftwarePiPSource?
```

--------------------------------

### Now Playing Session Management

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Interfaces for managing the system Now-Playing session on native video paths.

```APIDOC
## Now Playing Session Management

### Description
Configure and update the system Now-Playing information for custom-transport hosts.

### Properties
- **ownsVideoNowPlayingSession** (Bool) - Enables or disables the native video Now-Playing session.
- **videoNowPlayingSession** (MPNowPlayingSession?) - The active session object.

### Methods
- **setVideoNowPlayingInfo([String: Any])** - Updates the Now-Playing metadata using MPMediaItemProperty keys.
```

--------------------------------

### player.selectChapter(id:)

Source: https://github.com/superuser404notfound/aetherengine/blob/main/README.md

Seeks to a specific chapter within the selected disc title.

```APIDOC
## selectChapter(id:)

### Description
Performs a seek operation to the start of the specified chapter.

### Parameters
- **id** (chapterID) - Required - The identifier of the chapter to seek to.
```
Tokens:
Raw