# PlayerConfiguration Class

    @objc
    public class PlayerConfiguration : NSObject, NSCopying, Codable

This structure describes player configuration for a single asset.

### ClearKey usage

    guard let url = URL(string: "STREAM-URL") else { return }

    let config = PlayerConfiguration(with: url)
    config.contentType = .hls

    let player = PRESTOplaySDK.shared.player()
    player.open(config: config)

### FairPlay usage

    guard let url = URL(string: "STREAM-URL") else { return }

    let config = PlayerConfiguration(with: url)
    config.contentType = .hls
    config.drmSystem = .fairplay
    config.drmConfiguration = DrmConfiguration()
    config.drmConfiguration?.environment = .production
    config.drmConfiguration?.userId = "..."
    config.drmConfiguration?.sessionId = "..."
    config.drmConfiguration?.merchant = "..."
    config.drmConfiguration?.assetId = "..."
    config.drmConfiguration?.variantId = "..."

    let player = PRESTOplaySDK.shared.player()
    player.open(config: config)

### Custom RequestModifier usage

Example showing custom FairPlay URLs.

    guard let url = URL(string: "STREAM-URL") else { return }

    let config = PlayerConfiguration(with: url)
    config.contentType = .hls
    config.drmSystem = .fairplay
    config.drmConfiguration = DrmConfiguration()
    config.drmConfiguration?.licensingUrl = URL(string: "LICENSING-URL")
    config.drmConfiguration?.certificateUrl = URL(string: "CERTIFICATE-URL")

    // Add request/response modifiers on SDK level.
    PRESTOplaySDK.shared.requestModifiers.append(RequestModifier())
    PRESTOplaySDK.shared.responseModifiers.append(ResponseModifier())

    let player = PRESTOplaySDK.shared.player()
    player.open(config: config)

### Public

- `contentUrl`

  Primary content URL to open.

  #### Declaration

  Swift

      public var contentUrl: URL

- `redirectedUrl`

  Final redirected URL after manifest/content request resolution.

  #### Declaration

  Swift

      public var redirectedUrl: URL?

- `contentType`

  Content type hint. If `nil`, SDK attempts automatic detection.

  #### Declaration

  Swift

      public var contentType: ContentType?

- `startTime`

  Preferred start position in seconds.

  #### Declaration

  Swift

      public var startTime: Double? { get set }

- `autoPlay`

  Whether playback should start automatically after the player becomes ready. Default `true`.

  #### Declaration

  Swift

      public var autoPlay: Bool?

- `live`

  Optional live-content flag override.

  #### Declaration

  Swift

      public var live: Bool?

- `threesixty`

  Enables 360-video playback mode where supported.

  #### Declaration

  Swift

      public var threesixty: Bool?

- `autoSelectTextTrackMode`

  Policy used for automatic text-track selection.

  #### Declaration

  Swift

      public var autoSelectTextTrackMode: AutoSelectTextTrackMode?

- `preferredTextLanguage`

  Preferred text language (BCP-47 or provider-defined code).

  #### Declaration

  Swift

      public var preferredTextLanguage: String?

- `preferredAudioLanguage`

  Preferred audio language (BCP-47 or provider-defined code).

  #### Declaration

  Swift

      public var preferredAudioLanguage: String?

- `configurationUrl`

  Optional URL to a remote player-configuration payload (engine specific).

  #### Declaration

  Swift

      public var configurationUrl: URL?

- `drmType`

  DRM type hint for license/key handling.

  #### Declaration

  Swift

      public var drmType: DrmType?

- `drmSystem`

  DRM system to use for playback.

  #### Declaration

  Swift

      public var drmSystem: DrmSystem?

- `drmConfiguration`

  DRM configuration payload.

  #### Declaration

  Swift

      public var drmConfiguration: DrmConfiguration?

- `sideloadedTracks`

  Additional sideloaded tracks (subtitles/thumbnails).

  #### Declaration

  Swift

      public var sideloadedTracks: [SideloadedTrack]?

