Advanced usage
Turn on the setup / preview screen
The audio / video setup screen that appears for the participant right before
getting into the meeting is turned off by default. You can set showSetupScreen
in meetingConfig
to true
to turn it on (default value is false
).
<script>
const client = new DyteClient({ clientId: 'orgId|clientId' });
const meeting = client.Meeting({
roomName: '<roomName>',
authToken: '<authToken>',
showSetupScreen: true,
});
meeting.init('root');
</script>
Dynamic codec switching
Dyte uses VP9 codec by default, but switches to H264/VP8 depending on
participants' video codec support. VP9 is a superior codec but not all browsers
support it. If you set autoTune
in meetingConfig
to false
, Dyte will use
VP8 only for all participants (default value is true
).
<script>
const client = new DyteClient({ clientId: 'orgId|clientId' });
const meeting = client.Meeting({
roomName: '<roomName>',
authToken: '<authToken>',
autoTune: false,
});
meeting.init('root');
</script>
Get error details for meeting creation
You can optionally choose to subscribe to the error details, in case an error
occurs while joining a meeting from the client app, by passing a handler
function to the onError
method of DyteMeeting
. onError
expects a function
which has a single param of type Error
and is not expected to return anything.
<script>
const client = new DyteClient({ clientId: 'orgId|clientId' });
const meeting = client.Meeting({
roomName: '<roomName>',
authToken: '<authToken>',
autoTune: false,
});
meeting.onError(function (error) {});
meeting.init('root');
</script>
You can refer to this section for info on errors.
Control the meeting, and take meeting & participant actions
The Meeting
instance (referenced as meeting
above) helps you interact with
the meeting. You can take actions on the meeting as well as the participants.
You can also setup custom controls to that interact with the meeting in certain
ways that help you send events and messages across to other participants in the
meeting. You can find the complete reference to the Meeting
type
here. Read on to understand how to use these individual
controls.
Get the Dyte client version
You can get the version of the Dyte client SDK being used to help with logging and debugging purposes.
let version = DyteClient.version;
sets the value of version
to a semver compliant string.
Get info about meeting's connection configuration
You can get the connection configuration of the meeting in progress using the
connectionConfig
property of Meeting
.
let config = meeting.connectionConfig;
sets the value of config
to the following:
{
clientId: string,
roomName: string,
showSetupScreen: boolean,
autoTune: boolean,
}
Get info about the meeting's UI configuration
You can get the UI configuration of the meeting in progress using the uiConfig
property of Meeting
.
let config = meeting.uiConfig;
sets the value of config
to the following:
{
controlBar: boolean,
controlBarElements: {
fullscreen: boolean,
share: boolean,
screenShare: boolean,
layout: boolean,
chat: boolean,
polls: boolean,
participants: boolean,
plugins: boolean
},
header: boolean,
headerElements: {
logo: boolean,
title: boolean,
participantCount: boolean,
clock: boolean
},
dimensions:{
width: number,
height: number
},
logo: string_url,
colors: {
primary: string_hexColor
secondary: string_hexColor
textPrimary: string_hexColor
videoBackground: string_hexColor
}
}
Get info about the plugins configured for the meeting
You can get info about the plugins configured for the meeting in progress using
the plugins
property of Meeting
.
let plugins = meeting.plugins;
sets the value of plugins
to an array of with elements that are instances of
type DytePlugin
, whose prototype is defined below in the reference section and
can be directly used as a type if you prefer using TypeScript bindings.
Add (and remove) a custom button on the bottom control bar
You can add your own button with your custom handler, on the bottom control bar of the meeting. You can choose which section to place the button in, from the 3 sections, and the button placements would automatically be realigned to accommodate this new element.
To do this, you need to call the addButton
method of meeting.controlBar
and
pass it an icon
to display on the button, a label
text to show below the
icon, the position
of button group where you want your button to show up
(left
, center
& right
), and the onClick
handler.
button = meeting.controlBar.addButton({
icon: <div>😀</div>,
label: 'React',
position: 'center',
onClick: function () {
// your code to handle the click
},
});
This would result in the following
To remove this button, you can simply pass back the button reference to
removeButton
method of the same.
meeting.controlBar.removeButton(button);
Replace the meeting control buttons with your own buttons
Let's say you don't want to give many options to the participants in a meeting, other than the basic audio and video turning on, or you don't like our buttons and control bar design (you really should give us feedback too, in this case), or for any other reason - you just want to build your own buttons for basic meeting controls. This is possible with Dyte, with the minor caveat that you will need to put some validations at your end.
First thing in such a scenario would be to do away with our control bar
meeting.updateUIConfig({ controlBar: false });
Now you can perform the basic functions of a meeting, like below. These
functions can be used as the onClick
handlers of your own buttons.
Mic control
To turn off the mic
meeting.self.disableAudio();
To turn on the mic
meeting.self.enableAudio();
Camera control
To turn off the camera
meeting.self.disableVideo();
To turn on the camera
meeting.self.enableVideo();
Screenshare control
To turn off screenshare
meeting.self.disableScreenshare();
To turn on screenshare
meeting.self.enableScreenshare();
Leave meeting
To leave the meeting
meeting.leaveRoom();
Add a custom action to the context (right-click) menu
You can add your own menu option to the context menu that appears on right clicking a participant's video (or thumbnail image where the video is supposed to be). The option gets placed at the bottom of the list.
To do this, you need to call the addParticipantControl
method of meeting
and
pass it a label
text to show in the menu, and the onClick
handler which
receives a peerId
to indicate which participant's video was clicked upon.
meeting.addParticipantControl({
label: 'React 😀',
onClick: function (peerId) {
// your code to handle the click
},
});
This would result in the following
Change the video grid layout style
You can change the video grid layout from showing multiple participants in a
grid (default) to only showing the active speaker or highlighted participant,
and vice versa. Active speaker is the participant whose audio level has most
recently been the highest (kind of like LRU with the selection factor being
audio level). Call the update
method of meeting.grid
with the layout
as
either meeting.grid.layouts.MULTI
or meeting.grid.layouts.HIGHLIGHTED
.
meeting.grid.update({
layout: meeting.grid.layouts.MULTI | meeting.grid.layouts.HIGHLIGHTED,
});
MULTI
: This sets the participant videos in a grid.HIGHLIGHTED
: This makes the selected participant video occupy the majority of the screen.
Change the cropping behaviour of videos
You can also change the participant's video fitting and cropping behaviour on
the grid if it appears too cropped / zoomed in or too far away, using the same
method as above. The parameter, however, would change to fit
contained in
participantVideo
with the values of contain
or cover
.
meeting.grid.update({
participantVideo:
fit: 'contain' | 'cover'
});
contain
: this option maintains the aspect ratio and fits the video inside the container in such a way that the longer side matches the container size and leaves margins around the shorter side.cover
: this option ignores the aspect ratio and expands the video inside the container in such a way that the shorter side matches the container size to fill the container and there are no margins.
Send a custom message to other participants in the meeting (P2P message / data exchange)
You can send custom messages relevant to your app, JSON data, or any really any other data that is serializable, to other participants in the meeting. Think of it as a parallel data channel in the same P2P manner as the media streams. While the pre-built chat function supports sending messages and files, you can do more using this feature. Since these messages do not appear in the chat box, you can send and receive data specific to your app and choose to take actions as well as display them on the UI as you want.
To send such a message to all participants in the meeting room
meeting.sendRoomMessage(message);
where message
can be of any type.
To send a targeted message to specific participant in the meeting room
meeting.sendMessage(peerId, message);
where message
can be of any type and peerId
is a string representing the
unique ID of the participant as obtained from the participant list.
Get list of all participants in the meeting
You can get a list of all participants in the meeting using the participants
property of meeting
.
let participantList = meeting.participants;
sets the participantList
to an array whose elements are instances of type
DyteParticipant
, whose prototype is defined below in the reference section and
can be directly used as a type if you prefer using TypeScript bindings. There
will be exactly one element of type DyteSelfParticipant
, which refers to the
current participant.
Remove a participant from the meeting
You can remove a participant from the meeting using the kick
method. The
participant can, however, join the meeting back if they wish to. If you don't
want them to be able to join back, you should remove their access to the link or
the particular action which initializes the Dyte SDK on the frontend.
meeting.kick(peerID);
where peerID
can be obtained from the list of participants (refer
peer ID
section for more info).
Remove all participants from the meeting
You can remove all participants from the meeting using the kickAll
method. The
participants can, however, join the meeting back if they wish to. If you don't
want them to be able to join back, you should remove their access to the link or
the particular action which initializes the Dyte SDK on the frontend.
meeting.kickAll();
Controlling individual participants and actions
Dyte client SDK provide methods and properties to help you control participant actions and certain UI elements. This could include actions that affect the participant themselves as well as other participants (like a host with privileged permissions may want to control the video of other participants). This section defines all the possible properties and actions that can be taken.
Remember that despite the functions being available to every participant via the client SDK, they will not take affect until coupled with the right permissions for the participant who intends to use these.
Get participant list
To get a list of all participants, use meeting.participants
: it returns
Array[DyteParticipant|DyteSelfParticipant]
where all meeting participants are
DyteParticipant
and the current participant is
DyteSelfParticipant
.
Participant info and actions
Once you get the array of participants as mentioned above, you can iterate over that and get certain info about every participant.
We will consider the following iterator for the next section.
meeting.participants.forEach((p) => {
// participant specific code goes here
});
Peer ID
Get unique ID for every participant. This ID is generated by Dyte when a participant joins the meeting. This ID is used for referring to a participant within Dyte, such as for sending custom messages.
Even if the same participant, using the same auth token, rejoins the meeting, for example by refreshing the page / app or due to connection drop, the peer ID would be refreshed in that case.
let peerID = p.id;
sets the value of peerID
to a UUID string.
Client specific ID
Get the client specific ID as you have specified in the add participant API call. You may want to decide exposing custom controls or build other business logic based on this identifier, which helps you find the participant info in your system.
let clientSpecificID = p.clientSpecificId;
Participant name
Get the participant name as you have specified in the add participant API call. The participant may have changed this name, if enabled.
let name = p.name;
Participant thumbnail photo / avatar
Get the participant photo as you have specified in the add participant API call.
let name = p.picture;
Participant metadata about the preset
Get the preset that has been set for the participant either as a default or explicitly as specified in the add participant API call.
let preset = p.metadata.preset_name;
Participant metadata about the meeting view type
Get the view type that the participant is currently seeing.
let preset = p.metadata.view_type;
Check if participant's audio is on
To check whether a participant's audio is on (mic is turned on), you can use
let audio = p.audioEnabled;
which sets the value of audio
to a boolean specifying if the mic is on or not.
Get participant audio stream
If the participant's audio is on, you can get the associated audio stream using
let audioStream = p.audioTrack;
which sets the value of audioStream
to a MediaStreamTrack
that you can use
elsewhere such as a custom recording.
Disable participant's audio stream
To remotely turn the participant's mic off, you can do
p.disableAudio();
Check if participant's video is on
To check whether a participant's video is on (camera is turned on), you can use
let video = p.videoEnabled;
which sets the value of video
to a boolean specifying if the camera is on or
not.
Get participant video stream
If the participant's video is on, you can get the associated video stream using
let videoStream = p.videoTrack;
which sets the value of videoStream
to a MediaStreamTrack
that you can use
elsewhere such as a custom recording.
Disable participant's audio stream
To remotely turn the participant's camera off, you can do
p.disableVideo();
Check if the participant is pinned to the grid
To check whether a participant's video is pinned to the meeting grid; by the host, by the user, by the preset, or by any other mechanism; you can use
let pinned = p.isPinned;
which sets the value of pinned
to a boolean specifying whether the video is
pinned or not.
Pin a participant video to the grid
You can pin a participant's video to the grid using
p.pin();
Unpin a participant video from the grid
You can unpin a participant's video from the grid using
p.unpin();
Zoom a participant's video using custom logic
You can zoom on to a participant's video for everyone in the meeting. You would
need to specify the scale
, which represents the scale of zoom, as well as x
and y
offsets, which represent the offset from center to reposition the video
inside the container in the grid.
p.zoom({ scale: , x: , y: });
Set an overlay / filter on the participant video
You can add overlays or filters to individual participants. For this, you can do
participant.setOverlay(HTMLElement)
where you pass an HTML string to the
function.
Let's say you find the participant
using their id
or something similar, and
then
const targetPeer = meeting.participants.find((p) => p.id === peerId);
// find a peer you want to add overlay to
if (targetPeer) {
targetPeer.setOverlay(
'<canvas id="reaction-1" style="width: 100%; height: 100%;" />'
);
}
To remove, you can simply set the overlay to null.
targetPeer.setOverlay(null);
Send a custom message to a participant (P2P message / data exchange)
Just like sending a custom message to the whole room, you can target a particular participant to send a message.
p.sendMessage(message);
Check if the participant is current participant
You can check if the participant is the current participant by checking the
isMe
boolean property of the participant. If found to be true
, you can treat
that participant as an instance of type DyteSelfParticipant
, which is a
subclass of type DyteParticipant
. This unlocks a few additional actions that
you can take with that participant.
let currentParticipant = meeting.participants.find((p) => p.isMe);
Now all the methods that you can call on meeting.self
(as described under
replace meeting control buttons)
can be called on currentParticipant
.
Errors
There are 3 types of errors emitted when a meeting cannot be initialized. Read
more about these on the DyteErrors
page in the
reference section.
enum DyteErrors {
CLIENTID_INVALID,
MEETING_UNAUTHORIZED,
MEETING_NOTFOUND,
}
An example of handling such errors:
<script>
const client = new DyteClient({ clientId: 'orgId|clientId' });
const meeting = client.Meeting({
roomName: '<roomName>',
authToken: '<authToken>',
autoTune: false,
});
meeting.onError(function (error) {
if ((error = DyteErrors.CLIENTID_INVALID)) {
// take appropriate action
}
});
meeting.init('root');
</script>