Your app. A new playback boundary.

1. Add the correct package

In Xcode, add the local full SDK package at FullSDK/BOSSPlayer, then add BOSSPlayerCore and BOSSPlayerUI products. The repository root may contain the reduced GPL edition; the two are not interchangeable.

Current native targets are arm64 iOS 16+, tvOS 16+ and macOS 13+. iPad uses the iOS target. Catalyst, simulator and Intel support must be checked against the actual release manifest.

Retain the player above navigation

This pattern uses the matching FullConsumer example module. PlaybackOwner and PlaybackHost are example helpers, not Core/UI exports. Add the example package when included in your release.

import SwiftUI
import BOSSPlayerCore
import BOSSPlayerUI
import FullConsumer // matching release’s example helper module

@MainActor
struct AppRoot: View {
    @StateObject private var playback = PlaybackOwner()
    var body: some View {
        PlaybackHost(owner: playback) {
            NavigationStack { Text("Your library") }
        }
    }
}
// Resolve and authorize MediaSource in your app.
// playback.open(source, autoplay: false)
// For deliberate teardown: try await playback.closeAndWait()

Mount the host once before loading a source. Keep its owner alive through navigation, collapse and PiP. Deliberate teardown awaits retirement; an ordinary view disappearing must not destroy active playback.

2. Migrate from KSPlayer

BOSS is an alternative engine integration, not a binary-compatible implementation of KSPlayer classes. Start behind an engine selector with a working fallback.

1. Keep your host services. Library, source resolver, entitlements, parental rules and watch history remain in your app.
2. Translate source authority. Carry explicit Live/on-demand intent, origin-scoped headers, cancellation and revocation into MediaSource.
3. Replace one playback surface. Keep one owner and one video host; map play, pause, seek, audio and subtitles.
4. Validate real sources on each platform. Migrate VOD, Live, special transports, Dolby and subtitle combinations separately.
5. Retire only after acceptance. Remove KSPlayer dependencies once your actual routes and fallback behaviour are accepted.

There is no blanket KSOptions translation. Unsupported combinations must remain explicit.

3. Preserve the lifecycle contract

• Latest intent wins: stale seek, source, preparation and authorization callbacks cannot control a newer session.
• Only the current admitted attempt may produce audio. Admission and user mute are separate.
• Join output and worker retirement before releasing the player or granting a replacement audio rights.
• Keep the same owner through PiP; start admission is not system success. Acknowledge restoration only when the actual UI is visible and laid out.
• Live rewind is bounded by the actual retained/seekable window. A reconnect can create a fresh window and default tracks.
• Never place credentials or private stream URLs in logs.

4. Report source and output separately

Use current engine capability and diagnostic snapshots. Show discovered resolution, codecs and HDR/Dolby source information separately from actual output. Unknown discovery stays unknown.

P7 MEL conversion and FEL reconstruction are different routes. The implemented FEL route reconstructs BL+EL; the current Odyssey bridge includes FEL-to-Dolby policy. Actual output depends on the source, selected policy, device and display route. Multichannel PCM does not establish receiver-confirmed Atmos.

5. Test your actual workload

• MKV, AVI and MP4 with actual video, audio and subtitle combinations
• Live HLS and TS, network loss, reconnects, pause/resume and windowed seeks
• Remote remuxes, authentication, revocation and source replacement
• Overlapping seeks, stale completions and audio admission
• Tracks, dual/imported subtitles, PiP, app lifecycle and remote controls
• Visible output, audible sync, thermal behaviour and sustained resource use

A compile or submitted-frame counter is not physical playback, HDR output or Atmos receiver acceptance.

Audio output: PCM and spatial

The new spatial path is a development preview. Obtain its matching source, native companion, framework slices, notices and manifest; the historical SDK117 package does not establish availability of the newer APIs.

• Original PCM: decode the supplied track's available channels. Lossless source audio can retain its decoded samples; a lossy source cannot regain discarded information.
• Spatial PCM: render a supported TrueHD Atmos or DTS:X presentation into a 7.1.4 PCM layout. A rendered speaker layout is not the original object bitstream.
• APAC Spatial Audio: encode that supported rendered layout into Apple APAC. The current quality target is 4.096 Mbit/s; APAC is lossy.

Conversion currently requires a supported 48 kHz presentation. APAC uses supported Apple OS 26 or later APIs and needs a compatible output route. The ordinary-track compatibility path stays in BOSS and uses original PCM only when the decoder positively identifies a non-object presentation. It does not fabricate height channels or mark PCM as APAC.

Report requested mode, actual output format, channel layout and compatibility reason separately. Receiver branding and a system spatial indicator are not substitutes for measuring the actual speaker/height output. Current native and component checks are not an all-platform physical acceptance certificate. The standalone development SDK is now aligned to the reviewed 4 November Odyssey source cohort. The latest source update is separate from any app archive, TestFlight assignment, receiver or television display validation. See the update page for exact scope.

For full-engine FEL reconstruction, normalized Profile 8.1 output, audio interaction and the current evidence boundaries, read the FEL implementation guide in the paid SDK repository (repository access required). That guide does not announce a new SDK binary release.

6. Choose the edition

GPL edition policy: free standard playback across all supported formats, including MKV and AVI; advanced BOSS processing excluded. Expanded GPL packaging is pending; the current root package is native-only. Full LGPL SDK access and support: US$300/year, all full SDK features included, no per-feature fees or revenue share. Check the exact release’s licence versions, third-party notices, corresponding source and relinking materials before distribution.

LGPL can permit a private host application when its conditions are met. Rights to lawfully received copies do not expire with annual access. FFmpeg, libass, libdovi and optional VLCKit components retain their own applicable terms when shipped.