APSMediaUnit

Objective-C

@interface APSMediaUnit : NSObject <NSCopying, APSMediaTrackableObject>

Swift

class APSMediaUnit : NSObject, NSCopying, APSMediaTrackableObject

The APSMediaUnit class represents a clip that’s ready to be rendered by the player. A media unit also references an array of APSMediaOverlay objects, defining the overlays connected to the unit.

Creating a media unit

  • Initializes a media unit object.

    Declaration

    Objective-C

    - (APSMediaUnit *_Nullable)initWithURL:(NSURL *_Nonnull)url;

    Swift

    init?(url: URL)

    Parameters

    url

    The video clip URL.

    Return Value

    A new APSMediaUnit object

Managing the media overlays connected to the current unit

  • Adds an APSMediaOverlay object to the unit, to be rendered together.

    Declaration

    Objective-C

    - (void)addOverlay:(APSMediaOverlay *_Nonnull)overlay;

    Swift

    func add(_ overlay: APSMediaOverlay)

    Parameters

    overlay

    The APSMediaOverlay object to be connected to the unit.

  • Connects an array of APSMediaOverlay objects to the current unit.

    Declaration

    Objective-C

    - (void)setOverlays:(NSArray<APSMediaOverlay *> *_Nonnull)overlays;

    Swift

    func setOverlays(_ overlays: [APSMediaOverlay])

    Parameters

    overlays

    An array of APSMediaOverlay objects to be connected to the unit.

  • Removes all currently connected overlays.

    Declaration

    Objective-C

    - (void)clearOverlays;

    Swift

    func clearOverlays()

  • Returns an array containing all APSMediaOverlay objects currently connected to the unit.

    Declaration

    Objective-C

    - (NSArray *_Nullable)overlays;

    Swift

    func overlays() -> [Any]?

    Return Value

    An array of APSMediaOverlay objects.

  • Adds an object that implements the APSMediaEvent protocol to the unit.

    Declaration

    Objective-C

    - (void)addEvent:(APSMediaEvent *_Nonnull)overlay;

    Swift

    func addEvent(_ overlay: APSMediaEvent)

    Parameters

    overlay

    The event to be connected to the unit.

  • Connects an array of objects that implement the APSMediaEvent protocol to the current unit.

    Declaration

    Objective-C

    - (void)setEvents:(NSArray<APSMediaEvent *> *_Nonnull)events;

    Swift

    func setEvents(_ events: [APSMediaEvent])

    Parameters

    overlays

    An array of events to be connected to the unit.

  • Removes all currently connected events.

    Declaration

    Objective-C

    - (void)clearEvents;

    Swift

    func clearEvents()

  • Removes a specific media event.

    Declaration

    Objective-C

    - (void)removeEvent:(APSMediaEvent *_Nonnull)event;

    Swift

    func removeEvent(_ event: APSMediaEvent)

  • Returns an array containing all event objects currently connected to the unit, that are not dynamic (see [APSMediaEvent dynamicPosition]).

    Declaration

    Objective-C

    - (NSArray *_Nonnull)events;

    Swift

    func events() -> [Any]

    Return Value

    An array of objects that implement the APSMediaEvent protocol.

  • Returns an array containing all event objects currently connected to the unit, that are dynamic (see [APSMediaEvent dynamicPosition]).

    Declaration

    Objective-C

    - (NSArray *_Nonnull)dynamicEvents;

    Swift

    func dynamicEvents() -> [Any]

    Return Value

    An array of objects that implement the APSMediaEvent protocol.

