APIs topic

ZegoUIKitPrebuiltLiveAudioRoom

Live Audio Room Widget. You can embed this widget into any page of your project to integrate the functionality of a audio chat room. You can refer to our documentation, or our sample code.

  • function prototype:
class ZegoUIKitPrebuiltLiveAudioRoom extends StatefulWidget {
 const ZegoUIKitPrebuiltLiveAudioRoom({
   Key? key,
   required this.appID,
   required this.appSign,
   required this.userID,
   required this.userName,
   required this.roomID,
   required this.config,
   required this.events,
 }) : super(key: key);

 /// You can create a project and obtain an appID from the [ZEGOCLOUD Admin >Console](https://console.zegocloud.com).
 final int appID;

 /// You can create a project and obtain an appSign from the [ZEGOCLOUD Admin >Console](https://console.zegocloud.com).
 final String appSign;

 /// The ID of the currently logged-in user.
 /// It can be any valid string.
 /// Typically, you would use the ID from your own user system, such as Firebase.
 final String userID;

 /// The name of the currently logged-in user.
 /// It can be any valid string.
 /// Typically, you would use the name from your own user system, such as Firebase.
 final String userName;

 /// The ID of the audio chat room.
 /// This ID serves as a unique identifier for the room, so you need to ensure its uniqueness.
 /// It can be any valid string.
 /// Users who enter the same [roomID] will be logged into the same room to chat or listen to others.
 final String roomID;

 /// Initialize the configuration for the voice chat room.
 final ZegoUIKitPrebuiltLiveAudioRoomConfig config;

 /// Initialize the event for the voice chat room.
 final ZegoUIKitPrebuiltLiveAudioRoomEvents events;q
}

ZegoUIKitPrebuiltLiveAudioRoomController

leave

This function is used to end the Live Audio Room.

You can pass the context context for any necessary pop-ups or page transitions. By using the showConfirmation parameter, you can control whether to display a confirmation dialog to confirm ending the Live Audio Room.

This function behaves the same as the close button in the calling interface's top right corner, and it is also affected by the ZegoUIKitPrebuiltLiveAudioRoomEvents.onLeaveConfirmation and ZegoUIKitPrebuiltLiveAudioRoomEvents.onEnded settings in the config.

  • function prototype:
Future<bool> leave(
  BuildContext context, {
  bool showConfirmation = true,
}) async

hideInMemberList

hide some user in member list

  • function prototype:
void hideInMemberList(List<String> userIDs)

media

media series API

volume

volume of current media

  • function prototype:
int get volume

totalDuration

the total progress(millisecond) of current media resources

  • function prototype:
int get totalDuration

currentProgress

current playing progress of current media

  • function prototype:
int get currentProgress

type

type of current media

  • function prototype:
ZegoUIKitMediaType get type

enum ZegoUIKitMediaType {
  pureAudio,
  video,
  unknown,
}

volumeNotifier

volume notifier of current media

  • function prototype:
ValueNotifier<int> get volumeNotifier

currentProgressNotifier

current progress notifier of current media

  • function prototype:
ValueNotifier<int> get currentProgressNotifier

playStateNotifier

play state notifier of current media

  • function prototype:
ValueNotifier<ZegoUIKitMediaPlayState> get playStateNotifier

/// media play state
enum ZegoUIKitMediaPlayState {
  /// Not playing
  noPlay,

  /// not start yet
  loadReady,

  /// Playing
  playing,

  /// Pausing 
  pausing,

  /// End of play
  playEnded
}

typeNotifier

type notifier of current media

  • function prototype:
ValueNotifier<ZegoUIKitMediaType> get typeNotifier

/// media type
enum ZegoUIKitMediaType {
  pureAudio,
  video,
  unknown,
}

muteNotifier

mute state notifier of current media

  • function prototype:
ValueNotifier<bool> get muteNotifier

info

info of current media

  • function prototype:
ZegoUIKitMediaInfo get info

