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.

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)
}