Participant Class Methods - Flutter

note

Methods that return a Future complete when the SDK accepts the request, and throw VideoSDKError when the SDK refuses it. VideoSDKError carries the code, name and message listed in Room Error Codes. Await these methods inside try/catch: a call you do not await turns a refusal into an unhandled error.

Future<void> onPinPressed(Participant participant) async {
  try {
    await participant.pin();
  } on VideoSDKError catch (error) {
    log("Could not pin: ${error.code} ${error.name}");
  }
}

On Android, most methods called while the room reconnects report 3065 on the room's error event and return without throwing, so keep an Events.error handler as well.

On an AgentParticipant, the methods that do not apply to an AI agent, such as disableMic(), enableCam(), setQuality() and captureImage(), throw UnsupportedError.

enableCam()

• enableCam() is used to enable participant's camera.
• To turn on your own camera, use room.enableCam().

Events associated with enableCam():

• First the participant will get a callback on cameraRequested and once the participant accepts the request, camera device will be enabled.
• Every participant that receives the camera gets a streamEnabled event on the room, with the stream object.

Returns

• Future<void>

Example

try {
  await participant.enableCam();
} on VideoSDKError catch (error) {
  log("enableCam failed: ${error.code} ${error.name}");
}

---

disableCam()

• disableCam() is used to disable participant camera. The participant is not asked first.
• To turn off your own camera, use room.disableCam().

Events associated with disableCam():

• Every participant that receives the camera gets a streamDisabled event on the room, with the stream object.

Returns

• Future<void>

Example

try {
  await participant.disableCam();
} on VideoSDKError catch (error) {
  log("disableCam failed: ${error.code} ${error.name}");
}

---

enableMic()

• enableMic() is used to ask the participant to turn on their microphone.
• To unmute your own microphone, use room.unmuteMic().

Events associated with enableMic():

• First the participant will get a callback on micRequested and once the participant accepts the request, mic will be enabled.
• Every participant that receives the microphone gets a streamEnabled event on the room, with the stream object.

Returns

• Future<void>

Example

try {
  await participant.enableMic();
} on VideoSDKError catch (error) {
  log("enableMic failed: ${error.code} ${error.name}");
}

---

disableMic()

• disableMic() is used to turn off the participant's microphone. The participant is not asked first.
• To mute your own microphone, use room.muteMic().

Events associated with disableMic():

• Every participant that receives the microphone gets a streamDisabled event on the room, with the stream object.

Returns

• Future<void>

Example

try {
  await participant.disableMic();
} on VideoSDKError catch (error) {
  log("disableMic failed: ${error.code} ${error.name}");
}

---

setQuality()

• It is used to set the quality of the participant's video stream.
• It changes the quality you receive, not what the participant sends, so you can save bandwidth on a small tile. It has no effect on the local participant.
• The value is kept in the participant's videoQuality.

Parameters

• quality: VideoQuality.HIGH | VideoQuality.MEDIUM | VideoQuality.LOW

Returns

• Future<void>

Example

try {
  await participant.setQuality(VideoQuality.HIGH);
} on VideoSDKError catch (error) {
  log("setQuality failed: ${error.code} ${error.name}");
}

---

setScreenShareQuality()

• It is used to set the quality of the participant's screen share that you receive.
• It works like setQuality(), and the two do not affect each other. It has no effect on the local participant.

Parameters

• quality: VideoQuality - VideoQuality.LOW, VideoQuality.MEDIUM or VideoQuality.HIGH.

Returns

• Future<void>

Example

try {
  await participant.setScreenShareQuality(VideoQuality.HIGH);
} on VideoSDKError catch (error) {
  log("setScreenShareQuality failed: ${error.code} ${error.name}");
}

---

pin()

• It is used to set pin state of the participant. You can use it to pin the screen share, camera or both of the participant. It accepts an optional parameter of type PinType. Default PinType is SHARE_AND_CAM