/// Media Infomration of media file.
///
/// Meida information such as video resolution of media file.
class ZegoUIKitMediaInfo {
  /// Video resolution width.
  int width;

  /// Video resolution height.
  int height;

  /// Video frame rate.
  int frameRate;
}

play

start play current media

  • function prototype:
Future<ZegoUIKitMediaPlayResult> play({
  required String filePathOrURL,
  bool enableRepeat = false,
}) async

/// media play result
class ZegoUIKitMediaPlayResult {
  int errorCode;
  String message;
}

stop

stop play current media

  • function prototype:
Future<void> stop() async

destroy

destroy current media

  • function prototype:
Future<void> destroy() async

pause

pause current media

  • function prototype:
Future<void> pause() async

resume

resume current media

  • function prototype:
Future<void> resume() async

seekTo

set the current media playback progress

  • function prototype:
Future<ZegoUIKitMediaSeekToResult> seekTo(int millisecond)

class ZegoUIKitMediaSeekToResult {
  int errorCode;
  String message;
}

setVolume

set media player volume. Both the local play volume and the publish volume are set. the range is 0 ~ 100. The default is 30.

set isSyncToRemote to be true if you want to sync both the local play volume and the publish volume, if isSyncToRemote is false, that will only adjust the local play volume.

  • function prototype:
Future<void> setVolume(int volume, {bool isSyncToRemote = false,}) async

muteLocal

mute current media

  • function prototype:
Future<void> muteLocal(bool mute) async

pickPureAudioFile

pick pure audio media file

  • function prototype:
Future<List<PlatformFile>> pickPureAudioFile() async

pickVideoFile

pick video media file

  • function prototype:
Future<List<PlatformFile>> pickVideoFile() async

pickFile

If you want to specify the allowed formats, you can set them using allowedExtensions. Currently, for video, we support "avi", "flv", "mkv", "mov", "mp4", "mpeg", "webm", "wmv". For audio, we support "aac", "midi", "mp3", "ogg", "wav".

  • function prototype:
Future<List<PlatformFile>> pickFile({
  List<String>? allowedExtensions = const [
    /// video
    "avi",
    "flv",
    "mkv",
    "mov",
    "mp4",
    "mpeg",
    "webm",
    "wmv",

    /// audio
    "aac",
    "midi",
    "mp3",
    "ogg",
    "wav",
  ],
}) async

message

media series API

  • function prototype:
/// in-room message
class ZegoInRoomMessage {
 /// If the local message sending fails, then the message ID at this time is unreliable, and is a negative sequential value.
 int messageID;

 /// message sender.
 ZegoUIKitUser user;

 /// message content.
 String message;

 /// message attributes
 Map<String, String> attributes;

 /// The timestamp at which the message was sent.
 /// You can format the timestamp, which is in milliseconds since epoch, using DateTime.fromMillisecondsSinceEpoch(timestamp).
 int timestamp;

 ///
 var state = ValueNotifier<ZegoInRoomMessageState>(ZegoInRoomMessageState.success);
}


/// in-room message send state
enum ZegoInRoomMessageState {
  idle,
  sending,
  success,
  failed,
}

send

sends the chat message, @return Error code, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.

  • function prototype:
Future<bool> send(String message, {
    ZegoInRoomMessageType type = ZegoInRoomMessageType.broadcastMessage,
}) async

list

retrieves a list of chat messages that already exist in the room

return a List of ZegoInRoomMessage objects representing the chat messages that already exist in the room.

  • function prototype:
List<ZegoInRoomMessage> list({ZegoInRoomMessageType type = ZegoInRoomMessageType.broadcastMessage})

stream

retrieves a list stream of chat messages that already exist in the room.

the stream will dynamically update when new chat messages are received, and you can use a StreamBuilder to listen to it and update the UI in real time.

return a List of ZegoInRoomMessage objects representing the chat messages that already exist in the room.

Example:

