flutter_track_recorder_livekit 0.1.2
flutter_track_recorder_livekit: ^0.1.2 copied to clipboard
Records existing local LiveKit camera and microphone tracks through native track adapters.
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.