Parameters

• pinType: PinType.SHARE_AND_CAM | PinType.CAM | PinType.SHARE

Events associated with pin():

• Every participant receives a pinStateChanged event on the room.

Returns

• Future<void>

Example

try {
  await participant.pin(PinType.CAM);
} on VideoSDKError catch (error) {
  log("pin failed: ${error.code} ${error.name}");
}

---

unpin()

• It is used to unpin participant. You can use it to unpin the screen share, camera or both of the participant. It accepts an optional parameter of type PinType. Default PinType is SHARE_AND_CAM

Parameters

• pinType: PinType.SHARE_AND_CAM | PinType.CAM | PinType.SHARE

Events associated with unpin():

• Every participant receives a pinStateChanged event on the room.

Returns

• Future<void>

Example

try {
  await participant.unpin(PinType.CAM);
} on VideoSDKError catch (error) {
  log("unpin failed: ${error.code} ${error.name}");
}

---

setViewPort()

• setViewPort() is used to set the quality of the participant's video stream based on the viewport height and width.
• It applies to the video you receive from a remote participant. It does nothing for the local participant.

Parameters

• width: int - the width of the view, in physical pixels.
• height: int - the height of the view, in physical pixels.

A Flutter widget's size is in logical pixels. Multiply it by MediaQuery.of(context).devicePixelRatio, and round the result to an int.

Returns

• Future<void>

Example

try {
  await participant.setViewPort(480, 360);
} on VideoSDKError catch (error) {
  log("setViewPort failed: ${error.code} ${error.name}");
}

---

consumeMicStreams()

• consumeMicStreams() starts receiving the participant's microphone.
• Takes effect only when the room was created with autoConsume set to false.
• Streams are received automatically unless the room was created with autoConsume: false. Call it in that case, or after stopConsumingMicStreams().
• For participants who were already in the room when you joined, call it after the roomJoined event.
• When the stream arrives, the room emits a streamEnabled event and the stream is added to the participant's streams.

Returns

• Future<void>

Example

try {
  await participant.consumeMicStreams();
} on VideoSDKError catch (error) {
  log("consumeMicStreams failed: ${error.code} ${error.name}");
}

---

stopConsumingMicStreams()

• stopConsumingMicStreams() stops receiving the participant's microphone until you call consumeMicStreams().
• Takes effect only when the room was created with autoConsume set to false. With the default autoConsume: true, the server keeps sending the stream.

Returns

• Future<void>

Example

try {
  await participant.stopConsumingMicStreams();
} on VideoSDKError catch (error) {
  log("stopConsumingMicStreams failed: ${error.code} ${error.name}");
}

---

consumeWebcamStreams()

• consumeWebcamStreams() starts receiving the participant's camera.
• Takes effect only when the room was created with autoConsume set to false.
• Streams are received automatically unless the room was created with autoConsume: false. Call it in that case, or after stopConsumingWebcamStreams().
• For participants who were already in the room when you joined, call it after the roomJoined event.
• When the stream arrives, the room emits a streamEnabled event and the stream is added to the participant's streams.

Returns

• Future<void>

Example

try {
  await participant.consumeWebcamStreams();
} on VideoSDKError catch (error) {
  log("consumeWebcamStreams failed: ${error.code} ${error.name}");
}

---

stopConsumingWebcamStreams()

• stopConsumingWebcamStreams() stops receiving the participant's camera until you call consumeWebcamStreams().
• Takes effect only when the room was created with autoConsume set to false. With the default autoConsume: true, the server keeps sending the stream.

Returns

• Future<void>

Example

try {
  await participant.stopConsumingWebcamStreams();
} on VideoSDKError catch (error) {
  log("stopConsumingWebcamStreams failed: ${error.code} ${error.name}");
}

---

remove()

• It is used to remove participant from the room.

Returns

• Future<void>

Example

