Media Streams

Documentation

Peers

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 publish media streams to share them with connected peers and subscribe to streams published by others.

    sequenceDiagram
    autonumber
    Note over Peer1,Peer2: Publish media streams
    Peer1->>Peer1: Add transceiver
    Peer1->>Peer2: signaling DC: offer
    Peer2->>Peer2: Add transceiver
    Peer2->>Peer1: signaling DC: answer
    Peer2-xPeer1: signaling DC: offer (collision)
    Note over Peer1,Peer2: Streams shared

Publishing Streams

You can publish media streams to the room using the publish method:

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

// publish the camera stream to the room
peer.publish(cameraStream);

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

You can publish multiple streams using the same publish method:

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

// publish the screen stream to the room
peer.publish(screenStream);

You can also provide a label for each stream to manage them more easily and then unpublish 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 });

// publish the stream with a specific label and mark it as managed
peer.publish({ 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 published stream will be stopped automatically since it is marked as managed
peer.publish({ label: 'camera', stream: newCameraStream, managed: true });

Managed streams are automatically stopped when they are unpublished 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 unpublished or when the user switches to a different camera.

Note

When you publish 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 publish 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 published streams in order to control the bitrate, frame rate, and priority of the audio and video track encodings:

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

Unpublishing Streams

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

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

Note

When a peer unpublishes 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 unpublishing, the library will also stop sharing the entire stream.

Subscribing to Stream Changes

To receive media streams published 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 publishing a track in a stream
peer.on('track:add', (e) => {
  const { remote, stream, track, label } = e;
  console.log('Peer published a track:', track.id, 'in stream:', stream.id, 'label:', label);
});

// listen for peer unpublishing a track in a stream
peer.on('track:remove', (e) => {
  const { remote, stream, track, label } = e;
  console.log('Peer unpublished a track:', track.id, 'from stream:', stream.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 published streams.

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

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

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

Selective Operations

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

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

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

The same way you can use the unpublish 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 publish the streams again to share them with that peer, even if they are reconnected later.

Peer Connections Data Channels