• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Express API
    • Channel
    • Room
    • PCast™
  • Low-Level API
    • Room
    • Chat
    • PCast™
  • Examples
  • Release Notes

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
1import android.content.Context;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.environment.android.AndroidContext;
4import com.phenixrts.express.PCastExpress;
5import com.phenixrts.express.PCastExpressFactory;
6import com.phenixrts.express.PCastExpressOptions;
7import com.phenixrts.express.RoomExpress;
8import com.phenixrts.express.RoomExpressFactory;
9import com.phenixrts.express.RoomExpressOptions;
10import com.phenixrts.pcast.PCastInitializeOptions;
11
12// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
13final Context context = ...; // e.g. Activity.getApplication();
14AndroidContext.setContext(context);
15
16final PCastExpressOptions pcastExpressOptions =
17 PCastExpressFactory.createPCastExpressOptionsBuilder()
18 .withBackendUri("https://example.yourdomain.com/phenix/")
19 .withUnrecoverableErrorCallback((RequestStatus status, String description) -> {
20 // Best to restart app, or attempt to re-create PCastExpress
21 })
22 .buildPCastExpressOptions();
23
24final RoomExpressOptions roomExpressOptions =
25 RoomExpressFactory.createRoomExpressOptionsBuilder()
26 .withPCastExpressOptions(pcastExpressOptions)
27 .buildPCastExpressOptions();
28
29final RoomExpress roomExpress = RoomExpressFactory.createRoomExpress(roomExpressOptions);

RoomExpressOptionsBuilder

NameTypeDefaultDescription
withPCastExpressOptions (required)PCastExpressOptionsSee PCastExpressOptionsBuilder
buildRoomExpressOptionsnoneBuilds the RoomExpressOptions

Join a Room

Join a room and optionally, automatically subscribe to member changes.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.express.JoinRoomOptions;
3import com.phenixrts.express.RoomExpress;
4import com.phenixrts.express.RoomExpressFactory;
5import com.phenixrts.room.Member;
6import com.phenixrts.room.RoomService;
7
8final RoomExpress roomExpress = ...; // previously obtained
9
10final JoinRoomOptions joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder()
11 .withRoomAlias("myRoom42")
12 .withCapabilities(new String[] {"streaming"})
13 .buildJoinRoomOptions();
14
15roomExpress.joinRoom(joinRoomOptions, (RequestStatus status, RoomService roomService) -> {
16 if (status == RequestStatus.OK) {
17 // Hold on to roomService reference for as long as you wish to stay in the room
18 } else {
19 // Handle error
20 }
21});
22
23// With optional member update notification:
24this.roomExpress.joinRoom(
25 joinRoomOptions,
26 (RequestStatus status, RoomService roomService) -> {
27 if (status == RequestStatus.OK) {
28 // Hold on to roomService reference for as long as you wish to stay in the room
29 } else {
30 // Handle error
31 }
32 },
33 (Member[] members) -> {
34 // Do something with room members
35 });

Express Join Room Parameters

NameTypeDescription
options (required)JoinRoomOptionsOptions to join room with
joinRoomCallback (required)RoomExpress.JoinRoomCallbackFunction to call on success/failure of joining the room
membersChangedCallback (optional)RoomExpress.MembersChangedCallbackFunction 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

NameTypeDefaultDescription
withRoomId (required)StringId of channel to view
withRoomAlias (optional)StringAlias, alternative to ID
withCapabilities (required)String[]The list of all capabilities to subscribe with.
withRole (optional)MemberRoleMemberRole.AUDIENCEThe Member Role to join with
withScreenName (optional)StringThe 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
buildJoinRoomOptionsnoneBuilds the JoinRoomOptions

Express Join Room Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
roomServiceRoomServicePhenix 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
1import android.view.SurfaceView;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.express.RoomExpress;
4import com.phenixrts.express.RoomExpressFactory;
5import com.phenixrts.express.SubscribeToMemberStreamOptions;
6import com.phenixrts.room.ImmutableRoom;
7import com.phenixrts.room.Member;
8import com.phenixrts.room.Stream;
9import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
10
11final RoomExpress roomExpress = ...; // previously obtained
12final ImmutableRoom room = ...; // previously obtained
13final SurfaceView view = ...; // previously obtained
14
15final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
16
17// Just an example showing how to get a stream from a member.
18// In a real-world app you would want to subscribe to the room-members-observable on the room
19// to receive updates when the list of members changes, and then subscribe to the streams-observable
20// on each member to access their streams.
21final Member member = room.getObservableMembers().getValue()[0];
22final Stream memberStream = member.getObservableStreams().getValue()[0];
23
24final SubscribeToMemberStreamOptions options =
25 RoomExpressFactory.createSubscribeToMemberStreamOptionsBuilder()
26 .withRenderer(renderSurface)
27 .buildSubscribeToMemberStreamOptions();
28
29roomExpress.subscribeToMemberStream(
30 memberStream,
31 options,
32 (status, subscriber, renderer) -> {
33 if (status != RequestStatus.OK) {
34 // Handle subscribe error
35 return;
36 }
37
38 // Important: Store subscriber reference, otherwise we will stop subscription immediately:
39 //currentSubscriber = subscriber;
40 });

Subscribe To Member Stream Parameters

NameTypeDescription
memberStream (required)StreamThe room member's stream to subscribe to
options (required)Subscribe to Member's Stream OptionsPCast™ Express Subscribe Options to subscribe to member stream with
callback (required)FunctionFunction to call on success/failure of subscribing to the member stream

