withPreConnectAudio<T> method

Future<T> withPreConnectAudio<T>(
  1. Future<T> operation(), {
  2. Duration timeout = const Duration(seconds: 10),
  3. PreConnectOnError? onError,
})

Runs an async operation while a pre-connect audio buffer records.

This is primarily used for voice agent experiences to reduce perceived latency: the microphone starts recording before Room.connect completes, and the buffered audio is sent to the agent once it becomes active.

If operation throws, recording is stopped and the buffer is reset (discarding any buffered audio).

Example:

await room.withPreConnectAudio(
  () async {
    final creds = await tokenService.fetch();
    await room.connect(creds.serverUrl, creds.participantToken);
    return true;
  },
  timeout: const Duration(seconds: 20),
  onError: (error) => logger.warning('Preconnect failed: $error'),
);
  • Note: Ensure microphone permissions are granted early in your app lifecycle so pre-connect can start without additional prompts.
  • SeeAlso: PreConnectAudioBuffer

Implementation

Future<T> withPreConnectAudio<T>(
  Future<T> Function() operation, {
  Duration timeout = const Duration(seconds: 10),
  PreConnectOnError? onError,
}) async {
  preConnectAudioBuffer.setErrorHandler(onError);
  await preConnectAudioBuffer.startRecording(timeout: timeout);
  try {
    final result = await operation();
    unawaited(() async {
      try {
        await preConnectAudioBuffer.agentReadyFuture;
      } catch (error, stackTrace) {
        logger.warning('[Preconnect] agent readiness wait failed: $error', error, stackTrace);
      } finally {
        await preConnectAudioBuffer.reset();
      }
    }());
    return result;
  } catch (error) {
    await preConnectAudioBuffer.stopRecording(withError: error);
    await preConnectAudioBuffer.reset();
    logger.warning('[Preconnect] operation failed with error: $error');
    rethrow;
  }
}