IVSSession

Objective-C


@interface IVSSession : NSObject

Swift

class IVSSession : NSObject

The base of both Broadcast and Stage Sessions, providing common APIs for working with devices and getting a preview for the composited session.

  • 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) IVSSessionAudioSessionStrategy applicationAudioSessionStrategy;

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

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

    Declaration

    Objective-C

    @property (nonatomic) IVSBroadcastLogLevel logLevel;

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

    Declaration

    Objective-C

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

    Swift

    var mixer: IVSMixer { get }

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

    @discussion

    The return order of these devices is predictable:

    • All cameras will be returned before any microphones.

    Devices of the same type with be sorted by, in priority order:

    • position (based on rawValue of the IVSDevicePosition enum in ascending order)
    • isDefault (YES will appear before NO)
    • friendlyName (sorted alphabetically in ascending order)

    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() -> [any 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: (((any IVSDevice)?, (any 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: any IVSDevice, toSlotWithName slotName: String?, onComplete: (((any 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 (^)(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 (^)(void))onComplete;

    Swift

    func detach(_ device: any 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: any IVSDevice, withNewDevice newDevice: IVSDeviceDescriptor, onComplete: (((any IVSDevice)?, (any 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 (^)(void))onComplete;

    Swift

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

    Parameters

    onComplete

    Always invoked on the main queue.

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

    Swift

    func createImageSource(withName name: String) -> any IVSCustomImageSource

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

    Swift

    func createAudioSource(withName name: String) -> any IVSCustomAudioSource

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