public class

BroadcastSession

extends Object
implements Releasable
java.lang.Object
   ↳ com.amazonaws.ivs.broadcast.BroadcastSession

Class Overview

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

Summary

Nested Classes
class BroadcastSession.Listener Provide a listener to receive status updates and errors from the SDK. 
enum BroadcastSession.State  
Public Constructors
BroadcastSession(Context ctx, BroadcastSession.Listener listener, BroadcastConfiguration configuration, Descriptor[] startDevices)
Create a BroadcastSession object that can stream to an IVS endpoint via RTMPS.
Public Methods
void attachDevice(Device.Descriptor descriptor, boolean bindToPreference, TypedLambda<Device> onComplete)
Asynchronously attach and open a device for use with the broadcast session
void attachDevice(Device.Descriptor descriptor, TypedLambda<Device> onComplete)
Asynchronously attach and open a device for use with the broadcast session.
void attachDevice(Device device)
Asynchronously attach a device for use with the broadcast session.
void attachDevice(Device.Descriptor descriptor)
Asynchronously attach and open a device for use with the broadcast session.
void awaitDeviceChanges(Runnable task)
Run a task upon the completion of pending device attachments or detachments.
AudioDevice createAudioInputSource(int channels, BroadcastConfiguration.AudioSampleRate sampleRate, AudioDevice.Format format)
Create an audio input for a custom source.
SurfaceSource createImageInputSource()
Create an image input for a custom source.
Notification.Builder createServiceNotificationBuilder(String channelId, String friendlyName, Intent notificationIntent)
Create a notification builder that can create a persistent notification compatible with the MediaProjection API
void createSystemCaptureSources(Intent permissionGrantedIntent, Class<?> serviceClass, Notification notification, TypedLambda<List<Device>> onComplete)
This allows you to create an ImageDevice that can be used to capture the Android device's screen and an AudioDevice that can capture the Android device's audio (API 29 and above only).
void detachDevice(Device.Descriptor toRemove)
Close and detach a device
void detachDevice(Device device)
void exchangeDevices(Device.Descriptor old, Device.Descriptor next, TypedLambda<Device> onComplete)
void exchangeDevices(Device old, Device.Descriptor next, TypedLambda<Device> onComplete)
Exchange a device with another device of the same type
Mixer getMixer()
ImagePreviewView getPreviewView()
Gets a ImagePreviewView that will display a preview of the composited stream being produced by the SDK.
ImagePreviewView getPreviewView(BroadcastConfiguration.AspectMode aspectMode)
Gets a ImagePreviewView that will display a preview of the composited stream being produced by the SDK.
String getSessionId()
static String getVersion()
boolean isReady()
This state will be set once the session has been instantiated and will not change.
synchronized List<Device> listAttachedDevices()
List attached, active devices being used with the BroadcastSession
static Descriptor[] listAvailableDevices(Context context)
List available devices for use with the BroadcastSession.
BroadcastSessionTest recommendedVideoSettings(String url, String streamKey, double duration, TypedLambda<BroadcastSessionTest.Result> onNewResult)
This will perform a network test and provide recommendations for video configurations.
BroadcastSessionTest recommendedVideoSettings(String url, String streamKey, TypedLambda<BroadcastSessionTest.Result> onNewResult)
Runs a network test with a default duration of 8 seconds.
void release()
Release BroadcastSession resources.
void setListener(Session.SessionListener listener)
Set the callback to receive state, error, and analytics data
void setLogLevel(BroadcastConfiguration.LogLevel logLevel)
Logging level for the broadcast session.
void start(String url, String streamKey)
Start the configured broadcast session
void stop()
Stop the broadcast session, but do not deallocate resources.
void stopSystemCapture()
Stop the system capture foreground service launched by createSystemCaptureSources(...) by unbinding the service, if it exists.
Protected Methods
boolean isReady(long handle)
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.amazonaws.ivs.broadcast.Releasable

Public Constructors

public BroadcastSession (Context ctx, BroadcastSession.Listener listener, BroadcastConfiguration configuration, Descriptor[] startDevices)

Create a BroadcastSession object that can stream to an IVS endpoint via RTMPS. You must interact with the Broadcast Session from the thread you create it on. If initialization fails, isReady() will return false and an error will be emitted to the provided onError(BroadcastException) callback.

Parameters
ctx the current Application context
listener a BroadcastSession.Listener object
configuration a Broadcast configuration, either one of the Presets.Configuration or a custom configuration.
startDevices an optional list of devices to instantiate immediately. To get a list of devices see listAvailableDevices(Context)

Public Methods

public void attachDevice (Device.Descriptor descriptor, boolean bindToPreference, TypedLambda<Device> onComplete)

