PrivMX DOCS
C++

Stream Events

Stream events let your application react to Stream Room lifecycle changes and live media activity.

Types of Events

Stream Room Events

streamRoomCreated / streamRoomUpdated

  • streamRoomCreated - triggers when a new Stream Room is created in your Context
  • streamRoomUpdated - triggers when a Stream Room is updated

data is the full StreamRoom object for both events – an update simply carries the Stream Room's state after the change.

C++
struct StreamRoom {
    // ID of the Context the Stream Room was created in
    std::string contextId;
    // ID of the Stream Room
    std::string streamRoomId;
    // Stream Room creation timestamp
    int64_t createDate;
    // ID of the user who created the Stream Room
    std::string creator;
    // Stream Room last modification timestamp
    int64_t lastModificationDate;
    // ID of the user who last modified the Stream Room
    std::string lastModifier;
    // IDs of users with access to the Stream Room
    std::vector<std::string> users;
    // IDs of users with management rights
    std::vector<std::string> managers;
    // version number (increment on updates)
    int64_t version;
    // Stream Room's public metadata
    core::Buffer publicMeta;
    // Stream Room's private metadata
    core::Buffer privateMeta;
    // Stream Room's policies
    core::ContainerPolicyWithoutItem policy;
    // status code of retrieval and decryption of the Stream Room (0 on success)
    int64_t statusCode;
    // version of the Stream Room data structure and how it is encoded/encrypted
    int64_t schemaVersion;
    // "created" (not used yet) | "open" (a user has joined) | "closed" (all users left and emptyRoomTtl elapsed)
    std::string state;
    // grace period (ms) the Stream Room stays open after the last participant leaves
    int64_t emptyRoomTtl;
};

streamRoomDeleted

Triggers when a Stream Room is deleted from your Context.

C++
struct StreamRoomDeletedEventData {
    // ID of the deleted Stream Room
    std::string streamRoomId;
};

streamRoomJoined / streamRoomLeft

  • streamRoomJoined - triggers when a user joins a Stream Room
  • streamRoomLeft - triggers when a user leaves a Stream Room
C++
struct StreamRoomParticipantEventData {
    // ID of the Stream Room this event concerns
    std::string streamRoomId;
    // ID of the user who joined or left the Stream Room
    std::string userId;
};

Stream Events

streamPublished

Triggers when a new Stream is published in a Stream Room.

C++
struct StreamTrackInfo {
    // track type: "audio", "video", or "data" (data channel)
    std::string type;
    // index of the track's media line in the SDP
    int64_t mindex;
    // media line ID of the track in the SDP
    std::string mid;
    // true if the track is currently paused or removed by its publisher
    bool disabled;
    // codec used by the track, if known
    std::optional<std::string> codec;
    // track description provided by its publisher
    std::optional<std::string> description;
    // true if the track has been muted by a moderator
    bool moderated;
    // true if the track is sent using simulcast
    bool simulcast;
};

struct StreamInfo {
    // ID of the Stream (its streamId)
    int64_t id;
    // ID of the user who published the Stream
    std::string userId;
    // Stream's metadata, an app-defined serialized JSON string (unrelated to publicMeta/privateMeta)
    std::optional<std::string> metadata;
    // true if the Stream is a dummy (placeholder) Stream
    bool dummy;
    // details of the Stream's tracks
    std::vector<StreamTrackInfo> tracks;
};

// StreamPublishedEventData is also known as PublishedStreamData
struct StreamPublishedEventData {
    // ID of the Stream Room the Stream was published in
    std::string streamRoomId;
    // the published Stream's info and tracks
    StreamInfo stream;
    // ID of the user who published the Stream
    std::string userId;
};

streamUpdated

Triggers when tracks are added, removed, or modified in an already-published Stream.

