IVSBroadcastSession

Objective-C


@interface IVSBroadcastSession : IVSSession

Swift

class IVSBroadcastSession : IVSSession

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

  • 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: (any IVSBroadcastSession.Delegate)? { 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: (any IVSBroadcastSession.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: (any IVSBroadcastSession.Delegate)?, metalDevice: (any MTLDevice)?, metalCommandQueue: (any 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.

  • 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()

  • 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;

    Swift

    func createAppBackgroundImageSource(withAttemptTrim attemptTrim: Bool, onComplete: (((any Error)?) -> Void)? = nil) -> (any IVSBackgroundImageSource)?

    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.

  • Send timed metadata that will be automatically synchronized with the ongoing stream.

    Declaration

    Objective-C

    - (BOOL)sendTimedMetadata:(nonnull NSString *)contents
                    error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func sendTimedMetadata(_ contents: String) throws

    Parameters

    contents

    text-based metadata that will be interpreted by your receiver.

    Return Value

    YES if the operation is successful. If it returns NO then an error has occurred.