Asynchronously attach and open a device for use with the broadcast session

Parameters
descriptor The device descriptor for the device to be attached
bindToPreference Automatically bind to a slot with a preferred input device type that matches this device type. Defining multiple slots with the same preferred device type may result in unexpected behavior.
onComplete An optional task that will be run upon completion of attaching and opening the device. This task will be run on the main thread and will have a single parameter that passes the created device. For example, attachDevice(descriptor, device -> { Log.d("Example", "Attached %s", device.friendlyName); }); This task will not be invoked if the session is released while the device is being attached, or if the device failed to be attached.
Throws
BroadcastException if the Device.Descriptor is not correct or in a valid state
BroadcastException if the session is not ready (see isReady())

public void attachDevice (Device.Descriptor descriptor, TypedLambda<Device> onComplete)

Asynchronously attach and open a device for use with the broadcast session. If there is a mixer slot with a device type preference that matches this device type it will be bound automatically. Be aware that defining multiple slots with the same preferred device type may result in unexpected behavior.

Parameters
descriptor The device descriptor for the device to be attached
onComplete An optional task that will be run upon completion of attaching and opening the device. This task will be run on the main thread and will have a single parameter that passes the created device. For example, attachDevice(descriptor, device -> { Log.d("Example", "Attached %s", device.friendlyName); }); This task will not be invoked if the session is released while the device is being attached, or if the device fails to be attached.
Throws
BroadcastException if the Device.Descriptor is not correct or in a valid state
BroadcastException if the session is not ready (see isReady())

public void attachDevice (Device device)

Asynchronously attach a device for use with the broadcast session. If there is a mixer slot with a device type preference that matches this device type it will be bound automatically. Be aware that defining multiple slots with the same preferred device type may result in unexpected behavior.

Parameters
device The device to be attached
Throws
BroadcastException if the Device is not correct or in a valid state
BroadcastException if the session is not ready (see isReady())

public void attachDevice (Device.Descriptor descriptor)

Asynchronously attach and open a device for use with the broadcast session. If you wish to be notified of completion, see the other override for attachDevice or awaitDeviceChanges(Runnable)

Parameters
descriptor The device descriptor for the device to be attached
Throws
BroadcastException if the Device.Descriptor is not correct or in a valid state
BroadcastException if the session is not ready (see isReady())

public void awaitDeviceChanges (Runnable task)

Run a task upon the completion of pending device attachments or detachments. This can be used as an alternative to including tasks with individual device changes if you wish to perform multiple changes at once.

Parameters
task The task to be run when device changes have been completed. This task will be run on the main thread. This task will not be invoked if the session is released while the device is being attached.

public AudioDevice createAudioInputSource (int channels, BroadcastConfiguration.AudioSampleRate sampleRate, AudioDevice.Format format)

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.

Parameters
channels The number of audio channels.
sampleRate The sampling rate for the PCM audio.
format The sample format.
Returns
  • An AudioDevice that represents as Surface and can receive your samples.
Throws
BroadcastException if the session is not ready (see isReady())
BroadcastException if the parameters are invalid

public SurfaceSource createImageInputSource ()

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.

Returns
  • An SurfaceSource that represents as Surface and can receive your samples.
Throws
BroadcastException if the session is not ready (see isReady())
BroadcastException if creating the image input source failed

public Notification.Builder createServiceNotificationBuilder (String channelId, String friendlyName, Intent notificationIntent)

Create a notification builder that can create a persistent notification compatible with the MediaProjection API

Parameters
channelId The identifier for the notification channel to be created, for example "ivs_notifications".
friendlyName The friendly name for the channel to be created, for example "IVS Broadcast Service".
notificationIntent The notification content activity.
Returns
  • A notification.builder that can be completed, for example: createServiceNotificationBuilder("ivs_notifications", "IVS BrodacastService", new Intent(context, activity)) .setContentText("Test text") .setContentTitle("Test title") .build();

public void createSystemCaptureSources (Intent permissionGrantedIntent, Class<?> serviceClass, Notification notification, TypedLambda<List<Device>> onComplete)

This allows you to create an ImageDevice that can be used to capture the Android device's screen and an AudioDevice that can capture the Android device's audio (API 29 and above only). Calling this will launch a foreground service for your app. Implementers will need to call https://developer.android.com/reference/android/media/projection/MediaProjectionManager#createScreenCaptureIntent() and obtain a permission granted intent from the user in order to capture the screen or audio. That intent must be passed into this function. Implementers must add the following permission to their app manifest: and you must also add the following service specification, replacing ExampleSystemCaptureService with your service class: This service must extend SystemCaptureService.