- `metaData`

  Asset metadata surfaced to analytics/UI layers.

  #### Declaration

  Swift

      public var metaData: MetaData?

- `version`

  Optional content version string forwarded to integrations.

  #### Declaration

  Swift

      public var version: String?

- `userId`

  Optional user identifier forwarded to integrations/analytics.

  #### Declaration

  Swift

      public var userId: String?

- `liveConfiguration`

  Live-playback tuning parameters.

  #### Declaration

  Swift

      public var liveConfiguration: LiveConfiguration?

- `gstreamerPipeline`

  Custom GStreamer pipeline string for castlabs engine.

  #### Declaration

  Swift

      public var gstreamerPipeline: String?

- `gstreamerHDCPHostIP`

  Host IP used by castlabs engine HDCP/GStreamer scenarios.

  #### Declaration

  Swift

      public var gstreamerHDCPHostIP: String?

- `networkConfiguration`

  Network configuration overrides for requests associated with this asset.

  #### Declaration

  Swift

      public var networkConfiguration: NetworkConfiguration?

- `cmcdConfiguration`

  CMCD configuration for this asset.

  Remark

  HLS configuration for HLS streaming is limited to header based data.

  Remark

  It is enough to set the default configuration to enable CMCD.

  #### Declaration

  Swift

      public var cmcdConfiguration: CmcdConfiguration?

- `stateTimeoutConfiguration`

  Configuration to control per-state timeouts for the player state machine.

  Remark

  Must be set before calling `open` to affect initial states.

  Remark

  `nil` disables per-state timeout handling unless explicitly configured.

  #### Declaration

  Swift

      public var stateTimeoutConfiguration: StateTimeoutConfiguration?

- `abrConfiguration`

  Configuration to control the algorithm for quality switching.

  Remark

  not available for `PlayerEngine.apple`.

  Remark

  Must be set before calling `open`.

  #### Declaration

  Swift

      public var abrConfiguration: AbrConfiguration?

- `originUrl`

  For offline playback, points to the original remote URL from which the local stream was downloaded.

  Note

  Required for offline playback of protected content.

  #### Declaration

  Swift

      public var originUrl: URL?

- `preferredEngine`

  PRESTOplay uses two different players under the hood: `PlayerEngine.apple` (currently based on AVPlayer) and `PlayerEngine.castlabs` (currently based on VideoToolbox).

  Certain formats are only playable by one of those while others are supported by both.

  - HLS+Fairplay, MP3: only `PlayerEngine.apple`
  - DASH, SmoothStreaming: only `PlayerEngine.castlabs`
  - HLS, HLS+ClearKey, MP4: both This flag instructs what player engine is used for the common formats.

  When choosing the engine please pay attention what features you want to support as some of them are only available on one of them.

  - `PlayerEngine.apple` supports: Airplay, Picture in Picture.
  - `PlayerEngine.castlabs` supports: Widevine, ABR settings and other custom features (refers to the methods in `PlayerAPI` for the complete list).

  #### Declaration

  Swift

      public var preferredEngine: PlayerEngine?

- `description`

  Human-readable snapshot of core configuration fields.

  #### Declaration

  Swift

      override public var description: String { get }

### Lifecycle

- `init(with:)`

  Creates configuration from a content URL.

  If `contentUrl` is a local file URL and a matching download metadata entry exists, DRM-related fields are inferred from that download and persistent-license mode is enabled.

  #### Declaration

  Swift

      public convenience init(with contentUrl: URL)

  #### Parameters

  `contentUrl` | Asset URL to be played.

