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 rooms
- Subscribe to streams of members in a room
Initializing
JavaScript
const roomExpressOptions = {
authToken: token,
};
var roomExpress = new sdk.express.RoomExpress(roomExpressOptions);
Initializing Options
Name | Type | Description |
---|---|---|
adminApiProxyClient (optional) (deprecated) | [object AdminApiProxyClient] | It manages tokens if they are not passed in via options. Can not be used together with authToken, publishToken and streamToken options. |
features (optional) | [Array Feature] | The list of features you would like supported. |
onError (optional) | Function | Function to be called when authentication fails or a failure occurs that is unrecoverable. |
authToken (optional) | String | A token used for authentication. |
pcastExpress (optional) | [object PCastExpress] | Optionally pass in an already instantiated PCastExpress. This reduces the amount of overhead and is preferred to instantiating separate instances. If provided backendUri and authenticationData are not required. |
treatBackgroundAsOffline (optional) | Boolean | Treat background as offline. This is especially useful on iOS browsers where the network connection may be stopped when the browser is in background. This forces a reconnect upon entering foreground which can greatly improve the time to reconnect. |
reAuthenticateOnForeground (optional) | Boolean | Re-authenticate when entering foreground. This will force the session and connection to be revalidated upon entering foreground. This is automatically set to true if the treatBackgroundAsOffline option is enabled. |
Clean Up Room Express
Dispose of all connections and clean up handlers.
JavaScript
roomExpress.dispose();
Join a Room
Join a room and automatically subscribe to member changes.
JavaScript
var options = {
role: 'Audience',
alias: 'MyAwesomeRoomAlias', // Not required but if its provided we will use this as the alias instead of pre-generating one for you.
screenName: 'MyAwesomeScreenName',
};
roomExpress.joinRoom(
options,
function joinRoomCallback(error, response) {
if (error) {
// Handle error
}
if (response.status === 'room-not-found') {
// Handle room not found
} else if (response.status !== 'ok') {
// Handle error
}
// Successfully joined room
if (response.status === 'ok' && response.roomService) {
// Do something with roomService
}
},
function membersChangedCallback(members) {
// Successfully subscribed to observable members
// Do something with members
}
);
Join Room Parameters
Name | Type | Description |
---|---|---|
options (required) | Options | Options to join room with |
joinRoomCallback (required) | Function | Function to call on success/failure of joining the room |
membersChangedCallback (required) | Function | Function to call on when the participant members in the room changes. Returns array of Members. |
Join Room Options
Name | Type | Default Value | Description |
---|---|---|---|
role (required) | String | Member Role to join room as | |
alias (required) | String | Alias of the room to view | |
roomId (optional) | String | Alternative to alias - Id of the room to view | |
screenName (optional) | String | Member screen name to join room with | |
streams (optional) | Array of Objects | Streams to join room with |
Express Join Room Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Join Room Callback Status Codes |
roomService | [object RoomService] | Phenix room service object |
room | [object Room] | Immutable Phenix room object |
Subscribe to a Member's Stream
Subscribe to a room member's stream and automatically handle audio and video state changes.
JavaScript
var memberStream = member.getObservableStreams().getValue()[0];
var options = {
videoElement: document.querySelector('#myVideoId'),
};
roomExpress.subscribeToMemberStream(
memberStream,
options,
function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully subscribed to stream
if (response.status === 'ok' && response.mediaStream) {
// Do something with mediaStream
}
}
);
Subscribe to Member's Stream Parameters
Name | Type | Description |
---|---|---|
memberStream (required) | [object 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 |
Subscribe to Member's Stream Options
Name | Type | Default Value | Description |
---|---|---|---|
streamToken (optional) | String | The subscribe token generated using the Phenix EdgeAuth library. | |
videoElement (optional) | html5 video element | Video element to attach media stream to. If nothing is passed you may manually attach the media stream to an element. | |
monitor (optional) | Object | Monitor Options | |
connectOptions (optional) | Array of Strings | List of options for subscribing | |
tags (optional) | Array of Strings | Tags for the stream | |
subscriberOptions (optional) | [Object SubscriberOptions] | Additional options to use when subscribing. |
Publish to a Room
Publish to a local or remote media to a room.
Publishing remote media from the WebSDK is deprecated. Remote media should be published using the REST API.
JavaScript
var options = {
room: {
name: 'MyAwesomeRoom',
alias: 'MyAwesomeRoomAlias', // Not required but if its provided we will use this as the alias instead of pre-generating one for you.
},
streamType: 'User',
memberRole: 'Participant',
publishToken: 'DIGEST:...',
mediaConstraints: { audio: true, video: true },
videoElement: document.querySelector('#myVideoId'),
};
roomExpress.publishToRoom(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully published to room
if (response.status === 'ok' && response.publisher) {
// Do something with 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 |
Publish To Room Options
Name | Type | Default Value | Description |
---|---|---|---|
room (required) | Object | Room Options | |
streamType (required) | String | Type of stream to publish. See Stream Types | |
memberRole (required) | String | Role of member to join room as (used if not already in room). See Member Roles | |
capabilities (optional) (deprecated) | Array | The list of all capabilities to publish with. | |
mediaConstraints (required) | Object | Media constraints on the getting the user media. For example - {audio: true, video: true} | |
userMediaStream (optional) | Object | alternative to getUserMediaOptions - you can pass user media stream returned from getUserMedia. | |
streamUri (optional) | String | alternative to getUserMediaOptions . Use to publish remote media. Link to remote media (mp4, rtmp, etc.) | |
resolution (optional) | number | 720 | Desired size of the video |
frameRate (optional) | number | 15 | Desired frame rate of the video |
aspectRatio (optional) | string | 16x9 | Desired aspect ratio of the video |
onResolveMedia (optional) | function | Returns the options that were used to successfully get user media | |
publishToken (optional) | String | This token is a publish token that will include all capabilities and access rights to publish. | |
videoElement (optional) | html5 video element | Video element to attach media stream to. If nothing is passed you may manually attach the media stream to an element. | |
monitor (optional) | Object | Options for monitoring a publisher for failure. | |
connectOptions (optional) | Array of Strings | List of options for publishing from a remote source. | |
tags (optional) | Array of Strings | Tags for the stream | |
prerollSkipDuration (optional) | int | 500 | Remote media only. The amount of milliseconds to skip at the beginning of the media. |
Publish To Room Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Publish Callback Status Codes |
publisher | [object Publisher] | Phenix publisher object |
Create a Room (deprecated)
Creation of Rooms from client SDKs is deprecated. Rooms should be created by the backend using the REST API.
Create a room of any type.
JavaScript
var options = {
room: {
name: 'MyAwesomeRoom',
alias: 'MyAwesomeRoomAlias', // Not required but if its provided we will use this as the alias instead of pre-generating one for you.
},
};
roomExpress.createRoom(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status === 'already-exists') {
// Room already exists
// Do something with roomService
} else if (response.status !== 'ok') {
// Handle error
}
// Successfully created room
if (response.status === 'ok' && response.room) {
// Do something with room
}
});
Create Room Options
Name | Type | Default Value | Description |
---|---|---|---|
room (required) | Object | Room Options |
Express Create Room Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Create Room Callback Status Codes |
room | [object Room] | Immutable Phenix room object |
v2025-01-13T17:19:39.000Z