try {
  await participant.remove();
} on VideoSDKError catch (error) {
  log("remove failed: ${error.code} ${error.name}");
}

---

on()

• It is used to listen to a participant's events:
  • streamEnabled, streamDisabled, streamPaused, streamResumed and onE2EEStateChanged, for this participant's streams only.
  • On an AI agent participant (AgentParticipant): agentStateChanged, agentTranscriptionReceived and agentMetrics.
• The same stream events, for every participant, are also delivered on the room. Listen for them with room.on().

Parameters

• event

  • type: Events
  • This will specify the event to be listened.

• eventHandler

  • type: Function
  • This will be invoked whenever, specified event occurred.

Returns

• void

Example

participant.on(Events.streamEnabled, (RTCStream stream) {
  if (stream.kind == MediaType.VIDEO) {
    // show the participant's video
  }
});

if (participant is AgentParticipant) {
  participant.on(Events.agentStateChanged, (AgentState state) {
    // do something
  });
}

---

off()

• It is used to remove a handler that you added with on().

Parameters

• event

  • type: Events
  • The event that the handler was added for.

• eventHandler

  • type: Function
  • The same function that you passed to on().

Returns

• void

Example

void onAgentStateChanged(AgentState state) {
  // do something
}

agent.on(Events.agentStateChanged, onAgentStateChanged);

// Later, for example when the widget that shows the agent is disposed.
agent.off(Events.agentStateChanged, onAgentStateChanged);

---

removeAllEventListeners()

• It removes every handler you added with on() on this participant.

Returns

• void

Example

participant.removeAllEventListeners();

---

isAgent()

• It returns true when the participant is an AI agent. The participant is then an AgentParticipant.

Returns

• bool

Example

if (participant.isAgent()) {
  // show an agent tile
}

---

getAgentId()

• It returns the id of the AI agent. It is only on an AgentParticipant.

Returns

• String?

---

getAgentState()

• It returns the agent's latest state: AgentState.IDLE, LISTENING, THINKING or SPEAKING. It is only on an AgentParticipant.
• Changes arrive with the agentStateChanged event.

Returns

• AgentState

Example

room.on(Events.participantJoined, (Participant participant) {
  if (participant is AgentParticipant) {
    final AgentState state = participant.getAgentState();
    final String? agentId = participant.getAgentId();
  }
});

---

captureImage()

• It is used to capture image of local participant's current videoStream.
• It will return image in a form of base64.
• It works only for the local participant, while the camera is on.

Parameters

• height: int? - the maximum height of the image, in pixels.
• width: int? - the maximum width of the image, in pixels. Leave out height and width to keep the camera's own size.
• flash: CaptureFlash - CaptureFlash.ON lights the scene before the capture, which adds about half a second. It uses the camera's torch, or, on a front camera without one, the screen, after VideoSDK.setScreenFlash(true). Otherwise the image is captured unlit. Default is CaptureFlash.OFF.

Returns

• Future<String?> - the image as a base64-encoded JPEG, without a data: URI prefix.
• It throws VideoSDKError 3062 when the camera is off and 3069 when the capture fails. A 3069 failure is also reported on the room's error event. On a remote participant, the returned Future fails with an Exception.

Example

// Lights a front camera with a white screen when flash is on.
await VideoSDK.setScreenFlash(true);

try {
  final String? image = await room.localParticipant.captureImage(
    width: 640,
    height: 480,
    flash: CaptureFlash.ON,
  );
} on VideoSDKError catch (error) {
  log("captureImage failed: ${error.code} ${error.name}");
}

---

getVideoStats()

• getVideoStats() will return a List<dynamic>? which will contain details regarding the participant's critical video metrics such as Jitter, Packet Loss etc.
• It returns the sample fetched by your previous call and starts fetching the next one, so your first call returns null. Call it from a timer, for example once a second. It also returns null while the participant has no video stream.
• For the local participant, the list has one entry for each video layer you send.

Returns

