Stream Events

Listening for Stream events lets your app react to room lifecycle changes and real-time media activity.

Types of Events

The Stream module exposes the following event groups:

• streamRoomCreated - triggers when a new Stream Room is created
• streamRoomUpdated - triggers when a Stream Room is updated
• streamRoomDeleted - triggers when a Stream Room is deleted
• streamJoined - triggers when a user joins and publishes stream identifiers in a room
• streamPublished - triggers when a stream is published
• streamUpdated - triggers when a published stream changes
• streamUnpublished - triggers when a stream is unpublished
• streamLeft - triggers when a stream leaves the room
• remoteStreamsChanged - triggers when the set of remote streams available for subscription changes
• streamsUpdated - triggers when subscribed stream information changes

Handling Stream Events

Before receiving events, your application has to start an event loop and subscribe to specific events in the required scope. Use buildSubscriptionQuery(...) together with subscribeFor(...) to register subscriptions.

// subscribing for Stream events
const subscriptionIds = await streamApi.subscribeFor([
    await streamApi.buildSubscriptionQuery(
        Types.StreamEventType.STREAMROOM_CREATE,
        Types.StreamEventSelectorType.CONTEXT_ID,
        contextId,
    ),
    await streamApi.buildSubscriptionQuery(
        Types.StreamEventType.STREAM_PUBLISH,
        Types.StreamEventSelectorType.STREAMROOM_ID,
        streamRoomId,
    ),
    await streamApi.buildSubscriptionQuery(
        Types.StreamEventType.STREAM_UNPUBLISH,
        Types.StreamEventSelectorType.STREAMROOM_ID,
        streamRoomId,
    ),
]);
console.log("STREAM_EVENT_SUBSCRIPTIONS", subscriptionIds);

// reading one event from EventQueue
const eventQueue = await Endpoint.getEventQueue();
eventQueue.waitEvent().then((event) => {
    if (event.type.startsWith("stream")) {
        console.log("STREAM_EVENT", event);
    }
});

Choosing a Scope

StreamApi.buildSubscriptionQuery(...) uses:

• EventType - the type of Stream event to listen for
• EventSelectorType - the scope of the subscription
• selector ID - the concrete Context, Stream Room, or Stream ID

Typical scopes are:

• CONTEXT_ID - listen for room creation or updates in a whole Context
• STREAMROOM_ID - listen for publish, update, and room-specific activity
• STREAM_ID - listen for changes related to a particular stream

Recommended Usage

In most apps, a good setup is:

• subscribe at Context level for room lifecycle events
• subscribe at Stream Room level when a user enters a live room
• update the UI after remoteStreamsChanged and streamsUpdated
• clean up subscriptions when leaving the room

// unsubscribing from Stream events
await streamApi.unsubscribeFrom(subscriptionIds);