pro_video_editor

What's Changed

• fix(darwin): never start an AVAssetExportSession that was already cancelled by @hm21 in #191

Full Changelog: v2.11.2...v2.11.3

• FIX(iOS, macOS): Cancelling a render or split while its export still waits for the encoder no longer crashes the app. The queued session was cancelled and then started anyway, which AVFoundation answers with an Objective-C exception Swift cannot catch.
• FIX(iOS, macOS): A cancelled render now unwinds at the HDR pre-transcode or transition pre-render it is in, instead of building the whole composition first and reporting the cancellation as a render error.
• FIX(iOS, macOS): Cancelling an audio merge now stops its encoder instead of running the container to completion, and a cancelled extraction no longer encodes a result nobody reads.
• FIX(iOS, macOS): A cancelled or failed job no longer leaves a half-written file behind — a split half at the path you gave it, a transition blend, or a merge container.

What's Changed

• perf: keep a stop-motion export and its audio off the managed heap by @hm21 in #185

Full Changelog: v2.11.1...v2.11.2

• PERF(android, iOS, macOS): A file-backed image is handed to the renderer as a path and opened only while it is decoded, instead of crossing the platform channel as bytes. A few hundred stop-motion frames at 3–4 MB each used to exhaust Android's heap before the first one was decoded. Applies to StopMotionFrame, image VideoLayers and ChromaKey.backgroundImage built from EditorLayerImage.file; other sources still travel as bytes.
• PERF(android): A VideoRenderData.audioTracks entry is pre-rendered through a scratch file instead of one in-memory PCM byte array, which reached ~30 MB for a three-minute stereo track.
• FIX(android): A source whose decoder emits float PCM no longer comes out as noise in extractAudio/mergeAudio — the samples were read big-endian on a little-endian device.
• FIX(android): An audioTracks entry that is shorter than its slot and not looping now fills the rest of that slot with silence, as documented, instead of ending the exported audio early.

What's Changed

• fix: honor EXIF orientation when decoding caller-supplied images by @hm21 in #184

Full Changelog: v2.11.0...v2.11.1

• FIX(android, iOS, macOS): A ChromaKey.backgroundImage or image VideoLayer fed a photo straight from the gallery no longer renders sideways — the EXIF Orientation tag is now honored on all three platforms.
• FIX(iOS, macOS): A stop-motion frame no longer lands sideways when its thumbnail decode falls back to the full-size decode.
• PERF(android): An image VideoLayer is decoded at the size it will be scaled to instead of at full resolution, so a large gallery photo no longer risks an out-of-memory overlay.

What's Changed

• feat: chroma key (greenscreen) for the render pipeline by @hm21 in #183

Full Changelog: v2.10.0...v2.11.0

• FEAT(android, iOS, macOS): Add ChromaKey — green-screen removal with a soft edge and spill suppression. The keyed area becomes a backgroundColor, a backgroundImage, or (in a VideoComposition) the layer below. Settable on VideoRenderData, VideoLayer and VideoSegment, resolved per clip as segment → layer → global. H.264/HEVC carry no alpha, so on the single-track videoSegments path a key without a background is flattened to black.
• FEAT: ChromaKey.autoDetect(video) measures the key color and similarity off the footage, for any saturated screen hue. ChromaKey.detect returns the raw measurement. Costs one thumbnail decode, no render.
• FEAT: ChromaKey.greenScreen() and ChromaKey.blueScreen() presets. Blue separates skin better but crowds denim and blue eyes, so it keys tighter and despills more gently.
• FIX(android): A VideoComposition layer no longer squares its own alpha. VideoCompositionTransformation blended against an already-transparent framebuffer, thinning any partially transparent edge.
• FIX(android, iOS, macOS): Two sources resolved in the same millisecond no longer collide on one temp file in EditorVideo.safeFilePath.

What's Changed

• feat: end a clip where both of its tracks still have content by @hm21 in #182

Full Changelog: v2.9.0...v2.10.0

