video_forge library

Rust video engine — FRB bindings and native library loader only.

Classes

AudioTrackInput
Background audio lane for export mux (paths must be local FFmpeg-readable files).
BatchThumbnailBytesOptions
Batch in-memory thumbnails for UI previews (filmstrip, scrubber fallback).
BatchThumbnailBytesResult
BatchThumbnailOptions
BatchThumbnailResult
BurnInOverlay
One overlay layer baked to a PNG with alpha (paths from Flutter export rasterizer).
CompressOptions
CompressResult
DecoderCacheStats
Snapshot of the decoder cache state.
JobResult
MediaInfo
NativeBindings
Single entry point for loading the native library and initializing FRB.
OutputProfile
PlaybackFrame
PreviewFramePixelBuffer
Apple HW preview frame: BGRA CVPixelBuffer pointer for zero-copy texture present (V1.4).
PreviewFrameRgba
Single decoded preview frame (RGBA8888) for texture upload — Sprint V1.1.
PreviewFrameRgbaBuf
PR #5: preview frame paired with a ReleaseToken so the Dart side can hand the underlying buffer back to the Rust pool via a Finalizer (no manual bufferPoolRelease call required from app code). New code should prefer this struct; the bare PreviewFrameRgba is kept for back-compat.
ProgressEvent
ReleaseToken
PR #5: stable handle for a buffer the Rust pool owns. The Dart side can hand the underlying Uint8List directly to a texture (no copy), and when the parent ReleaseToken becomes unreachable, a Finalizer returns the buffer to the Rust pool via bufferPoolReleaseByToken.
RustLib
Main entrypoint of the Rust API
RustLibApi
ThumbnailBytesOptions
In-memory thumbnail (JPEG/WebP bytes) — no filesystem write.
ThumbnailOptions
VideoForgeError
VideoPreviewSession

Enums

ProcessingPhase
ThumbnailDecodeStatus
PR #3: per-position status surfaced from the Rust decode pipeline.
ThumbnailFormat
VideoCodec
VideoQuality

Extensions

JobResultPatterns on JobResult
Adds pattern-matching-related methods to JobResult.
OutputProfilePatterns on OutputProfile
Adds pattern-matching-related methods to OutputProfile.
PlaybackFramePatterns on PlaybackFrame
Adds pattern-matching-related methods to PlaybackFrame.
VideoForgeErrorPatterns on VideoForgeError
Adds pattern-matching-related methods to VideoForgeError.

Functions

activeJobCount() → Future<int>
Returns the number of active jobs.
batchThumbnailBytes({required BatchThumbnailBytesOptions options}) → Future<BatchThumbnailBytesResult>
Batch thumbnails as in-memory frames for filmstrip / scrub previews.
batchThumbnails({required BatchThumbnailOptions options}) → Future<BatchThumbnailResult>
Extract multiple thumbnails in one pass.
bufferPoolAcquire({required int minCapacity}) → Uint8List
Acquires a buffer from the video processor's native pool with a minimum capacity.
bufferPoolAcquireWithToken({required int minCapacity}) → (Uint8List, BigInt)
PR #5: acquire a buffer + return a stable token. The token can be passed back to buffer_pool_release_by_token when the consumer (e.g. a Dart ReleaseToken finalizer) is done with the buffer. The token is also useful for diagnostics ("5 PreviewFrameRgba in flight").
bufferPoolRelease({required List<int> buf}) → void
Releases a buffer back to the video processor's native pool.
bufferPoolReleaseByToken({required BigInt token}) → void
PR #5: release a buffer by its token. Called by the Dart-side Finalizer on a ReleaseToken when the corresponding frame object is garbage-collected. The token 0 is a no-op (reserved for "no token").
bufferPoolStats() → (BigInt, BigInt)
Returns the current statistics of the video processor's buffer pool (count, total bytes).
cancelJob({required String jobId}) → Future<bool>
Cancel a running job by id.
cleanupJob({required String jobId}) → Future<void>
Cleanup completed job state.
clearDecoderCache() → BigInt
Drop all cached demuxer/decoder pairs and return the number of entries dropped. Use for tests, low-memory warnings, or after a project is closed (so the next call for a new project does not see stale state from a previous one).
decodePreviewFramePixelBuffer({required String inputPath, required BigInt positionMs, int? maxEdge}) → Future<PreviewFramePixelBuffer>
Decode one preview frame as a BGRA CVPixelBuffer (Apple VideoToolbox — V1.4).
decodePreviewFrameRgba({required String inputPath, required BigInt positionMs, int? maxEdge}) → Future<PreviewFrameRgba>
Decode one preview frame as RGBA8888 (texture / in-memory scrub — no JPEG write).
decodePreviewFrameRgbaBuf({required String inputPath, required BigInt positionMs, int? maxEdge}) → Future<PreviewFrameRgbaBuf>
PR #5: same as decode_preview_frame_rgba but returns a PreviewFrameRgbaBuf paired with a release_token so the Dart side can return the underlying buffer to the pool via its Finalizer (no manual bufferPoolRelease required).
decoderCacheStats() → DecoderCacheStatsDto
Snapshot of the demuxer/decoder cache state. Cheap; takes the cache lock briefly. Use for telemetry, memory pressure warnings, and integration tests.
dropDecoderCache() → Future<int>
Drop every cached demuxer/decoder. Returns the number of entries dropped. Use this in low-memory warnings or when a project is closed. The underlying FFI is sync.
getMediaInfo({required String path}) → Future<MediaInfo>
Probe media metadata (fast mp4parse path, FFmpeg fallback).
initialize() → Future<void>
Initialize the native video processor (call once at app startup).
prefetchRemoteInput({required String url, required String destDir}) → String
Stream-copy a remote URL to a local file under dest_dir (opt-in; saves repeated HTTP opens).
prefetchRemoteInputRange({required String url, required BigInt startBytes, required BigInt endBytes, required String destDir}) → String
PR #4: download a byte range of a remote URL to a local file. Currently performs a full stream copy (Range-aware follow-up is tracked separately). See crate::ffmpeg::prefetch::prefetch_remote_input_range.
readDecoderCacheStats() → Future<DecoderCacheStats>
Read the current decoder cache stats. Cheap; takes the Rust lock briefly. The underlying FFI is sync (a parking_lot::Mutex read), so we wrap it in a Future for API consistency with the rest of the Dart bindings.
releasePreviewPixelBuffer({required BigInt pixelBufferPtr}) → void
Release a native preview pixel buffer not adopted by pixel_surface.
startCompress({required CompressOptions options}) → Stream<ProgressEvent>
Start compression in the background; returns job id immediately.
startPrefetchRemoteInput({required String url, required String destDir}) → Stream<ProgressEvent>
PR #4: stream-copy a remote URL to a local file asynchronously, reporting progress events through progress. Returns a job_id that can be polled with wait_for_job or cancelled via cancel_job. Reuses the same JobRegistry as compression so the kit's existing job-orchestration code can manage the lifecycle.
thumbnail({required ThumbnailOptions options}) → Future<String>
Extract a single thumbnail at the given position.
thumbnailBytes({required ThumbnailBytesOptions options}) → Future<Uint8List>
Thumbnail as encoded image bytes (JPEG/WebP) — no filesystem write (UI previews).
waitForJob({required String jobId}) → Future<JobResult>
Wait for a job to complete and return its result.

Typedefs

VideoProcessorError = VideoForgeError
Deprecated alias for VideoForgeError. Will be removed in 2.1.0.