Video player SDK for iOS

The SDK allows you to embed a player for Cloud Video content into your iOS app.

To use the SDK, you need the Xcode IDE version 16.4 or higher and Swift version 5.10 or higher. Minimum supported iOS version: 15.

Adding a video player SDK libraryAdding a video player SDK library

Importing the librariesImporting the libraries

To import the libraries, add the following lines to your code file:

import CloudVideoPlayer
import CloudVideoPlayerUI

Using the SDKUsing the SDK

Set up the start of playbackSet up the start of playback

1. Import a library in the file:

   import CloudVideoPlayer
   

2. Create the Configuration, Environment, and YaPlayer objects:

   let environment = Environment(configuration: Configuration(from: From(raw: "your-app-bundle")))
   
   class ViewController: UIViewController {
     let player = environment.player()
   }
   

3. Create the VideoSurface UIView component, add it to the hierarchy, and attach to the player instance:

   let surface = VideoSurface()
   
   override func loadView() {
     super.loadView()
     self.view.addSubview(surface)
     surface.frame = UIScreen.main.bounds
   }
   
   override func viewDidLoad() {
     super.viewDidLoad()
     surface.attach(player: player)
   }
   

4. Start playback:

   if let source = ContentIdEndpoint(url: URL(string: "https://runtime.video.cloud.yandex.net/player/...")!) {
     player.set(source: source)
     player.play()
   }
   

Where https://runtime.video.cloud.yandex.net/player/... is a link to a video, broadcast, or playlist.

import CloudVideoPlayer

let environment = Environment(configuration: Configuration(from: From(raw: "your-app-bundle")))

class ViewController: UIViewController {

  let player = environment.player()
  let surface = VideoSurface()

  override func loadView() {
    super.loadView()
    self.view.addSubview(surface)
    surface.frame = UIScreen.main.bounds
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    surface.attach(player: player)

    if let source = ContentIdEndpoint(url: URL(string: "https://runtime.video.cloud.yandex.net/player/...")!) {
      player.set(source: source)
      player.play()
    }
  }
}

Connecting a video player skinConnecting a video player skin

1. Import a library in the file:

   import CloudVideoPlayerUI
   

2. Create the VideoView UIView component, add it to the hierarchy, and connect to the player instance:

   let videoView = VideoView()
   
   override func loadView() {
     super.loadView()
     self.view.addSubview(videoView)
     videoView.frame = UIScreen.main.bounds
   }
   
   override func viewDidLoad() {
     super.viewDidLoad()
     videoView.attach(player: player)
   }
   

import CloudVideoPlayerUI

let videoView = VideoView()

override func loadView() {
  super.loadView()
  self.view.addSubview(videoView)
  videoView.frame = UIScreen.main.bounds
}

override func viewDidLoad() {
  super.viewDidLoad()
  videoView.attach(player: player)
}

Playback in SwiftUIPlayback in SwiftUI

To embed your player in SwiftUI, wrap VideoView from CloudVideoPlayerUI into UIViewRepresentable, then bind it to the YaPlayer instance created via Environment.

1. Import these libraries in the file:

   import SwiftUI
   import CloudVideoPlayer
   import CloudVideoPlayerUI
   

2. Create the Environment and YaPlayer objects:

   let environment = Environment(configuration: Configuration(from: From(raw: "your-app-bundle")))
   
   final class PlayerViewModel: ObservableObject {
     let player: YaPlayer = environment.player()
   
     init() {
       guard
         let url = URL(string: "https://runtime.video.cloud.yandex.net/player/..."),
         let source = ContentIdEndpoint(url: url)
       else {
         return
       }
       player.set(source: source)
       player.play()
     }
   }
   

3. Create the UIViewRepresentable type that creates your VideoView and calls attach(player:):

   struct VideoViewRepresentable: UIViewRepresentable {
     let player: YaPlayer
   
     func makeUIView(context: Context) -> VideoView {
       let view = VideoView()
       view.attach(player: player)
       return view
     }
   
     func updateUIView(_ uiView: VideoView, context: Context) {
       uiView.attach(player: player)
     }
   }
   

