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.
-
Interface Summary Interface Description LocalScreenCaptureTrack.ScreenCaptureListener Space.AcrScoreSubmissionCallback Callback for success/failure of submitting an ACR score.Space.Listener The Listener interface is the way applications receive information about events occurring in a Space. -
Class Summary Class Description LocalAudioTrack LocalParticipant A LocalParticipant is the local peer connected to the space.LocalScreenCaptureTrack A LocalTrack specific to screen sharingLocalTrack A Track that can be published and unpublished by the LocalParticipant Can also be muted/unmutedLocalVideoCameraTrack Represents local video streams sourced from cameras Camera switching is performed hereMuxError<T extends java.lang.Enum> The base error class for the SDKParticipant A superclass of local and remote participants.RemoteParticipant A RemoteParticipant is a remote peer connected to the space.RemoteTrack A Track belonging to a remote participant.Space A Space is where participants meet.SpaceConfiguration Configuration options used for retrieving aSpace
.SpaceConfiguration.Builder A class for building SpaceConfigurations using the builder pattern.Spaces Entry point into the Mux Spaces SDK for Android app developersSpaces.SdkOptions Options which affect the whole instance of the SDK and are not alterable on a per-Space basis.Spaces.SdkOptions.Builder Track<T extends MediaStreamTrackHolder> A Track is used to interact with participant tracks. -
Enum Summary Enum Description LocalParticipant.Errors RemoteParticipant.Errors Space.AcrScore Space.BroadcastState Space.Errors Track.TrackType -
Exception Summary Exception Description SpaceConfigurationException