Skip to main content

Introducing API Stream Forward

· 4 min read
Stefan Benicke
Stefan Benicke
Senior Developer @ Eyeson

The Eyeson API provides a powerful way to forward the stream of any meeting client in real-time and at its original quality to your desired destination for further processing.

This feature forms the backbone of the Eyeson AI Adatpter.

tl;dr
  • Your API key is required
  • You can forward a single stream from any client (source), the entire meeting stream (MCU), or a public video file (playback)
  • A WHIP-compatible destination endpoint is expected
  • You can forward audio only, video only, or both
  • The same stream can be forwarded multiple times to different destinations

For full API documentation, visit https://docs.eyeson.com/docs/rest/references/forward.

Structure​

Eyeson Video Meetings are built on MCU (Multipoint Control Unit) technology. In this system, a media server aggregates, processes, and combines multiple audio and video streams into one or a few unified streams. To learn more about MCU, read Understanding SFU, MCU & Eyeson’s MCU+.

The Eyeson API allows you to forward the incoming media stream directly, before it even reaches the media server.

You can also forward the generated MCU+ One View media stream.

Setup​

To make sure only authorized people can forward a stream, authentication with an API key is required.

You will need a compatible WHIP (WebRTC-HTTP Ingestion Protocol) server as the destination endpoint.

While the same source can be forwarded to multiple destinations, each forward request must have its unique forward-id.

When the source is disconnected, the forward will automatically stop. To detect disconnections, you can use the Eyeson Meeting Observer's participant_update and playback_update. These provide insights when a source drops out or reconnects.

Application​

This feature is the foundation of the Eyeson AI Adatpter which allows a customer-implemented AI module to process streams and return instructions, such as layout changes or enhanced audio/video content. Since the AI module runs on the customer’s side, this setup is flexible and supports many use cases.

In its simplest form, you might want to capture important streams for processing or recording in their original quality, even if they are not visible on the MCU media stream.

API Usage​

The full API documentation is available at /docs/rest/references/forward.

To make integration easier, we've provided SDKs for quick implementation in Node.js, Go, and PHP.

Start a Source Forward​

The following example demonstrates how to forward a video source. For more examples, refer to the API documentation.

curl -X POST \
-H "Authorization: $API_KEY" \
-d "forward_id=$FORWARD_ID" \
-d "user_id=$USER_ID" \
-d "type=video" \
-d "url=${https://example.com/whip}" \
"https://api.eyeson.team/rooms/$ROOM_ID/forward/source"

Stop Any Active Forward​

curl -X GET \
-H "Authorization: $API_KEY" \
"https://api.eyeson.team/rooms/$ROOM_ID/forward/$FORWARD_ID"

Combination with Meeting Observer​

We recommend combining the forward stream feature with the Eyeson Meeting Observer to track each client’s connection and disconnection states, as the forward stream does not automatically handle these events.

import Eyeson from '@eyeson/node';

const eyeson = new Eyeson({ apiKey: '<API_KEY>' });
const room_id = '<ROOM_ID>';
const user_id = '<USER_ID>';

const forward = eyeson.createRoomForward(room_id);

const connection = eyeson.observer.connect(room_id);
connection.on('event', event => {
    if (event.type === 'room_update') {
        const { participants } = event.content;
        if (participants.some(({ id }) => id === user_id)) {
            startForwardUser();
        }
    }
    else if (event.type === 'participant_update') {
        const { id, online } = event.participant;
        if (id === user_id && online) {
            startForwardUser();
        }
    }
});

const startForwardUser = async () => {
    await forward.source('<FORWARD_ID>', user_id, 'video', 'https://example.com/whip...');
};

Contact​

We’d love to hear from you!

If you have any questions or would like to share feedback, feel free to create a ticket on GitHub.