Package com.mux.sdk.webrtc.spaces

Mux Real Time Spaces SDK for Android

Welcome to the Mux Real Time Spaces SDK beta! Please note that while the API in here is intended to be stable there are still edges and some change in future is inevitable. If something isn't a public method please don't use it, and avoid anything in the "internal" package as that is assumed by us to be totally changeable.

There is an online getting started guide, and we assume you found us through that. It is the best overall introduction to the platform and SDKs at this time and can be found on the Mux website.

If anything comes up please email us at real-time-video@mux.com

Concepts

The Android SDK follows a similar class hierarchy to the JavaScript one, with slight adjustments to Android idioms, such as using a listener (also known as the observer pattern) for event delivery and the very different view system.

Spaces

Spaces is the core entity of the SDK. You use this to obtain instances of the Space class by creating a SpaceConfiguration, using a SpaceConfiguration.Builder.

Space

A Mux Space is where participants gather. After joining a Space the LocalParticipant can publish media such as audio and video. As well as subscribe to other participants' published media in the form of tracks. After joining a Space events are delivered to the Space.Listener on the application main thread so that it is safe to directly access view components from callbacks.

Participant

A Participant is someone who has joined a Space. They know about other participants in the Space and can publish media for other participants to subscribe to. In the SDK we differentiate between a LocalParticipant and RemoteParticipant because a LocalParticipant can publish their own tracks, mute themselves and unpublish tracks. Unlike the JavaScript SDK "Participant Events" are actually emitted via Space.Listener.

Track

A Track is audio or video media that is published and subscribed to. This usually comes in the form of webcam video, microphone audio, or screen share audio and video. Events related to the Tracks are also emitted by the Space.Listener.

We similarly distinguish between LocalTrack and RemoteTrack.

Events

Unlike the JavaScript SDK for simplicity all events on Android are dispatched through the Space.Listener. All calls are made on the main application UI thread so that it is safe to access your Views directly. This does also mean you shouldn't initiate long running tasks in listener callbacks. The API of the SDK is non-blocking, so it is safe to call methods like publish, however, this is also why there is an onError callback as opposed to traditional try/catch.

Views

For actually displaying video the SDK provides a TrackRendererSurfaceView class. This contains a SurfaceView in a layout and provides some convenience functions for things like aspect ratio management.

In the case of audio right now if the app is subscribed to an audio track it will be mixed automatically.

In all cases it is not recommended to attempt to access the MediaStreamTrack directly as the lifecycle and behaviour of doing so is subject to change. If you have a use case for doing this please reach out to us at real-time-video@mux.com

Subscription Model

In Spaces there is the notion of subscriptions. In this context "subscribing" to a remote track means you will start receiving the media associated with the track. "Unsubscribing" from a track means you will no longer receive media for that track. It is important to distinguish between when a track is published and when you subscribe to it.

Automatic mode

By default, an instance of a Space operates under the automatic mode, which works by subscribing to a maximum of 20 participants which have the highest priority server-side. For example, recently speaking and non-muted participants have higher priority than non-speaking and muted participants, and you will automatically be subscribed to such participants if you are unsubscribed.

To alter this parameter call SpaceConfiguration.Builder.setManagedSubscriptions(int) with the desired maximum.

Manual mode

If you need custom subscription logic, you may programmatically use the manual mode to subscribe to a RemoteParticipant using the RemoteParticipant.subscribe and RemoteParticipant.unsubscribe methods

This is activated by calling SpaceConfiguration.Builder.setManagedSubscriptions(int) with 0.