From b91c822fbab9e9ef68265a2fdffff0203919c378 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Sun, 12 Dec 2021 19:09:38 +0700 Subject: [PATCH] more docs --- example/lib/widgets/controls.dart | 2 +- lib/src/participant/local_participant.dart | 6 ++-- lib/src/participant/participant.dart | 20 +++++++----- lib/src/track/local.dart | 23 +++++++++++--- lib/src/track/options.dart | 36 +++++++++++++++++----- 5 files changed, 63 insertions(+), 24 deletions(-) diff --git a/example/lib/widgets/controls.dart b/example/lib/widgets/controls.dart index 5dc961a..a1ebad3 100644 --- a/example/lib/widgets/controls.dart +++ b/example/lib/widgets/controls.dart @@ -74,7 +74,7 @@ class _ControlsWidgetState extends State { if (track == null) return; try { - final newPosition = position.swap(); + final newPosition = position.switched(); await track.setCameraPosition(newPosition); setState(() { position = newPosition; diff --git a/lib/src/participant/local_participant.dart b/lib/src/participant/local_participant.dart index fb4d410..ff957f7 100644 --- a/lib/src/participant/local_participant.dart +++ b/lib/src/participant/local_participant.dart @@ -85,7 +85,8 @@ class LocalParticipant extends Participant { return pub; } - /// Publish a video track to the room + /// Publish a [LocalVideoTrack] to the [Room]. + /// For most cases, using [setCameraEnabled] would be simpler and recommended. Future> publishVideoTrack( LocalVideoTrack track, { VideoPublishOptions? publishOptions, @@ -174,7 +175,7 @@ class LocalParticipant extends Participant { return pub; } - /// Unpublish a track that's already published + /// Unpublish a [LocalTrackPublication] that's already published by this [LocalParticipant]. @override Future unpublishTrack(String trackSid, {bool notify = true}) async { logger.finer('Unpublish track sid: $trackSid, notify: $notify'); @@ -279,6 +280,7 @@ class LocalParticipant extends Participant { } /// A convenience method to publish a track for a specific [TrackSource]. + /// This is the recommended method to publish tracks. Future setSourceEnabled( TrackSource source, bool enabled) async { logger.fine('setSourceEnabled(source: $source, enabled: $enabled)'); diff --git a/lib/src/participant/participant.dart b/lib/src/participant/participant.dart index dd1c8d6..2f093f6 100644 --- a/lib/src/participant/participant.dart +++ b/lib/src/participant/participant.dart @@ -10,8 +10,10 @@ import '../publication/track_publication.dart'; import '../room.dart'; import '../support/disposable.dart'; import '../track/track.dart'; +import '../track/local.dart'; import '../types.dart'; import 'remote_participant.dart'; +import 'local_participant.dart'; /// Represents a Participant in the room, notifies changes via delegates as /// well as ChangeNotifier/providers. @@ -63,27 +65,29 @@ abstract class Participant return DateTime.now(); } - /// if participant is currently speaking + /// if [Participant] is currently speaking. bool get isSpeaking => _isSpeaking; - /// true if participant is publishing an audio track and is muted + /// true if [Participant] is publishing an [AudioTrack] and is muted. bool get isMuted => audioTracks.firstOrNull?.muted ?? true; + /// true if this [Participant] has more than 1 [AudioTrack]. bool get hasAudio => audioTracks.isNotEmpty; + /// true if this [Participant] has more than 1 [VideoTrack]. bool get hasVideo => videoTracks.isNotEmpty; - /// Connection quality of the participant + /// Connection quality between the [Participant] and the Server. ConnectionQuality get connectionQuality => _connectionQuality; - /// tracks that are subscribed to + /// [Track]s that this [Participant] is subscribed to. List get subscribedTracks => trackPublications.values.where((e) => e.subscribed).toList(); - // Must be implemented by child class + // Must be implemented by child class. List get videoTracks; - // Must be implemented by child class + // Must be implemented by child class. List get audioTracks; /// for internal use @@ -220,11 +224,11 @@ abstract class Participant e.name == Track.screenShareName)); } - // Equality operators - // Object is considered equal when sid is equal + /// (Equality operator) [Participant.hashCode] is same as [sid.hashCode]. @override int get hashCode => sid.hashCode; + /// (Equality operator) [Participant] is considered equal when [sid]'s are equal. @override bool operator ==(Object other) => other is Participant && sid == other.sid; } diff --git a/lib/src/track/local.dart b/lib/src/track/local.dart index 25c57d2..3bbd5d0 100644 --- a/lib/src/track/local.dart +++ b/lib/src/track/local.dart @@ -9,12 +9,22 @@ import '../proto/livekit_models.pb.dart' as lk_models; import '../types.dart'; import 'options.dart'; import 'track.dart'; +import '../track/local/audio.dart'; +import '../track/local/video.dart'; +import '../track/remote/audio.dart'; +import '../track/remote/video.dart'; +import '../events.dart'; +import '../participant/remote_participant.dart'; +/// Used to group [LocalVideoTrack] and [RemoteVideoTrack]. mixin VideoTrack on Track {} + +/// Used to group [LocalAudioTrack] and [RemoteAudioTrack]. mixin AudioTrack on Track {} +/// Base class for [LocalAudioTrack] and [LocalVideoTrack]. abstract class LocalTrack extends Track { - // Options used for this track + /// Options used for this track abstract LocalTrackOptions currentOptions; LocalTrack( @@ -31,8 +41,9 @@ abstract class LocalTrack extends Track { mediaStreamTrack, ); - // Only local tracks can set muted. - // Returns true if muted, false if unchanged. + /// Mutes this [LocalTrack]. This will stop the sending of track data + /// and notify the [RemoteParticipant] with [TrackMutedEvent]. + /// Returns true if muted, false if unchanged. Future mute() async { logger.fine('LocalTrack.mute() muted: $muted'); if (muted) return false; // already muted @@ -44,7 +55,9 @@ abstract class LocalTrack extends Track { return true; } - // Returns true if unmuted, false if unchanged. + /// Un-mutes this [LocalTrack]. This will re-start the sending of track data + /// and notify the [RemoteParticipant] with [TrackUnmutedEvent]. + /// Returns true if un-muted, false if unchanged. Future unmute() async { logger.fine('LocalTrack.unmute() muted: $muted'); if (!muted) return false; // already un-muted @@ -67,7 +80,7 @@ abstract class LocalTrack extends Track { return didStop; } - /// Creates a [rtc.MediaStream] from LocalTrackOptions. + /// Creates a [rtc.MediaStream] from [LocalTrackOptions]. @internal static Future createStream( LocalTrackOptions options, diff --git a/lib/src/track/options.dart b/lib/src/track/options.dart index 81970ad..0e3140a 100644 --- a/lib/src/track/options.dart +++ b/lib/src/track/options.dart @@ -1,23 +1,23 @@ import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc; +import '../track/local/video.dart'; +import '../track/local/audio.dart'; -enum LocalVideoTrackType { - camera, - display, -} - +/// A type that represents front or back of the camera. enum CameraPosition { front, back, } +/// Convenience extension for [CameraPosition]. extension CameraPositionExt on CameraPosition { /// Return a [CameraPosition] which front and back is switched. - CameraPosition swap() => { + CameraPosition switched() => { CameraPosition.front: CameraPosition.back, CameraPosition.back: CameraPosition.front, }[this]!; } +/// Options used when creating a [LocalVideoTrack] that captures the camera. class CameraTrackOptions extends LocalVideoTrackOptions { final CameraPosition cameraPosition; @@ -44,6 +44,7 @@ class CameraTrackOptions extends LocalVideoTrackOptions { ); } +/// Options used when creating a [LocalVideoTrack] that captures the screen. class ScreenShareTrackOptions extends LocalVideoTrackOptions { const ScreenShareTrackOptions(); } @@ -55,7 +56,7 @@ abstract class LocalTrackOptions { Map toMediaConstraintsMap(); } -/// Options when creating a LocalVideoTrack. +/// Base class for options when creating a [LocalVideoTrack]. abstract class LocalVideoTrackOptions extends LocalTrackOptions { // final LocalVideoTrackType type; final VideoParameters params; @@ -69,6 +70,7 @@ abstract class LocalVideoTrackOptions extends LocalTrackOptions { params.toMediaConstraintsMap(); } +/// A type that represents video encoding information. class VideoEncoding { final int maxFramerate; final int maxBitrate; @@ -83,6 +85,7 @@ class VideoEncoding { '${runtimeType}(maxFramerate: ${maxFramerate}, maxBitrate: ${maxBitrate})'; } +/// Convenience extension for [VideoEncoding]. extension VideoEncodingExt on VideoEncoding { rtc.RTCRtpEncoding toRTCRtpEncoding({ String? rid, @@ -242,12 +245,29 @@ class VideoParameters { }; } -/// Options when creating an LocalAudioTrack. Placeholder for now. +/// Options used when creating a [LocalAudioTrack]. class LocalAudioTrackOptions extends LocalTrackOptions { + /// Attempt to use noiseSuppression option (if supported by the platform) + /// See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings/noiseSuppression + /// Defaults to true. final bool noiseSuppression; + + /// Attempt to use echoCancellation option (if supported by the platform) + /// See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings/echoCancellation + /// Defaults to true. final bool echoCancellation; + + /// Attempt to use autoGainControl option (if supported by the platform) + /// See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/autoGainControl + /// Defaults to true. final bool autoGainControl; + + /// Attempt to use highPassFilter options (if supported by the platform) + /// Defaults to false. final bool highPassFilter; + + /// Attempt to use typingNoiseDetection option (if supported by the platform) + /// Defaults to true. final bool typingNoiseDetection; const LocalAudioTrackOptions({