Adaptive Media Player

AmpCore Docs

AmpPlayer

@objc
open class AmpPlayer : NSObject

Main class of AmpCore, it handles all type of configurations and events of the player.

  • Enum representation of the media characteritics.

    See more

    Declaration

    Swift

    @objc
    public enum MediaCharacteristic : Int
  • This property contains a reference to the AVFoundation instance that reproduces the content.

    Declaration

    Swift

    @objc
    open var player: AVPlayer? { get }
  • Enables or disables the player controls during an ad break.

    The default value is false

    Declaration

    Swift

    @objc
    open var enableAdUI: Bool { get set }
  • This property contains the current stream information

    It is updated as soon as new values are available.

    Declaration

    Swift

    @objc
    open var streamInfo: StreamInfo? { get set }
  • Static value that contains the version of AmpCore currently in use.

    Declaration

    Swift

    @objc
    public var version: String { get }
  • Property used to communicate with external playback outputs eg. Chromecast.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var externalPlaybackDelegate: ExternalPlaybackDelegate? { get set }
  • This flag will be true when the app is on background.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    public var isAppInBackground: Bool { get set }
  • License provided by Akamai

    The preferred validation method at the moment is the API key wich is also provided by Akamai. If you are interested in updating your license please open a ticket in AMP Support.

    Declaration

    Swift

    @objc
    open var licenseString: String? { get set }
  • This property contains a reference to the AVPlayerItem instance that holds the content being reproduced.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open var playerItem: AVPlayerItem? { get }
  • This flag enables or disables the playback of content while the app is in background.

    In case this flag is disabled the playback will be paused and resumed when the app comes to foreground again.

    Important

    Enable background playback for modes with Audio, Airplay and Picture in Picture

    Declaration

    Swift

    open var allowBackgroundPlayback: Bool { get set }
  • Flag to enable or disable the playback widget while the app is on background

    Declaration

    Swift

    open var nowPlayingInfoCenterEnabled: Bool { get set }
  • This property will determine the playback state that the player will switch to after the app switches from background to foreground.

    Available values:

    Declaration

    Swift

    open var playbackStateOnAppDidBecomeActive: PlaybackState { get set }
  • Title of the stream.

    This will be used on the default UI provided.

    Declaration

    Swift

    @objc
    open var title: String? { get set }
  • Subtitle of the stream.

    This will be used on the default UI provided.

    Declaration

    Swift

    @objc
    open var subtitle: String? { get set }
  • Container for the observers of the player’s changes.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var observable: Observable<PlayerEventObserver>? { get }
  • Enabled or disable stream autorecovery

    The stream autorecovery will be triggered when the stream stalls.

    Default value false

    Declaration

    Swift

    open var isStreamAutoRecoveryEnabled: Bool { get set }
  • url

    The URL of the current main content.

    Declaration

    Swift

    @objc
    dynamic open var url: String? { get }
  • This property will be updated when an ad starts or stops playing.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var isAdPlaying: Bool { get set }
  • This property will be updated when an external player has taken control of the content shown.

    It will be true when working a Freewheel and IMA while showing their ads or content. Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var isExternalPlayerPlaying: Bool { get set }
  • This property will store the total stream time without ads

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var timeWithoutAds: Double? { get set }
  • This property indicates the existance of a postroll ad after the main content

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    open var hasPostroll: Bool { get set }
  • This property will manage the media object.

    You can use this property to initialize playback by passing the AMPPlayer a single object.

    Declaration

    Swift

    @objc
    open var media: Media? { get set }
  • This flag indicates if the content should be played automatically after the content has been loaded

    Declaration

    Swift

    @objc
    open var autoplay: Bool { get set }
  • Flag that indicates if the Live content (with an available buffer window) should be seekable.

    This flag is only useful for Live content. VoD content is always seekable. On tvOS this value can’t be changed.

    Declaration

    Swift

    @objc
    open var isDVREnabled: Bool { get set }
  • The type of stream represented as an enum.

    Declaration

    Swift

    @objc
    open var streamType: StreamType { get set }
  • The current playback state of the loaded content.

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open var playbackState: PlaybackState { get set }
  • This property holds Metadata available at the current time frame

    Metadata or ID3Tags contain additional information about the current point in the video

    Declaration

    Swift

    @objc
    open var timedMetadata: [AVMetadataItem] { get set }
  • Current buffering state of the player

    Overriding this value may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open var bufferingState: BufferingState { get set }
  • This class is the main manager of stream loading.

    Users can add their own implementations of AmpCore/StreamHandler to cover specific requirements.

    Declaration

    Swift

    open var streamDownloader: StreamDownloader? { get }
  • Flag that indicated if a player item media doesn’t arrive in time to continue

    This is usually recoverable as long as the origin is in the delay of the media data.

    Declaration

    Swift

    open var isStalled: Bool { get }
  • Container of the UI of the player components and events

    Declaration

    Swift

    @objc
    open var playerView: AmpPlayerView? { get set }
  • Enables or disables the autorecovery feature.

    Once this flag is enabled the stream will try to recover after being stalled or finding an error.

    Default value false

    Declaration

    Swift

    open var isAutoRecoveryEnabled: Bool { get set }
  • Current system volume level

    Declaration

    Swift

    open var currentSystemVolume: Float { get set }
  • Time interval to retry the stream recovery after stalling

    Default value 10.0

    Declaration

    Swift

    open var streamAutoRecoveryInterval: Double { get set }
  • Checks if the stream is VoD or Live

    Declaration

    Swift

    open var isLiveStream: Bool { get }
  • Image that will be displayed as an overlay on the player while waiting for the buffer to fill or when working with audio-only streams

    Declaration

    Swift

    open var posterImage: PosterImage? { get set }
  • fps

    Current video frame rate

    Declaration

    Swift

    open var fps: Float { get }
  • Total stream duration

    On Live streams with DVR make sure to enable isDVREnabled to obtain the correct value

    Declaration

    Swift

    open var streamDuration: Double { get }
  • Starting point of a DVR stream

    Declaration

    Swift

    open var dvrStartTime: Double { get }
  • Lastest seekable time in a DVR stream

    Declaration

    Swift

    open var dvrLiveTime: Double { get }
  • Returns the current playing time on the stream.

    Declaration

    Swift

    open var currentStreamTime: Double { get }
  • Returns the current playing time on the stream in date format

    Declaration

    Swift

    open var currentUTCTime: Double? { get }
  • Player reproduction rate

    A value of 1.0 would be normal playback, 2.0 would be double the speed. Values can also be between 0.0 and 0.1 to play at a slow rate. Or negative to reverse the playback.

    Declaration

    Swift

    open var playerSpeed: Float { get set }
  • Enables and disables the loading indicator that is shown while loading the content.

    The loading indicator will only be shown while requesting the stream. Rebuffering won’t show this indicator.

    Declaration

    Swift

    open var loadingIndicatorEnabled: Bool { get set }
  • List of available audio tracks

    The tracks availble will be defined by the manifest file

    Declaration

    Swift

    open var audioTracks: [String] { get }
  • List of available Close Captions

    You can add additional close captions by using a WebVTT file using setCloseCaption(url:forLanguage:)

    Declaration

    Swift

    open var closeCaptions: [String] { get }
  • Flag to enable or disable AirPlay playback

    Declaration

    Swift

    open var airplayEnabled: Bool { get set }
  • Flag to enable or diasble Chromecast discovery and playback

    Before trying to cast from you app, make sure your app complies with Google Cast’s Guide.

    Declaration

    Swift

    open var chromecastEnabled: Bool { get set }
  • Flag to enable or disable AMP’s logs

    Declaration

    Swift

    open var logsEnabled: Bool { get set }
  • Flag to enable or disable AMP’s logs coloring

    Declaration

    Swift

    open var logColoringEnabled: Bool { get }
  • The duration of the buffer ahead of the playhead to prevent playback disruption.

    More details

    Declaration

    Swift

    open var fowardBufferDuration: TimeInterval { get set }
  • The desired limit, in bits per second, of network bandwidth consumption for this item.

    More details

    Declaration

    Swift

    open var peakBitRate: Double { get set }
  • An array of time ranges indicating media data that is readily available.

    More details

    Declaration

    Swift

    open var loadedTimeRanges: [NSValue]? { get }
  • Fairplay certificate url of the current content

    Declaration

    Swift

    open var certificateUrl: String? { get set }
  • Fairplay verification server url

    Declaration

    Swift

    open var serverUrl: String? { get set }
  • Fairplay custom headers dictionary.

    The custom headers will be sent to the serverUrl

    Declaration

    Swift

    open var customHeaders: [String : String]? { get set }
  • Handler of the Fairplay configuration specifications

    Declaration

    Swift

    open var fairplayConfiguration: FairplayConfiguration? { get set }
  • This property will keep mute activated while changing volume.

    Unless this keepMute is true the mute will be removed when the volume is raised.

    Declaration

    Swift

    open var keepMute: Bool { get set }
  • Customized view for an inline player instance

    Declaration

    Swift

    @objc
    open var inlineCustomView: AmpUIView? { get set }
  • Customized view for a fullscren player instance

    Declaration

    Swift

    @objc
    open var fullCustomScreenView: AmpUIView? { get set }
  • Holds an instance of the UIViewController that contains the player

    Declaration

    Swift

    @objc
    public var parentViewController: UIViewController? { get }
  • Flag syncronized with the fullscreen state of the player

    Declaration

    Swift

    @objc
    open var isFullscreen: Bool { get set }
  • Size of the inline player

    Declaration

    Swift

    open var playerFrame: CGRect? { get }
  • Size of the fullscreen player

    Declaration

    Swift

    open var fullscreenFrame: CGRect? { get }
  • Enables or disables the snapshow funcionaility when returning the app from background

    The snapshot functionality is an image of the last frame of the video that was seen. When coming to foreground if the content has to be rebuffered the user will see the snapshot instead of the empty player.

    Declaration

    Swift

    @objc
    open var isBackgroundSnapshotEnabled: Bool { get set }
  • Return true or false if the player supports Picture in Picture

    Declaration

    Swift

    @objc
    open var isPreplaybackCoverEnabled: Bool { get set }
  • Enables or disables the use of Picture in Picture

    Declaration

    Swift

    @objc
    dynamic open var isPictureInPictureEnabled: Bool { get set }
  • Instance of the AVPictureInPictureControllerDelegate currently in use

    To add your own AVPictureInPictureControllerDelegate use the pictureInPictureDelegate

    Declaration

    Swift

    @objc
    open var pictureDelegate: AVPictureInPictureControllerDelegate? { get }
  • Instance of the AVPictureInPictureController currently in use

    Declaration

    Swift

    @objc
    open var pictureController: AVPictureInPictureController? { get }
  • Instance of anAVPictureInPictureControllerDelegate used for propagation for the client app.

    Declaration

    Swift

    open var pictureInPictureDelegate: AVPictureInPictureControllerDelegate? { get set }
  • Flag that indicates if Picture in Picture is supported by the device

    Declaration

    Swift

    open var isPictureInPictureSupported: Bool { get }
  • Enables or disables the use of SharePlay.

    If enables will appear a option in the player to start/end a SharePlay session.

    Declaration

    Swift

    @available(iOS 15, *)
    @objc
    open var isSharePlayEnabled: Bool { get set }
  • Name of the activity in Facetime.

    Declaration

    Swift

    @available(iOS 15, *)
    public var sharePlayActivityTitle: String { get set }
  • This function triggers the background mode of the player.

    There is no need to call this function manually, when the app goes to background AmpCore manages it automatically.

    Declaration

    Swift

    @objc
    open func handleWillResignActive()
  • This function triggers the foreground mode of the player.

    There is no need to call this function manually, when the app comes to foreground AmpCore manages it automatically.

    Declaration

    Swift

    @objc
    open func handleDidBecomeActive()
  • Setter for the player license provided by Akamai

    In the latest version of AmpCore the use of license has become legacy in favor of the API key. In case you want to provide an API key use setApiKey(_:) instead.

    Important

    If the license is invalid you won’t be able to make use of the AMPPlayer or it’s components

    Declaration

    Swift

    @objc(setLicense:)
    open func setLicense(_ license: String)

    Parameters

    license

    String representation of the license

  • Setter for the player API key provided by Akamai

    Important

    If the license is invalid you won’t be able to make use of the AMPPlayer or its components

    Declaration

    Swift

    @objc(setApiKey:)
    public static func setApiKey(_ apiKey: String)

    Parameters

    apiKey

    String representation of the API key

  • Handler of the event AVPlayerItemNewAccessLogEntry

    The event handler is triggered by the system, manual calls to this function may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open func handleAVPlayerAccess(_ notification: Notification)

    Parameters

    notification

    Log entry event notification

  • Function to set the URL of the new content to play.

    You can use this function to replace the current video stream. If you want to send an AVURLAsset instead, use play(asset:). If you want to reproduce a Fairplay stream use play(url:configuration:) instead.

    Declaration

    Swift

    @objc
    open func play(url streamUrl: String)

    Parameters

    streamUrl

    String representation of the new URL

  • Function to start SharePlay.

    If the user cancels the SharePlay, local playback will be used instead.

    Declaration

    Swift

    @available(iOS 15, tvOS 15, *)
    @objc
    open func startSharePlay(title: String, url streamUrl: String? = nil)

    Parameters

    title

    Name of the activity in Facetime

    streamUrl

    String representation of the url. Optional, this defaults to the current item

  • Function to leave the SharePlay session

    Declaration

    Swift

    @available(iOS 15, tvOS 15, *)
    @objc
    open func leaveSharePlay()
  • Function to end the SharePlay session

    Declaration

    Swift

    @available(iOS 15, tvOS 15, *)
    @objc
    open func endSharePlay()
  • Function to complete the information required for SharePlay DRM content

    Declaration

    Swift

    @objc
    open func completeSharePlayDRMInformation(url: String, configuration: FairplayConfiguration)

    Parameters

    url

    String representation of the URL

    configuration

    FairplayConfiguration instance with the credentials for the stream

  • Function to set the URL of the new content to play.

    You can use this function to replace the current video stream. If you want to send a String representation of the URL instead, use play(url:). If you want to reproduce a Fairplay stream use play(url:configuration:) instead.

    Declaration

    Swift

    @objc
    open func play(asset: AVURLAsset)

    Parameters

    streamUrl

    String representation of the new URL

  • Function to set the URL and credentials of the new content to play.

    You can use this function to replace the current video stream. If your content isn’t Fairplay protected use play(url:) or play(asset:).

    Declaration

    Swift

    @objc
    open func play(url: String, configuration: FairplayConfiguration)

    Parameters

    url

    String representation of the URL

    configuration

    FairplayConfiguration instance with the credentials for the stream

  • Function start the Event Manager

    Declaration

    Swift

    open func setEventManager(_ url: String, states: [State], verificationTimeSeconds: Int)

    Parameters

    url

    URL to the text file

    states

    Array of States to verify

    verificationTimeSeconds

    Seconds to try again

  • Function to set the Image Poster that will be displayed on video start-up or audio-only streams

    Declaration

    Swift

    open func setPoster(_ url: String, type: PosterImageType = .poster, mode: UIView.ContentMode? = nil, parentView: UIView? = nil)

    Parameters

    url

    String representation of the URL of the poster image

    type

    Type of poster image the be displayed. Values poster, streamAutoRecovery

    mode

    Optional UIView.ContentMode to display the image on the view

    parentView

    Optional parent view

  • Function to set the Image Poster that will be displayed on video start-up or audio-only streams

    Declaration

    Swift

    open func setPoster(_ image: UIImage, type: PosterImageType = .poster, mode: UIView.ContentMode? = nil, parentView: UIView? = nil)

    Parameters

    image

    Image to be displayed as a poster

    type

    Type of poster image the be displayed. Values poster, streamAutoRecovery

    mode

    Optional UIView.ContentMode to display the image on the view

    parentView

    Optional parent view

  • Forced display of the poster image

    As long as there is a posterImage available, this will be called automatically during this display scenarios. In case this function is called manually use hidePosterImage(type:) to remove the poster.

    Declaration

    Swift

    open func showPosterImage(type: PosterImageType = .poster)

    Parameters

    type

    Type of poster image that’s being used. Available values poster, streamAutoRecovery

  • Forced hiding of the poster image

    This method is called automatically by AmpCore. However if showPosterImage(type:) was called manually to hide it again this method must be called.

    Declaration

    Swift

    open func hidePosterImage(type: PosterImageType = .poster)

    Parameters

    type

    Type of poster image that’s being used. Available values poster, streamAutoRecovery

  • Handler of the event AVPlayerItemNewAccessLogEntry

    The event handler is triggered by the system, manual calls to this function may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open func playerInfoChanged(_ notification: Notification)

    Parameters

    notification

    Log entry event notification

  • Handles the event AVPlayerItemDidPlayToEndTime

    The event handler is triggered by the system, manual calls to this function may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open func playerItemDidPlayToEndTime(_ notification: Notification)

    Parameters

    notification

    Notification of the event “play to end time”

  • Handles the event AVPlayerItemPlaybackStalled

    The event handler is triggered by the system, manual calls to this function may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open func playerDidStall(_ notification: Notification)

    Parameters

    notification

    Notification of the event “playback stalled”

  • Check if the playhead matches the end of the video

    Declaration

    Swift

    @objc
    open func isPlaybackComplete() -> Bool
  • Handler of the event when the player fails to play until the end of the video AVPlayerItemFailedToPlayToEndTime

    The event handler is triggered by the system, manual calls to this function may result in unexpected behaviours.

    Declaration

    Swift

    @objc
    open func playerItemFailedToPlayToEndTime(_ notification: Notification)

    Parameters

    notification

    Notification of the event “failed to play to end time”

  • Forced update of the current position of the playhead

    Declaration

    Swift

    @objc
    open func updatePosition()
  • Forced update of the current position of the playback scrub bar

    Declaration

    Swift

    @objc
    open func changePosition()
  • Adds media metadata to the backgroudn widget

    Check more information on what to include in this dictionary

    Declaration

    Swift

    open func setMediaInfo(_ data: [String : Any])
  • Resumes the playback and updates the PlaybackState

    Declaration

    Swift

    open func play()
  • Pauses the stream and updates the PlaybackState

    Declaration

    Swift

    open func pause()
  • If the playback has ended it is restarted and the PlaybackState is updated

    Declaration

    Swift

    open func replay()
  • Changes the playhead of the stream by a certain amount of seconds

    This functions works as a skip an amount of seconds, you can pass negative values to go backwards on the playhead time.

    Important

    The preferred way to move the playhead is seekTo(_:)

    Declaration

    Swift

    open func jumpToTime(seconds: TimeInterval)

    Parameters

    seconds

    Seconds expressed as a TimeInterval

  • Sets the playhead to the latest available point in time of the current Live stream

    This method won’t make any change for VoD or non-DVR Live streams.

    Declaration

    Swift

    open func goLive()
  • Sets the playhead to the specified point in time

    Declaration

    Swift

    public func seekTo(_ seconds: TimeInterval)

    Parameters

    seconds

    Point in time to set the playhead of the current video in seconds

  • Sets the playhead to the specified date

    Declaration

    Swift

    open func seekTo(_ date: Date)

    Parameters

    date

    Date to set the playhead of the current video

  • Completely stop the current stream and updates the PlaybackState

    After calling this method you won’t be able to recover the stream, to add content for playback play(url:) must be called again.

    Declaration

    Swift

    open func stop()
  • Destroys the player instance and clear references to avoind memory leaks.

    Declaration

    Swift

    open func destroy()
  • Forces a switch of audio or close caption selection

    Forces a switch of audio or close caption selection

    If you want to turn off the close captions you can send "Off" as the name value

    Declaration

    Swift

    open func setMediaCharacteristic(_ mediaCharacteristic: String, type: MediaCharacteristic)

    Parameters

    mediaCharacteristic

    String representation of the name of the (audio/close caption) selection

    type

    Type of selection. Available values audio, closeCaptions

  • Registers a new observer to be able to receive notifications of the player events.

    To remove a single observer you will need the returned ID

    Declaration

    Swift

    @objc
    open func registerObserver(_ observer: PlayerEventObserver) -> Int

    Parameters

    observer

    Instance of the observer to register

    Return Value

    ID of the registered observer

  • Removes a registered observer

    Declaration

    Swift

    @objc
    open func removeObserver(_ id: Int)

    Parameters

    id

    ID of the obeserver to delete

  • Forces the mute of the current content

    Declaration

    Swift

    open func mute()
  • Forces the un-mute of the current content

    Declaration

    Swift

    open func unmute()
  • Sets the max quality level of the current stream

    Declaration

    Swift

    open func setMaxQualityLevel(level: QualityLevel)

    Parameters

    level

    Quality level desired

  • Toggles the fullscreen visualization of the player

    Declaration

    Swift

    open func manageFullScreen()
  • Toggle the Close Captions of the stream

    Important

    Only works when using inlineCustomView

    Declaration

    Swift

    open func toggleCloseCaptions(_ sender: AnyObject)
  • Shows the popup with the available Close Captions of the stream

    Important

    Only works when using inlineCustomView

    Declaration

    Swift

    open func manageCloseCaptions(_ sender: AnyObject)
  • Toggles on or off the Picture in Picture functionality

    Declaration

    Swift

    open func managePictureInPicture()
  • Forces a tap event on the player

    Declaration

    Swift

    open func tap()
  • Foces the visibility of the spinner indicator.

    Declaration

    Swift

    public func setSpinnerVisibility(shown: Bool)

    Parameters

    shown

    true to show the spinner, false otherwise.

  • Adds a new Close Caption for the current content from a WebVTT file.

    Important

    forLanguage doesn’t represent an identifier but a label, multiple captions can use the same language, wich may be confusing for the final user. Make sure to use different language labels eg. Spanish, Spanish (Latinamerican)

    Declaration

    Swift

    open func setCloseCaption(url: String, forLanguage: String)

    Parameters

    url

    URL string representation of the WebVTT captions file

    forLanguage

    Language of the Close Caption the file represents

  • Removes all of the WebVTT files added for captions.

    Declaration

    Swift

    open func removeCloseCaptions()
  • Adds thumbnails to the player’s scrub bar for the current content from a WebVTT file.

    Declaration

    Swift

    open func setThumbnail(url: String, path: String? = nil)

    Parameters

    url

    URL string representation of the WebVTT thumbnails file

  • This function sets a new fullscreen handler for the player

    This funcion is not requiered for a correct setup of the player since AmpCore comes with an integrated fullscreen handler.

    Declaration

    Swift

    open func setupFullscreen(handler: FullscreenHandler?, autoFullscreen: Bool = false)

    Parameters

    handler

    FullscreenHandler instance for the player

    autoFullscreen

    Check if the player can go into fullscreen mode by rotation or only with user interaction.