C++
struct StreamTrackInfo {
    // track type: "audio", "video", or "data" (data channel)
    std::string type;
    // index of the track's media line in the SDP
    int64_t mindex;
    // media line ID of the track in the SDP
    std::string mid;
    // true if the track is currently paused or removed by its publisher
    bool disabled;
    // codec used by the track, if known
    std::optional<std::string> codec;
    // track description provided by its publisher
    std::optional<std::string> description;
    // true if the track has been muted by a moderator
    bool moderated;
    // true if the track is sent using simulcast
    bool simulcast;
};

struct StreamTrackModificationPair {
    // track's state before the modification, absent if the track was just added
    std::optional<StreamTrackInfo> before;
    // track's state after the modification, absent if the track was removed
    std::optional<StreamTrackInfo> after;
};

struct StreamUpdatedEventData {
    // ID of the Stream Room the event occurred in
    std::string streamRoomId;
    // publisher Stream ID that changed
    int64_t streamId;
    // ID of the user who publishes the Stream
    std::string userId;
    // tracks added to the Stream
    std::vector<StreamTrackInfo> tracksAdded;
    // tracks removed from the Stream
    std::vector<StreamTrackInfo> tracksRemoved;
    // tracks modified in the Stream, with their state before and after the change
    std::vector<StreamTrackModificationPair> tracksModified;
};

streamUnpublished

Triggers when a Stream stops being published.

C++
struct StreamUnpublishedEventData {
    // ID of the Stream Room the Stream was published in
    std::string streamRoomId;
    // ID of the publisher Stream which stopped being published
    int64_t streamId;
};

streamSubscribed / streamUnsubscribed

  • streamSubscribed - triggers when a participant subscribes to Stream feeds
  • streamUnsubscribed - triggers when a participant unsubscribes from Stream feeds
C++
struct StreamSubscription {
    // ID of the remote Stream being subscribed to
    int64_t streamId;
    // ID of a single track, or absent to subscribe to the whole Stream
    std::optional<std::string> streamTrackId;
};

struct StreamSubscriptionEventData {
    // ID of the Stream Room this event concerns
    std::string streamRoomId;
    // ID of the user who subscribed or unsubscribed
    std::string userId;
    // list of the affected stream subscriptions
    std::vector<StreamSubscription> subscriptions;
};

Handling Stream Events

Sample code on this page is based on the initial assumptions.

Before receiving events, your application has to start an event loop and subscribe to specific events in the given scope. Use Context-level subscriptions for Stream Room lifecycle changes and Stream Room-level subscriptions for real-time activity inside a selected room.

C++
// handle events
core::EventQueue eventQueue {core::EventQueue::getInstance()};
std::thread t([&](){
    while(true) {
        core::EventHolder event = eventQueue.waitEvent();
        std::cout << "onEvent: " << event.type() << std::endl;
        std::cout << event.toJSON() << std::endl;
    }
});
t.detach();

// subscribing for Stream events
auto subscriptionIds = streamApi.subscribeFor(std::vector<std::string>{
    // subscribe to `streamRoomCreated` events in the given Context
    streamApi.buildSubscriptionQuery(
        stream::EventType::STREAMROOM_CREATE,
        stream::EventSelectorType::CONTEXT_ID,
        CONTEXT_ID
    ),
    // subscribe to `streamPublished` events in the given Stream Room
    streamApi.buildSubscriptionQuery(
        stream::EventType::STREAM_PUBLISH,
        stream::EventSelectorType::STREAMROOM_ID,
        streamRoomId
    ),
    // subscribe to `streamUnpublished` events in the given Stream Room
    streamApi.buildSubscriptionQuery(
        stream::EventType::STREAM_UNPUBLISH,
        stream::EventSelectorType::STREAMROOM_ID,
        streamRoomId
    )
});

To stop receiving events, unsubscribe using the IDs returned by subscribeFor(...).

C++
streamApi.unsubscribeFrom(subscriptionIds);

We use cookies on our website. We use them to ensure proper functioning of the site and, if you agree, for purposes such as analytics, marketing, and targeting ads.

On this page

Stream Events | PrivMX Docs