Consume a stream

Overview

While being connected to a session, a peer can subscribe to listen to any stream published to the session. The stream can be published by the peer itself or by another peer connected to the session.

Listen for stream added events

To listen for stream added events, you need to register a listener for the stream_added event. The event handler receives a StreamRemote object as an argument. The StreamRemote object contains the following properties:

• kind: The type of the stream. Can be video or audio.
• peerId: The peer ID of the peer who published the stream.
• peerHash: The peer hash of the peer who published the stream.
• name: The name of the stream. Which is the same as the name of which the peer who published the stream assigned.

Having the StreamRemote object, you can subscribe to the stream by creating a new consumer. And view the stream by calling the view method on the consumer object.

session.on("stream_added", (stream) => {
  const consumer = session.createConsumer(stream);
  const stream = consumer.view("key");
});

The view method takes a required argument key which is the key for the Session to keep track of. Mostly used for limiting the simulcast layers.

note

If you want to listen to your own stream, you can use the mystream_added event instead of the stream_added event.

Simulcast

If the stream is published with simulcast, you can specify which layers you want to view by passing the limit parameter to the view method. The limit parameter is a StreamLimit object which contains the following properties:

• priority: The priority of the layer. Can be any positive integer. This is to specify which layer to view first.
• maxSpatial: The maximum spatial layer to view. Can be any positive integer.
• maxTemporal: The maximum temporal layer to view. Can be any positive integer.
• minSpatial: The minimum spatial layer to view (Optional).
• minTemporal: The minimum temporal layer to view (Optional).

consumer.view("key", {
  priority: 50,
  maxSpatial: 2,
  maxTemporal: 2,
  minSpatial: 1,
  minTemporal: 1,
});

or use the limit method on the consumer object.

consumer.limit({
  priority: 50,
  maxSpatial: 2,
  maxTemporal: 2,
  minSpatial: 1,
  minTemporal: 1,
});

Consumer Events

You can subscribe to the following events on the consumer object by using the on method:

• audio_level - Fired when the audio level of the stream changes. The event handler receives a number as an argument.
• state - Fired when the state of the stream changes. The event handler receives a string as an argument. The possible values are no_source, connecting, live, paused, key_only, source_deactivated.
• quality - Fired when the quality of the stream changes. The event handler receives a RemoteStreamQuality object as an argument. The object contains the following properties:
  • peer: The peer ID of the peer who published the stream.
  • name: The name of the stream. Which is the same as the name of which the peer who published the stream assigned.
  • kind: The type of the stream. Can be video or audio.
  • mos: The mean opinion score of the stream.
  • slot: The slot of the stream.