# PRESTOplaySDK Class

    public class PRESTOplaySDK

Main interface for initializing the SDK and additional plugins.

- `CASTLABS_RECEIVER_V6_APP_ID`

  Default Castlabs Receiver V6 application identifier for Chromecast sessions.

  #### Declaration

  Swift

      public static let CASTLABS_RECEIVER_V6_APP_ID: String

- `ErrorHandler`

  Error callback invoked when a component reports an SDK error.

  #### Declaration

  Swift

      public typealias ErrorHandler = (ComponentProtocol?, PRESTOerror) -> Void

- `AuthTokenHandler`

  Callback used to resolve an authorization token for a given player configuration.

  #### Declaration

  Swift

      public typealias AuthTokenHandler = (PlayerConfiguration) -> String?

### Public

- `Log`

  Logging controls for SDK-level diagnostics.

  See more

  #### Declaration

  Swift

      public struct Log

- `shared`

  Returns the globally shared SDK instance.

  #### Declaration

  Swift

      public static let shared: PRESTOplaySDK

- `version`

  Current SDK version string.

  #### Declaration

  Swift

      public static var version: String { get }

- `requestModifiers`

  Request modifiers applied by default to newly created components.

  #### Declaration

  Swift

      public var requestModifiers: [any RequestModifierProtocol]

- `responseModifiers`

  Response modifiers applied by default to newly created components.

  #### Declaration

  Swift

      public var responseModifiers: [any ResponseModifierProtocol]

- `networkConfiguration`

  NetworkConfiguration (if set) is applied to NetworkEngine

  #### Declaration

  Swift

      public var networkConfiguration: NetworkConfiguration?

- `enableClearKeyCache`

  Enables ClearKey license caching where supported.

  #### Declaration

  Swift

      public var enableClearKeyCache: Bool

- `recreatePlayerOnMediaServicesReset`

  When true, the SDK will recreate the player when a System Media Services Reset occurs.

  #### Declaration

  Swift

      public var recreatePlayerOnMediaServicesReset: Bool

- `useRedirectedManifestURLForDownloads`

  When enabled, uses the redirect-resolved manifest URL as the base for segment downloads. Default is `false` to preserve legacy behavior.

  #### Declaration

  Swift

      public var useRedirectedManifestURLForDownloads: Bool

- `stateTimeout`

  State timeout in seconds

  Throws `.network_error` with timeout message if the Player remains in `.playing` state for longer than this value without positive effective playback rate.

  The feature is enabled if value is greater than `0.0`.

  #### Declaration

  Swift

      public var stateTimeout: Double

- `onError`

  Callback for SDK errors and warnings.

  #### Declaration

  Swift

      public var onError: ErrorHandler?

- `onDeviceAuthTokenRequired`

  Returns the authentication key for the device. Client is responsible for implementing this method.

  #### Declaration

  Swift

      public var onDeviceAuthTokenRequired: AuthTokenHandler?

- `onAirplayAuthTokenRequired`

  Returns the authentication key for AirPlay. Client is responsible for implementing this method.

  #### Declaration

  Swift

      public var onAirplayAuthTokenRequired: AuthTokenHandler?

- `rootFolder`

  Root folder used by the SDK for persisted data.

  #### Declaration

  Swift

      public let rootFolder: URL

- `register(_:_:_:)`

  Initialises the SDK. This method should be called before any other.

  Only the first call to this method is honoured. Subsequent calls are no-ops.

  #### Declaration

  Swift

      @available(*, deprecated, message: "Will be removed in 4.2.0, use `setup(﹚` instead.")
      public func register(
          _ license: String,
          _ plugins: [CLPluginProtocol],
          _ companion: CompanionSDK? = nil
      ) -> LicenseCheck

  #### Parameters

  `license` | License description.
  `plugins` | Array of plugins to enable.
  `companion` | Companion SDK metadata.

  #### Return Value

  License validation result.

- `setup(_:_:_:)`

  Initialises the SDK. This method should be called before any other.

  Only the first call to this method is honoured. Subsequent calls are no-ops.

  #### Declaration

  Swift

      public func setup(
          _ license: String,
          _ plugins: [CLPluginProtocol],
          _ companion: CompanionSDK? = nil
      ) -> PRESTOerror?

  #### Parameters

  `license` | License description.
  `plugins` | Array of plugins to enable.
  `companion` | Companion SDK metadata.

  #### Return Value

  Initialization error, or `nil` on success.

