SwiftVLC Documentation

SwiftVLC is a Swift 6 wrapper around libVLC 4.0 designed specifically for SwiftUI applications. It provides a modern Swift interface by binding directly to the libVLC C API without an Objective-C intermediary.

Key architectural features include:

• Observable state: The Player class is @Observable and @MainActor, allowing SwiftUI views to automatically track properties like state, currentTime, duration, and track lists.
• Typed errors: Errors use throws(VLCError), providing a full, type-safe error surface.
• Structured events: Playback, discovery, logging, and dialog prompts are surfaced via AsyncStream, supporting multiple concurrent consumers.
• Ownership-aware overlays: Components like Marquee, Logo, and VideoAdjustments are ~Copyable and ~Escapable, scoped to the player's lifetime to prevent dangling pointers.

SwiftVLC is built using a modern Swift stack to ensure high performance and safety.

Core Requirements:

• Language: Swift 6.3+ with Xcode 26.4+
• Platforms: iOS 18+, macOS 15+, tvOS 18+, visionOS 2+, Mac Catalyst 18+

Key Technologies:

• C Bindings: Direct access to the libVLC 4.0 C API (no Objective-C intermediary).
• State Management: @Observable and @MainActor for SwiftUI integration.
• Concurrency: AsyncStream<PlayerEvent> for native structured concurrency.
• Video Rendering: Platform-native UIView / NSView via set_nsobject for zero-copy rendering.
• Testing: Swift Testing framework.

The Player class is the core of SwiftVLC. It is @Observable and @MainActor. Each instance manages a single libvlc_media_player_t and a stream of PlayerEvent values.

Lifecycle & Performance:

• Construction allocates underlying libVLC resources.
• deinit handles native release calls off the main actor to prevent UI thread blocking.
• To optimize app launch, call VLCInstance/prewarmShared(priority:) during startup to move libVLC's one-time initialization work away from the first player screen.

@State private var player = Player()

SwiftVLC uses a VideoView architecture that integrates directly with libVLC's internal rendering engine.

Key characteristics:

• There is no manual CALayer, MTKView, or AVPlayerLayer configuration required.
• libVLC handles all rendering internally.
• The VideoSurface (a UIView on iOS or NSView on macOS) is passed to libVLC via set_nsobject(view pointer).
• On resize, layoutSubviews() is used to synchronize sublayer frames.
• When the view is dismantled, set_nsobject(nil) is called to clean up.

The direct renderer provides a low-latency path for video by using vmem callbacks to pipe raw frames into an AVSampleBufferDisplayLayer.

The Pipeline Flow:

1. formatCallback: Sets the BGRA format and creates a CVPixelBufferPool.
2. lockCallback: Retrieves a buffer from the pool and locks its base address.
3. unlockCallback: Unlocks the base address.
4. displayCallback: Wraps the buffer as a CMSampleBuffer and enqueues it to the layer on a dedicated serial queue.
5. cleanupCallback: Releases the pool.

Technical Note: This path uses a device-RGB Core Image target for resizing, meaning it is limited to SDR content and does not preserve HDR metadata.

On iOS, use PiPVideoView instead of VideoView to enable Picture-in-Picture (PiP) functionality. PiPVideoView uses libVLC's native iOS drawable path to interface with the AVKit PiP controller.

Important Constraints:

• Do not share players: VideoView and PiPVideoView should not share the same player instance.
• macOS Support: On macOS, PiPVideoView provides a native drawable container for inline playback, but native PiP functionality is not part of the stable public API. It requires a build opting into the PrivateMacOSPiP SPI, which uses private Apple framework symbols and is outside the public compatibility contract.

Because Player is @Observable, you can bind SwiftUI controls directly to its properties to create a reactive interface. Common properties include:

• player.state: The current playback state.
• player.position: The current playback position (for progress bars).
• player.isPlaying: A boolean indicating if playback is active.

Use player.togglePlayPause() to switch between playing and paused states.

Text(player.state.description)
ProgressView(value: player.position)
Button(player.isPlaying ? "Pause" : "Play") {
    player.togglePlayPause()
}

SwiftVLC follows libVLC's rule that renderer selection should ideally happen before the first play. There are two ways to manage the output device:

1. Before playback starts: Use Player.setRenderer(_:) to specify the target device. This ensures the media starts playing directly on the renderer.
2. During active playback: Use Player.recast(to:). This method replaces the native handle and restarts the current media on the new device while keeping the same Player instance.

To return playback to the local device, pass nil to either setRenderer(_:) or recast(to:).

To prevent stalling SwiftUI transitions, several @MainActor types release their underlying C resources on a background utility queue during deinit.

When a type is released, the event manager is detached first, and then stop and release operations are executed asynchronously. Because this happens on a background queue, the deinit call returns immediately to the caller, and no explicit waiting is required.