flutter_track_recorder_livekit

Record an existing local LiveKit camera and microphone with flutter_track_recorder. The adapter attaches native sample sinks to borrowed tracks, without opening another camera or microphone, connecting a room, or changing audio-session policy.

Native adapters are provided for iOS and Android. Physical synchronization, interruptions and long-duration recording still require validation on target devices.

Usage

Supply active, unmuted LocalVideoTrack and LocalAudioTrack instances owned by your application. They must have camera and microphone sources respectively.

import 'package:flutter_track_recorder/flutter_track_recorder.dart';
import 'package:flutter_track_recorder_livekit/flutter_track_recorder_livekit.dart';

final recorder = LiveKitTrackRecorder();
final capabilities = await recorder.queryCapabilities();
if (!capabilities.supported) {
  // Explain that recording is unavailable for this source or device.
  return;
}

final subscription = recorder.recorder.states.listen((event) {
  // Update the recording indicator, progress and terminal result.
});

await recorder.start(
  videoTrack: localCamera,
  audioTrack: localMicrophone,
  configuration: const RecordingConfiguration(width: 1280, height: 720),
);

// The application can continue transmitting after the recorder stops.
final recording = await recorder.stop();
if (recording.isPlayable) {
  // Keep the private file, or export it through an optional exporter.
}

await subscription.cancel();
await recorder.dispose();

The native writer announces RecordingState.recording only after receiving audio and video. An acknowledgement from start() alone is not proof of captured media. recorder.recorder also exposes the core's local inventory and lifecycle API.

When configuration is omitted, the adapter derives an even-sized output canvas from the camera settings, limiting its longest side to 1280 pixels. Native fitting preserves source proportions. The recorder applies source rotation and does not add the mirror used only by a front-camera preview widget.

Ownership and source changes

  • The application owns the tracks. Stop recording before disposing the broadcast or transferring capture to another session. The adapter never closes a track, capture device or LiveKit room.
  • Stopping detaches sample listeners while the writer finalizes. File completion does not command the broadcast to end.
  • Repeated operations are serialized. Repeating start() with the same active sources does not allocate another recording.
  • Intentional microphone/camera toggles and camera replacements can keep the same file through updateSources. Unannounced replacements, unavailable enabled sources and expired transitions still stop with a typed reason.
  • Only the local camera and microphone are recorded. Remote participants, shared screens, chat, widgets and the mixed room output are excluded.

Changing camera or microphone state

Wrap the application's existing source operation so the native recorder can gate samples before capture changes, then attach the resulting local tracks:

While recording, wrap every application-driven microphone/camera enable, disable, camera switch or track restart in updateSources. This also rejects queued samples from before a change, even when mute and unmute happen quickly. Checking a track's current enabled state alone cannot provide that boundary.

await recorder.updateSources(
  videoEnabled: cameraEnabled,
  audioEnabled: false,
  audioChanging: true,
  videoTrack: () => currentCameraTrack,
  audioTrack: () => currentMicrophoneTrack,
  change: () async {
    await localParticipant.setMicrophoneEnabled(false);
  },
);

Use videoChanging: true for camera toggles, camera switching or a camera-track restart. Pass the intended final videoEnabled and audioEnabled values and getters that return the current tracks after the operation. The writer retains its original dimensions and fits replacement frames without stretching them.

While intentionally disabled, the camera produces black frames in the file and the microphone produces silence. When both are disabled, the recording clock continues. This does not keep capture running secretly or record a frozen image from before the camera was disabled. Normal samples resume after reattachment.

Only use this transaction for deliberate local source changes. A missing source outside the transaction remains a failure, and a transition that does not finish within ten seconds stops the recorder. Storage checks continue during silence and black video. Recorder-only errors do not prevent the requested application operation; an error thrown by change still propagates to its caller.

LiveKitRecorderSourceBinding is the optional native source-change interface. Custom binding wrappers must forward it to support continuous source changes. Bindings without this interface finalize recording before executing change.

Compatibility

The native integration targets livekit_client 2.13.2 and flutter_webrtc 1.6.3. Native sample-tap APIs are version-sensitive; compatibility with other versions must be checked before changing these dependencies.

The core and adapter require Dart 3.8 or later and Flutter 3.44 or later. Implementations are provided for iOS and Android only. Other platforms report unsupported capabilities. Capture permissions belong to the application that already owns the tracks. No server-side recording is invoked.

Audio and timing limits

WebRTC exposes a factory-wide local microphone tap. The application must ensure exclusive microphone ownership and stop recording before transferring capture to another call or session. iOS additionally checks the native microphone inventory; Android's SDK does not expose an equivalent public inventory, so global exclusivity cannot be verified independently there.

Muted microphone samples are suppressed. iOS receives postprocessed PCM, whereas Android's tap can precede the software processing applied to transmitted audio. Recorded processing can therefore differ from what remote participants hear.

When a source does not expose its original microphone capture timestamp, audio uses a sample clock anchored to monotonic delivery time. Actual lip sync, route changes and long-term drift require device measurements. Background recording is not guaranteed when the operating system suspends capture.

On iOS, a brief microphone delivery gap re-anchors that clock instead of ending the recording. When real microphone audio resumes, the core represents the missing interval as silence so AAC encoding does not shift later sound ahead of the video. This does not replace an unavailable microphone or extend the missing-source timeout. Without capture timestamps, delayed PCM bursts cannot be recovered losslessly: chunks that would overlap existing audio or start in the future are dropped. Valid camera timestamps keep their original cadence when delivery is late. Missing enabled media for five seconds, unexpected source changes, storage limits and writer failures still stop recording with a typed reason. Explicitly suppressed inputs are the only exception to source liveness.

Privacy

This adapter does not add analytics, tracking or network uploads. It observes tracks from a room owned by the host app; it does not connect that room. An iOS privacy manifest is bundled with the adapter. The core, LiveKit and WebRTC dependencies retain their own privacy declarations, and the host app remains responsible for its recording consent and data practices.

License

MIT. See LICENSE.