1.3.8. Media Server Services

1.3.8.1. Media server services connection

Media server services are owned and managed by the main MediaServerSession object. Services are automatically connected when the main session object itself conncts to the media session.

Note that the services connection is independent of the main media session connection. For this reason, services connect and activate shortly after the main session connection is established. Also, services may disconnect independently of the main session connection (e.g. due to poor network connectivity).

There are two events emitted by the media server session to notify when services are connected or disconnected:

// Notify when the session services are connected
mediaSession->onSessionServicesConnected(
    [](const auto& session)
    {
        // Session services are now connected and available...
    });

// Notify when the session services disconnect, possibly in error
mediaSession->onSessionServicesDisconnected(
    [](const auto& session, error_code error)
    {
        if (error) {
            // Handle error disconnecting...
        } else {
            // Session services have disconnected gracefully...
        }
    });

Because services are supplementary to the core media session functionality, service disconnection is not considered a critical error by the SDK, and it will continue to attempt reconnection automatically. Your application may consider service disconnection as an error condition that needs to be handled according to your needs (e.g. closing the session if services are disconnected for too long).

Finally, you can also check if services are currently connected directly:

if (mediaSession->areSessionServicesConnected()) {
    // Session services are currently connected...
}

1.3.8.2. Remote recording service

The remote recording feature offers the media session recording functionality available in the main Proximie Live App web application’s session interface:

• Monitor and query the status of the session recording

• Start/stop remote recordings of the media session on the media server

• Report on recording duration, including calculating live time when actively recording

If your application needs to support remote recording, there are a few steps to follow.

Firstly, you should set up a onRecordingStateChanged() callback for when the recording state changes. This callback will be invoked whenever the recording status changes, and should be considered the “source of truth” for the recording status. Even when the application requests a recording status change, the actual status could be overwritten by other participants in the session, or poor network conditions could cause delays or failures in processing the request.

// Notify when the remote recording state changes
mediaSession->onRecordingStateChanged(
    [](const auto& session, const auto& state)
    {
        // Handle recording state change in state...
        // e.g. state.on indicates if recording is active
    });

The state passed to the callback is a MediaServerSession::SessionRecordingState value object, which contains information about the current recording status.

The on member value indicates if recording is currently active or not. You can call the state’s totalRunningDurationMs() method to find the total recorded duration in milliseconds.

To request a change in the recording status, use the requestSessionRecording() method. This method sends a request to the media server to start or stop recording the session. You should check the result returned from the call to confirm the request was accepted.

// Make a request to activate recording
auto requested = mediaSession->requestSessionRecording(true);
if (!requested) {
    // Request failed...
    auto error = requested.error();
}

As noted above, the actual recording status will be reported via the recording state callback and you should not assume that the recording reflects your requested state even if the request was accepted. You can query the current recording state at any time using the sessionRecordingState() method.

auto recordingState = mediaSession->sessionRecordingState();
if (recordingState.updatePending) {
    // A recording state update is currently pending...
}

If you have made a request but not received a confirmed state via the callback, the state returned by sessionRecordingState() will have its updatePending member set to true. This indicates that the state is still pending confirmation from the media server. Importantly, the state’s on flag only ever reflects the last confirmed recording status, and is not changed when the request is sent. Therefore, your application should take care in reporting recording status to users until the pending state is resolved.

If updatePending is true

• A request has been made but is not yet confirmed,

• The current on value does not reflect the request, just the last confirmed status.

If updatePending is false:

• No requests are pending, (though of course other participants may still change the status),

• The current on value reflects the confirmed recording status.

Applications that want to show a “live” recording duration can do so by periodically checking the recording state and calling the totalRunningDurationMs() method. When recording is active, this method will return the total recorded duration including the current live time.