Working with Streams

Streams allow users to communicate in real time using audio, video, and desktop sharing inside Stream Rooms. Each Context can contain any number of Stream Rooms identified by streamRoomId.

Before working with Streams, follow the Getting Started Guide.

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

To work with Streams, use StreamApi, which provides methods used to manage Stream Rooms and real-time media streams.

C++

// initialize Endpoint connection and APIs required by Stream API
auto connection = core::Connection::connect(userPrivKey, solutionId, bridgeUrl);
auto eventApi = event::EventApi::create(connection);
auto streamApi = stream::StreamApi::create(connection, eventApi);

Creating Stream Rooms

Use createStreamRoom(...) to create a room with selected users, managers, and metadata.

C++

// creating Stream Room
auto streamRoomId = streamApi.createStreamRoom(
    contextId,
    users,
    users,
    core::Buffer::from("stream-room-public-meta"),
    core::Buffer::from("stream-room-private-meta"),
    std::nullopt
);
std::cout << "CREATED_STREAM_ROOM_ID: " << streamRoomId << std::endl;

Listing and Reading Stream Rooms

Use listStreamRooms(...) for paged room listing and getStreamRoom(...) to fetch a single room.

C++

// listing Stream Rooms
auto streamRooms = streamApi.listStreamRooms(contextId, defaultListQuery);
std::cout << "STREAM_ROOMS: " << streamRooms.readItems.size() << std::endl;

C++

// getting Stream Room
auto createdStreamRoom = streamApi.getStreamRoom(streamRoomId);
std::cout << "STREAM_ROOM_VERSION: " << createdStreamRoom.version << std::endl;

Updating and Deleting Stream Rooms

Use updateStreamRoom(...) to overwrite the current room definition, including users, managers, metadata, and version.

C++

// updating Stream Room
streamApi.updateStreamRoom(
    streamRoomId,
    users,
    users,
    createdStreamRoom.publicMeta,
    core::Buffer::from("new-private-meta"),
    createdStreamRoom.version,
    false,
    false,
    createdStreamRoom.policy
);

C++

// deleting Stream Room
bool deleteStreamRoomAtEnd = false;
if (deleteStreamRoomAtEnd) {
    streamApi.deleteStreamRoom(streamRoomId);
}

Devices and Track Sources

The API lets you inspect local capture sources using:

getAudioDevices()
getVideoDevices()
getDesktopDevices(...)

C++

// listing local media devices
auto audioDevices = streamApi.getAudioDevices();
auto videoDevices = streamApi.getVideoDevices();
auto desktopDevices = streamApi.getDesktopDevices(stream::DesktopType::Screen);
std::cout << "AUDIO_DEVICES: " << audioDevices.size() << std::endl;
std::cout << "VIDEO_DEVICES: " << videoDevices.size() << std::endl;
std::cout << "DESKTOP_DEVICES: " << desktopDevices.size() << std::endl;

Joining a Room and Publishing a Stream

Join the room before creating local streams or subscribing to remote ones. Then create a stream handle, add tracks, and publish it.

C++

// joining Stream Room
streamApi.joinStreamRoom(streamRoomId);

// listing published streams
auto streamsBeforePublish = streamApi.listStreams(streamRoomId);
std::cout << "STREAMS_BEFORE_PUBLISH: " << streamsBeforePublish.size() << std::endl;

// creating local stream handle
auto streamHandle = streamApi.createStream(streamRoomId);

// adding local track
std::optional<stream::MediaDevice> selectedAudioDevice;
if (!audioDevices.empty()) {
    selectedAudioDevice = audioDevices.front();
    stream::MediaTrackConstrains constrains;
    auto localTrack = streamApi.addTrack(streamHandle, *selectedAudioDevice, constrains);
    localTrack.setEnabled(true);
}

// publishing stream
auto publishResult = streamApi.publishStream(streamHandle);
std::cout << "PUBLISH_RESULT: " << publishResult.published << std::endl;

If you add or remove tracks after publishing, call updateStream(...). To stop sending media, call unpublishStream(...).

C++

// updating published stream after removing track
if (selectedAudioDevice.has_value()) {
    streamApi.removeTrack(streamHandle, *selectedAudioDevice);
    auto updateResult = streamApi.updateStream(streamHandle);
    std::cout << "UPDATE_RESULT: " << updateResult.published << std::endl;
}

Use listStreams(...) to inspect currently published streams and subscribeToRemoteStreams(...) to receive selected remote tracks. Incoming tracks are handled through addRemoteStreamListener(...).

C++

// subscribing to remote streams
if (!streamsAfterPublish.empty()) {
    stream::StreamSubscription subscription;
    subscription.streamId = streamsAfterPublish.front().id;
    streamApi.subscribeToRemoteStreams(streamRoomId, {subscription});

    // modifying remote streams subscriptions
    streamApi.modifyRemoteStreamsSubscriptions(streamRoomId, {subscription}, {});

    // unsubscribing from remote streams
    streamApi.unsubscribeFromRemoteStreams(streamRoomId, {subscription});
}

C++

// adding remote stream listener
auto listener = std::make_shared<SampleOnTrackListener>();
streamApi.addRemoteStreamListener(streamRoomId, std::nullopt, listener);

To react to room and stream changes, continue with Stream Events.

Working with Streams