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.
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
room.onJoined = ({ room, peer }) => {
}
room.onPeerJoined = ({ room, peer }) => {
if (peer.isRemote) {
} else {
}
}
room.onPeerLeft = ({ room, peer }) => {}
room.onStatusChanged = ({ oldState, newState }) => {}
room.onAudioOutputStarted = ({ room, peer, media }) => {
const volume = state.getVolumeFor(peer.id);
media.setVolume(volume);
}
room.onAudioOutputStopped = ({ room, peer, media }) => {
}
room.onMessageReceived = ({ room, peer, message }) => {
const json = uint8ArrayToValue(message);
}
room.onUserDataChanged = ({ room, peer }) => {
const json = uint8ArrayToValue(peer.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
peer.onAudioOutputStarted = ({ room, peer, media }) => {
const volume = state.getVolumeFor(peer.id);
media.setVolume(volume);
}
peer.onAudioOutputStopped = ({ room, peer, media }) => {
}
peer.onMessageReceived = ({ room, peer, message }) => {
const json = uint8ArrayToValue(message);
}
room.onUserDataChanged = ({ room, peer }) => {
const json = uint8ArrayToValue(peer.data);
}
room.onAudioActivity = ({ media }) => {
console.log(media.activity)
}
room.onPowerLevel = ({ media }) => {
console.log(media.powerLevel)
}
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.
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.
Example media events
media.onAudioActivity = ({ media }) => {
console.log(media.activity)
}
media.onPowerLevel = ({ media }) => {
console.log(media.powerLevel)
}