IVSBroadcastSession

Objective-C


@interface IVSBroadcastSession : NSObject

Swift

class IVSBroadcastSession : NSObject

BroadcastSession is the primary interaction point with the IVS Broadcast SDK. You must create a BroadcastSession in order to begin broadcasting.

Note

If there as a live broadcast when this object deallocates, internally stop will be called during deallocation, and it will block until the stream has been gracefully terminated or a timeout is reached. Because of that it is recommended that you always explicitly stop a live broadcast before deallocating.

  • Unavailable

    Do not create instances of this class directly

    Declaration

    Objective-C

    IVS_INIT_UNAVAILABLE

  • Unavailable

    Do not create instances of this class directly

    Declaration

    Objective-C

    IVS_INIT_UNAVAILABLE

  • The broadcast SDK version.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *_Nonnull sdkVersion;

    Swift

    class var sdkVersion: String { get }

  • The unique ID of this broadcast session. This will be updated every time the stream is stopped.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSString *_Nonnull sessionId;

    Swift

    var sessionId: String { get }

  • Whether or not the session is ready for use.

    This state is constant once the session has been initialized with the exception of when your app is backgrounded. When backgrounded, isReady will become NO regardless of its previous state when the SDK tears down some resources. When coming back to the foreground isReady will receive a new isReady value. Outside of backgrounding and foregrounding the value of isReady will never change. If this method returns NO, be sure to assign the delegate property in the IVSBroadcastSession initializer so that you receive the relevant error.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isReady;

    Swift

    var isReady: Bool { get }

  • A protocol for client apps to listen to important updates from the Broadcast SDK.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IVSBroadcastSessionDelegate> delegate;

    Swift

    weak var delegate: Delegate? { get set }

  • The session mixer instance. This allows you to control on-screen elements.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nonnull) IVSBroadcastMixer *mixer;

    Swift

    var mixer: IVSBroadcastMixer { get }

  • Logging level for the broadcast session. Default is IVSBroadcastLogLevelError.

    Declaration

    Objective-C

    @property (nonatomic) IVSBroadcastLogLevel logLevel;

    Swift

    var logLevel: IVSBroadcastSession.LogLevel { get set }

  • A value that indicates whether the broadcast session automatically changes settings in the app’s shared audio session.

    Note

    Changing this property can impact the devices return by listAvailableDevices.

    The value of this property defaults to playAndRecord, causing the broadcast session to automatically configure the app’s shared AVAudioSession instance . You can also set it to .recordOnly to still let the SDK manage the settings, but use the record AVAudioSession category instead of playAndRecord. Note there is an issue with recording audio with AirPods using recordOnly, so playAndRecord is recommended. If you set this property’s value to noAction, your app is responsible for selecting appropriate audio session settings. Recording may fail if the audio session’s settings are incompatible with the the desired inputs. Letting the broadcast SDK manage the audio session is especially useful when dealing with audio input devices other than the built in microphone, as it will allow the SDK to manage all of the routing for you. If this value is anything except noAction, it is expected that your app will not interact with AVAudioSession while an IVSBroadcastSession is allocated. If you switch this to noAction after, setting up the IVSBroadcastSession, the broadcast SDK will immediately stop interacting with AVAudioSession. It will not reset any values to their original state, so if your app needs control, be prepared to set all relevant properties since the broadcast SDK may have changed many things.

    Declaration

    Objective-C

    @property (class, nonatomic) IVSBroadcastSessionAudioSessionStrategy applicationAudioSessionStrategy;

    Swift

    class var applicationAudioSessionStrategy: IVSBroadcastSession.AudioSessionStrategy { get set }

  • Create an IVSBroadcastSession object that can stream to an IVS endpoint via RTMP

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithConfiguration:(nonnull IVSBroadcastConfiguration *)config
              descriptors:(nullable NSArray<IVSDeviceDescriptor *> *)descriptors
                 delegate:(nullable id<IVSBroadcastSessionDelegate>)delegate
                    error:(NSError *_Nullable *_Nullable)outError;

    Swift

    init(configuration config: IVSBroadcastConfiguration, descriptors: [IVSDeviceDescriptor]?, delegate: Delegate?) throws

    Parameters

    config

    a Broadcast configuration, either one of the IVSPresets or a custom configuration.
    descriptors

    an optional list of devices to instantiate immediately. To get a list of devices see listAvailableDevices.
    delegate

    an IVSBroadcastSessionDelegate to receive callbacks from the broadcast session.
    outError

    On input, a pointer to an error object. If an error occurs, the pointer is an NSError object that describes the error. If you don’t want error information, pass in nil.

  • Create a BroadcastSession object that can stream to an IVS endpoint via RTMP.

    This initializer is specific to allowing a MTLDevice and MTLCommandQueue to be provided. These are expensive resources, and Apple recommends only allocating a single instance of each per application. If your app is going to be using Metal outside of the broadcast SDK, you should provide your MTLDevice and MTLCommandQueue here so they can be reused.

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithConfiguration:(nonnull IVSBroadcastConfiguration *)config
              descriptors:(nullable NSArray<IVSDeviceDescriptor *> *)descriptors
                 delegate:(nullable id<IVSBroadcastSessionDelegate>)delegate
              metalDevice:(nullable id<MTLDevice>)metalDevice
        metalCommandQueue:(nullable id<MTLCommandQueue>)metalCommandQueue
                    error:(NSError *_Nullable *_Nullable)outError;

    Swift

    init(configuration config: IVSBroadcastConfiguration, descriptors: [IVSDeviceDescriptor]?, delegate: Delegate?, metalDevice: MTLDevice?, metalCommandQueue: MTLCommandQueue?) throws

    Parameters

    config

    a Broadcast configuration, either one of the IVSPresets or a custom configuration.
    descriptors

    an optional list of devices to instantiate immediately. To get a list of devices see listAvailableDevices.
    delegate

    an IVSBroadcastSessionDelegate to receive callbacks from the broadcast session.
    metalDevice

    the MTLDevice for the broadcast SDK to use.
    metalCommandQueue

    the MTLCommandQueue for the broadcast SDK to use.
    outError

    On input, a pointer to an error object. If an error occurs, the pointer is an NSError object that describes the error. If you don’t want error information, pass in nil.

  • List available devices for use with a broadcast session. The value of applicationAudioSessionStrategy will impact the devices returned by this API.

    Declaration

    Objective-C

    + (nonnull NSArray<IVSDeviceDescriptor *> *)listAvailableDevices;

    Swift

    class func listAvailableDevices() -> [IVSDeviceDescriptor]

  • List attached, active devices being used with this broadcast session.

    Note

    since devices are attached and detached asynchronously, this might not include the most recent changes. Use awaitDeviceChanges to wait for all changes to complete before calling this to guarantee up to date results.

    Declaration

    Objective-C

    - (nonnull NSArray<id<IVSDevice>> *)listAttachedDevices;

    Swift

    func listAttachedDevices() -> [IVSDevice]

  • Create and attach a device based on a descriptor for use with the broadcast session.

    Declaration

    Objective-C

    - (void)attachDeviceDescriptor:(nonnull IVSDeviceDescriptor *)descriptor
                toSlotWithName:(nullable NSString *)slotName
                    onComplete:
                        (nullable void (^)(id<IVSDevice> _Nullable,
                                           NSError *_Nullable))onComplete;

    Swift

    func attach(_ descriptor: IVSDeviceDescriptor, toSlotWithName slotName: String?, onComplete: ((IVSDevice?, Error?) -> Void)? = nil)

    Parameters

    descriptor

    The device descriptor for the device to be attached
    slotName

    The name of a slot to bind to when attaching. If nil is provided it will attach to the first compatible slot.
    onComplete

    A callback that contains the new device or any error that occured while attaching. Invoked when the operation has completed. Always invoked on the main queue.

  • Attach a device for use with the broadcast session.

    Declaration

    Objective-C

    - (void)attachDevice:(nonnull id<IVSDevice>)device
      toSlotWithName:(nullable NSString *)slotName
          onComplete:(nullable void (^)(NSError *_Nullable))onComplete;

    Swift

    func attach(_ device: IVSDevice, toSlotWithName slotName: String?, onComplete: ((Error?) -> Void)? = nil)

    Parameters

    device

    The device to be attached
    slotName

    The name of a slot to bind to when attaching. If nil is provided it will attach to the first compatible slot.
    onComplete

    A callback that contains any error that occured while attaching. Invoked when the operation has completed. Always invoked on the main queue.

  • Close and detach a device based on its descriptor.

    Declaration

    Objective-C

    - (void)detachDeviceDescriptor:(nonnull IVSDeviceDescriptor *)descriptor
                    onComplete:(nullable void (^)())onComplete;

    Swift

    func detach(_ descriptor: IVSDeviceDescriptor, onComplete: (() -> Void)? = nil)

    Parameters

    descriptor

    The descriptor for the device to close.
    onComplete

    Invoked when the operation has completed. Always invoked on the main queue.

  • Close and detach a device.

    Declaration

    Objective-C

    - (void)detachDevice:(nonnull id<IVSDevice>)device
          onComplete:(nullable void (^)())onComplete;

    Swift

    func detach(_ device: IVSDevice, onComplete: (() -> Void)? = nil)

    Parameters

    device

    The device to close.
    onComplete

    Invoked when the operation has completed. Always invoked on the main queue.

  • Exchange a device with another device of the same type. For hardware backed devices, this API might make performance optimizations around locking compared to detaching and attaching the devices separately. This method should not be used for custom audio and image sources.

    Declaration

    Objective-C

    - (void)exchangeOldDevice:(nonnull id<IVSDevice>)oldDevice
            withNewDevice:(nonnull IVSDeviceDescriptor *)newDevice
               onComplete:(nullable void (^)(id<IVSDevice> _Nullable,
                                             NSError *_Nullable))onComplete;

    Swift

    func exchangeOldDevice(_ oldDevice: IVSDevice, withNewDevice newDevice: IVSDeviceDescriptor, onComplete: ((IVSDevice?, Error?) -> Void)? = nil)

    Parameters

    oldDevice

    The device to replace
    newDevice

    The descriptor of the new device to attach
    onComplete

    A callback that contains the new device or any error that occured while attaching. Invoked when the operation has completed. Always invoked on the main queue.

  • Waits for all pending device operations to complete, then invokes onComplete.

    Declaration

    Objective-C

    - (void)awaitDeviceChanges:(nonnull void (^)())onComplete;

    Swift

    func awaitDeviceChanges(_ onComplete: @escaping () -> Void)

    Parameters

    onComplete

    Always invoked on the main queue.

  • Start the configured broadcast session.

    Declaration

    Objective-C

    - (BOOL)startWithURL:(nonnull NSURL *)url
           streamKey:(nonnull NSString *)streamKey
               error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func start(with url: URL, streamKey: String) throws

    Parameters

    url

    the RTMPS endpoint provided by IVS.
    streamKey

    the broadcaster’s stream key that has been provided by IVS.
    outError

    A reference to an NSError that would be set if an error occurs.

    Return Value

    if the operation is successful. If it returns NO check isReady.

  • Stop the broadcast session, but do not deallocate resources. Stopping the stream happens asynchronously while the SDK attempts to gracefully end the broadcast. Please obverse state changes in the IVSBroadcastSessionDelegate to know when you can start a new stream.

    If this IVSBroadcastSession object deallocates during the stop operation, the deallocation will block until the stop completes successfully or a timeout is reached. This is to ensure the live broadcast is properly shut down, preventing it from staying live longer than expected.

    Declaration

    Objective-C

    - (void)stop;

    Swift

    func stop()

  • Create an image input for a custom source. This should only be used if you intend to generate and feed image data to the SDK manually.

    Declaration

    Objective-C

    - (nonnull id<IVSCustomImageSource>)createImageSourceWithName:
    (nonnull NSString *)name;

  • Create an audio input for a custom source. This should only be used if you intend to generate and feed pcm audio data to the SDK manually.

    Declaration

    Objective-C

    - (nonnull id<IVSCustomAudioSource>)createAudioSourceWithName:
    (nonnull NSString *)name;

  • Gets a view that will render a preview image of the composited video stream. This will match what consumers see when watching the broadcast.

    Note

    this must be called on the main thread

    Declaration

    Objective-C

    - (nullable IVSImagePreviewView *)
    previewViewWithAspectMode:(IVSAspectMode)aspectMode
                        error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func previewView(with aspectMode: IVSBroadcastConfiguration.AspectMode) throws -> IVSImagePreviewView

    Parameters

    aspectMode

    the aspect mode to apply to the image stream rendering on the view.
    outError

    On input, a pointer to an error object. If an error occurs, the pointer is an NSError object that describes the error. If you don’t want error information, pass in nil.

  • Runs a network test with a default duration of 8 seconds.

    See

    -[IVSBroadcastSession recommendedVideoSettingsWithURL:streamKey:duration:results:]

    Declaration

    Objective-C

    - (nullable IVSBroadcastSessionTest *)
    recommendedVideoSettingsWithURL:(nonnull NSURL *)url
                          streamKey:(nonnull NSString *)streamKey
                            results:(nonnull IVSSessionTestResultCallback)
                                        onNewResult;

    Swift

    func recommendedVideoSettings(with url: URL, streamKey: String, results onNewResult: @escaping IVSSessionTestResultCallback) -> IVSBroadcastSessionTest?

  • This will perform a network test and provide recommendations for video configurations. It will not publish live video, it will only test the connection quality. The callback will be called periodically and provide you with a status, progress, and continuously updated recommendations. The longer the test runs the more refined the suggestions will be, however you can cancel the test at any time and make use of previous recommendations. But these recommendations might not be as stable, or as high quality as a fully completed test.

    Note

    This can not be called while an existing broadcast is in progress, and a new broadcast can not be started while a test is in progress.

    Declaration

    Objective-C

    - (nullable IVSBroadcastSessionTest *)
    recommendedVideoSettingsWithURL:(nonnull NSURL *)url
                          streamKey:(nonnull NSString *)streamKey
                           duration:(NSTimeInterval)duration
                            results:(nonnull IVSSessionTestResultCallback)
                                        onNewResult;

    Swift

    func recommendedVideoSettings(with url: URL, streamKey: String, duration: TimeInterval, results onNewResult: @escaping IVSSessionTestResultCallback) -> IVSBroadcastSessionTest?

    Parameters

    url

    the RTMPS endpoint provided by IVS.
    streamKey

    the broadcaster’s stream key that has been provided by IVS.
    duration

    How long to run the test for. It’s recommended the test runs for at least 8 seconds, and the minimum is 3 seconds. The test can always be cancelled early.
    onNewResult

    a block that will be called periodically providing you with an update on the test’s progress and recommendations.

    Return Value

    a handle to the network test, providing you a way to cancel it, or nil if there is an error starting the test.

  • Invoking this API changes the default behavior when your application goes into the background. By default any active broadcast will stop, and all I/O devices will be shutdown until the app is foregrounded again. After calling this API and receiving an error free callback, the broadcast will remain active in the background and will loop the video provided to the IVSBackgroundImageSource returned by this API. The audio sources will stay live.

    The total duration of the background video must be an internal of the keyframe interval provided to the IVSVideoConfiguration.keyframeInterval If the keyframeInterval is 2 seconds, the targetFramerate is 30, and you provide 45 images, the last 15 images will be trimmed, or the last image will be repeated 15 times based on the value of the attemptTrim param. Because of this, the API will work best if the number of images provide is a multiple of (keyframeInterval * targetFramerate). A single image can also be provided to this source before calling finish, and that image will be encoded to a full GOP for a static background.

    Note

    This is an expensive API, it is recommended that you call this before going live to prevent dropping frames. Additionally, this API must be called while the application is in the foreground.

    Note

    In order to continue to operate in the background, you will need to enable the background audio entilement for your application.

    Declaration

    Objective-C

    - (nullable id<IVSBackgroundImageSource>)
    createAppBackgroundImageSourceWithAttemptTrim:(BOOL)attemptTrim
                                       OnComplete:
                                           (nullable void (^)(
                                               NSError *_Nullable))onComplete;

    Parameters

    onComplete

    A callback that is invoked when the setup for background image broadcasting is complete. Always invoked on the main queue.
    attemptTrim

    if this is YES, this API will attempt to trim the submitted samples to create a perfect looping clip, which means some samples might be dropped to correctly end on a keyframe. If this is NO, the last frame will be repeated until the GOP is closed. If this is YES and there were not enough samples submitted to create a full GOP, the last frame will always be repeated and the trim will not occur.

  • Removes the behavior change from calling createAppBackgroundImageSourceOnComplete and cleans up the artifacts generated by that API. Which means if the app goes into the background, the stream will be stopped again. This API must be called while the application is in the foreground, otherwise an error will be returned.

    Note

    This does not need to be called to resume streaming in the foreground. Only call this API if you want to disable the ability to stream in the background.

    Declaration

    Objective-C

    - (BOOL)removeImageSourceOnAppBackgroundedWithError:
    (NSError *_Nullable *_Nullable)outError;

    Swift

    func removeImageSourceOnAppBackgrounded() throws

    Parameters

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is an NSError object that describes the error. If you don’t want error information, pass in nil.