Merge pull request #29 from StreamAMG/feature/CORE-5100-Playlist-docu…

…mentation

CORE-5100 CORE-5085 Playlist documentation

README.md

@@ -62,7 +62,14 @@ Example:
 
         switch result {
         case .success(let license):
-            val customPlugin = BitmovinVideoPlayerPlugin()
+            let customPlugin = BitmovinPlayerPlugin()
+
+            // Setting up player plugin
+            var config = VideoPlayerConfig()
+            config.playbackConfig.autoplayEnabled = true // Toggle autoplay
+            config.playbackConfig.backgroundPlaybackEnabled = true // Toggle background playback
+            customPlugin.setup(config: config)
+
             VideoPlayerPluginManager.shared.registerPlugin(customPlugin)
         case .failure(let error):
             // Handle error
@@ -78,11 +85,89 @@ To load the player UI in your application, use the `loadPlayer` method of the `P
 Example:
 
 ```swift
-PlaybackSDKManager.shared.loadPlayer(entryID: entryId, authorizationToken: authorizationToken) { error in
+PlaybackSDKManager.shared.loadPlayer(
+    entryID: entryId,
+    authorizationToken: authorizationToken
+) { error in
     // Handle player UI error 
 } 
 ```
 
+# Loading a Playlist
+
+To load a sequential list of videos into the player UI, use the `loadPlaylist` method of the `PlaybackSDKManager` singleton object. This method is a Composable function that you can use to load and render the player UI.
+`entryIDs`: An array of Strings containing the unique identifiers of all the videos in the playlist.
+`entryIDToPlay`: (Optional) Specifies the unique video identifier that will be played first in the playlist. If not provided, the first video in the `entryIDs` array will be played.
+
+Example:
+
+```swift
+PlaybackSDKManager.shared.loadPlayer(
+    entryIDs: listEntryId,
+    entryIDToPlay: "0_xxxxxxxx",
+    authorizationToken: authorizationToken
+) { errors in
+    // Handle player UI playlist errors
+} 
+```
+
+## Controlling Playlist Playback
+To control playlist playback, declare a VideoPlayerPluginManager singleton instance as a @StateObject variable. This allows you to access various control functions and retrieve information about the current playback state.
+
+Here are some of the key functions you can utilize:
+
+`playFirst()`: Plays the first video in the playlist.
+`playPrevious()`: Plays the previous video in the playlist.
+`playNext()`: Plays the next video in the playlist.
+`playLast()`: Plays the last video in the playlist.
+`seek(entryIdToSeek)`: Seek a specific video Id
+`activeEntryId()`: Returns the unique identifier of the currently playing video.
+
+By effectively leveraging these functions, you can create dynamic and interactive video player experiences.
+
+Example:
+
+```swift
+@StateObject private var pluginManager = VideoPlayerPluginManager.shared
+...
+// You can use the following playlist controls
+pluginManager.selectedPlugin?.playFirst() // Play the first video
+pluginManager.selectedPlugin?.playPrevious() // Play the previous video
+pluginManager.selectedPlugin?.playNext() // Play the next video
+pluginManager.selectedPlugin?.playLast() // Play the last video
+pluginManager.selectedPlugin?.seek(entryIdToSeek) { success in // Seek a specific video
+    if (!success) {
+        let errorMessage = "Unable to seek to \(entryIdToSeek)"
+    }
+}
+pluginManager.selectedPlugin?.activeEntryId() // Get the active video Id
+```
+
+## Receiving Playlist Events
+To receive playlist events, declare a VideoPlayerPluginManager singleton instance, similar to how you did in the Controlling Playlist Playback section.
+Utilize the `onReceive` modifier to listen for player events, such as the `PlaylistTransitionEvent`. This event provides information about the transition from one video to another.
+
+Example:
+
+```swift
+@StateObject private var pluginManager = VideoPlayerPluginManager.shared
+...
+PlaybackSDKManager.shared.loadPlaylist(
+    entryIDs: entryIDs,
+    entryIDToPlay: entryIDToPlay,
+    authorizationToken: authorizationToken
+) { errors in
+        ...
+}
+.onReceive(pluginManager.selectedPlugin!.event) { event in
+    if let event = event as? PlaylistTransitionEvent { // Playlist Event
+        if let from = event.from.metadata?["entryId"], let to = event.to.metadata?["entryId"] {
+            print("Playlist event changed from \(from) to \(to)")
+        }
+    }
+}
+```
+
 # Playing Access-Controlled Content
 To play on-demand and live videos that require authorization, at some point before loading the player your app must call CloudPay to start session, passing the authorization token:
 ```swift

Sources/PlaybackSDK/Documentation.docc/Resources/PlayBackDemoApp.swift → Sources/PlaybackSDK/Documentation.docc/Resources/PlaybackDemoApp.swift

@@ -22,6 +22,13 @@ struct PlaybackDemoApp: App {
 
                 // Register the video player plugin
                 let bitmovinPlugin = BitmovinPlayerPlugin()
+
+                // Setting up player plugin
+                var config = VideoPlayerConfig()
+                config.playbackConfig.autoplayEnabled = true // Toggle autoplay
+                config.playbackConfig.backgroundPlaybackEnabled = true // Toggle background playback
+                bitmovinPlugin.setup(config: config)
+
                 VideoPlayerPluginManager.shared.registerPlugin(bitmovinPlugin)
 
             case .failure(let error):

Sources/PlaybackSDK/Documentation.docc/Resources/PlayBackDemoAppWithUserAgent.swift → Sources/PlaybackSDK/Documentation.docc/Resources/PlaybackDemoAppWithUserAgent.swift

@@ -26,6 +26,13 @@ struct PlaybackDemoApp: App {
 
                 // Register the video player plugin
                 let bitmovinPlugin = BitmovinPlayerPlugin()
+
+                // Setting up player plugin
+                var config = VideoPlayerConfig()
+                config.playbackConfig.autoplayEnabled = true // Toggle autoplay
+                config.playbackConfig.backgroundPlaybackEnabled = true // Toggle background playback
+                bitmovinPlugin.setup(config: config)
+
                 VideoPlayerPluginManager.shared.registerPlugin(bitmovinPlugin)
 
             case .failure(let error):

Sources/PlaybackSDK/Documentation.docc/Resources/PlayerTestPlaylistControlsAndEventsView.swift

@@ -0,0 +1,65 @@
+import SwiftUI
+import PlaybackSDK
+
+struct PlayerTestPlaylistControlsAndEventsView: View {
+
+    @StateObject private var pluginManager = VideoPlayerPluginManager.shared
+    private let entryIDs = ["ENTRY_ID1", "ENTRY_ID_2", "ENTRY_ID_3"]
+    private let entryIDToPlay = "ENTRY_ID_2" // Optional parameter
+    private let entryIdToSeek = "ENTRY_ID_TO_SEEK"
+    private let authorizationToken = "JWT_TOKEN"
+
+    var body: some View {
+        VStack {
+            // Load playlist with the playback SDK
+            PlaybackSDKManager.shared.loadPlaylist(entryIDs: entryIDs, entryIDToPlay: entryIDToPlay, authorizationToken: authorizationToken) { errors in
+                handlePlaybackError(errors)
+            }
+            .onReceive(pluginManager.selectedPlugin!.event) { event in
+                if let event = event as? PlaylistTransitionEvent { // Playlist Event
+                    if let from = event.from.metadata?["entryId"], let to = event.to.metadata?["entryId"] {
+                        print("Playlist event changed from \(from) to \(to)")
+                    }
+                }
+            }
+            .onDisappear {
+                // Remove the player here
+            }
+
+            Spacer()
+
+            Button {
+                // You can use the following playlist controls
+                pluginManager.selectedPlugin?.playFirst() // Play the first video
+                pluginManager.selectedPlugin?.playPrevious() // Play the previous video
+                pluginManager.selectedPlugin?.playNext() // Play the next video
+                pluginManager.selectedPlugin?.playLast() // Play the last video
+                pluginManager.selectedPlugin?.seek(entryIdToSeek) { success in // Seek a specific video
+                    if (!success) {
+                        let errorMessage = "Unable to seek to \(entryIdToSeek)"
+                    }
+                }
+                pluginManager.selectedPlugin?.activeEntryId() // Get the active video Id
+            } label: {
+                Image(systemName: "list.triangle")
+            }
+
+            Spacer()
+        }
+        .padding()
+    }
+
+    private func handlePlaybackErrors(_ errors: [PlaybackAPIError]) {
+
+        for error in errors {
+            switch error {
+            case .apiError(let statusCode, let message, let reason):
+                let message = "\(message) Status Code \(statusCode), Reason: \(reason)"
+                print(message)
+            default:
+                print("Error code and errorrMessage not found: \(error.localizedDescription)")
+            }
+        }
+    }
+
+}

Sources/PlaybackSDK/Documentation.docc/Resources/PlayerTestPlaylistView.swift

@@ -0,0 +1,37 @@
+import SwiftUI
+import PlaybackSDK
+
+struct PlayerTestPlaylistView: View {
+
+    private let entryIDs = ["ENTRY_ID1", "ENTRY_ID_2", "ENTRY_ID_3"]
+    private let entryIDToPlay = "ENTRY_ID_2" // Optional parameter
+    private let authorizationToken = "JWT_TOKEN"
+
+    var body: some View {
+        VStack {
+            // Load playlist with the playback SDK
+            PlaybackSDKManager.shared.loadPlaylist(entryIDs: entryIDs, entryIDToPlay: entryIDToPlay, authorizationToken: authorizationToken) { errors in
+                handlePlaybackError(errors)
+            }
+            .onDisappear {
+                // Remove the player here
+            }
+            Spacer()
+        }
+        .padding()
+    }
+
+    private func handlePlaybackErrors(_ errors: [PlaybackAPIError]) {
+
+        for error in errors {
+            switch error {
+            case .apiError(let statusCode, let message, let reason):
+                let message = "\(message) Status Code \(statusCode), Reason: \(reason)"
+                print(message)
+            default:
+                print("Error code and errorrMessage not found: \(error.localizedDescription)")
+            }
+        }
+    }
+
+}

Sources/PlaybackSDK/Documentation.docc/Resources/PlayerTestView.swift

@@ -20,7 +20,7 @@ struct PlayerTestView: View {
         .padding()
     }
 
-    private func handlePlaybackError(_ error: PlaybackError) {
+    private func handlePlaybackError(_ error: PlaybackAPIError) {
         switch error {
         case .apiError(let statusCode, let errorMessage, let reason):
             print("\(errorMessage) Status Code \(statusCode)")

Sources/PlaybackSDK/Documentation.docc/Tutorial/GetStarted.tutorial

@@ -16,7 +16,7 @@
         @Steps {
 
             @Step {
-                Initialize the Playback SDK by providing your API key and register the default player plugin. 
+                Initialize the Playback SDK by providing your API key, setup and register the default player plugin.
                 **Make sure this step is done when the app starts.**
 
 
@@ -40,6 +40,25 @@
 
                 @Code(name: "PlayerTestView.swift", file: PlayerTestView.swift)
             }
+            @Step {
+                Load the player passing a playlist using the Playback SDK and handle any playlist errors.
+
+                To load a playlist and handle errors, use the **loadPlaylist** function provided by the Playback SDK to initialize and load the video player. This function takes an array of entry IDs, the starting entry ID, and an authorization token as parameters. Additionally, it includes a closure to handle any potential playlist errors that may occur during the loading process.
+                The **handlePlaybackErrors** function is called within the closure to handle the playlist errors. It iterates through an array of **PlaybackError** objects and, for each error, switches on the error type to provide appropriate error handling.
+                The code also includes a placeholder comment to indicate where the removal of the player can be implemented in the **onDisappear** modifier.
+                If you want to allow users to access free content or implement a guest mode, you can pass an empty string or **nil** value as the **authorizationToken** when calling the **loadPlaylist** function. This will bypass the need for authentication, enabling unrestricted access to the specified content.
+
+                @Code(name: "PlayerTestPlaylistView.swift", file: PlayerTestPlaylistView.swift)
+            }
+            @Step {
+                Playlist controls and events
+
+                To control playlist playback and events, declare a **VideoPlayerPluginManager** singleton instance as a **@StateObject** variable. This allows you to access playlist controls and listen to player events.
+                In the **onReceive** modifier, you can listen to player events such as the **PlaylistTransitionEvent**, which provides information about transitions between videos.
+                Through the **pluginManager.selectedPlugin**, you can interact with playlist controls and retrieve the current video ID using the **activeEntryId** function. 
+
+                @Code(name: "PlayerTestPlaylistControlsAndEventsView.swift", file: PlayerTestPlaylistControlsAndEventsView.swift, previousFile: PlayerTestPlaylistView.swift)
+            }
             @Step {
                 Handle the playback errors from Playback SDK.
 

preview_docc

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# This is a convenience script to preview Swift DocC documentation to prepare for GitHub Pages publishing
+# Source: https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation
+
+swift package --disable-sandbox preview-documentation --target PlaybackSDK