..foreground = Positioned(
    left: 10,
    bottom: 50,
    child: StreamBuilder<List<ZegoInRoomMessage>>(
      stream: liveController.message.stream(),
      builder: (context, snapshot) {
        final messages = snapshot.data ?? <ZegoInRoomMessage>[];

        return Container(
          width: 200,
          height: 200,
          decoration: BoxDecoration(
            color: Colors.white.withOpacity(0.2),
          ),
          child: ListView.builder(
            itemCount: messages.length,
            itemBuilder: (context, index) {
              final message = messages[index];
              return Text('${message.user.name}: ${message.message}');
            },
          ),
        );
      },
    ),
  )
  • function prototype:
Stream<List<ZegoInRoomMessage>> stream({ZegoInRoomMessageType type = ZegoInRoomMessageType.broadcastMessage})

clear

clear local messages and remote messages

  • function prototype:
List<ZegoInRoomMessage> clear({
    ZegoInRoomMessageType type = ZegoInRoomMessageType.broadcastMessage,
    bool clearRemote = true,
})

minimizing

the APIs related to minimizing.

state

current minimize state

  • function prototype:
ZegoLiveAudioRoomMiniOverlayPageState get state

/// page state of current minimize page
enum ZegoLiveAudioRoomMiniOverlayPageState {
  idle,
  inAudioRoom,
  minimizing,
}

