handbreak library
handbreak — production-grade Flutter media compression inspired by HandBrake's pipeline architecture.
See ARCHITECTURE.md for the HandBrake analysis that drives this design.
Classes
- AdvancedEncoderOptions
-
Advanced encoder knobs — codec-specific tuning without polluting the basic API.
Example:
AdvancedEncoderOptions(crf: 22, preset: 'slow', tune: 'film', extra: {'profile':'high'}) - AudioOptions
- AudioStreamInfo
- AverageBitrateRateControl
- Average-bitrate mode. Two-pass only where it provides real value — disabled by default on mobile.
- CompressionJob
-
Live handle returned by
VideoCompressor.start/ImageCompressor.start. Mirrors HandBrake's job lifecycle (HB_STATE_WORKING → HB_STATE_DONE) with Dart streams. - CompressionProgress
- Progress based on actual media timestamps/frames — mirrors sync.c's frame_count/est_frame_count model. Never faked with timers.
- CompressionResult
- Returned after mux+validate. Re-probed output is embedded as outputMediaInfo.
- ConstantQualityRateControl
- Constant-quality via discrete level → codec-aware CRF resolution.
- ConstantQualityValueRateControl
- Constant-quality via explicit native CRF/QP numeric. Advanced; codec-specific valid ranges apply — see QualityMapper.validRangeFor.
- ContainerSupport
- Muxer reality per platform — what containers can actually be written. Android MediaMuxer: MPEG_4, WEBM (VP8/VP9 + Opus/Vorbis), 3GP(h263), OGG(Opus API29+). iOS AVAssetExportSession: mp4/mov/m4v only.
- CropFilter
- DeinterlaceFilter
- DenoiseFilter
- EncodePlanResolver
- GrayscaleFilter
- HandbreakPlatform
- Stable async platform contract — mirrrors HandBrake's job/probe lifecycle.
- HandbreakProbe
- Robust source analysis — must run before encode when safe processing requires it. Mirrors HandBrake's scan.c → hb_title_t.
- HardwareCapabilities
- Snapshot of device encode/decode capabilities. Queried via native MediaCodecList / VideoToolbox.
- ImageCompressionOptions
- ImageCompressor
- ImagePlanTokens
- Small helper so callers without full MediaInfo can still resolve image jobs consistently.
- JobHandle
- Internal convenience used by platform impls that back jobs with EventChannel + MethodChannel.
- MediaInfo
- Robust source analysis — mirrors HandBrake's scan.c title probe. Every field that can influence the encode decision is surfaced here.
- PadFilter
- QualityMapper
- Codec-aware quality mapping. HandBrake's lesson: lower number can mean higher quality depending on codec. Each codec has its own valid CRF/QP range; we map discrete VideoQuality → native value.
- RateControl
- Preferred rate-control mode. Constant-quality is default (HandBrake-aligned).
- ResolutionCalculator
- Pure, heavily-tested resolution math — mirrors HandBrake's picture sizing (sanitize_filter_list_pre/post + hb_geometry_t handling).
- ResolvedAudioPlan
- Effective audio execution plan after fallback resolution.
- ResolvedPlan
- Fully-resolved, native-executable encode plan.
- RotateFilter
- ScaleFilter
- SharpenFilter
- Validation
- VideoCompressionOptions
- VideoCompressor
- VideoFilter
- Composable filter pipeline inspired by HandBrake's hb_filter_object_t chain. Filters are data objects; native resolves ordering and executes them.
- VideoStreamInfo
Enums
- AudioCodec
- Audio codec/mode. We never destroy audio silently.
- AudioMode
- DeinterlaceMode
- DenoiseStrength
- FrameRateMode
- Frame-rate handling. Mirrors HandBrake's CFR/VFR choice.
- HardwareAcceleration
- Hardware encoder selection policy — mirrors HandBrake's hwaccel fallback logic.
- ImageFormat
- ScaleAlgorithm
- SharpenStrength
- VideoCodec
- Pluggable video codecs. Default is H.264 for broad mobile compatibility.
- VideoContainer
- Container. MP4 is default; MKV used where Opus/AV1 passthrough prefers it.
- VideoPresetId
- Presets — conceptual analogues of HandBrake's built-ins, but tuned for mobile. Each preset maps to {codec, container, quality, max resolution, max fps, audio, hw policy}.
- VideoQuality
- Discrete constant-quality levels. Mapped codec-specifically in QualityMapper. DO NOT treat these as universal numbers; each codec maps them to its own CRF/QP range.
Extensions
Constants
- defaultTargetPlatformName → const String
- Name used for capability lookups when the platform query itself failed.
-
kAndroidMp4CopyableAudio
→ const Set<
String> - Audio codecs that can be bit-copied into MP4-family containers on Android.
-
kCanonicalFilterOrder
→ const List<
String> - Canonical filter order mirroring HandBrake's sanitize_filter_list_pre/post: crop → scale → pad → rotate → deinterlace → denoise → sharpen → grayscale
-
kIosCopyableAudio
→ const Set<
String> - iOS ExportSession re-encodes regardless; treat copy conservatively.
Functions
-
canonicalizeFilters(
List< VideoFilter> filters) → List<Map< String, dynamic> > -
mapNativeError(
Map< String, dynamic> map) → HandbreakException - Map a native error code string to a typed exception.
Typedefs
- VideoPresetAlias = VideoPresetId
-
Legacy alias so callers can write
VideoPreset.balancedlike the spec example.
Exceptions / Errors
- CancelledCompressionException
- CompressionTimeoutException
- Native watchdog/stall timeout — a codec stopped producing/consuming data and the job was terminated instead of being allowed to hang (P3-1).
- EncodingException
- HandbreakException
- Structured error hierarchy mirroring HandBrake's done_error categories. Every native error is mapped to one of these; nativeCode/nativeMessage are preserved for diagnostics without leaking internals.
- InsufficientStorageException
- InvalidInputException
- OutOfMemoryException
- OutputCreationException
- UnsupportedFormatException