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 an 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 reeached. Because of that it is recommended that you always explicitly stop a live broadcast before deallocating.

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

    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

    device

    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

    device

    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.

    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.