filmopen_engine_mlt

A snapshot

This specification is a copy of docs/software/packages/filmopen_engine_mlt.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.

Prototype A of the timeline engine (Software Specification §19): MLT behind filmopen_engine’s TimelineEngine, as a Flutter plug-in for Linux and Windows.

Flutter. 7 files, 1,604 lines under lib/; 69 tests in 6 files. Barrel: lib/filmopen_engine_mlt.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: ffi.

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/encoder_choice.dart

• variable const gpuEncoders — The GPU’s H.264 encoders, tried in this order before the software one; one the build lacks is passed over.
• variable const testFrame — The frame every candidate is given: 256×256, since NVENC refuses anything under 145×49; 25 frames a second.
• typedef typedef EncoderTestResult — What a test frame did in an encoder: whether it gave a packet, the stage reached (find, alloc, open, frame, send, flush, receive, done; args for a size or rate refused, thread for a thread that did…
• function String softwareEncoder({required bool windows}) — The software H.264 encoder: Microsoft’s MFT on Windows (h264_mf, which uses no GPU unless asked), Cisco’s OpenH264 on Linux.
• class EncoderChoice — What [chooseEncoder] found: the encoder auto uses (null when none opened), whether it is the GPU’s, why, the candidates test-encoded in order, and the encoders an export may name.
  • const EncoderChoice({this.encoder, this.hardware = false, required this.reason, this.tried = const [], this.available = const []}) — A choice; [encoder] null is “no encoder”.
  • final String? encoder — The encoder auto uses, or null.
  • final bool hardware — Whether [encoder] is one of [gpuEncoders].
  • final String reason — Why it was chosen, or why none was.
  • final List<String> tried — The candidates test-encoded, in order.
  • final List<String> available — The encoders an export may name: [encoder] first, then every other candidate the build has; none when no encoder opened.
• function EncoderChoice chooseEncoder({ required String software, required bool Function(String encoder) has, required EncoderTestResult Function(String enco… — Chooses the encoder: each of [gpuEncoders] the build [has] is given one test frame ([test]) and the first that opens is used, else [software] if it opens; [policy] software (the export’s ExportSettings.encoder, fr…
• class EncoderChoices — The engine’s encoder choices, one per policy (auto, software), each made at its first need and kept, so that a person switching the setting back and forth probes each at most once.
  • EncoderChoices(this._choose) — Choices made by [choose], given the policy.
  • EncoderChoice of(String policy) — The choice for [policy], made now if it was not made before.
  • EncoderChoice? made(String policy) — The choice for [policy] if it was made, without making it.
• typedef typedef ExportEncoder — What [exportEncoder] decided: the encoder (null: no_encoder, said by cause) and because, why it runs.
• function ExportEncoder exportEncoder(String asked, EncoderChoices choices) — The encoder an export asking [asked] uses: auto and software are their policies’ choices; any other name is the caller’s, allowed when the automatic choice lists it.

lib/src/mlt_compiler.dart

• class MltCompiled — What [compileMlt] made: the XML, and the counts the engine logs as engine.native.compile.
  • const MltCompiled(this.xml, {required this.tracks, required this.producers, required this.frames, this.holds = 0, this.monoBoosts = 0, this.subtitl… — A compiled timeline.
  • final String xml — The MLT XML document.
  • final int tracks, producers, frames — The playlists, the producers, and the timeline’s length in frames.
  • final int holds, monoBoosts — The decisions the log needs to explain a frozen frame or a level: the holds made (stills and held tails) and the mono sources given +3.0103 dB.
  • final bool subtitleFilter — Whether the tractor burns subtitles through FFmpeg’s subtitles filter.
  • Map<String, Object?> toJson() — The counts as JSON, for the log.
• typedef typedef MltSubtitles — The subtitles a compile burns: the ASS file the engine wrote from assOf, and the folder of fonts libass reads.
• function MltCompiled compileMlt(EngineTimeline t, {Set<String> monoSources = const {}, Map<String, Duration> durations = const {}, MltSubtitles? subtitles}) — Compiles [t] to MLT’s XML, every time through the engine’s one frame arithmetic, frameAt (§19.3).
• variable const monoUpmixDb — What a mono source gains so that FFmpeg’s −3 dB centre becomes one full copy on each side: 20·log10(√2).

lib/src/mlt_engine_stub.dart

• typedef typedef MltTextureHandle — The texture the frames go to: its id for Flutter’s Texture, and the C sink and context the shim hands frames to.
• class MltTexture — The texture where there is no dart:ffi: the barrel exports the native one, mlt_engine.dart’s plug-in texture, where it is; here there is no plug-in.
  • const MltTexture() — The plug-in’s texture.
  • Future<MltTextureHandle> create() — Refused: there is no plug-in to make a texture.
  • Future<int> dispose(int textureId) — Nothing to end: no texture was made.
• class MltEngine — The engine where there is no dart:ffi (the web): the barrel exports the native one, mlt_engine.dart’s MLT over the C shim for Linux and Windows, where it is; here every operation is refused with unsupported, and…
  • MltEngine({String? libraryDir, this.texture, String? fontsDir, AppLog? log}) — An engine that refuses everything; the arguments are the native engine’s, kept so that one line builds both.
  • final String libraryDir — The folder it was given, where there is no native library to look in.
  • final MltTexture? texture — The texture it was given, never drawn to.
  • final String fontsDir — The fonts folder it was given, never read.

Internal

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

• lib/src/mlt_engine.dart: MltTextureHandle, MltTexture, MltEngine, _probeIn, _closeExport, _exportStartIn, _MltExport
• lib/src/native.dart: FoEvent, FoPresented, FoStats, FoProbe, FoMemory, FoExportState, FoEncoderTest, FoCode, cString, MltNative
• lib/src/subtitle_sweep.dart: sweepSubtitleFolders