YouTubePlayerKit

The YouTubePlayer is the central object for interacting with the YouTube iFrame API. You can initialize it with a simple URL string or with full control using Source, Parameters, and Configuration.

• Source: Defines what to play (video, playlist, channel, etc.).
• Parameters: Controls the behavior and style of the YouTube player (e.g., autoPlay, loopEnabled, showControls). Note: Updating parameters at runtime causes the player to reload.
• Configuration: Linked to the underlying web view (e.g., fullscreenMode, allowsInlineMediaPlayback). Configuration cannot be modified after instantiation.

let youTubePlayer = YouTubePlayer(
    // Possible values: .video, .videos, .playlist, .channel
    source: .video(id: "psL_5RIBqnY"),
    // The parameters of the player
    parameters: .init(
        autoPlay: true,
        loopEnabled: true,
        startTime: .init(value: 5, unit: .minutes),
        showControls: true
    ),
    // The configuration of the underlying web view
    configuration: .init(
        fullscreenMode: .system,
        allowsInlineMediaPlayback: true,
        customUserAgent: "MyCustomUserAgent"
    )
)

For advanced customization of the underlying HTML, you can provide a custom YouTubePlayer.HTMLBuilder during YouTubePlayer initialization. This allows you to override the JavaScript variable name, URL schemes, and provide a custom htmlProvider closure to return a custom HTML string.

let youTubePlayer = YouTubePlayer(
    source: .video(id: "psL_5RIBqnY"),
    configuration: .init(
        htmlBuilder: .init(
            youTubePlayerJavaScriptVariableName: "youtubePlayer",
            youTubePlayerEventCallbackURLScheme: "youtubeplayer",
            youTubePlayerEventCallbackDataParameterName: "data",
            youTubePlayerIframeAPISourceURL: .init(string: "https://www.youtube.com/iframe_api")!,
            htmlProvider: {
                htmlBuilder, jsonEncodedYouTubePlayerOptions in
                // TODO: Return custom HTML string
            }
        )
    )
)

In SwiftUI, use YouTubePlayerView to display a YouTubePlayer. You can provide a simple URL string or a YouTubePlayer instance. YouTubePlayerView also supports an optional overlay closure to handle different player states like .idle, .ready, or .error.

import SwiftUI
import YouTubePlayerKit

struct ContentView: View {

    let youTubePlayer: YouTubePlayer = "https://youtube.com/watch?v=psL_5RIBqnY"

    var body: some View {
        YouTubePlayerView(self.youTubePlayer) { state in
            // An optional overlay view for the current state of the player
            switch state {
            case .idle:
                ProgressView()
            case .ready:
                EmptyView()
            case .error(let error):
                ContentUnavailableView(
                    "Error",
                    systemImage: "exclamationmark.triangle.fill",
                    description: Text("YouTube player couldn't be loaded: \(error)")
                )
            }
        }
        // Optionally react to specific updates such as the fullscreen state
        .onReceive(
            self.youTubePlayer.fullscreenStatePublisher
        ) { fullscreenState in
            if fullscreenState.isFullscreen {
                // ...
            }
        }
    }

}

You can monitor the communication between the library and the YouTube Player iFrame JavaScript API using the unified logging system (OSLog). This is useful for debugging player options, JavaScript events, and evaluations.

• Enable logging during initialization using the isLoggingEnabled parameter.
• Toggle logging at runtime by updating the isLoggingEnabled property on the YouTubePlayer instance.
• Access the underlying Logger instance via the logger() method if logging is enabled.

// Enable or disable logging during initialization
let youTubePlayer = YouTubePlayer(
    source: [
        "w87fOAG8fjk",
        "RXeOiIDNNek",
        "psL_5RIBqnY"
    ],
    isLoggingEnabled: true
)

// To update during runtime update the isLoggingEnabled property
youTubePlayer.isLoggingEnabled = false

// Additionally, you can retrieve an instance of the logger if logging is enabled.
let logger: Logger? = youTubePlayer.logger()