Skip to main content

flutter_track_recorder 0.1.1 copy "flutter_track_recorder: ^0.1.1" to clipboard
flutter_track_recorder: ^0.1.1 copied to clipboard

Native local recording of existing audio and video sources, with storage safeguards and recoverable file metadata.

flutter_track_recorder #

Native local recording of existing audio and video sources. The recorder creates H.264/AAC MP4 files, reports lifecycle and storage events, and keeps files in private persistent storage until explicitly deleted.

Native compilation and synthetic-file tests do not establish compatibility with every physical device, camera, audio route or background transition. Check the capabilities API and validate your target devices before shipping.

Package boundaries #

  • flutter_track_recorder: writer, lifecycle API, bounded input queues, storage inventory and owned-file deletion. Depends only on the Flutter SDK.
  • flutter_track_recorder_livekit: optional adapter for existing local camera and microphone tracks. It does not connect rooms or acquire capture devices.
  • flutter_track_recorder_gallery: optional add-only gallery export. It does not delete the original file or require broad media-library read access.

The core does not depend on LiveKit, WebRTC, a gallery package, a server, or an application's widgets. Additional source adapters can use its native registry and native sample inputs without moving video frames through Dart channels.

Recording existing tracks #

The following example also uses the optional flutter_track_recorder_livekit package. It targets livekit_client 2.13.2 with flutter_webrtc 1.6.3. Compatibility with another version must be checked against its native track and audio-tap APIs.

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 this source/platform is unavailable.
  return;
}

final subscription = recorder.recorder.states.listen((event) {
  // Update your UI. "starting" is not proof of captured audio/video.
  // Only the native writer can announce "recording".
});

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

final recording = await recorder.stop();
if (recording.isPlayable) {
  // The persistent file is available at recording.path.
}

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

The application owns the source tracks. The LiveKit adapter's updateSources API wraps intentional microphone/camera toggles and camera replacement, keeping one output file. Intentionally disabled inputs become silence or black video; the adapter never reactivates a muted capture device. Unexpected source loss still terminates only the recording. Finish recording before disposing the broadcast or transferring capture to another session.

The initial source must be an active, unmuted local camera and microphone. Remote participants and screen sharing are rejected. The recorded content is the local camera and microphone only; guests, remote sound, chat and UI overlays are not composited into the file.

Configuration #

RecordingConfiguration describes a fixed output canvas. It does not resize or reconfigure the application's capture source.

Setting Default
Output H.264 video and AAC audio in an MP4 file
Canvas 720 × 1280 pixels
Frame rate 30 FPS
Video bitrate 4,000,000 bits per second
Audio bitrate 128,000 bits per second
Audio format 48 kHz, mono
Free-space reserve 128 MiB
Pending video At most 3 frames
Pending audio At most 300 ms

Check queryCapabilities() before recording. An accepted configuration or a successful prepare() does not guarantee that an encoder or storage operation cannot fail later. Listen for terminal events and handle RecordingException.

Lifecycle and concurrency #

TrackRecorder exposes:

  • queryCapabilities()
  • prepare(configuration) and start() for a native source adapter
  • states, state, currentSessionId, currentRecording
  • stop(reason: ...)
  • listRecordings() and deleteRecording(id)
  • dispose()

Commands are serialized. Repeated starts of an active session and repeated stops do not allocate additional writers. Old-session events cannot change the new session. A controller used only to list files does not own another controller's recording and cannot stop it on disposal.

States are idle, prepared, starting, recording, stopping, completed and failed. A completed result is exportable only if it contains a valid, nonempty audio/video file. An incomplete recovery entry is not a successful recording.

Stop reasons distinguish a user action, source replacement, interruption, unavailable samples, storage pressure, write failure and input backpressure. A recording failure is never a command to terminate the source or broadcast.

Storage and export #

The default reserve is 128 MiB. Space is checked before preparation and during writing; actual write failures are handled independently. The reserve reduces the risk of running out of room during finalization, but cannot guarantee success when another process consumes space or the storage device fails.

