Page Content
Room Express
Single-step configuration based API for setting up a room - a solution for all your other streaming applications including Group Broadcast, Group Chat, and One to One Chat. The Room Express extends the lower-level Room Service API to provide easy solutions to:
- Join, create, and publish to a room
- Subscribe to streams of members in a room
Initializing
Java
import android.content.Context;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.environment.android.AndroidContext;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PCastExpressOptions;
import com.phenixrts.express.RoomExpress;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.express.RoomExpressOptions;
import com.phenixrts.pcast.PCastInitializeOptions;
// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
final Context context = ...; // e.g. Activity.getApplication();
AndroidContext.setContext(context);
final PCastExpressOptions pcastExpressOptions =
PCastExpressFactory.createPCastExpressOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withUnrecoverableErrorCallback((RequestStatus status, String description) -> {
// Best to restart app, or attempt to re-create PCastExpress
})
.buildPCastExpressOptions();
final RoomExpressOptions roomExpressOptions =
RoomExpressFactory.createRoomExpressOptionsBuilder()
.withPCastExpressOptions(pcastExpressOptions)
.buildPCastExpressOptions();
final RoomExpress roomExpress = RoomExpressFactory.createRoomExpress(roomExpressOptions);RoomExpressOptionsBuilder
| Name | Type | Default | Description |
|---|---|---|---|
| withPCastExpressOptions (required) | PCastExpressOptions | See PCastExpressOptionsBuilder | |
| buildRoomExpressOptions | none | Builds the RoomExpressOptions |
Join a Room
Join a room and optionally, automatically subscribe to member changes.
Java
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.JoinRoomOptions;
import com.phenixrts.express.RoomExpress;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.room.Member;
import com.phenixrts.room.RoomService;
final RoomExpress roomExpress = ...; // previously obtained
final JoinRoomOptions joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder()
.withRoomAlias("myRoom42")
.buildJoinRoomOptions();
roomExpress.joinRoom(joinRoomOptions, (RequestStatus status, RoomService roomService) -> {
if (status == RequestStatus.OK) {
// Hold on to roomService reference for as long as you wish to stay in the room
} else {
// Handle error
}
});
// With optional member update notification:
this.roomExpress.joinRoom(
joinRoomOptions,
(RequestStatus status, RoomService roomService) -> {
if (status == RequestStatus.OK) {
// Hold on to roomService reference for as long as you wish to stay in the room
} else {
// Handle error
}
},
(Member[] members) -> {
// Do something with room members
});Express Join Room Parameters
| Name | Type | Description |
|---|---|---|
| options (required) | JoinRoomOptions | Options to join room with |
| joinRoomCallback (required) | RoomExpress.JoinRoomCallback | Function to call on success/failure of joining the room |
| membersChangedCallback (optional) | RoomExpress.MembersChangedCallback | Function to call on when the participant members in the room changes. Returns array of Members. Callback is guaranteed to be called at least once when room is joined. |
JoinRoomOptionsBuilder
| Name | Type | Default | Description |
|---|---|---|---|
| withRoomId (required) | String | Id of channel to view | |
| withRoomAlias (optional) | String | Alias, alternative to ID | |
| withRole (optional) | MemberRole | MemberRole.AUDIENCE | The Member Role to join with |
| withScreenName (optional) | String | The member screen name to join with. A random string will be generated if not provided. | |
| withStreams (optional) | Stream[] | [] | The member streams to join with. Empty if not provided |
| buildJoinRoomOptions | none | Builds the JoinRoomOptions |
Express Join Room Callback Arguments
| Name | Type | Description |
|---|---|---|
| status | RequestStatus | The status of the operation. |
| roomService | RoomService | Phenix room service object |
Subscribe to a Member's Stream
Subscribe to a room member's stream and automatically handle audio and video state changes.
Java
import android.view.SurfaceView;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.RoomExpress;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.express.SubscribeToMemberStreamOptions;
import com.phenixrts.room.ImmutableRoom;
import com.phenixrts.room.Member;
import com.phenixrts.room.Stream;
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
final RoomExpress roomExpress = ...; // previously obtained
final ImmutableRoom room = ...; // previously obtained
final SurfaceView view = ...; // previously obtained
final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
// Just an example showing how to get a stream from a member.
// In a real-world app you would want to subscribe to the room-members-observable on the room
// to receive updates when the list of members changes, and then subscribe to the streams-observable
// on each member to access their streams.
final Member member = room.getObservableMembers().getValue()[0];
final Stream memberStream = member.getObservableStreams().getValue()[0];
final SubscribeToMemberStreamOptions options =
RoomExpressFactory.createSubscribeToMemberStreamOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withRenderer(renderSurface)
.buildSubscribeToMemberStreamOptions();
roomExpress.subscribeToMemberStream(
memberStream,
options,
(status, subscriber, renderer) -> {
if (status != RequestStatus.OK) {
// Handle subscribe error
return;
}
// Important: Store subscriber reference, otherwise we will stop subscription immediately:
//currentSubscriber = subscriber;
});Subscribe To Member Stream Parameters
| Name | Type | Description |
|---|---|---|
| memberStream (required) | Stream | The room member's stream to subscribe to |
| options (required) | Subscribe to Member's Stream Options | PCast™ Express Subscribe Options to subscribe to member stream with |
| callback (required) | Function | Function to call on success/failure of subscribing to the member stream |
SubscribeToMemberStreamOptionsBuilder
| Name | Type | Default | Description |
|---|---|---|---|
| withStreamToken (required) | NSString | The subscribe token generated using the Phenix EdgeAuth library. | |
| withRenderer (optional) | AndroidVideoRenderSurface | none | Render surface on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated. |
| withRenderer (optional) | none | false | Will trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface |
| withRendererOptions (optional) | RendererOptions | none | Options passed to renderer. Will trigger instantiation of renderer |
| withMonitor (optional) | MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptions | none | Options for monitoring a subscriber for failure |
| withTags (optional) | String[] | [] | Tags for the stream |
| buildSubscribeToMemberStreamOptions | none | Builds the SubscribeToMemberStreamOptions |
Subscribe To Member Stream Callback Arguments
| Name | Type | Description |
|---|---|---|
| status | RequestStatus | The status of the operation. |
| publisher | Subscriber | Phenix subscriber object |
| renderer | Renderer | Optional renderer if renderer was enabled, else nil |
Publish to a Room
Publish local media to a room. An error will be returned if a room corresponding to the Room Options passed does not exist. If you have not entered the room via joinRoom or publishToRoom methods then a model for Self will be created.
Java
import android.view.SurfaceView;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PublishOptions;
import com.phenixrts.express.PublishToRoomOptions;
import com.phenixrts.express.RoomExpress;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.pcast.DeviceCapability;
import com.phenixrts.pcast.FacingMode;
import com.phenixrts.pcast.RendererOptions;
import com.phenixrts.pcast.UserMediaOptions
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
import com.phenixrts.room.MemberRole;
import com.phenixrts.room.RoomOptions;
import com.phenixrts.room.RoomServiceFactory;
import com.phenixrts.room.StreamType;
final RoomExpress roomExpress = ...; // previously obtained
final SurfaceView view = ...; // previously obtained
final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
final UserMediaOptions mediaConstraints = new UserMediaOptions();
// Customize constraints if needed
final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withMediaConstraints(mediaConstraints)
.withPreviewRenderer(renderSurface)
.buildPublishOptions();
// Using RoomOptions means that the room may or may not already exist.
// If the room ID is known in advance, it is recommended to use `withRoomId` instead
// of `withRoomOptions` when assembling the `PublishToRoomOptions` below
final RoomOptions roomOptions = RoomServiceFactory.createRoomOptionsBuilder()
.withName("MyAwesomeRoom")
.buildRoomOptions();
final PublishToRoomOptions localPublishToRoomOptions =
RoomExpressFactory.createPublishToRoomOptionsBuilder()
.withStreamType(StreamType.USER)
.withMemberRole(MemberRole.PARTICIPANT)
.withRoomOptions(roomOptions)
.withPublishOptions(publishOptions)
.buildPublishToRoomOptions();
roomExpress.publishToRoom(
localPublishToRoomOptions,
(publishStatus, roomService, publisher, previewRenderer) -> {
if (publishStatus != RequestStatus.OK) {
// Handle channel publish error
return;
}
// Important: Store publisher reference, otherwise we will stop publishing again immediately:
currentPublisher = publisher;
}
);
Publish To Room Parameters
| Name | Type | Description |
|---|---|---|
| options (required) | Options | Options to publish to room with |
| callback (required) | Function | Function to call on success/failure of publishing to the room |
PublishToRoomOptionsBuilder
| Name | Type | Default | Description |
|---|---|---|---|
| withRoomOptions (required) | RoomOptions | If omitted, then withRoomId needs to be provided. | |
| withRoomId (required) | String | ID of room to publish to. If omitted, then withRoomOptions needs to be provided. | |
| withPublishOptions (required) | PublishOptions | Publish options | |
| withMemberRole (required) | MemberRole | Role of member to join room as (used if not already in room). See Member Roles | |
| withStreamType (required) | StreamType | Type of stream to publish. See Stream Types | |
| withScreenName (optional) | String | automatically generated | Screen name of self member |
| withViewerStreamSelectionStrategy (optional) | StreamSelectionStrategy | StreamSelectionStrategy.MOST_RECENT | Stream Selection Strategy |
| buildPublishToRoomOptions | none | Builds the PublishToRoomOptions |
Publish To Room Callback Arguments
| Name | Type | Description |
|---|---|---|
| status | RequestStatus | The status of the operation. |
| roomService | RoomService | Phenix room service |
| publisher | Publisher | Phenix publisher object |
| previewRenderer | Renderer | Optional renderer if preview renderer was enabled |
Get PCast™ Express
Get the underlying instance of the PCast™ Express. This is preferred to creating another instance as this will introduce more overhead.
Java
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.RoomExpress;
final RoomExpress roomExpress = ...; // previously obtained
final PCastExpress pcastExpress = roomExpress.getPCastExpress();Clean Up
Underlying resources are kept alive for as long as you hold any references to any of the returned objects (room service, subscriber, renderer) an do not call close on them. Once those references as well as any reference to the room express instance itself have been released (or close has been called), all underlying resources will be automatically cleaned up and released.
v2023-12-04T20:36:01.000Z