Media Streams

Media Stream is a fundamental part of WebRTC applications, allowing you to share audio and video content between peers. In Peerix , you can share media streams with connected peers and subscribe to streams shared by others.

    sequenceDiagram
    autonumber
    Note over Peer A, Peer B: Share media streams
    Peer A ->> Peer A: Add transceiver
    Peer A ->> Peer B: signaling DC: offer
    Peer B ->> Peer B: Add transceiver
    Peer B ->> Peer A: signaling DC: answer
    Peer B -x Peer A: signaling DC: offer (collision)
    Note over Peer A, Peer B: Streams shared

Sharing Streams

You can share media streams with the room using the share method:

// get a media stream from the user's camera and microphone
const cameraStream = await navigator.mediaDevices.getUserMedia({
  video: true,
  audio: true,
});

// share the camera stream with the room
peer.share(cameraStream);

This allows other peers in the room to subscribe to your media streams and view or listen to them.

You can share multiple streams using the same share method:

// get another media stream from the user's screen
const screenStream = await navigator.mediaDevices.getDisplayMedia({
  video: true,
});

// share the screen stream with the room
peer.share(screenStream);

You can also provide a label for each stream to manage them more easily and then unshare or update them later:

// get a media stream from the user's camera and microphone
const cameraStream = await navigator.mediaDevices.getUserMedia({
  video: true,
  audio: true,
});

// share the stream with a specific label and mark it as managed
peer.share({ label: 'camera', stream: cameraStream, managed: true });

// get another media stream from the user's microphone only
const newCameraStream = await navigator.mediaDevices.getUserMedia({
  video: false,
  audio: true,
});

// update the existing stream with new tracks, keeping the same label,
// previously shared stream will be stopped automatically since it is marked as managed
peer.share({ label: 'camera', stream: newCameraStream, managed: true });

Managed streams are automatically stopped when they are unshared or updated, which is useful for handling media streams tied to specific user actions or states. For example, a camera stream should be stopped when it is unshared or when the user switches to a different camera.

Note

When you share a media stream, Peerix will automatically negotiate the connection with all connected peers in the room and share the stream with them. This means that you can share a stream before or after joining a room, and the library will handle the sharing of the stream as needed.

You can also set optional sender parameters for shared streams in order to control the bitrate, frame rate, and priority of the audio and video track encodings:

// share the camera stream with a bitrate
peer.share({
  label: 'camera',
  stream: cameraStream,
  audioParameters: {
    maxBitrate: 16000, // 16 kbps for audio tracks
  },
  videoParameters: {
    maxBitrate: 64000, // 64 kbps for video tracks
  },
});

Unsharing Streams

To stop sharing a media stream with other peers, you can unshare it using the unshare method:

// unshare the specific stream
peer.unshare(cameraStream);
// or unshare the stream with the specified label
peer.unshare('camera');
// or the same with label parameter
peer.unshare({ label: 'camera' });

Note

When a peer unshares a track from a stream, Peerix will automatically stop sharing that track with all connected peers in the room. If the stream has no more tracks after unsharing, the library will also stop sharing the entire stream.

Subscribing to Stream Changes

To receive media streams shared by other peers or watch for changes in existing streams, you can listen for the track:add and track:remove events emitted by the Peer instance:

// listen for peer adding a track to a stream
peer.on('track:add', (e) => {
  const { remote, stream, track, label } = e;
  console.log('Added new track:', track.id, 'label:', label);
});

// listen for peer removing a track from a stream
peer.on('track:remove', (e) => {
  const { remote, stream, track, label } = e;
  console.log('Removed track:', track.id, 'label:', label);
});

Tip

You can use these events to update your application’s UI. For example, you can show or hide video elements based on the presence of video tracks in the shared streams.

You can also listen for the stream:add and stream:remove events to track when new streams are shared or unshared by peers:

// listen for peer adding a new stream
peer.on('stream:add', (e) => {
  const { remote, stream, label } = e;
  console.log('Added new stream:', stream.id, 'label:', label);
});

// listen for peer removing a stream
peer.on('stream:remove', (e) => {
  const { remote, stream, label } = e;
  console.log('Removed stream:', stream.id, 'label:', label);
});

Selective Operations

Peerix allows you to share, unshare and listen for events on specific peer connections, rather than on all of them in the room.

To share a stream with a specific peer, you can get the remote peer instance and use the share method with the stream:

const remote = peer.connections.get('peer-id');
if (remote) {
  remote.share({ label: 'camera', stream });
}

The same way you can use the unshare method on the remote peer instance and listen for events with the remote.on method to handle media streams with specific peers in the room.

Please note that these operations continue to run while the peer connection is established. If the connection is closed, you will need to share the streams again to share them with that peer, even if they are reconnected later.

Peer Connections Data Channels