Files and bounded JSON manifests live under an application-private flutter_track_recorder directory. Deletion accepts recording identifiers, not arbitrary paths, and rejects active or unowned files. Interrupted files are kept; an unfinished MP4 is not promised to be repairable.

The inventory belongs to the application installation; the core does not know about accounts or profiles. Applications that support multiple accounts must persist and enforce their own recording ownership before attaching sources, listing files, exporting or deleting recordings.

Use a separate controller to inspect completed files without acquiring a camera or microphone:

final catalog = TrackRecorder();
final recordings = await catalog.listRecordings();
final playable = recordings.where((recording) => recording.isPlayable);
// Present authorized results from `playable` to the user.
await catalog.dispose();
import 'package:flutter_track_recorder_gallery/flutter_track_recorder_gallery.dart';

final exporter = NativeGalleryRecordingExporter();
final destination = await exporter.export(recording);
// destination.location identifies the confirmed gallery result.
// The private original is still retained.

Gallery export is a separate operation. It uses file paths/native streaming, not a complete video loaded into Dart memory. Permit additional disk space for the destination copy. A denied permission, cancellation, low-space condition or failed export leaves the original intact. In-flight exports are deduplicated; native receipts support retries after an application restart.

On iOS, an interrupted Photos transaction may be impossible to confirm with add-only permission. exportUncertain means that the user should inspect Photos; the exporter will not automatically create another copy. No read permission is requested to resolve that uncertainty.

On iOS the host must provide NSPhotoLibraryAddUsageDescription. Add-only export requires iOS 14 or later. Android gallery export uses MediaStore on API 29 or later, without broad READ_MEDIA_* or legacy storage permissions. Capture permissions remain the responsibility of the application that owns the tracks.

Source and timing limits #

  • The installed WebRTC SDK exposes a factory-wide local microphone tap. Both adapters validate local identity. iOS additionally rejects concurrent local microphone tracks. The Android SDK does not expose a public inventory of all local tracks, so the consuming application must ensure exclusive microphone ownership and stop recording before transferring it to another call/session. Neither tap provides arbitrary per-track audio isolation.
  • Mute is checked when samples arrive and before queued samples are submitted. Muted microphone data is never intentionally written as audible content.
  • iOS receives postprocessed microphone PCM; Android's local ADM tap may precede software noise processing. The recording's processing can therefore differ from the transmitted track on Android.
  • Video rotation is applied natively and the fixed output canvas preserves proportions. Intentional replacements use the adapter's source-change transaction. Unannounced replacements or unsupported sources end recording.
  • The recorder preserves track pixels and applies their rotation. It does not add the visual mirror used by a front-camera preview widget.
  • The audio tap does not expose a precise original capture timestamp on every platform. Audio uses a sample clock anchored to monotonic callback time; video timestamps are mapped into that clock domain. Physical audiovisual synchronization, route changes and long-duration drift require device tests.
  • Background recording is not guaranteed when the OS suspends capture. Missing sources cause controlled termination; the plugin does not create a second capture session to keep recording.
  • Encoding adds CPU/GPU, storage and thermal load. Bounded queues protect the source from unbounded work; they are not a claim of zero performance impact.

Platform requirements #

The core requires Dart 3.8 or later and Flutter 3.44 or later. Native writers are provided for iOS 13 or later and Android 7 (API 24) or later. The optional source and gallery adapters may impose additional requirements. No web or desktop writer is implemented.

The application must already hold any camera or microphone permissions required by its source. The core does not request access to capture devices or the media library.

Privacy #

The package does not send recordings or device information to a server and does not include analytics or tracking. Its bundled iOS privacy manifest declares disk-space access (E174.1) to prevent or stop recording when storage is low. Space information and derived values must remain on the device. The host app is responsible for its own data practices and the source adapter's dependencies.

License #

MIT. See LICENSE.

0
likes
130
points
354
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Native local recording of existing audio and video sources, with storage safeguards and recoverable file metadata.

Homepage
Repository (GitHub)
View/report issues

Topics

#recording #video #audio #camera

License

MIT (license)

Dependencies

flutter

More

Packages that depend on flutter_track_recorder

Packages that implement flutter_track_recorder