- `setLogLevel(_:)`

  Sets the logging verbosity.

  #### Declaration

  Swift

      public func setLogLevel(_ level: CLLogLevel)

  #### Parameters

  `level` | Log level.

- `player()`

  Creates player without configuration.

  Configuration can be provided later using `open(config:)`.

  #### Declaration

  Swift

      public func player() -> PlayerAPI

  #### Return Value

  Common player interface.

- `player(for:)`

  Creates player for given configuration.

  #### Declaration

  Swift

      public func player(for config: PlayerConfiguration) -> PlayerAPI?

  #### Parameters

  `config` | Player configuration.

  #### Return Value

  Player instance.

- `playerViewController(channels:analytics:loopChannels:)`

  Creates a PlayerViewControllerAPI instance with the channel items and analytics data.

  #### Declaration

  Swift

      @available(tvOS 15.0, *)
      public func playerViewController(
          channels: [ChannelItem],
          analytics: [AnalyticsBackend?: AnalyticsMetadata]?,
          loopChannels: Bool
      )
          -> PlayerViewControllerAPI?

  #### Parameters

  `channels` | Array of channel items to be played.
  `analytics` | AnalyticsBackend instance and the necessary metadata for analytics.
  `loopChannels` | Loop the channel list at the first or last channel.

  #### Return Value

  An optional PlayerViewControllerAPI instance.

- `prefetcher(for:)`

  Creates DRM Prefetcher for given configuration.

  #### Declaration

  Swift

      public func prefetcher(for config: PlayerConfiguration) -> CLDrmPrefetcherAPI?

  #### Parameters

  `config` | Player configuration.

  #### Return Value

  DRM prefetcher instance.

- `decryptor(for:)`

  Creates an audio sample decryptor for the given configuration.

  #### Declaration

  Swift

      public func decryptor(for config: PlayerConfiguration) -> DecryptorComponentProtocol?

  #### Parameters

  `config` | Player configuration.

  #### Return Value

  Decryptor instance, or `nil` if no registered plugin can handle the content.

- `downloader()`

  Creates downloader without configuration.

  Configuration can be loaded later with `createDownload` method.

  #### Declaration

  Swift

      public func downloader() -> DownloaderAPI

  #### Return Value

  Common downloader interface.

- `defaultStorage()`

  Returns the default storage component implementation.

  #### Declaration

  Swift

      public func defaultStorage() -> StorageComponentProtocol

- `setPlaybackRateRange(of:to:)`

  Sets the default playback rate range.

  #### Declaration

  Swift

      public func setPlaybackRateRange(of playerEngine: PlayerEngine, to range: ClosedRange<Double>)

  #### Parameters

  `playerEngine` | Type of player engine.
  `range` | Playback rate range.

- `getPlaybackRateRange(of:)`

  Retrieves the playback rate range for the player engine type.

  #### Declaration

  Swift

      public func getPlaybackRateRange(of playerEngine: PlayerEngine?) -> ClosedRange<Double>?

  #### Parameters

  `playerEngine` | Type of player engine.

  #### Return Value

  Playback rate range.

- `cast(for:)`

  Initialises cast with cast settings.

  At this point authorisation requests are triggered if required.

  #### Declaration

  Swift

      public func cast(
          for castSettings: CastSettings
      ) -> CastAPI?

  #### Parameters

  `castSettings` | Cast settings.

  #### Return Value

  Instance of cast.

- `cast(forSession:engine:)`

  Returns the cast client for a given session with a player instance.

  #### Declaration

  Swift

      public func cast(
          forSession sessionId: String,
          engine castEngine: CastEngine? = CastEngine(rawValue: 0)
      ) -> CastAPI?

  #### Parameters

  `sessionId` | Current session with player instance.
  `castEngine` | Cast engine.

  #### Return Value

  Cast client.

- `cast(for:engine:)`

  Returns the cast client for a given player.

  #### Declaration

  Swift

      public func cast(
          for player: PlayerAPI,
          engine castEngine: CastEngine? = CastEngine(rawValue: 0)
      ) -> CastAPI?

  #### Parameters

  `player` | Current player instance.
  `castEngine` | Cast engine.

  #### Return Value

  Cast client.

