more docs

lib/src/events.dart

@@ -1,4 +1,5 @@
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
+import 'package:meta/meta.dart';
 
 import 'participant/local_participant.dart';
 import 'participant/participant.dart';
@@ -10,17 +11,26 @@ import 'publication/remote_track_publication.dart';
 import 'publication/track_publication.dart';
 import 'track/track.dart';
 import 'types.dart';
+import 'room.dart';
+import 'rtc_engine.dart';
+import 'signal_client.dart';
 
+/// Base type for all LiveKit events.
 abstract class LiveKitEvent {}
 
+/// Base type for all [Room] events.
 abstract class RoomEvent implements LiveKitEvent {}
 
+/// Base type for all [Participant] events.
 abstract class ParticipantEvent implements LiveKitEvent {}
 
+/// Base type for all [Track] events.
 abstract class TrackEvent implements LiveKitEvent {}
 
+/// Base type for all [RTCEngine] events.
 abstract class EngineEvent implements LiveKitEvent {}
 
+/// Base type for all [SignalClient] events.
 abstract class SignalEvent implements LiveKitEvent {}
 
 /// When the connection to the server has been interrupted and it's attempting
@@ -277,6 +287,8 @@ class EngineRemoteMuteChangedEvent with EngineEvent {
 //
 // Signal events
 //
+
+@internal
 class SignalConnectedEvent with SignalEvent {
   final lk_rtc.JoinResponse response;
   const SignalConnectedEvent({
@@ -284,6 +296,7 @@ class SignalConnectedEvent with SignalEvent {
   });
 }
 
+@internal
 class SignalCloseEvent with SignalEvent {
   final CloseReason? reason;
   const SignalCloseEvent({
@@ -291,6 +304,7 @@ class SignalCloseEvent with SignalEvent {
   });
 }
 
+@internal
 class SignalOfferEvent with SignalEvent {
   final rtc.RTCSessionDescription sd;
   const SignalOfferEvent({
@@ -298,6 +312,7 @@ class SignalOfferEvent with SignalEvent {
   });
 }
 
+@internal
 class SignalAnswerEvent with SignalEvent {
   final rtc.RTCSessionDescription sd;
   const SignalAnswerEvent({
@@ -305,6 +320,7 @@ class SignalAnswerEvent with SignalEvent {
   });
 }
 
+@internal
 class SignalTrickleEvent with SignalEvent {
   final rtc.RTCIceCandidate candidate;
   final lk_rtc.SignalTarget target;
@@ -314,6 +330,7 @@ class SignalTrickleEvent with SignalEvent {
   });
 }
 
+@internal
 // relayed by Engine
 class SignalParticipantUpdateEvent with SignalEvent, EngineEvent {
   final List<lk_models.ParticipantInfo> participants;
@@ -322,6 +339,7 @@ class SignalParticipantUpdateEvent with SignalEvent, EngineEvent {
   });
 }
 
+@internal
 class SignalConnectionQualityUpdateEvent with SignalEvent, EngineEvent {
   final List<lk_rtc.ConnectionQualityInfo> updates;
   const SignalConnectionQualityUpdateEvent({
@@ -329,6 +347,7 @@ class SignalConnectionQualityUpdateEvent with SignalEvent, EngineEvent {
   });
 }
 
+@internal
 class SignalLocalTrackPublishedEvent with SignalEvent {
   final String cid;
   final lk_models.TrackInfo track;
@@ -338,7 +357,8 @@ class SignalLocalTrackPublishedEvent with SignalEvent {
   });
 }
 
-// speaker update received through websocket
+@internal
+// Speaker update received through websocket
 // relayed by Engine
 class SignalSpeakersChangedEvent with SignalEvent, EngineEvent {
   final List<lk_models.SpeakerInfo> speakers;
@@ -347,6 +367,7 @@ class SignalSpeakersChangedEvent with SignalEvent, EngineEvent {
   });
 }
 
+@internal
 // Event received through data channel
 class EngineActiveSpeakersUpdateEvent with EngineEvent {
   final List<lk_models.SpeakerInfo> speakers;
@@ -355,6 +376,7 @@ class EngineActiveSpeakersUpdateEvent with EngineEvent {
   });
 }
 
+@internal
 class SignalLeaveEvent with SignalEvent {
   final bool canReconnect;
   const SignalLeaveEvent({
@@ -362,6 +384,7 @@ class SignalLeaveEvent with SignalEvent {
   });
 }
 
+@internal
 class SignalMuteTrackEvent with SignalEvent {
   final String sid;
   final bool muted;

lib/src/livekit.dart

@@ -6,7 +6,9 @@ import 'room.dart';
 class LiveKitClient {
   static const version = '0.5.4';
 
-  /// Connects to a LiveKit room
+  /// Convenience method for connecting to a LiveKit server.
+  /// Returns a [Room] upon a successful connect or throws when it fails.
+  /// Alternatively, it is possible to instantiate [Room] and call [Room.connect] directly.
   static Future<Room> connect(
     String url,
     String token, {

lib/src/participant/local_participant.dart

@@ -12,13 +12,16 @@ import '../options.dart';
 import '../proto/livekit_models.pb.dart' as lk_models;
 import '../publication/local_track_publication.dart';
 import '../rtc_engine.dart';
+import '../track/local.dart';
 import '../track/local/audio.dart';
 import '../track/local/video.dart';
 import '../types.dart';
 import '../utils.dart';
+import '../room.dart';
 import 'participant.dart';
 
-/// Represents the current participant in the room.
+/// Represents the current participant in the room. Instance of [LocalParticipant] is automatically
+/// created after successfully connecting to a [Room] and will be accessible from [Room.localParticipant].
 class LocalParticipant extends Participant<LocalTrackPublication> {
   @internal
   final VideoPublishOptions? defaultVideoPublishOptions;
@@ -40,7 +43,8 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
     updateFromInfo(info);
   }
 
-  /// publish an audio track to the room
+  /// Publish an [AudioTrack] to the [Room].
+  /// For most cases, using [setMicrophoneEnabled] would be simpler and recommended.
   Future<LocalTrackPublication<LocalAudioTrack>> publishAudioTrack(
     LocalAudioTrack track, {
     AudioPublishOptions? options,
@@ -250,12 +254,14 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
   List<LocalTrackPublication> get subscribedTracks =>
       super.subscribedTracks.cast<LocalTrackPublication>().toList();
 
+  /// A convenience property to get all video tracks.
   @override
   List<LocalTrackPublication<LocalVideoTrack>> get videoTracks =>
       trackPublications.values
           .whereType<LocalTrackPublication<LocalVideoTrack>>()
           .toList();
 
+  /// A convenience property to get all audio tracks.
   @override
   List<LocalTrackPublication<LocalAudioTrack>> get audioTracks =>
       trackPublications.values

lib/src/participant/participant.dart

@@ -29,30 +29,31 @@ abstract class Participant<T extends TrackPublication>
   @internal
   final RTCEngine engine;
 
-  /// map of track sid => published track
+  /// Map of track sid => published track
   final Map<String, T> trackPublications = {};
 
-  /// audio level between 0-1, 1 being the loudest
+  /// Audio level between 0-1, 1 being the loudest.
   double audioLevel = 0;
 
-  /// server assigned unique id
+  /// Server assigned unique id.
   final String sid;
 
-  /// user-assigned identity
+  /// User-assigned identity.
   String identity;
 
-  /// client-assigned metadata, opaque to livekit
+  /// Client-assigned metadata, opaque to livekit.
   String? metadata;
 
-  /// when the participant had last spoken
+  /// When the participant had last spoken.
   DateTime? lastSpokeAt;
 
   lk_models.ParticipantInfo? _participantInfo;
   bool _isSpeaking = false;
 
+  /// Connection quality between the [Participant] and the server.
   ConnectionQuality _connectionQuality = ConnectionQuality.unknown;
 
-  // suppport for multiple event listeners
+  // Suppport for multiple event listeners.
   final EventsEmitter<RoomEvent> roomEvents;
 
   /// when the participant joined the room
@@ -169,9 +170,10 @@ abstract class Participant<T extends TrackPublication>
     trackPublications[pub.sid] = pub;
   }
 
-  // Must implement
+  // Must be implemented by subclasses.
   Future<void> unpublishTrack(String trackSid, {bool notify = true});
 
+  /// Convenience method to unpublish all tracks.
   Future<void> unpublishAllTracks({bool notify = true}) async {
     final trackSids = trackPublications.keys.toSet();
     for (final trackid in trackSids) {
@@ -179,31 +181,26 @@ abstract class Participant<T extends TrackPublication>
     }
   }
 
-  //
+  /// Convenience property to check whether [TrackSource.camera] is published or not.
-  // Equality operators
-  // Object is considered equal when sid is equal
-  //
-  @override
-  int get hashCode => sid.hashCode;
-
-  @override
-  bool operator ==(Object other) => other is Participant && sid == other.sid;
-
   bool isCameraEnabled() {
     return !(getTrackPublicationBySource(TrackSource.camera)?.muted ?? true);
   }
 
+  /// Convenience property to check whether [TrackSource.microphone] is published or not.
   bool isMicrophoneEnabled() {
     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);
   }
 
-  /// Find a track publication by its [TrackSource]
+  /// Tries to find a [TrackPublication] by its [TrackSource]. Otherwise, will
+  /// return a compatible type of [TrackPublication] for the [TrackSource] specified.
+  /// returns null when not found.
   T? getTrackPublicationBySource(TrackSource source) {
     if (source == TrackSource.unknown) return null;
     // try to find by source
@@ -226,4 +223,12 @@ abstract class Participant<T extends TrackPublication>
                 e.kind == lk_models.TrackType.AUDIO &&
                 e.name == Track.screenShareName));
   }
+
+  // Equality operators
+  // Object is considered equal when sid is equal
+  @override
+  int get hashCode => sid.hashCode;
+
+  @override
+  bool operator ==(Object other) => other is Participant && sid == other.sid;
 }

lib/src/rtc_engine.dart

@@ -21,6 +21,7 @@ import 'signal_client.dart';
 import 'support/disposable.dart';
 import 'transport.dart';
 import 'types.dart';
+import 'room.dart';
 
 class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
   static const _lossyDCLabel = '_lossy';
@@ -49,7 +50,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
 
   ConnectionState _connectionState = ConnectionState.disconnected;
 
-  /// connection state of the room
+  /// Connection state of the [Room].
   ConnectionState get connectionState => _connectionState;
 
   // true if publisher connection has already been established.
@@ -120,7 +121,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
     return event.response;
   }
 
-  // there is no side-effect calling this method multiple times
+  /// Close connection between the server.
   Future<void> close() async {
     logger.fine('[$objectId] close()');
     if (_connectionState == ConnectionState.disconnected) {
@@ -143,6 +144,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
     // notifyListeners();
   }
 
+  @internal
   Future<lk_models.TrackInfo> addTrack({
     required String cid,
     required String name,
@@ -173,6 +175,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
     return event.track;
   }
 
+  @internal
   Future<void> negotiate({bool? iceRestart}) async {
     if (publisher == null) {
       return;
@@ -182,7 +185,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
     publisher!.negotiate(null);
   }
 
-  /* @internal */
+  @internal
   Future<void> sendDataPacket(
     lk_models.DataPacket packet,
   ) async {
@@ -227,6 +230,7 @@ class RTCEngine extends Disposable with EventsEmittable<EngineEvent> {
     logger.fine('[PUBLISHER] connected');
   }
 
+  @internal
   Future<void> reconnect() async {
     if (_connectionState == ConnectionState.disconnected) {
       logger.fine('$objectId reconnect() already closed');