filmopen_engine_mpv

A snapshot

This specification is a copy of docs/software/packages/filmopen_engine_mpv.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

Pure compilers translate an EngineTimeline into an mpv EDL loaded through memory:// and an FFmpeg export command. The picture, clip sound and audio lanes use the same frame boundaries and gains. Audio gaps are explicit silence; the mix never normalises. Each result supplies segment and filter counts for the engine’s compile log event. Invalid timelines and unsupported layouts are refused with EngineException before a native command is built. Windows tools and shared libraries live beside the executable. Its presentation callback follows rendering and precedes the Flutter texture mark, using QueryPerformanceCounter. The Windows video output starts at the timeline’s canvas size and registers its initial texture ID. When both output dimensions are configured, the SDK’s source-size observer leaves that canvas unchanged; source dimensions do not replace its texture. Disposal unregisters the callback before closing it. Observed loaded sibling DLL paths or their not-loaded state are logged once after the first presentation, or on initialization failure. Windows requests auto-safe decoding and logs the actual decoder, codec and timeline position during playback after real presentations; preparation alone does not establish hardware decoding. Before Windows playback opens, the adapter enumerates native audio devices. A real WASAPI endpoint retains the existing output selection. With none, it sets ao=null, verifies the native readback and emits the informational audio/no_audio_device event. The synthetic auto entry is not an endpoint. Every read, choice, write and verification is logged with values and timing; unavailable required properties or a failed verification fail initialization honestly. No retry or device watcher is added. Its output canvas is limited to 8,294,400 bytes at four bytes per pixel in every Windows rendering mode; a larger canvas is refused with unsupported before native access. Replacing a timeline with a different canvas is refused with unsupported and reason size_changed before changing the prepared state. A new project format needs disposal and preparation of a new engine session. The bound concerns the output canvas, not the source media’s dimensions. The barrel exports the native adapter where dart:ffi is available, and a resource-free adapter that refuses native operations elsewhere. The app selects its fake on the web, Android and desktops without app-local libmpv, logging path, presence and reason. Plain Flutter builds with no native prefix warn, bundle no runtime and use the video texture stub; an existing Windows prefix missing libmpv refuses configuration. Wrappers build native first. The Windows vendored plug-ins use the sibling engine package beneath Flutter’s logical plug-in folders, or their direct source layout, without canonicalizing a symlink with REALPATH. They log the selected native path and layout. The engine owns its Flutter texture.

Flutter. 7 files, 1,796 lines under lib/; 53 tests in 9 files. Barrel: lib/filmopen_engine_mpv.dart.

Depends on

• filmopen_engine — uses EngineCapabilities, EngineClock, EngineEvent, EngineException, EngineItem, EngineOutcome, EnginePresented, EngineTimeline, ExportJob, ExportResult, ExportSettings, ItemKind, LoggingEngine, MediaProbe, TimelineEngine, TrackKind, assOf, frameAt, frameStart
• filmopen_store — uses AppLog
• filmopen_format (dev) — uses nothing by name the digest could see
• filmopen_test_support (dev) — uses nothing by name the digest could see
• filmopen_timeline (dev) — uses nothing by name the digest could see

Third-party: media_kit, media_kit_video, media_kit_libs_linux, media_kit_libs_windows_video.

Used by

filmopen_app, filmopen_engine_bench

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/edl_compiler.dart

• class EdlCompilation — An EDL loaded as memory data, its mix graph and the counts to log at preparation.
  • const EdlCompilation(this.edl, this.filter, this.videoFilter, this.counts) — A compiled playback description.
  • final String edl — The complete EDL text, with one partition per lane.
  • final String filter — The fixed-number audio mix passed to lavfi-complex.
  • final String videoFilter — The same player’s native video filters, including frame holds and the rational output timebase.
  • final Map<String, Object?> counts — Segment and filter counts for the engine’s compile event.
  • String get uri — The memory origin allows the EDL’s lavfi black and silence sources to open.
• function EdlCompilation compileEdl(EngineTimeline timeline, {Set<String> silentOwnSoundSources = const {}}) — Compiles explicit lane layouts so embedded or multiple audio streams cannot shift aid numbers.

lib/src/ffmpeg_compiler.dart

• class FfmpegCompilation — An FFmpeg argument vector and graph, never a shell command.
  • const FfmpegCompilation(this.arguments, this.filter, this.counts) — A compiled export description.
  • final List<String> arguments — Arguments passed directly to Process.start, retaining stdin for cancellation.
  • final String filter — The graph whose concatenations and volumes define the export.
  • final Map<String, Object?> counts — Segment and filter counts for the engine’s compile event.
• function FfmpegCompilation compileFfmpeg(EngineTimeline t, ExportSettings settings, String encoder, {Set<String> silentOwnSoundSources = const {}, String va… — Compiles frame-bounded picture holds and covered audio lanes into an unnormalised H.264 export.
• function String subtitleFilterPath(String path) — Encodes a subtitle path through FFmpeg’s option parser, then its filtergraph parser.

lib/src/mpv_engine_stub.dart

• class MpvEngine — Refuses native playback where dart:ffi is unavailable; the app selects its fake there.
  • MpvEngine({String? nativeDirectory, String? fontsDirectory}) — Accepts the native constructor’s arguments without opening any resource.
  • String? debugEncoder([String policy = 'auto']) — Refuses the encoder probe, which needs dart:ffi’s native toolkit.
  • void debugPrepareNative(EngineTimeline timeline, {Future<String> Function(String property)? property}) — Refuses the native handlers’ simulation, which needs dart:ffi.
  • Future<void> debugPlayNative(Duration length, {Duration from = Duration.zero, bool ends = false}) — Refuses the native handlers’ simulation, which needs dart:ffi.
  • String get libraryDir — No native library folder exists where dart:ffi is unavailable.

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/audio_output.dart: configureWindowsAudioOutput
• lib/src/lanes.dart: CompilerLane, seconds, frameSeconds, channelLayout, totalFrames, compilerLanes, _covered, segmentFrames, compileCounts, channelPan
• lib/src/mpv_engine.dart: _EncoderChoice, MpvEngine, _EndFile, _ObservedProperty, _WakeupCallback, _FrameCallback, _SetCallback, _PresentationHook, _FfmpegJob