From 858ba2eb13cd4f55b7814b4d491d4aa3adda9c88 Mon Sep 17 00:00:00 2001 From: Stefano Russello Date: Wed, 27 Nov 2024 10:38:19 +0100 Subject: [PATCH] CORE-5100 Playlist documentation - Fixed Tutorial controls and events - Control and Events on Readme with examples --- README.md | 59 +++++++++++++++++-- .../Tutorial/GetStarted.tutorial | 15 +++-- 2 files changed, 60 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 60ef98c..d305628 100644 --- a/README.md +++ b/README.md @@ -93,8 +93,8 @@ PlaybackSDKManager.shared.loadPlayer(entryID: entryId, authorizationToken: autho # 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`: specifies the unique video identifier that will be played first in the playlist. Optional parameter +`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: @@ -104,11 +104,58 @@ PlaybackSDKManager.shared.loadPlayer(entryIDs: listEntryId, entryIDToPlay: "0_xx }  ``` -## Control playlist -xxx +## 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. -## Playlist events -xxx +Here are some of the key functions you can utilize: + +`first()`: Plays the first video in the playlist. +`playPrevious()`: Plays the previous video in the playlist. +`playNext()`: Plays the next video in the playlist. +`last()`: Plays the last video in the playlist. +`seek(to: entryIdToSeek)`: Seek to 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?.first() // Play the first video +pluginManager.selectedPlugin?.playPrevious() // Play the previous video +pluginManager.selectedPlugin?.playNext() // Play the next video +pluginManager.selectedPlugin?.last() // Play the last video +pluginManager.selectedPlugin?.seek(to: entryIdToSeek) { success in // Seek to 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: diff --git a/Sources/PlaybackSDK/Documentation.docc/Tutorial/GetStarted.tutorial b/Sources/PlaybackSDK/Documentation.docc/Tutorial/GetStarted.tutorial index d993dda..d11b8c2 100644 --- a/Sources/PlaybackSDK/Documentation.docc/Tutorial/GetStarted.tutorial +++ b/Sources/PlaybackSDK/Documentation.docc/Tutorial/GetStarted.tutorial @@ -43,20 +43,19 @@ @Step { Load the player passing a playlist using the Playback SDK and handle any playlist errors. - In this step, the code utilizes the **loadPlaylist** function provided by the Playback SDK to initialize and load the video player. The function takes an array of entry ID, the starting entry ID to play 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's an array of PlaybackError and for every error it switches on the type of error received and provides appropriate error handling based on the type of error encountered. - The code also includes a placeholder comment to indicate where the removal of the player could be implemented in the **onDisappear** modifier. - If you want to allow users to access free content or if you're implementing 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 contents. + 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. + f 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 - Declaring the **VideoPlayerPluginManager** singleton instance as **@StateObject** variable like in the example, allow you to access to the playlist controls as well as the playlist events - In the **onReceive** modifier, you can listen to the player events such as the **PlaylistTransitionEvent** that gives you information regarding the transition between a video to another - Through the **pluginManager.selectedPlugin** is possible to interact with playlist controls like in the example and get to know the current video that is playing with **activeEntryId** function. + 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) }