- `ads(forSession:settings:)`

  Returns the advertisements client.

  #### Declaration

  Swift

      public func ads(
          forSession sessionId: String,
          settings adsSettings: AdsSettings? = nil
      ) -> AdsAPI?

  #### Parameters

  `sessionId` | Current session id with player instance.
  `adsSettings` | Ad configuration. If nil, default configuration will be used

  #### Return Value

  Advertisements instance.

- `ads(for:settings:)`

  Returns the advertisements client.

  #### Declaration

  Swift

      public func ads(
          for player: PlayerAPI,
          settings adsSettings: AdsSettings? = nil
      ) -> AdsAPI?

  #### Parameters

  `player` | Current player instance.
  `adsSettings` | Ad configuration. If nil, default configuration will be used

  #### Return Value

  Advertisements instance.

- `analytics(forSession:_:)`

  Creates an Analytics client for a given session with player and analytics backend.

  #### Declaration

  Swift

      public func analytics(
          forSession sessionId: String,
          _ backend: AnalyticsBackend? = nil
      ) -> AnalyticsAPI?

  #### Parameters

  `sessionId` | Session identifier with existing player instance.
  `backend` | Analytics backend.

- `analytics(for:_:)`

  Creates an Analytics client for a given player and analytics backend.

  #### Declaration

  Swift

      public func analytics(
          for player: PlayerAPI,
          _ backend: AnalyticsBackend? = nil
      )
          -> AnalyticsAPI?

  #### Parameters

  `player` | Player instance.
  `backend` | Analytics backend.

- `subtitles(forSession:callbacksQueue:)`

  Returns the Subtitles client for a given session with player instance.

  #### Declaration

  Swift

      public func subtitles(
          forSession sessionId: String,
          callbacksQueue: DispatchQueue? = nil
      ) -> SubtitlesAPI?

  #### Parameters

  `sessionId` | Current session with the player instance.

  #### Return Value

  Subtitles client.

- `subtitles(for:callbacksQueue:)`

  Returns the Subtitles client for a given player.

  #### Declaration

  Swift

      public func subtitles(
          for player: PlayerAPI,
          callbacksQueue: DispatchQueue? = nil
      ) -> SubtitlesAPI?

  #### Parameters

  `player` | Current player instance.

  #### Return Value

  Subtitles client.

- `thumbnails(forSession:engine:)`

  Returns the Thumbnails client for a given session with player instance.

  #### Declaration

  Swift

      public func thumbnails(
          forSession sessionId: String,
          engine thumbnailsEngine: ThumbnailsEngine = .castlabs
      ) -> ThumbnailsAPI?

  #### Parameters

  `sessionId` | Session Id with player instance.

  #### Return Value

  Thumbnails client.

- `thumbnails(for:engine:)`

  Returns the Thumbnails client for a given player.

  #### Declaration

  Swift

      public func thumbnails(
          for player: PlayerAPI,
          engine thumbnailsEngine: ThumbnailsEngine = .castlabs
      ) -> ThumbnailsAPI?

  #### Parameters

  `player` | Current player instance.

  #### Return Value

  Thumbnails client.

- `playlist(forSession:mode:loopList:)`

  Returns the playlist api client.

  #### Declaration

  Swift

      public func playlist(
          forSession sessionId: String,
          mode: PlaylistMode = .playerRecreate,
          loopList: Bool? = true
      ) -> PlaylistAPI?

  #### Parameters

  `sessionId` | Session Id with player instance..
  `mode` | Playlist mode.
  `loopList` | Loops the playlist. Default is true. False value is effective only in `.nativeQueue` mode.

  #### Return Value

  Playlist manager instance.

- `playlist(for:mode:loopList:)`

  Returns the playlist api client.

  #### Declaration

  Swift

      public func playlist(
          for player: PlayerAPI,
          mode: PlaylistMode = .playerRecreate,
          loopList: Bool? = true
      ) -> PlaylistAPI?

  #### Parameters

  `player` | Current player instance.
  `mode` | Playlist mode.
  `loopList` | Loops the playlist. Default is true. False value is effective only in `.nativeQueue` mode.

  #### Return Value

  Playlist manager instance.