- `init(contentUrl:contentType:redirectedUrl:startTime:autoPlay:live:threesixty:autoSelectTextTrackMode:preferredTextLanguage:preferredAudioLanguage:configurationUrl:drmType:drmSystem:drmConfiguration:sideloadedTracks:metaData:version:userId:liveConfiguration:gstreamerPipeline:gstreamerHDCPHostIP:networkConfiguration:cmcdConfiguration:stateTimeoutConfiguration:abrConfiguration:originUrl:preferredEngine:)`

  Creates configuration with explicit values.

  #### Declaration

  Swift

      public convenience init(
          contentUrl: URL,
          contentType: ContentType? = nil,
          redirectedUrl: URL? = nil,
          startTime: Double? = 0.0,
          autoPlay: Bool? = true,
          live: Bool? = nil,
          threesixty: Bool? = nil,
          autoSelectTextTrackMode: AutoSelectTextTrackMode? = .forcedTracksOnly,
          preferredTextLanguage: String? = nil,
          preferredAudioLanguage: String? = nil,
          configurationUrl: URL? = nil,
          drmType: DrmType? = nil,
          drmSystem: DrmSystem? = nil,
          drmConfiguration: DrmConfiguration? = nil,
          sideloadedTracks: [SideloadedTrack]? = nil,
          metaData: MetaData? = nil,
          version: String? = nil,
          userId: String? = nil,
          liveConfiguration: LiveConfiguration? = nil,
          gstreamerPipeline: String? = nil,
          gstreamerHDCPHostIP: String? = nil,
          networkConfiguration: NetworkConfiguration? = nil,
          cmcdConfiguration: CmcdConfiguration? = nil,
          stateTimeoutConfiguration: StateTimeoutConfiguration? = nil,
          abrConfiguration: AbrConfiguration? = nil,
          originUrl: URL? = nil,
          preferredEngine: PlayerEngine? = .apple
      )

  #### Parameters

  `contentUrl` | Primary content URL.
  `contentType` | Content type hint. If `nil`, SDK attempts automatic detection.
  `redirectedUrl` | Redirect-resolved URL.
  `startTime` | Preferred start position in seconds.
  `autoPlay` | Autoplay flag.
  `live` | Live-content override flag.
  `threesixty` | 360-video mode flag.
  `autoSelectTextTrackMode` | Automatic text-track selection mode.
  `preferredTextLanguage` | Preferred text language.
  `preferredAudioLanguage` | Preferred audio language.
  `configurationUrl` | Optional remote configuration URL.
  `drmType` | DRM type hint.
  `drmSystem` | DRM system.
  `drmConfiguration` | DRM configuration payload.
  `sideloadedTracks` | Additional sideloaded tracks.
  `metaData` | Asset metadata.
  `version` | Content version string.
  `userId` | User identifier.
  `liveConfiguration` | Live-playback tuning.
  `gstreamerPipeline` | Custom GStreamer pipeline string.
  `gstreamerHDCPHostIP` | GStreamer HDCP host IP.
  `networkConfiguration` | Per-asset network configuration.
  `cmcdConfiguration` | CMCD configuration.
  `stateTimeoutConfiguration` | Per-state timeout configuration.
  `abrConfiguration` | ABR tuning configuration.
  `originUrl` | Original remote URL for offline scenarios.
  `preferredEngine` | Preferred playback engine.

- `init(with:)`

  Creates offline-playback configuration from an existing download descriptor.

  This constructor automatically maps DRM configuration from the download and enables persistent-license mode.

  Throws

  `.manifest_url_not_set` when local URL is missing.

  #### Declaration

  Swift

      public convenience init(with download: Download) throws

  #### Parameters

  `download` | Download metadata object carrying local URL and DRM context.

- `create(from:)`

  Parses and builds a configuration from a JSON string.

  If `contentType` is missing in the JSON payload, it is inferred from `contentUrl`.

  #### Declaration

  Swift

      public class func create(from json: String) -> PlayerConfiguration?

  #### Parameters

  `json` | JSON payload matching `PlayerConfiguration` coding keys.

  #### Return Value

  Parsed configuration or `nil` when decoding fails.

### Private

- `isEqual(_:)`

  Equality check based on `contentUrl`.

  #### Declaration

  Swift

      public override func isEqual(_ object: Any?) -> Bool

- `hash`

  Hash value derived from the primary content URL.

  #### Declaration

  Swift

      public override var hash: Int { get }

- `==(_:_:)`

  Value equality based on primary content URL.

  #### Declaration

  Swift

      public static func == (lhs: PlayerConfiguration, rhs: PlayerConfiguration) -> Bool