APSMediaBuilder

Objective-C

@interface APSMediaBuilder : KRHub

Swift

class APSMediaBuilder : KRHub

The APSMediaBuilder assists in creating playlists of fully configurable APSMediaUnits, together with attached, configurable APSMediaOverlays, using JSON files or using a NSDictionary, both following the same structure.

The media builder also has class methods that assist with the generation of individual APSMediaUnit and APSMediaOverlay objects from corresponding JSON or NSDictionary structures.

Plugins can be attached to a media builder. Each plugin can dynamically insert, edit or remove units and/or overlays from the generated playlist.

Unit and Overlay Factory Methods

  • Factory method to generate new instance of APSMediaUnit via NSDictionary configuration.

    Declaration

    Objective-C

    + (APSMediaUnit *_Nullable)unitFromDictionary:
    (NSDictionary *_Nonnull)unitConfigurations;

    Swift

    class func unit(from unitConfigurations: [AnyHashable : Any]) -> APSMediaUnit?

    Parameters

    unitConfigurations

    Dictionary unit configuration.

    Return Value

    An instance of APSMediaUnit or nil if error.

  • Factory method to generate new instance of APSMediaOverlay via NSDictionary configuration.

    Declaration

    Objective-C

    + (APSMediaOverlay *_Nullable)overlayFromDictionary:
    (NSDictionary *_Nonnull)overlayConfigurations;

    Swift

    class func overlay(from overlayConfigurations: [AnyHashable : Any]) -> APSMediaOverlay?

    Parameters

    overlayConfigurations

    Dictionary overlay configuration.

    Return Value

    An instance of APSMediaOverlay or nil if error.

Media Builder Initialization

  • Initializes builder with a playlist of a single media unit.

    Declaration

    Objective-C

    - (instancetype _Nullable)initWithMediaUnit:(APSMediaUnit *_Nonnull)contentUnit;

    Swift

    init?(mediaUnit contentUnit: APSMediaUnit)

    Parameters

    contentUnit

    APSMediaUnit object to be played.

    Return Value

    APSMediaBuilder object.

  • Initializes builder with a playlist of media units.

    Declaration

    Objective-C

    - (instancetype _Nullable)initWithMediaUnits:(NSArray *_Nonnull)contentUnits;

    Swift

    init?(mediaUnits contentUnits: [Any])

    Parameters

    contentUnits

    Array of APSMediaUnit objects to be played.

    Return Value

    APSMediaBuilder object.

Media Builder Configuration

  • Configures the builder from a JSON structure.

    Warning

    This method may execute blocking network I/O on the calling thread.

    Declaration

    Objective-C

    - (BOOL)configureFromURL:(NSURL *_Nonnull)url;

    Swift

    func configure(from url: URL) -> Bool

    Parameters

    url

    The URL of the JSON structure to load. This can be a remote file or a local file.

    Return Value

    YES on succes.

  • Configures the builder asynchronously from a JSON structure.

    Declaration

    Objective-C

    - (void)configureFromURL:(NSURL *_Nonnull)url
              onComplete:(void (^_Nonnull)(void))block;

    Swift

    func configure(from url: URL, onComplete block: @escaping () -> Void)

    Parameters

    url

    The URL of the JSON structure to load. This can be a remote file or a local file.
    block

    The block to be executed after configuration is finished.

  • Configures the builder from a NSData object.

    Warning

    UTF8 encoding is assumed.

    Declaration

    Objective-C

    - (BOOL)configureFromData:(NSData *_Nonnull)data;

    Swift

    func configure(from data: Data) -> Bool

    Parameters

    data

    Configuration data - UTF8 encoded.

    Return Value

    YES on succes.

  • Configures the builder from a NSDictionary object.

    Declaration

    Objective-C

    - (BOOL)configureFromDictionary:(NSDictionary *_Nonnull)configuration;

    Swift

    func configure(from configuration: [AnyHashable : Any]) -> Bool

    Parameters

    configuration

    The configuration dictionary.

    Return Value

    YES on succes.

  • Array containing the main content APSMediaUnits that will make up the playlist.

    In the finally rendered playlist, units from bumperUnits will be prefixed to the main content units, while units from exitUnits will be inserted after the main content units. Every array’s content may be modified by attached builder plugins.

    Declaration

    Objective-C

    @property (nonatomic) NSArray *_Nullable contentUnits;

    Swift

    var contentUnits: [Any]? { get set }

  • Array containing APSMediaUnits that will be scheduled before ones in contentUnits in the generated playlist.

    Declaration

    Objective-C

    @property (nonatomic) NSArray *_Nullable bumperUnits;

    Swift

    var bumperUnits: [Any]? { get set }

  • Array containing APSMediaUnits that will be scheduled after ones in contentUnits in the generated playlist.

    Declaration

    Objective-C

    @property (nonatomic) NSArray *_Nullable exitUnits;

    Swift

    var exitUnits: [Any]? { get set }

Properties

  • The user agent that should be used when making HTTP requests.

    Declaration

    Objective-C

    @property (nonatomic) NSString *_Nullable userAgent;

    Swift

    var userAgent: String? { get set }

  • This property enables or disables console logging on all generated units.

    Declaration

    Objective-C

    @property (nonatomic) BOOL debugMode;

    Swift

    var debugMode: Bool { get set }

Generating the Final Playlist

  • Returns a generated playlist of APSMediaUnits, based on builder configuration and registered plugins.

    Warning

    This method may execute blocking network I/O on the calling thread.

    Declaration

    Objective-C

    - (NSArray *_Nonnull)mediaUnits;

    Swift

    func mediaUnits() -> [Any]

    Return Value

    An array of APSMediaUnits.

  • Asynchronously generates a playlist of APSMediaUnits, based on builder configuration and registered plugins.

    Declaration

    Objective-C

    - (void)requestMediaUnitsWithCompletionBlock:
    (void (^_Nonnull)(NSArray *_Nonnull))block;

    Swift

    func requestMediaUnits(completionBlock block: @escaping ([Any]) -> Void)

    Parameters

    block

    The block to be executed when playlist is generated.

Adding Plugins