isMinimizingNotifier(ValueNotifier

is it currently in the minimized state or not

  • example:
ValueListenableBuilder<bool>(
  valueListenable:
  ZegoUIKitPrebuiltLiveAudioRoomController().minimize.isMinimizingNotifier,
  builder: (context, isMinimized, _) {
    ...
  },
)

isMinimizing

is it currently in the minimized state or not

  • function prototype:
bool get isMinimizing

restore

restore the ZegoUIKitPrebuiltLiveAudioRoom from minimize

  • function prototype:
bool restore(
  BuildContext context, {
  bool rootNavigator = true,
  bool withSafeArea = false,
})

minimize

minimize the ZegoUIKitPrebuiltLiveAudioRoom

  • function prototype:
bool minimize(
  BuildContext context, {
  bool rootNavigator = true,
})

hide

if audio room ended in minimizing state, not need to navigate, just hide the minimize widget.

  • function prototype:
void hide()

pip

enable

  • function prototype:
Future<PiPStatus> enable({
  int aspectWidth = 1,
  int aspectHeight = 1,
}) async

enableWhenBackground

  • function prototype:
Future<PiPStatus> enableWhenBackground({
  int aspectWidth = 1,
  int aspectHeight = 1,
}) async

cancelBackground

  • function prototype:
Future<PiPStatus> cancelBackground() async

seat

userMapNotifier

the seat user map of the current live audio room.

  • function prototype:
ValueNotifier<Map<String, String>>? get userMapNotifier

localIsHost

local user is host or not

  • function prototype:
bool get localIsHost

localIsAudience

local user is audience or not

  • function prototype:
bool get localIsAudience

localIsSpeaker

local user is speaker or not

  • function prototype:
bool get localIsSpeaker

localIsCoHost

local user is co-host or not

co-host have the same permissions as hosts if host is not exist

  • function prototype:
bool get localIsCoHost

localHasHostPermissions

local user has host permission or not

co-host have the same permissions as hosts if host is not exist

  • function prototype:
bool get localHasHostPermissions

isRoomSeatLocked

is room seat locked or not

  • function prototype:
bool get isRoomSeatLocked

isAHostSeatIndex

is a host seat index or not

  • function prototype:
bool isAHostSeatIndex(int seatIndex)

getUserByIndex

get user who on the target seat index

  • function prototype:
ZegoUIKitUser? getUserByIndex(int targetIndex)

getEmptySeats

get the currently empty seat

set includeHostSeats to true if ZegoLiveAudioRoomSeatConfig.hostIndexes is included, default does not include

  • function prototype:
List<int> getEmptySeats({bool includeHostSeats = false,})

getSeatIndexByUserID

get seat index of target user

  • function prototype:
int getSeatIndexByUserID(String targetUserID)

muteStateNotifier

Is the current seat muted or not. Set isLocally to true to find out if it is muted locally.

  • function prototype:
ValueNotifier<bool> muteStateNotifier(
  int targetIndex, {
  bool isLocally = false,
})

muteLocally

Mute the user at the targetIndex seat locally. After mute, if you want to un-mute, you can set muted to false.

And on side of the user at the targetIndex seat, return true/false in the callback of ZegoLiveAudioRoomAudioVideoEvents.onMicrophoneTurnOnByOthersConfirmation to open microphone or not.

  • function prototype:
Future<bool> muteLocally({
  int targetIndex = -1,
  bool muted = true,
}) async

muteLocallyByUserID

Mute the seat by targetUserID locally. After mute, if you want to un-mute, you can set muted to false.

And on side of the user at the targetIndex seat, return true/false in the callback of ZegoLiveAudioRoomAudioVideoEvents.onMicrophoneTurnOnByOthersConfirmation to open microphone or not.

  • function prototype:
Future<bool> muteLocallyByUserID(
  String targetUserID, {
  bool muted = true,
}) async

host

APIs of host

open

Opens (unlocks) the seat. allows you to unlock all seats in the room at once, or only unlock specific seat by targetIndex.

After opening(locks) the seat, all audience members can freely choose an empty seat to join and start chatting with others.

  • function prototype:
Future<bool> open({
  int targetIndex = -1,
}) async

close

Closes (locks) the seat. allows you to lock all seats in the room at once, or only lock specific seat by targetIndex.

After closing(locks) the seat, audience members need to request permission from the host or be invited by the host to occupy the seat.

  • function prototype:
Future<bool> close({
  int targetIndex = -1,
}) async

removeSpeaker

Removes the speaker with the user ID userID from the seat.

  • function prototype:
Future<void> removeSpeaker(String userID, {bool showDialogConfirm = true,}) async

acceptTakingRequest

The host accepts the seat request from the audience with the ID audienceUserID.

  • function prototype:
Future<bool> acceptTakingRequest(String audienceUserID) async

rejectTakingRequest

The host rejects the seat request from the audience with the ID audienceUserID.

  • function prototype:
Future<bool> rejectTakingRequest(String audienceUserID) async

inviteToTake

Host invite the audience with id userID to take seat

  • function prototype:
Future<bool> inviteToTake(String userID) async

mute

Mute the user at the targetIndex seat

After mute, if you want to un-mute, you can set muted to true.

And on side of the user at the targetIndex seat, return true/false in the callback of ZegoLiveAudioRoomAudioVideoEvents.onMicrophoneTurnOnByOthersConfirmation to open microphone or not.

  • function prototype:
Future<bool> mute({
  int targetIndex = -1,
  bool muted = true,
}) async

muteByUserID

Mute the user on seat by userID

After mute, if you want to un-mute, you can set muted to true.

And on side of the user at the targetIndex seat, return true/false in the callback of ZegoLiveAudioRoomAudioVideoEvents.onMicrophoneTurnOnByOthersConfirmation to open microphone or not.

  • function prototype:
Future<bool> muteByUserID(
  String userID, {
  bool muted = true,
}) async

audience

APIs of audience

take

Assigns the audience to the seat with the specified index, where the index represents the seat number starting from 0.

  • function prototype:
Future<bool> take(int index) async

applyToTake

The audience actively requests to occupy a seat.

  • function prototype:
Future<bool> applyToTake() async

cancelTakingRequest

The audience cancels the request to occupy a seat.

  • function prototype:
Future<bool> cancelTakingRequest() async

acceptTakingInvitation

Accept the seat invitation from the host. The context parameter represents the Flutter context object.

  • function prototype:
 Future<bool> acceptTakingInvitation({
   required BuildContext context,
   bool rootNavigator = false,
 }) async

speaker

APIs of speaker

leave

The speaker can use this method to leave the seat. If the showDialog parameter is set to true, a confirmation dialog will be displayed before leaving the seat.

  • function prototype:
Future<bool> leave({bool showDialog = true}) async

audio video

APIs related to audio video

microphone

microphone series APIs

localState

microphone state of local user

  • function prototype:
bool get localState

localStateNotifier

microphone state notifier of local user

  • function prototype:
ValueNotifier<bool> get localStateNotifier

state

microphone state of userID

  • function prototype:
bool state(String userID)

stateNotifier

microphone state notifier of userID

  • function prototype:
ValueNotifier<bool> stateNotifier(String userID)

turnOn

turn on/off userID microphone, if userID is empty, then it refers to local user

  • function prototype:
void turnOn(bool isOn, {String? userID})

switchState

switch userID microphone state, if userID is empty, then it refers to local user

  • function prototype:
void switchState({String? userID})

seiStream

stream of SEI(Supplemental Enhancement Information)

  • function prototype:
Stream<ZegoUIKitReceiveSEIEvent> seiStream()

class ZegoUIKitReceiveSEIEvent {
 final String typeIdentifier;

 final String senderID;
 final Map<String, dynamic> sei;

 final String streamID;
 final ZegoStreamType streamType;
}

sendSEI

if you want synchronize some other additional information by audio-video, send SEI(Supplemental Enhancement Information) with it.

  • function prototype:
Future<bool> sendSEI(
  Map<String, dynamic> seiData, {
  ZegoStreamType streamType = ZegoStreamType.main,
})

room

property

updateProperty/updateProperties

add/update room properties

  • function prototype:
Future<bool> updateProperty({
  required String roomID,
  required String key,
  required String value,
  bool isForce = false,
  bool isDeleteAfterOwnerLeft = false,
  bool isUpdateOwner = false,
}) async

Future<bool> updateProperties({
 required String roomID,
 required Map<String, String> roomProperties,
 bool isForce = false,
 bool isDeleteAfterOwnerLeft = false,
 bool isUpdateOwner = false,
}) async

deleteProperties

delete room properties

  • function prototype:
Future<bool> deleteProperties({
  required String roomID,
  required List<String> keys,
  bool isForce = false,
}) async

queryProperties

query room properties

  • function prototype:
Future<Map<String, String>> queryProperties({
  required String roomID,
}) async

propertiesStream

room properties stream notify

  • function prototype:
Stream<ZegoSignalingPluginRoomPropertiesUpdatedEvent> propertiesStream()

class ZegoSignalingPluginRoomPropertiesUpdatedEvent {
  final String roomID;
  final Map<String, String> setProperties;
  final Map<String, String> deleteProperties;
}

command

sendCommand

send room command

  • function prototype:
 Future<bool> sendCommand({
   required String roomID,
   required Uint8List command,
 }) async

commandReceivedStream

room command stream notify

  • function prototype:
Stream<ZegoSignalingPluginInRoomCommandMessageReceivedEvent> commandReceivedStream()


class ZegoSignalingPluginInRoomCommandMessageReceivedEvent {
  final List<ZegoSignalingPluginInRoomCommandMessage> messages;
  final String roomID;
}

class ZegoSignalingPluginInRoomCommandMessage {
  /// If you have a string encoded in UTF-8 and want to convert a Uint8List
  /// to that string, you can use the following method:
  ///
  /// import 'dart:convert';
  /// import 'dart:typed_data';
  ///
  /// String result = utf8.decode(commandMessage.message); // Convert the Uint8List to a string
  ///
  final Uint8List message;

  final String senderUserID;
  final int timestamp;
  final int orderKey;
}

Classes

ZegoUIKit APIs Features
ZegoUIKitPrebuiltLiveAudioRoom APIs Events Configs Components Migration_v3.x
Live Audio Room Widget. You can embed this widget into any page of your project to integrate the functionality of a audio chat room. You can refer to our documentation, or our sample code.
ZegoUIKitPrebuiltLiveAudioRoom APIs Events Configs Components Migration_v3.x
Live Audio Room Widget. You can embed this widget into any page of your project to integrate the functionality of a audio chat room. You can refer to our documentation, or our sample code.