4. Add the wrapper to the SwiftUI hierarchy:

   struct ContentView: View {
     @StateObject private var viewModel = PlayerViewModel()
   
     var body: some View {
       VideoViewRepresentable(player: viewModel.player)
         .aspectRatio(16 / 9, contentMode: .fit)
         .frame(maxHeight: .infinity, alignment: .top)
     }
   }
   

Where https://runtime.video.cloud.yandex.net/player/... is a link to a video, broadcast, or playlist.

import SwiftUI
import CloudVideoPlayer
import CloudVideoPlayerUI

let environment = Environment(configuration: Configuration(from: From(raw: "your-app-bundle")))

final class PlayerViewModel: ObservableObject {
  let player: YaPlayer = environment.player()

  init() {
    guard
      let url = URL(string: "https://runtime.video.cloud.yandex.net/player/..."),
      let source = ContentIdEndpoint(url: url)
    else {
      return
    }
    player.set(source: source)
    player.play()
  }
}

struct VideoViewRepresentable: UIViewRepresentable {
  let player: YaPlayer

  func makeUIView(context: Context) -> VideoView {
    let view = VideoView()
    view.attach(player: player)
    return view
  }

  func updateUIView(_ uiView: VideoView, context: Context) {
    uiView.attach(player: player)
  }
}

struct ContentView: View {
  @StateObject private var viewModel = PlayerViewModel()

  var body: some View {
    VideoViewRepresentable(player: viewModel.player)
      .aspectRatio(16 / 9, contentMode: .fit)
      .frame(maxHeight: .infinity, alignment: .top)
  }
}

Configuring playbackConfiguring playback

To specify the initial position, audio state, and automatic playback start, provide a PlaybackConfig object to the set(source:config:) method:

let config = PlaybackConfig(
  autoplay: true,
  isMuted: false,
  startPosition: Time(sec: 30)
)
player.set(source: source, config: config)

In the example, player is an earlier created YaPlayer instance, and source is a ContentIdEndpoint source. The player will start playback from the 30-second mark, with sound on. If no config is specified, the following PlaybackConfig.base configuration is used: playback from the beginning, not muted, no automatic start.

To change the playback speed, check its availability using the canSet(playbackSpeed:) method, then call set(playbackSpeed:):

if player.canSet(playbackSpeed: .x150) {
  do {
    try player.set(playbackSpeed: .x150)
  } catch {
    print("Failed to change speed: \(error)")
  }
}

For predefined speed values, see the PlaybackSpeed reference.

Monitoring the player stateMonitoring the player state

To receive notifications about changes in the player's state, subscribe to events using Combine. For example, create an object that tracks the player's state, playback position, and errors:

import Combine
import CloudVideoPlayer

final class PlayerObserver {
  private var subscriptions = Set<AnyCancellable>()

  init(player: YaPlayer) {
    player.playerStatusDidChange()
      .sink { status in
        print("Player state: \(status)")
      }
      .store(in: &subscriptions)

    player.periodicTimePublisher(interval: 1)
      .sink { time in
        print("Playback position: \(time)")
      }
      .store(in: &subscriptions)

    player.errorDidDetected()
      .sink { error in
        print("Playback error: \(error)")
      }
      .store(in: &subscriptions)
  }
}

Create a PlayerObserver(player: player) instance and store it, e.g., in a controller property. Subscriptions must be maintained while you are tracking events. Releasing an object cancels its associated subscriptions. By default, events are delivered to the .main queue. To select a different queue, provide the queue parameter to the subscription method.

For the full list of properties and methods, see the YaPlayer reference.

Returning to liveReturning to live

To return to live after rewinding the broadcast, call the goToLive() asynchronous method:

Task {
  do {
    try await player.goToLive()
  } catch {
    print("Failed to return to live: \(error)")
  }
}

The method moves the playback position to the right edge of the broadcast timeline. If the transition is not possible, e.g., during video-on-demand (VOD) playback, the method returns an error.

Useful linksUseful links

SDK library references:

• CloudVideoPlayer: Main library with Environment, YaPlayer, and VideoSurface objects and playback settings.
• CloudVideoPlayerUI: Additional UI component library with a ready-made VideoView player shell.