@@ -34,7 +34,17 @@ import '../types/participant_state.dart';
3434
3535typedef PreConnectOnError = void Function (Object error);
3636
37+ /// Captures and buffers microphone audio before a room connection completes.
38+ ///
39+ /// This is used by `Room.withPreConnectAudio` to reduce perceived latency for
40+ /// voice agent experiences: the microphone can begin recording while the app is
41+ /// still connecting and dispatching an agent, then the buffered audio is sent
42+ /// once the agent becomes active.
43+ ///
44+ /// Audio is buffered in memory (bounded by [defaultMaxSize] ); if it overflows,
45+ /// the oldest audio is dropped until the agent is ready.
3746class PreConnectAudioBuffer {
47+ /// Topic used to send the buffered audio stream to agents.
3848 static const String dataTopic = 'lk.agent.pre-connect-audio-buffer' ;
3949
4050 static const int defaultMaxSize = 10 * 1024 * 1024 ; // 10MB
@@ -72,16 +82,33 @@ class PreConnectAudioBuffer {
7282 }) : _onError = onError,
7383 _requestSampleRate = sampleRate;
7484
75- // Getters
85+ /// Whether pre-connect recording is currently active.
7686 bool get isRecording => _isRecording;
87+
88+ /// Number of buffered bytes currently stored.
7789 int get bufferedSize => _buffer.length;
90+
91+ /// The local audio track used for recording while pre-connecting.
7892 LocalAudioTrack ? get localTrack => _localTrack;
7993
8094 Future <LocalTrackPublishedEvent >? _localTrackPublishedEvent;
8195
82- /// Future that completes when an agent is ready.
96+ /// Completes when an agent becomes active and the buffer has been sent.
97+ ///
98+ /// If the configured timeout elapses before an agent becomes active, this
99+ /// future completes with an error.
83100 Future <void > get agentReadyFuture => _agentReadyManager.future;
84101
102+ /// Starts capturing audio into an in-memory buffer.
103+ ///
104+ /// [timeout] controls how long to wait for an agent to become active. When the
105+ /// agent becomes active, buffered audio is sent automatically and
106+ /// [agentReadyFuture] completes. If the timeout is reached first,
107+ /// [agentReadyFuture] completes with an error and callers should [reset] the
108+ /// buffer.
109+ ///
110+ /// - Note: Ensure microphone permissions are granted before calling this, or
111+ /// audio capture may fail depending on platform.
85112 Future <void > startRecording ({
86113 Duration timeout = const Duration (seconds: 20 ),
87114 }) async {
@@ -180,6 +207,11 @@ class PreConnectAudioBuffer {
180207 ));
181208 }
182209
210+ /// Stops recording and releases native audio capture resources.
211+ ///
212+ /// If [withError] is provided, [agentReadyFuture] completes with that error.
213+ /// Otherwise, [agentReadyFuture] completes successfully (if not already
214+ /// completed).
183215 Future <void > stopRecording ({Object ? withError}) async {
184216 if (! _isRecording) return ;
185217 _isRecording = false ;
@@ -219,7 +251,8 @@ class PreConnectAudioBuffer {
219251 logger.info ('[Preconnect audio] stopped recording' );
220252 }
221253
222- // Clean-up & reset for re-use
254+ /// Stops recording and clears buffered audio and listeners so the instance
255+ /// can be reused.
223256 Future <void > reset () async {
224257 await stopRecording ();
225258 _timeoutTimer? .cancel ();
@@ -240,12 +273,19 @@ class PreConnectAudioBuffer {
240273 logger.info ('[Preconnect audio] reset' );
241274 }
242275
243- // Dispose the audio buffer and clean up all resources .
276+ /// Disposes this buffer (alias for [reset] ) .
244277 Future <void > dispose () async {
245278 await reset ();
246279 logger.info ('[Preconnect audio] disposed' );
247280 }
248281
282+ /// Sends the currently buffered audio to one or more agent identities.
283+ ///
284+ /// This is a one-shot operation; repeated calls are ignored after the buffer
285+ /// has been sent.
286+ ///
287+ /// The stream is written to [topic] (default: [dataTopic] ) and includes
288+ /// attributes that help the agent interpret the raw audio payload.
249289 Future <void > sendAudioData ({
250290 required List <String > agents,
251291 String topic = dataTopic,
0 commit comments