• List<dynamic>?, where each entry has:
  • jitter : It represents the distortion in the stream, in milliseconds.
  • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
  • totalPackets : It represents the number of packets transmitted for the stream since the previous sample.
  • packetsLost : It represents the number of packets lost since the previous sample.
  • rtt : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  • codec: It represents the codec used for the stream.
  • network: It represents the network used to transmit the stream
  • size: It is object containing the width, height and framerate of the stream.

Example

// Timer is in dart:async.
final Timer statsTimer = Timer.periodic(const Duration(seconds: 1), (_) {
  final List<dynamic>? stats = participant.getVideoStats();
  if (stats != null && stats.isNotEmpty) {
    log("Video bitrate: ${stats.first['bitrate']} kbps");
  }
});

// Call statsTimer.cancel() when you no longer show the stats.

note

getVideoStats() will return the metrics for the participant at that given point of time and not average data of the complete room.

To view the metrics for the complete room using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

---

getAudioStats()

• getAudioStats() will return a List<dynamic>? which will contain details regarding the participant's critical audio metrics such as Jitter, Packet Loss etc.
• It returns the sample fetched by your previous call and starts fetching the next one, so your first call returns null. Call it from a timer, for example once a second. It also returns null while the participant has no audio stream.

Returns

• List<dynamic>?, where each entry has:
  • jitter : It represents the distortion in the stream, in milliseconds.
  • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
  • totalPackets : It represents the number of packets transmitted for the stream since the previous sample.
  • packetsLost : It represents the number of packets lost since the previous sample.
  • rtt : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  • codec: It represents the codec used for the stream.
  • network: It represents the network used to transmit the stream

note

getAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete room.

To view the metrics for the complete room using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

---

getShareStats()

• getShareStats() will return a List<dynamic>? which will contain details regarding the participant's critical video metrics such as Jitter, Packet Loss etc.
• It returns the sample fetched by your previous call and starts fetching the next one, so your first call returns null. Call it from a timer, for example once a second. It also returns null while the participant is not sharing their screen.

Returns

• List<dynamic>?, where each entry has:
  • jitter : It represents the distortion in the stream, in milliseconds.
  • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
  • totalPackets : It represents the number of packets transmitted for the stream since the previous sample.
  • packetsLost : It represents the number of packets lost since the previous sample.
  • rtt : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  • codec: It represents the codec used for the stream.
  • network: It represents the network used to transmit the stream
  • size: It is object containing the width, height and framerate of the stream.

note

getShareStats() will return the metrics for the participant at that given point of time and not average data of the complete room.

To view the metrics for the complete room using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

---

getTransportStats()

• getTransportStats() returns statistics for the connection that carries the participant's media.

Returns

• Future<Map<String, dynamic>?>, or null when the connection is not ready yet. The map has:
  • send: outgoingBitrate in kbps and totalSentBytes.
  • receive: incomingBitrate in kbps and totalReceivedBytes.

Example

try {
  final Map<String, dynamic>? transport = await participant.getTransportStats();
  log("Outgoing bitrate: ${transport?['send']?['outgoingBitrate']} kbps");
} on VideoSDKError catch (error) {
  log("getTransportStats failed: ${error.code} ${error.name}");
}

---

getShareAudioStats()

• getShareAudioStats() returns statistics for the audio shared with the participant's screen share. For the microphone, use getAudioStats().

Returns

• Future<List<dynamic>?>, with one entry for each shared audio track. It is null or an empty list when the participant is not sharing audio. Each entry has the same keys as getAudioStats().

Example

try {
  final List<dynamic>? shareAudioStats = await participant.getShareAudioStats();
  if (shareAudioStats != null && shareAudioStats.isNotEmpty) {
    log("Share audio bitrate: ${shareAudioStats.first['bitrate']} kbps");
  }
} on VideoSDKError catch (error) {
  log("getShareAudioStats failed: ${error.code} ${error.name}");
}