Parameters
permissionGrantedIntent An intent that gives user permission to capture the screen
serviceClass A class that extends SystemCaptureService
notification A notification that will be displayed during the lifetime of the foreground service. You can use createServiceNotificationBuilder(String, String, Intent) to provide a NotificationBuilder that should be customized. The notification is only required for Android API 26 and newer.
onComplete An optional lambda that will receive the created screen capture and audio capture devices.

public void detachDevice (Device.Descriptor toRemove)

Close and detach a device

Parameters
toRemove The descriptor for the device to close.

public void detachDevice (Device device)

public void exchangeDevices (Device.Descriptor old, Device.Descriptor next, TypedLambda<Device> onComplete)

public void exchangeDevices (Device old, Device.Descriptor next, TypedLambda<Device> onComplete)

Exchange a device with another device of the same type

Parameters
old The device to replace
next The descriptor of the new device to attach and open
onComplete an optional lambda to be run on completion
Throws
BroadcastException if the session is not ready (see isReady())
BroadcastException if the device types don't match
BroadcastException if the old device is not currently attached

public Mixer getMixer ()

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

public ImagePreviewView getPreviewView ()

Gets a ImagePreviewView that will display a preview of the composited stream being produced by the SDK. This will include all mixer slots, fill colors, etc. Warning: Using many ImagePreviewViews at once may result in performance degradation.

Returns
  • A preview of the composited image stream.
Throws
BroadcastException If unable to get the preview.

public ImagePreviewView getPreviewView (BroadcastConfiguration.AspectMode aspectMode)

Gets a ImagePreviewView that will display a preview of the composited stream being produced by the SDK. This will include all mixer slots, fill colors, etc.

Parameters
aspectMode The aspect mode the preview view should be in.
Returns
  • A preview of the composited image stream.
Throws
BroadcastException If unable to get the preview.

public String getSessionId ()

Returns
  • A unique identifier for the session. The session identifier can be shared with support or displayed in a user interface to help troubleshoot or diagnose issues.

public static String getVersion ()

Returns
  • the Broadcast SDK version string

public boolean isReady ()

This state will be set once the session has been instantiated and will not change. So if, after instantiating the BroadcastSession isReady is TRUE, it will continue to be true. If this method returns FALSE, be sure to assign a listener in the BroadcastSession constructor so that you receive the relevant error.

Returns
  • whether or not the session is ready for use.

public synchronized List<Device> listAttachedDevices ()

List attached, active devices being used with the BroadcastSession

Returns

public static Descriptor[] listAvailableDevices (Context context)

List available devices for use with the BroadcastSession.

Parameters
context the current Application context
Returns
  • a list of Device.Descriptors representing attached devices such as cameras, microphones, and screen recording sessions.

public BroadcastSessionTest recommendedVideoSettings (String url, String streamKey, double duration, TypedLambda<BroadcastSessionTest.Result> onNewResult)

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.

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.
Returns
  • a handle to the network test, providing you a way to cancel it, or `null` if there is an error starting the test.

public BroadcastSessionTest recommendedVideoSettings (String url, String streamKey, TypedLambda<BroadcastSessionTest.Result> onNewResult)

Runs a network test with a default duration of 8 seconds. recommendedVideoSettings(String, String, double, TypedLambda)

public void release ()

Release BroadcastSession resources. If a call to stop() is still in progress, this call to release will block until the stop operation completes, or the timeout is reached. This is required to properly terminate the current broadcast, otherwise the broadcast may remain live beyond the expected lifecycle. Because of the synchronous nature of calling release during a stop operation, is it recommended to wait for the disconnected state change after calling stop.

public void setListener (Session.SessionListener listener)

Set the callback to receive state, error, and analytics data

Parameters
listener a BroadcastSession.Listener object

public void setLogLevel (BroadcastConfiguration.LogLevel logLevel)

Logging level for the broadcast session. Default is `ERROR`.

public void start (String url, String streamKey)

Start the configured broadcast session

Parameters
url the RTMPS endpoint provided by IVS.
streamKey the broadcaster's stream key that has been provided by IVS.
Throws
BroadcastException if the session is not ready (see isReady())
BroadcastException if the provided url contains an unsupported scheme

public void stop ()

Stop the broadcast session, but do not deallocate resources. This operation is asynchronous. When it completes DISCONNECTED will be emitted by onStateChanged(State). If release() is called before this operation completes, the call to release will block until this operation completes, or the timeout is reached. This is required to properly terminate the current broadcast, otherwise the broadcast may remain live beyond the expected lifecycle. Because of the synchronous nature of calling release during a stop operation, is it recommended to wait for the disconnected state change.

public void stopSystemCapture ()

Stop the system capture foreground service launched by createSystemCaptureSources(...) by unbinding the service, if it exists.

Protected Methods

protected boolean isReady (long handle)