Skip to main content

Working with Events

Events are a fundamental aspect of working with the SDK. As introduced in the getting started section, events enable your application to respond to various changes and updates. For example, you can be notified when a

RemotePeer

joins or leaves the room, or starts an

AudioOutput

.

The SDK primarily revolves around three core Entities, each associated with a specific set of events:

Room Events​

The room is the main entity to work with. It's important to register its event handlers before joining. This ensures you capture all relevant events, particularly initial ones like the

RoomStatus

Event or

PeerJoined

 Event.

info

As for all Events, there are two ways to register EventHandlers (callbacks). The obj.addEventlistener() and obj.onEvent approach. In the following examples, for simplicity, the onEvent property approach is used.

Most relevant room events​

Example room events
// Called, after the room was successfully joined.
room.onJoined = ({ room, peer }) => {
  // Start Audio
  // Manage UI state
}

// Called when a Peer joined. Also, gets called for peers who were already present.
// Peers that were already present will emit before the own  peer. This can be handy in some cases.
room.onPeerJoined = ({ room, peer }) => {
  if (peer.isRemote) {
    // Do something for remote peers
  } else {
    // Do something for the local peer, also after this event occured, all following events will be peers that joined after.
  }
}

// Called when a Peer left the room
room.onPeerLeft = ({ room, peer }) => {}

// Called, when the room status changed.
room.onStatusChanged = ({ oldState, newState }) => {}

// Called, when a RemotePeer started to transmit audio.
room.onAudioOutputStarted = ({ room, peer, media }) => {
  // media is a AudioOutput, can be used to adjust playback volume or get acitvity
  const volume = state.getVolumeFor(peer.id);
  // Default is 1
  media.setVolume(volume);
  // UI Handling, for example display that the peer has audio
}

// Called, when a RemotePeer stopped to transmit audio.
room.onAudioOutputStopped = ({ room, peer, media }) => {
  // UI handling, for example that this peer has no audio
}

// Called, when a message was received from a RemotePeer. Messages are trasmitted using `Uint8Arrays` and we offering helper functions
// to convert them into JSON and vice versa.
room.onMessageReceived = ({ room, peer, message }) => {
  const json = uint8ArrayToValue(message);
}

// Called, when a RemotePeer updated its userdata. Userdata is trasmitted using `Uint8Arrays` and we offering helper functions
// to convert them into JSON and vice versa.
room.onUserDataChanged = ({ room, peer }) => {
  const json = uint8ArrayToValue(peer.data);
  // This can be information, if the user muted his mic or other user related information.
}

// Called, when one AudioInput or AudioOutput that is attached to the room is transmitting audio data.
room.onAudioActivity = ({ media }) => {
  console.log(media.activity)
}

Peer Events​

There are two types of Peers, the

LocalPeer

(always one per room), representing the own peer, and

RemotePeer

, representing other peers in the room. All

PeerEvents

 are also available on the

Room

, however, it can be very handy in some context to have them directly attached to the specific peer they are related to.

Most relevant peer events​

Example peer events

// Called, when this RemotePeer started to transmit audio.
peer.onAudioOutputStarted = ({ room, peer, media }) => {
  // media is a AudioOutput, can be used to adjust playback volume or get acitvity
  const volume = state.getVolumeFor(peer.id);
  // Default is 1
  media.setVolume(volume);
  // UI handling, for example that the peer has audio
}

// Called, when this RemotePeer stopped to transmit audio.
peer.onAudioOutputStopped = ({ room, peer, media }) => {
  // UI handling, for example that this peer has no audio
}

// Called, when a message was received from this RemotePeer. Messages are trasmitted using `Uint8Arrays` and we offering helper functions
// to convert them into JSON and vice versa.
peer.onMessageReceived = ({ room, peer, message }) => {
  const json = uint8ArrayToValue(message);
}

// Called, when this RemotePeer updated its userdata. Userdata is trasmitted using `Uint8Arrays` and we offering helper functions
// to convert them into JSON and vice versa.
room.onUserDataChanged = ({ room, peer }) => {
  const json = uint8ArrayToValue(peer.data);
  // This can be information, if the user muted his mic or other user related information.
}

// Called, when one of the AudioInputs or AudioOutputs of this peer are active.
room.onAudioActivity = ({ media }) => {
  console.log(media.activity)
}

// Called, when the powerLevel of one of the AudioInputs or AudioOutputs of this peer emits a new value.
room.onPowerLevel = ({ media }) => {
  console.log(media.powerLevel)
}

Media (AudioInput / AudioOutput) Events​

Similar to Peers, Medias are separated into

AudioInput

and

AudioOutput

. As explained in the getting started section, the

AudioInput

 is representing the local audio capturing and is created locally. Usually one. AudioOutputs are representing the audio playback from

RemotePeer

's.

More details about configuring the

AudioInput

will be provided in the working with devices section, this guide focuses only on events.

info

Important Note: In the most apps, a Peer will always have one

AudioInput

or one

AudioOutput

. That's why it might be easier to use the events on the Peer, since all

MediaEvents

 are available there too.

Most relevant media events​

Example media events
// Called, when the media is active
media.onAudioActivity = ({ media }) => {
  console.log(media.activity)
}

// Called, when the powerLevel changed
media.onPowerLevel = ({ media }) => {
  console.log(media.powerLevel)
}