• FEAT(iOS, macOS): Add VideoRenderData.trimToCommonTrackEnd (default false). Ends each clip where both its video and audio track still have content, so an export no longer finishes on a stretch of missing audio — the seam a looping player replays every cycle. Leave it off when a clip is meant to outlast its own audio.

What's Changed

• fix: distinguish transient codec-resource failures from encoder incompatibility by @hm21 in #181

Full Changelog: v2.8.0...v2.9.0

• FEAT(android): RenderEncoderException now carries isTransient. A render that failed because the device's codec resources were exhausted is flagged as retryable, so it can be told apart from a genuine format/encoder incompatibility, which is not. Covers a starved decoder as well as a starved encoder.
• FIX(android): The software-encoder fallback no longer silently re-runs the hardware encoder under a software-encoder label. It is skipped with an explicit log line when the device has no usable software encoder.

What's Changed

• feat: Implement audio merging functionality with configuration models by @hm21 in #180

Full Changelog: v2.7.1...v2.8.0

• FEAT(android, iOS, macOS): Add ProVideoEditor.mergeAudioToFile — merge an ordered list of trimmed clip windows (AudioMergeConfigs) into one gap-less audio file plus a per-segment offset map (AudioMergeResult) that maps each clip back onto the output timeline. Every segment is brought to one uniform format (optional sampleRate/channels resample/downmix), a clip without an audio track contributes silence instead of throwing, and a single-segment merge is byte-for-byte identical to extractAudioToFile. WAV output is exact on all platforms; other formats encode to AAC. Not supported on Web/Windows/Linux.

What's Changed

• fix: render transitions that fully consume an adjacent clip by @hm21 in #179

Full Changelog: v2.7.0...v2.7.1

• FIX(android, iOS, macOS): A clip transition whose blend fully consumes an adjacent clip (no non-blended body left) now renders instead of degrading to a hard cut. planOverlap previously required both sides to keep some non-blended body, so a boundary where a clip is entirely the blend — two back-to-back transitions sharing a short clip, or a pre-rendered seam trimmed to exactly the blend — fell back to a hard cut (not enough content for boundary). The fully-consumed side is now dropped and the blend takes its place; zero-length clips are no longer fed to the composer.

What's Changed

• perf: stream-copy split halves instead of re-encoding them by @hm21 in #178

Full Changelog: v2.6.0...v2.7.0

