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 and publish to a room
• Subscribe to streams of members in a room

Initializing

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((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

Join a Room

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

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()
    .withStreamToken("stream token")
    .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

JoinRoomOptionsBuilder

Express Join Room Callback Arguments

Subscribe to a Member's Stream

Subscribe to a room member's stream and automatically handle audio and video state changes.

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

SubscribeToMemberStreamOptionsBuilder

Subscribe To Member Stream Callback Arguments

Publish to a Room

Publish local media to a room.

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.UserMediaOptions;
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 UserMediaOptions mediaConstraints = new UserMediaOptions();
// Customize constraints if needed

final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
    .withStreamToken("DIGEST:eyJhc...")
    .withMediaConstraints(mediaConstraints)
    .buildPublishOptions();

final PublishToRoomOptions localPublishToRoomOptions =
    RoomExpressFactory.createPublishToRoomOptionsBuilder()
        .withStreamType(StreamType.USER)
        .withMemberRole(MemberRole.PARTICIPANT)
        .withPublishOptions(publishOptions)
        .buildPublishToRoomOptions();

roomExpress.publishToRoom(
    localPublishToRoomOptions,
    (publishStatus, roomService, publisher) -> {
      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

PublishToRoomOptionsBuilder

Publish To Room Callback Arguments

Get PCast™ Express

Get the underlying instance of the PCast™ Express. This is preferred to creating another instance as this will introduce more overhead.

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) and do not call dispose on them. Once those references as well as any reference to the room express instance itself have been released (or dispose has been called), all underlying resources will be automatically cleaned up and released.