SubscribeToMemberStreamOptionsBuilder

NameTypeDefaultDescription
withCapabilities (optional)String[][]The list of all capabilities to subscribe with
withRenderer (optional)AndroidVideoRenderSurfacenoneRender surface on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated.
withRenderer (optional)nonefalseWill trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface
withRendererOptions (optional)RendererOptionsnoneOptions passed to renderer. Will trigger instantiation of renderer
withMonitor (optional)MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptionsnoneOptions for monitoring a subscriber for failure
withConnectOptions (optional)String[][]List of options for subscribing
withTags (optional)String[][]Tags for the stream
buildSubscribeToMemberStreamOptionsnoneBuilds the SubscribeToMemberStreamOptions

Subscribe To Member Stream Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
publisherSubscriberPhenix subscriber object
rendererRendererOptional renderer if renderer was enabled, else nil

Publish to a Room

Publish local or remote 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
1import android.view.SurfaceView;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.express.PCastExpressFactory;
4import com.phenixrts.express.PublishOptions;
5import com.phenixrts.express.PublishRemoteOptions;
6import com.phenixrts.express.PublishToRoomOptions;
7import com.phenixrts.express.RoomExpress;
8import com.phenixrts.express.RoomExpressFactory;
9import com.phenixrts.pcast.DeviceCapability;
10import com.phenixrts.pcast.FacingMode;
11import com.phenixrts.pcast.RendererOptions;
12import com.phenixrts.pcast.UserMediaOptions
13import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
14import com.phenixrts.room.MemberRole;
15import com.phenixrts.room.RoomOptions;
16import com.phenixrts.room.RoomServiceFactory;
17import com.phenixrts.room.StreamType;
18
19final RoomExpress roomExpress = ...; // previously obtained
20final SurfaceView view = ...; // previously obtained
21
22final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
23
24final UserMediaOptions mediaConstraints = new UserMediaOptions();
25// Customize constraints if needed
26
27final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
28 .withCapabilities(new String[]{"hd", "streaming"})
29 .withMediaConstraints(mediaConstraints)
30 .withPreviewRenderer(renderSurface)
31 .buildPublishOptions();
32
33// Using RoomOptions means that the room may or may not already exist.
34// If the room ID is known in advance, it is recommended to use `withRoomId` instead
35// of `withRoomOptions` when assembling the `PublishToRoomOptions` below
36final RoomOptions roomOptions = RoomServiceFactory.createRoomOptionsBuilder()
37 .withName("MyAwesomeRoom")
38 .buildRoomOptions();
39
40final PublishToRoomOptions localPublishToRoomOptions =
41 RoomExpressFactory.createPublishToRoomOptionsBuilder()
42 .withStreamType(StreamType.USER)
43 .withMemberRole(MemberRole.PARTICIPANT)
44 .withRoomOptions(roomOptions)
45 .withPublishOptions(publishOptions)
46 .buildPublishToRoomOptions();
47
48roomExpress.publishToRoom(
49 localPublishToRoomOptions,
50 (publishStatus, roomService, publisher, previewRenderer) -> {
51 if (publishStatus != RequestStatus.OK) {
52 // Handle channel publish error
53 return;
54 }
55
56 // Important: Store publisher reference, otherwise we will stop publishing again immediately:
57 currentPublisher = publisher;
58 }
59);
60
61// OR for a remote stream:
62final PublishRemoteOptions remotePublishOptions = PCastExpressFactory
63 .createPublishRemoteOptionsBuilder()
64 .withStreamUri("http://example.com/mystream.mp4")
65 .buildPublishRemoteOptions();
66
67final PublishToRoomOptions remotePublishToRoomOptions =
68 RoomExpressFactory.createPublishToRoomOptionsBuilder()
69 .withStreamType(StreamType.USER)
70 .withMemberRole(MemberRole.PARTICIPANT)
71 .withRoomOptions(roomOptions)
72 .withPublishRemoteOptions(remotePublishOptions)
73 .buildPublishToRoomOptions();
74
75// Remaining code is the same as for local stream

Publish To Room Parameters

NameTypeDescription
options (required)OptionsOptions to publish to room with
callback (required)FunctionFunction to call on success/failure of publishing to the room

PublishToRoomOptionsBuilder

NameTypeDefaultDescription
withRoomOptions (required)RoomOptionsIf omitted, then withRoomId needs to be provided.
withRoomId (required)StringID of room to publish to. If omitted, then withRoomOptions needs to be provided.
withPublishOptions (required)PublishOptionsEither local or remote publish options are required
withPublishRemoteOptions (required)PublishRemoteOptionsEither local or remote publish options are required
withMemberRole (required)MemberRoleRole of member to join room as (used if not already in room). See Member Roles
withStreamType (required)StreamTypeType of stream to publish. See Stream Types
withScreenName (optional)Stringautomatically generatedScreen name of self member
withViewerStreamSelectionStrategy (optional)StreamSelectionStrategyStreamSelectionStrategy.MOST_RECENTStream Selection Strategy
buildPublishToRoomOptionsnoneBuilds the PublishToRoomOptions

Publish To Room Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
roomServiceRoomServicePhenix room service
publisherPublisherPhenix publisher object
previewRendererRendererOptional 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
1import com.phenixrts.express.PCastExpress;
2import com.phenixrts.express.RoomExpress;
3
4final RoomExpress roomExpress = ...; // previously obtained
5
6final 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.

Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10