• PERF(iOS, macOS): Splitting without an explicit bitrate now stream-copies both halves (passthrough export, frame-accurate via a container edit list) instead of re-encoding them. Measured on an M-series Mac: 29.5s 720p H.264 404ms → 32ms, 5s 10-bit HEVC 793ms → 13ms, 32s 4K60 14.3s → 0.12s. This also fixes two quality losses of the old re-encode: 60fps sources no longer drop to 30fps, and HEVC/HDR sources are no longer converted to 8-bit H.264. An explicit bitrate/qualityConfig re-encodes as before; a source that cannot be stream-copied falls back to the re-encode automatically.
• PERF(android): A split without an explicit bitrate now transmuxes both halves losslessly (Media3 edit-list trim: the mid-GOP half keeps samples from the preceding keyframe and an MP4 edit list gates playback at the exact cut — frame-accuracy verified pixel-exact against the plugin's own thumbnail/metadata pipelines). Measured on a Galaxy S26: 32s 4K60 8.6s → 1.2s, 5s 10-bit HEVC 724ms → 290ms, 29.5s 720p H.264 1.4s → 1.0s. The halves no longer lose quality and HEVC/HDR no longer converts to 8-bit H.264. An out-of-range split position is now validated explicitly up front (same PlatformException as before, since a transmux — unlike the old transcode — would not fail on its own).
• FIX(iOS, macOS): The export watchdog now fires reliably for bounds tighter than its 250ms poll interval, and a stall/timeout is no longer misreported as a cancellation when the force-cancelled export happens to finish the race first.

What's Changed

• fix: diagnose split-export stalls and serialize encoder-heavy exports by @hm21 in #176
• fix: guard render encodes with the stall watchdog and serialize them on Android by @hm21 in #177

Full Changelog: v2.5.1...v2.6.0

• FIX(android, iOS, macOS): Concurrent split and render re-encodes no longer contend for the hardware encoder. They share a process-wide gate so only one runs at a time; previously they starved each other on the shared encoder pool — measured, three concurrent 4K re-encodes each took ~43s versus ~19s alone — and on a throttled device a starved session could sit at 0% until the watchdog (the reported split freeze). Each encode now runs at its solo speed, and the wait is queued before the watchdog starts, so it never counts as a stall. Passthrough/stream-copy exports (no encoder) stay ungated.
• FEAT(android, iOS, macOS): Split and render exports are guarded by a stall watchdog: an encode that makes no forward progress for stallTimeout (split default 12s) is force-cancelled with a diagnostic reason instead of hanging — e.g. Split export stalled after 12s with no progress [half=end progress=0.00 segment=0.52s split=0.53s total=1.05s preset=… audio=false] (preset on iOS/macOS, mime on Android). A wedged encode therefore releases its gate slot instead of deadlocking later exports. exportTimeout (hard bound) and stallTimeout (inner bound) are tunable on SplitVideoModel (stallTimeout must be < exportTimeout); successful exports are unaffected.

• FIX(iOS, macOS): Loading many clips no longer freezes the editor. A thumbnail decoder race (out-of-order callbacks seen on iOS 26.5) could hang getThumbnails forever or map frames to the wrong timestamps; frames now stay index-aligned with their requested timestamps and the call always completes.

• FEAT(android, iOS, macOS): A ClipTransition on the last (or only) VideoSegment now wraps back into the first segment, so a single-track render loops seamlessly — e.g. a dissolve on one segment cross-dissolves on restart. Overlap types (dissolve/slide/push/wipe) shorten the output by the transition duration and require a single clip longer than 2× the duration (otherwise the wrap is skipped); dip types (fadeToBlack/fadeToWhite) keep the length and dip through the color at the seam. Previously a transition on the last segment was silently ignored.

• FIX(android, iOS, macOS): The render bitrate is now enforced as a real maximum instead of being silently ignored (Android transmuxed the source untouched; iOS/macOS picked an AVAssetExportSession preset with its own bitrate). A source above the cap is re-encoded down to it, a source already within it keeps a lossless fast path (transmux / passthrough), and a null bitrate is unchanged. Note: an over-cap source that used to export losslessly is now re-encoded.

• CHORE(android): Migrate the Android module to Flutter's built-in Kotlin (drop the manual Kotlin Gradle Plugin apply) so the plugin no longer triggers the KGP deprecation warning and stays AGP 9+ compatible. Now requires Flutter 3.44+.

• FIX(android, iOS, macOS): Stop-motion render progress now advances smoothly instead of sitting near 0% and snapping to 100% at the end. Media3's image-to-video export reports no intra-export progress on Android, so the encode phase is now driven by a smooth, monotonic time-based estimate (using the real value when available); Darwin reports 100% only after the writer finishes so the finalize step stays visible.

• PERF(android): Timestamp thumbnails (getThumbnails) are now extracted with up to three parallel hardware decoders that each decode forward through a contiguous timeline chunk (every GOP decoded at most once), with frames GPU-scaled straight to the thumbnail size — instead of one software MediaMetadataRetriever per timestamp. Measured on a Galaxy S26: 20 timeline thumbnails from a 720p H.264 video 2.8s → 0.64s (~4x), 10 from a 1080p 10-bit HEVC video 6.2s → 0.3s (~20x), 14 from a 6s 4K60 HEVC clip 3.6s → 1.3s (~3x), with roughly 3-4x less CPU overall. Extraction keeps its speed while the UI is actively rendering (batch-mode decoder hints, non-blocking pump at display priority). Frame positions are unchanged (still the closest frame) and HDR10/rotation are handled by the GPU. Falls back to Media3 FrameExtractor, then to the previous retriever path when a video can't be decoded in hardware.

• FIX(android, iOS, macOS): Layer animateOut / animateInOut animations now play for layers that run until the end of the video (endTime unset). An open-ended layer's end previously resolved to "infinity", so the out-phase never triggered and the layer popped off at the last frame; it now resolves to the composition length, so the layer animates out. Only layers carrying an out-phase animation are affected.
• FIX(iOS, macOS): Smoother clip transitions. The pre-rendered transition clip is now authored at the composition's frame rate (max(30, source fps)) instead of only the outgoing clip's, so a 25 fps source no longer stutters at the transition seams; directional slide / push transitions also use one easing ramp per output frame, removing velocity kinks with bounce / elastic curves.

• FIX(iOS, macOS): Fix a layer sliding in from an edge briefly shifting and shrinking the video (e.g. a black bar at the top) when a custom output resolution is set. Off-frame overlay content is now clipped to the video frame before letterboxing, so the frame no longer inflates during the animation.

• FEAT(android, iOS, macOS): Add ProVideoEditor.splitVideo — a frame-accurate split that cuts one video into two files (SplitVideoModel). Each half is re-encoded from the exact cut frame without the render compositor/effects, making it far faster and more stall-resistant than splitting via renderVideoToFile; every export is guarded by a watchdog timeout. Cancellable and progress-reporting via the task id. Web/Windows/Linux throw UnimplementedError.

• FIX(iOS, macOS): Make FlutterEngine detach terminal for method-channel result delivery. After detach, a late render/audio/waveform/metadata/thumbnail callback no longer calls a captured FlutterResult against a torn-down engine, closing the remaining NSInternalInconsistencyException: Sending a message before the FlutterEngine has been run path from 2.1.2.

• FIX(iOS, macOS): Cancel active tasks and clear event sinks when the FlutterEngine is torn down. In-flight render/audio/waveform callbacks no longer message a stopped engine, fixing NSInternalInconsistencyException: Sending a message before the FlutterEngine has been run crashes on app termination or surface recreation.

• FIX(android): The global output trim now respects per-clip and global playbackSpeed. A sped-up composition capped by endTime was trimmed against the source timeline, cutting the output far shorter than the preview; the cap now limits the post-speed output length, matching iOS.

• FIX(android, iOS, macOS): VideoQualityConfig.custom(resolution: …) now renders to exactly that resolution. The video is scaled to fit (preserving aspect ratio), centered, and padded with black instead of producing an aspect-scaled size (e.g. a 720x720 source with a 1080x1920 resolution previously exported 1080x1080, now 1080x1920 letterboxed). Android letterboxes with a Presentation effect; Darwin composites the frame onto a black canvas. Quality presets keep their aspect-preserving scale. A qualityConfig's bitrate is now also applied when used without an explicit bitrate.
• FEAT(android, iOS, macOS): Animated GIF image layers. ImageLayer now detects animated GIFs automatically and plays them back frame by frame; the new loop flag (default true) repeats the animation for the layer's time range or holds the last frame when false. All existing layer properties (position, size, rotation, timing, animations) apply unchanged. Android decodes frames via Movie and swaps them per overlay frame; Darwin decodes via CGImageSource and selects the frame per composition time. Web/Windows/Linux ignore the field.
• FEAT(android, iOS, macOS): Add an output frame-rate cap via a new maxFrameRate field on VideoRenderData. It is an upper limit, not a target: a faster source is reduced to it (e.g. 60→30 fps) while a slower source is left untouched, lowering encoding cost and output file size. Android drops surplus frames with Media3's FrameDropEffect; Darwin caps the composition frameDuration. Web/Windows/Linux ignore the field.
• FEAT(android, iOS, macOS): Add per-layer rotation to image overlays via a new rotation field on ImageLayer (radians, clockwise around the layer center — matches Flutter's Transform.rotate, so a pro_image_editor layer rotation can be forwarded directly). offset/size keep describing the layout box before rotation. Web/Windows/Linux ignore the field.

• BREAKING: Remove the previously deprecated APIs. Migrate as follows:
  • VideoRenderData.video → videoSegments: [VideoSegment(video: …)]
  • VideoRenderData.imageBytes → imageLayers
  • VideoRenderData.playbackSpeed → VideoSegment.playbackSpeed
  • VideoRenderData.colorMatrixList → colorFilters (ColorFilter)
  • VideoRenderData.customAudioPath / customAudioStartTime / customAudioVolume / loopCustomAudio → audioTracks (VideoAudioTrack)
  • VideoRenderData.originalAudioVolume → VideoSegment.volume
  • VideoMetadata.originalResolution → rawResolution

• FEAT(android, iOS, macOS): Add multi-layer video compositions via a new composition field on VideoRenderData (VideoComposition). A composition stacks several VideoLayers on a fixed-size canvas, each layer being a time-ordered track of VideoSegments composited bottom-to-top with its own opacity and placement (SegmentTransform: offset, size, fit = fill/contain/cover). Clips gain timelineStart (delayed entry on a layer) and transform (per-clip placement), enabling picture-in-picture, side-by-side and grid layouts over a configurable backgroundColor. Android composites layered Media3 sequences with a per-clip GL transform (cover overflow is scissored to its rect); Darwin uses a custom AVVideoCompositing compositor. Per-clip transition, playbackSpeed and reverseVideo are not applied inside a composition. Web/Windows/Linux ignore the field.

• FIX(android): Fix video export failing with a codec exception on Qualcomm c2.qti.* encoders. The encoder is now retried through a fallback chain (operating-rate cap → unset → Main/Baseline profile → software) before surfacing a typed RenderEncoderException; working devices keep their original export speed.
• FIX(android, iOS, macOS): Fix a render/cancel race where cancelling right after starting an export failed with TASK_NOT_FOUND. An early cancel is now handled in the Dart layer before the native task starts, so the render resolves as canceled.

• FIX(android, iOS, macOS): Fix layer slide animations only moving the layer by its own size, leaving it partly visible at the animation's start/end. Slides are now edge-aware and carry the layer fully off-screen in the slide direction. Requires the matching pro_image_editor release so the in-editor preview matches the export.

• FIX(android): Fix OutOfMemoryError when pre-rendering longer overlap clip transitions (dissolve/slide/push/wipe). Both sides previously decoded every I420 frame into memory at once (~370 MB for a 2 s 1080p30 transition); frames are now spilled to a temp file and streamed back one at a time during encoding, so heap use stays constant regardless of duration/fps/resolution — at full quality.

• FIX(android, iOS, macOS): Fix per-segment playbackSpeed being ignored on clips that take part in an overlap clip transition (dissolve/slide/push/wipe). The transition pre-render now resolves the blend in output (post-speed) time and replays each side at its own speed, so footage inside the transition plays at the requested speed instead of falling back to 1×. Independent per-side speeds are supported; dip transitions (fadeToBlack/fadeToWhite) already honored speed.

• FIX(android): Fix overlap clip transitions (dissolve/slide/push/wipe) appearing rotated 90°/180° when a clip carries container rotation metadata (e.g. portrait phone videos). The transition pre-render decodes coded (un-rotated) frames, so it now re-applies the source rotation via MediaMuxer.setOrientationHint and maps geometric directions into coded space.

• FEAT(android, iOS, macOS): Add clip transitions between adjacent VideoSegments via a new transition field (ClipTransition with type, duration, curve, direction). Supports dissolve, slide, push and wipe (overlap and shorten the output) plus fadeToBlack and fadeToWhite (dip through a color, duration unchanged). Web/Windows/Linux ignore the field.

• FEAT(android, iOS, macOS): Add stop-motion support to turn a sequence of still images into a video via ProVideoEditor.instance.renderStopMotion / renderStopMotionToFile. Each StopMotionFrame is held for 1 / frameRate seconds (or a per-frame duration override) and encoded into a single silent video. The output size defaults to the first frame and frames are mapped onto it via StopMotionFit (contain / cover / stretch). Darwin encodes with AVAssetWriter + a pixel-buffer adaptor; Android uses Media3 Transformer image input with a Presentation effect. Progress and cancellation reuse the existing render task infrastructure. Audio is not mixed in — pass the result through renderVideo with audioTracks to add music. Web/Windows/Linux are not supported.

• FIX(iOS, macOS): Fix custom audio tracks being silently dropped when the source asset's duration fails to resolve. AudioPreRenderer previously fell back to a zero duration on asset.load(.duration) failure, which collapsed an open-ended trim (audioEndTime == nil) into a zero-length range and discarded the track with a misleading invalid trim range … end=0.0s log. The renderer now loads the audio track first and falls back to its timeRange duration (the real audio length), only aborting when neither source resolves. Android already decodes to the real end-of-stream for an open-ended trim, so no change was needed there.

• FEAT(android, iOS, macOS): Forward native plugin logs back to Dart via ProVideoEditor.instance.logStream. Every entry written through the shared native logger (including the full renderer diagnostics) is now emitted as a NativeLogEntry (level, tag, message, timestamp, optional stackTrace), so host apps can pipe these into their own Dart logger and export them. Forwarding is gated by the same nativeLogLevel as the native console output. Web/Windows/Linux keep an empty stream.

• FEAT(android, iOS, macOS): Add speed to AudioExtractConfigs for pitch-preserving playback-speed changes during audio extraction (e.g. 2.0 for double speed, 0.5 for half). WAV applies the time-stretch directly on the decoded PCM (Android SonicAudioProcessor; AVFoundation AVAssetReaderAudioMixOutput with the spectral time-pitch algorithm), while compressed formats are re-encoded — Android via a Media3 Transformer, Darwin via AVAssetExportPresetAppleM4A with a scaled time range. Note: on Apple platforms a non-1.0 speed re-encodes to AAC/M4A, so caf output falls back to M4A content.

• FIX(iOS, macOS): Fix unstable/glitchy audio on reversed clips inside multi-clip timelines. AudioReverser now preserves the source audio format (sample rate and channel count) instead of forcing 44.1 kHz stereo, so a reversed clip's audio matches its untouched neighbours and AVFoundation no longer has to reconcile mixed formats within a single composition audio track during looped playback. The reversed segment is also written as an AVFoundation-authored CAF/PCM file (replacing the hand-authored WAV) and inserted at its decoded duration without padding, avoiding encoder priming artifacts and audio-timing drift in the exported video.

• FIX(android): Fix custom audio tracks extending sped-up renders to the original source duration. Custom audio is now constrained to the rendered video timeline after global and per-clip playback speed, preventing the final video frame from freezing after the sped-up video content ends.

• FIX(web, wasm): Fix pub.dev platform compatibility score. Replace direct dart:io and package:path_provider imports in the package's public import chain with conditional platform shims, eliminating the "Package does not support platform Web" and "Not compatible with runtime wasm" warnings.

• FEAT(darwin): Add Swift Package Manager (SPM) support for iOS and macOS. The darwin implementation is now distributed as a local SPM package, replacing the previous CocoaPods-only setup.

• FIX(android): Prevent RENDER_ERROR codec exceptions on hardware encoders (e.g. Qualcomm AVC c2.qti.avc.encoder) by enabling encoder fallback in the main render path, clamping the requested bitrate into the codec's supported range, and preferring VBR over CBR at high bitrates.
• FIX(android): Harden the reverse-video pre-render against crashes. The all-intra encoder is now configured with a clamped bitrate and progressive fallback to avoid MediaCodec.CodecException, and the in-memory remux is guarded against OutOfMemoryError by checking the temp file size against available heap before loading frames. On failure the clip gracefully degrades to forward playback.