Unit Properties

  • url

    The video clip URL.

    Declaration

    Objective-C

    @property (nonatomic) NSURL *_Nullable url;

    Swift

    var url: URL? { get set }

  • If an ad, the URL to mezzanine file which was the source of this ad

    Declaration

    Objective-C

    @property (nonatomic) NSURL *_Nullable mezzanineUrl;

    Swift

    var mezzanineUrl: URL? { get set }

  • Initial video playback time in seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval initialPlaybackTime;

    Swift

    var initialPlaybackTime: TimeInterval { get set }

  • Defines how the controls bar will be displayed for the unit. See APSMediaControlsDisplay for possible values.

    Declaration

    Objective-C

    @property (nonatomic) APSMediaControlsDisplay controlsDisplay;

    Swift

    var controlsDisplay: APSMediaControlsDisplay { get set }

  • Assigns a unit manager to the current unit. See APSUnitManagerProtocol for more information.

    Declaration

    Objective-C

    @property (nonatomic) NSString *_Nullable managerType;

    Swift

    var managerType: String? { get set }

  • A NSURL pointing to the SRT subtitles to be loaded

    Declaration

    Objective-C

    @property (nonatomic) NSURL *_Nullable subtitlesURL;

    Swift

    var subtitlesURL: URL? { get set }

  • The configuration for the controls bar overlay.

    The following keys are available:

    • kAPSControlsBarColor: Set this to a UIColor that represents the background color of the controls bar.
    • kAPSControlsBarAlpha: NSNumber that represents the opacity of the controls bar.
    • kAPSControlsComponents: Set this to a mask that you get using OR operations on APSControlsOverlayComponents constants.
    • kAPSControlsPlayedTrackColor: The UIColor of the portion of the seek bar that indicates the currently played duration of the movie.
    • kAPSControlsBufferedTrackColor: The UIColor of the portion of the seek bar that indicates the currently buffered duration of the movie.
    • kAPSControlsEmptyTrackColor: The UIColor of the portion of the seek bar that indicates the currently unbuffered duration of the movie.
    • kAPSControlsPlayImage: The UIImage of the play button to use in the playback controls bar. Only displayed if the playback component is selected.
    • kAPSControlsPauseImage: The UIImage of the pause button to use in the playback controls bar. Only displayed if the playback component is selected.
    • kAPSControlsFullscreenImage: The UIImage of the fullscreen button to use in the playback controls bar. Only displayed if the playback component is selected.
    • kAPSControlsPreviousImage: The UIImage of the back button to use in the playback controls bar. Only displayed if the back button component is selected.
    • kAPSControlsNextImage: The UIImage of the forward button to use in the playback controls bar. Only displayed if the forward button component is selected.
    • kAPSControlsVisibileOnlyInFullscreen: Defines whether the playback controls bar should only be visible while the player is in fullscreen mode. This is useful if implementing a custom player UX for normal mode. Set this to a NSNumber boolean.
    • kAPSControlsAutohideDuration: The number of seconds the playback controls bar should automatically become hidden after. Set this to a NSNumber.
    • kAPSControlsLiveText: The text to display instead of the total video duration, for live streams. Only has effect when the total duration component is selected. Defaults to @"LIVE".
    • kAPSControlsPlaybackTimeText: The text to display instead of the current playback time, for live streams. Only has effect when the current playback time component is selected.
    • kAPSControlsUpdateCurrentTimeWhileSeeking: The current time text is showing the current seek position when dragging the seek bar

    Declaration

    Objective-C

    @property (nonatomic) NSDictionary<NSString *, id> *_Nullable controlsParameters;

    Swift

    var controlsParameters: [String : Any]? { get set }

  • The video clip scaling mode, relative to the player surface. Defaults to APSMovieScalingModeNone.

    Declaration

    Objective-C

    @property (nonatomic) APSMovieScalingMode scalingMode;

    Swift

    var scalingMode: APSMovieScalingMode { get set }

  • An array of other media units to be played instead of the current one, should an error be encountered. The unit at index 0 has the highest priority.

    Declaration

    Objective-C

    @property (nonatomic) NSMutableArray<APSMediaUnit *> *_Nullable buffet;

    Swift

    var buffet: NSMutableArray? { get set }

  • Defines if pinch-to-fullscreen should be allowed.

    Declaration

    Objective-C

    @property (nonatomic) BOOL pinchToFullscreen;

    Swift

    var pinchToFullscreen: Bool { get set }

  • Defines if the unit should start playing as soon as it loads or wait for a play command.

    Declaration

    Objective-C

    @property (nonatomic) BOOL shouldAutoplay;

    Swift

    var shouldAutoplay: Bool { get set }

  • Defines whether the player can replay the current unit or not after it has ended in the playlist.

    Declaration

    Objective-C

    @property (nonatomic) BOOL canReplay;

    Swift

    var canReplay: Bool { get set }

  • Toggle to enable logs.

    Declaration

    Objective-C

    @property (nonatomic) BOOL debug;

    Swift

    var debug: Bool { get set }

  • Additional unit key-value information.

    Declaration

    Objective-C

    @property (nonatomic) NSMutableDictionary *_Nullable metadata;

    Swift

    var metadata: NSMutableDictionary? { get set }

  • The APSVASTAdBreak objects which created this unit

    Declaration

    Objective-C

    @property (nonatomic, strong) APSVASTAdBreak *_Nullable adbreak;

    Swift

    var adbreak: APSVASTAdBreak? { get set }

Ad Handling

  • Defines how mid content ads should be handled when the user has skipped over several batches. Use this parameter to instruct the player to render: only the first ad batch, only the last ad batch or all passed ad batches. Defaults to APSHandleSeekEventPlayLastBreak.

    Declaration

    Objective-C

    @property (nonatomic) APSHandleSeekEvent seekHandling;

    Swift

    var seekHandling: APSHandleSeekEvent { get set }

  • For ad breaks assigned to this unit without an ad offset (breaks that should be auto-positioned within the content), this parameter defines the minimum time interval in seconds to wait before displaying the first ad batch. Defaults to 300 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval midcontentAdMinimumInitialOffset;

    Swift

    var midcontentAdMinimumInitialOffset: TimeInterval { get set }

  • For ad breaks assigned to this unit without an ad offset (breaks that should be auto-positioned within the content), this parameter defines the minimum time interval in seconds (relative to the end of the video) that should be ad-free. Defaults to 300 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval midcontentAdMinimumFinalOffset;

    Swift

    var midcontentAdMinimumFinalOffset: TimeInterval { get set }

  • For ad breaks assigned to this unit without an ad offset (breaks that should be auto-positioned within the content), this parameter defines the minimum time interval in seconds to wait between ad batches. Defaults to 300 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval midcontentAdMinimumSpacing;

    Swift

    var midcontentAdMinimumSpacing: TimeInterval { get set }

Utility Methods

  • Converts a string format to a APSMovieScalingMode value.

    Possible input values are:

    • “aspectFit”, that will be converted to APSMovieScalingModeAspectFit
    • “aspectFill”, that will be converted to APSMovieScalingModeAspectFill

    • “fill”, that will be converted to APSMovieScalingModeFill

    Declaration

    Objective-C

    + (APSMovieScalingMode)scalingModeFromString:(NSString *_Nonnull)string;

    Swift

    class func scalingMode(from string: String) -> APSMovieScalingMode

    Parameters

    string

    A string format to be converted.

    Return Value

    A APSMovieScalingMode value.