Expose ParticipantState (#848)

Author: hiroshihorie

lib/livekit_client.dart

@@ -50,14 +50,15 @@ export 'src/track/remote/audio.dart';
 export 'src/track/remote/remote.dart';
 export 'src/track/remote/video.dart';
 export 'src/track/track.dart';
+export 'src/types/attribute_typings.dart';
 export 'src/types/data_stream.dart';
 export 'src/types/other.dart';
 export 'src/types/participant_permissions.dart';
+export 'src/types/participant_state.dart';
 export 'src/types/rpc.dart';
 export 'src/types/transcription_segment.dart';
 export 'src/types/video_dimensions.dart';
 export 'src/types/video_encoding.dart';
 export 'src/types/video_parameters.dart';
 export 'src/widgets/screen_select_dialog.dart';
 export 'src/widgets/video_track_renderer.dart';
-export 'src/types/attribute_typings.dart';

lib/src/events.dart

@@ -26,6 +26,7 @@ import 'track/processor.dart';
 import 'track/track.dart';
 import 'types/other.dart';
 import 'types/participant_permissions.dart';
+import 'types/participant_state.dart' show ParticipantState;
 import 'types/transcription_segment.dart';
 
 /// Base type for all LiveKit events.
@@ -372,10 +373,21 @@ class ParticipantMetadataUpdatedEvent with RoomEvent, ParticipantEvent {
   String toString() => '${runtimeType}(participant: ${participant})';
 }
 
+class ParticipantStateUpdatedEvent with RoomEvent, ParticipantEvent {
+  final Participant participant;
+  final ParticipantState state;
+  const ParticipantStateUpdatedEvent({
+    required this.participant,
+    required this.state,
+  });
+
+  @override
+  String toString() => '${runtimeType}(participant: ${participant})';
+}
+
 /// [Pariticpant]'s [ConnectionQuality] has updated.
 /// Emitted by [Room] and [Participant].
-class ParticipantConnectionQualityUpdatedEvent
-    with RoomEvent, ParticipantEvent {
+class ParticipantConnectionQualityUpdatedEvent with RoomEvent, ParticipantEvent {
   final Participant participant;
   final ConnectionQuality connectionQuality;
   const ParticipantConnectionQualityUpdatedEvent({

lib/src/participant/participant.dart

@@ -26,6 +26,7 @@ import '../publication/track_publication.dart';
 import '../support/disposable.dart';
 import '../types/other.dart';
 import '../types/participant_permissions.dart';
+import '../types/participant_state.dart';
 import '../utils.dart';
 
 /// Represents a Participant in the room, notifies changes via delegates as
@@ -38,8 +39,8 @@ import '../utils.dart';
 
 /// Base for [RemoteParticipant] and [LocalParticipant],
 /// can not be instantiated directly.
-abstract class Participant<T extends TrackPublication>
-    extends DisposableChangeNotifier with EventsEmittable<ParticipantEvent> {
+abstract class Participant<T extends TrackPublication> extends DisposableChangeNotifier
+    with EventsEmittable<ParticipantEvent> {
   /// Reference to [Room]
   @internal
   final Room room;
@@ -80,16 +81,18 @@ abstract class Participant<T extends TrackPublication>
   ParticipantPermissions get permissions => _permissions;
 
   /// Attributes associated with the participant
-  UnmodifiableMapView<String, String> get attributes =>
-      UnmodifiableMapView(_attributes);
+  UnmodifiableMapView<String, String> get attributes => UnmodifiableMapView(_attributes);
   Map<String, String> _attributes = {};
 
+  // Participant state
+  ParticipantState get state => _state;
+  ParticipantState _state = ParticipantState.unknown;
+
   /// when the participant joined the room
   DateTime get joinedAt {
     final pi = _participantInfo;
     if (pi != null) {
-      return DateTime.fromMillisecondsSinceEpoch(pi.joinedAt.toInt() * 1000,
-          isUtc: true);
+      return DateTime.fromMillisecondsSinceEpoch(pi.joinedAt.toInt() * 1000, isUtc: true);
     }
     return DateTime.now();
   }
@@ -176,15 +179,22 @@ abstract class Participant<T extends TrackPublication>
     }
   }
 
+  void _setParticipantState(ParticipantState state) {
+    final didChange = _state != state;
+    _state = state;
+    if (didChange) {
+      [events, room.events].emit(ParticipantStateUpdatedEvent(
+        participant: this,
+        state: state,
+      ));
+    }
+  }
+
   void _setAttributes(Map<String, String> attrs) {
-    final diff = mapDiff(_attributes, attrs)
-        .map((k, v) => MapEntry(k as String, v as String));
+    final diff = mapDiff(_attributes, attrs).map((k, v) => MapEntry(k as String, v as String));
     _attributes = attrs;
     if (diff.isNotEmpty) {
-      [
-        events,
-        room.events
-      ].emit(ParticipantAttributesChanged(participant: this, attributes: diff));
+      [events, room.events].emit(ParticipantAttributesChanged(participant: this, attributes: diff));
     }
   }
 
@@ -201,9 +211,7 @@ abstract class Participant<T extends TrackPublication>
   @internal
   Future<bool> updateFromInfo(lk_models.ParticipantInfo info) async {
     logger.fine('LocalParticipant.updateFromInfo(info: $info)');
-    if (_participantInfo != null &&
-        _participantInfo!.sid == info.sid &&
-        _participantInfo!.version > info.version) {
+    if (_participantInfo != null && _participantInfo!.sid == info.sid && _participantInfo!.version > info.version) {
       return false;
     }
 
@@ -219,6 +227,7 @@ abstract class Participant<T extends TrackPublication>
     _setAttributes(info.attributes);
     _participantInfo = info;
     setPermissions(info.permission.toLKType());
+    _setParticipantState(info.state.toLKType());
 
     return true;
   }
@@ -278,19 +287,14 @@ abstract class Participant<T extends TrackPublication>
   T? getTrackPublicationBySource(TrackSource source) {
     if (source == TrackSource.unknown) return null;
     // try to find by source
-    final result =
-        trackPublications.values.firstWhereOrNull((e) => e.source == source);
+    final result = trackPublications.values.firstWhereOrNull((e) => e.source == source);
     if (result != null) return result;
     // try to find by compatibility
-    return trackPublications.values
-        .where((e) => e.source == TrackSource.unknown)
-        .firstWhereOrNull((e) =>
-            (source == TrackSource.microphone && e.kind == TrackType.AUDIO) ||
-            (source == TrackSource.camera && e.kind == TrackType.VIDEO) ||
-            (source == TrackSource.screenShareVideo &&
-                e.kind == TrackType.VIDEO) ||
-            (source == TrackSource.screenShareAudio &&
-                e.kind == TrackType.AUDIO));
+    return trackPublications.values.where((e) => e.source == TrackSource.unknown).firstWhereOrNull((e) =>
+        (source == TrackSource.microphone && e.kind == TrackType.AUDIO) ||
+        (source == TrackSource.camera && e.kind == TrackType.VIDEO) ||
+        (source == TrackSource.screenShareVideo && e.kind == TrackType.VIDEO) ||
+        (source == TrackSource.screenShareAudio && e.kind == TrackType.AUDIO));
   }
 
   /// Convenience property to check whether [TrackSource.camera] is published or not.
@@ -300,20 +304,17 @@ abstract class Participant<T extends TrackPublication>
 
   /// Convenience property to check whether [TrackSource.microphone] is published or not.
   bool isMicrophoneEnabled() {
-    return !(getTrackPublicationBySource(TrackSource.microphone)?.muted ??
-        true);
+    return !(getTrackPublicationBySource(TrackSource.microphone)?.muted ?? true);
   }
 
   /// Convenience property to check whether [TrackSource.screenShareVideo] is published or not.
   bool isScreenShareEnabled() {
-    return !(getTrackPublicationBySource(TrackSource.screenShareVideo)?.muted ??
-        true);
+    return !(getTrackPublicationBySource(TrackSource.screenShareVideo)?.muted ?? true);
   }
 
   /// Convenience property to check whether [TrackSource.screenShareAudio] is published or not.
   bool isScreenShareAudioEnabled() {
-    return !(getTrackPublicationBySource(TrackSource.screenShareAudio)?.muted ??
-        true);
+    return !(getTrackPublicationBySource(TrackSource.screenShareAudio)?.muted ?? true);
   }
 
   /// (Equality operator) [Participant.hashCode] is same as [sid.hashCode].

lib/src/types/participant_state.dart

@@ -0,0 +1,43 @@
+// Copyright 2025 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import '../proto/livekit_models.pb.dart' as lk_models;
+
+/// Represents the state of a participant in the room.
+enum ParticipantState {
+  /// Websocket is connected, but no offer has been sent yet
+  joining,
+
+  /// Server has received the client's offer
+  joined,
+
+  /// ICE connectivity has been established
+  active,
+
+  /// Websocket has disconnected
+  disconnected,
+
+  /// Unknown state
+  unknown,
+}
+
+extension ParticipantStateExt on lk_models.ParticipantInfo_State {
+  ParticipantState toLKType() => switch (this) {
+        lk_models.ParticipantInfo_State.JOINING => ParticipantState.joining,
+        lk_models.ParticipantInfo_State.JOINED => ParticipantState.joined,
+        lk_models.ParticipantInfo_State.ACTIVE => ParticipantState.active,
+        lk_models.ParticipantInfo_State.DISCONNECTED => ParticipantState.disconnected,
+        _ => ParticipantState.unknown,
+      };
+}