filmopen_engine

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

The timeline engine interface as pure Dart (Software Specification §19): EngineTimeline — one flat, fully resolved timeline with its tracks, items and markers, its JSON (timeline.dart) and validate()’s codes —, the one frame arithmetic frameAt / frameStart (time.dart), the TimelineEngine interface with the presentation record EnginePresented, the clock, the native events, the export job and the one error type EngineException (engine.dart), FakeEngine (fake_engine.dart) and LoggingEngine (logging_engine.dart).

pure Dart. 8 files, 1,554 lines under lib/; 65 tests in 7 files. Barrel: lib/filmopen_engine.dart.

Depends on

filmopen_store — uses AppLog

Used by

filmopen_app, filmopen_engine_android, filmopen_engine_bench, filmopen_engine_mlt, filmopen_engine_mpv, filmopen_media_ui, filmopen_state, filmopen_timeline, filmopen_timeline_ui

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/ass.dart`

function String assOf(EngineTimeline timeline) — [timeline]’s subtitles as an ASS file: one style in its [EngineTimeline.subtitleStyle], one event per subtitle.

`lib/src/engine.dart`

class TimelineEngine — A backend that plays and exports an [EngineTimeline] (Software Specification §19).
- String get name — fake, mlt, mpv.
- EngineCapabilities get capabilities — What this engine can do: its encoders, hardware decoding, export.
- Future<MediaProbe> probe(String path) — The measured duration, rate, size, audio rate and codec of the file at [path].
- Future<void> prepare(EngineTimeline timeline) — Loads [timeline] and presents its first frame; refuses a timeline that [EngineTimeline.validate] faults.
- Future<void> replaceTimeline(EngineTimeline timeline) — Puts [timeline] in place of the prepared one after an edit, at a pause; keeps the playhead where still valid.
- Future<void> play() — Starts playback from the playhead, on the native audio clock where there is sound.
- Future<void> pause() — Stops playback; the playhead stays on the frame shown.
- Future<EnginePresented> seek(Duration to) — Completes with the presentation of frameAt(to); a seek displaced by a later one completes with the later one’s record, its [EnginePresented.supersededRequest] naming this seek.
- int scrub(Duration to) — Asks for the picture at [to] without sound and returns the request’s number; only the latest request is kept, and one superseded before any frame answered it gets the event superseded.
- int nowUs() — The engine’s monotonic clock now, in microseconds: the basis of [EnginePresented.presentedUs].
- Future<EnginePresented> endScrub(Duration to) — Ends a scrub with an exact seek to [to].
- Stream<EnginePresented> get presented — Every frame made available to Flutter’s texture.
- Stream<EngineClock> get clock — About ten times a second: position, playing, and totals of presented and dropped frames and audio underruns.
- Stream<EngineEvent> get events — The native side’s stages, in the common vocabulary of [EngineEvent].
- int? get textureId — The Flutter texture; null before [prepare] and on the fake.
- Future<ExportJob> export(EngineTimeline timeline, ExportSettings settings) — Exports [timeline] in a session of its own, pinned to it.
- List<int> get ownedProcesses — The process ids of the children the engine runs now (an exporter).
- Future<void> dispose() — Ends everything the engine owns: its texture, its threads, its processes.
class EngineCapabilities — What an engine can do: whether it exports at all.
- const EngineCapabilities({this.exportAvailable = false}) — Capabilities; the default is an engine that does not export.
- final bool exportAvailable — Whether [TimelineEngine.export] makes a file at all.
class MediaProbe — A media file as measured: its duration, rate, size, audio rate and codec.
- const MediaProbe({ required this.duration, this.fpsNum, this.fpsDen, this.width, this.height, this.audioRate, required this.codec, }) — A probe’s result; the video fields are null for a sound file.
- final Duration duration — The measured duration.
- final int? fpsNum, fpsDen, width, height, audioRate — The frame rate, the picture size and the audio sample rate, where the file has them.
- final String codec — The first stream’s codec, as the native library names it.
- Map<String, Object?> toJson() — This value as JSON, snake_case keys: for the log and the reports.
class EnginePresented — One frame put on screen: which, for what request, when, and where the sound was.
- const EnginePresented({ required this.revision, required this.request, required this.frame, required this.presentedUs, this.supersededRequest, this… — One presentation record.
- final int revision — The timeline revision it belongs to.
- final int request — The seek or scrub request it answers; 0 during playback.
- final int frame — The timeline frame shown (frameAt of its position).
- final int presentedUs — When the frame was made available to Flutter’s texture, on the engine’s monotonic clock (µs).
- final int? supersededRequest — Set on the record that completes a displaced seek or endScrub: that earlier request’s number, answered with the later request’s frame.
- final int? audioUs — The audio clock’s position at that instant (µs of timeline time), where sound plays.
- EnginePresented supersede(int earlier) — This record answering the displaced request [earlier].
- Map<String, Object?> toJson() — This value as JSON, snake_case keys: for the log and the reports.
class EngineClock — The engine’s clock: position, playing, and its running totals.
- const EngineClock({ required this.position, required this.playing, this.presented = 0, this.dropped = 0, this.underruns = 0, }) — One reading of the clock.
- final Duration position — The playhead.
- final bool playing — Whether playback runs.
- final int presented, dropped, underruns — Running totals: frames presented, frames dropped, audio underruns.
enum EngineOutcome — How a native stage went.
- values: start, ok, refused, failed, info
class EngineEvent — One native stage, in the common vocabulary: [stage] is open, load, decode, present, audio, seek, export, encode, mux, close, superseded or playback; [cause] is the native library’s own message…
- const EngineEvent(this.stage, this.outcome, {this.code, this.ms, this.cause, this.data = const {}}) — One event of [stage] with its [outcome].
- final String stage — The native stage, in the common vocabulary.
- final EngineOutcome outcome — How the stage went.
- final String? code — The common code, where the stage refused or failed.
- final int? ms — How long the stage took, in milliseconds.
- final String? cause — The native library’s own message, logged whole.
- final Map<String, Object?> data — Anything else the stage reports.
class ExportSettings — What an export makes: the file, its container and codecs, the bitrates and the encoder (auto, software or a name the engine’s automatic choice lists).
- const ExportSettings({ required this.path, this.container = 'mp4', this.video = 'h264', this.audio = 'aac', this.videoBitrate = 12000000, this.audi… — Settings; the defaults are H.264 and AAC in MP4 at 12 Mb/s and 192 kb/s, the encoder chosen by the engine.
- final String path — The file to write.
- final String container, video, audio — The container and the video and audio codecs.
- final int videoBitrate, audioBitrate — The bitrates, in bits per second.
- final String encoder — auto; software, the engine’s software encoder with no hardware encoder tried (an engine whose software encoder does not open refuses with no_encoder); or a name the engine’s automatic choice lists, else `no_enco…
- Map<String, Object?> toJson() — This value as JSON, snake_case keys: for the log and the reports.
class ExportResult — How an export ended: the file, or a code and the stage that gave it.
- const ExportResult.file(String this.path, {this.encoder}) — An export that made [path].
- const ExportResult.failed(String this.code, String this.stage, {this.cause}) — An export that ended with [code] at [stage].
- final String? path — The file made, or null.
- final String? encoder — The encoder actually used.
- final String? code, stage, cause — The code, the stage and the native cause of a failed export.
- bool get ok — Whether the export made its file.
class ExportJob — One running export: its monotonic progress (0..1), its end, and a cancel that completes only when no process, thread or file the job owns remains.
- Stream<double> get progress — The share done, 0 to 1, never decreasing.
- Future<ExportResult> get done — The job’s end: the file, or a code and the stage.
- Future<void> cancel() — Cancels the job; completes only when nothing it owns remains.
class EngineException — The one error an engine raises: a code, the stage, and the native cause where there is one.
- const EngineException(this.code, this.stage, [this.cause]) — An error with [code] at [stage], and the native [cause] where there is one.
- final String code — The common code.
- final String stage — The stage that gave it.
- final String? cause — The native library’s own message.
- static const refusalCodes — The codes that refuse a request rather than report a failure: what the caller asked for cannot be done.
- bool get refusal — Whether the code refuses the request rather than reports a failure.

`lib/src/fake_engine.dart`

class FakeEngine — A [TimelineEngine] in pure Dart that opens no media: it validates, keeps a clock at the timeline’s rate and presents frame numbers, and never exports.
- FakeEngine({int Function()? clockUs, this.answerDelay = Duration.zero}) — [clockUs] stands in for the monotonic clock in tests; [answerDelay] is how long a seek or scrub takes to present.
- final Duration answerDelay — How long a seek or scrub takes to present its frame.
- void emitEvent(EngineEvent event) — A test door: says [event] as a native stage would.
- void failPlayback(String code, String cause) — A test door: playback stops because of a failure, as a native decoder’s can — the playback failed event with [code] and [cause], then the clock saying it stopped (§19.7).

`lib/src/file_timeline.dart`

function EngineTimeline fileTimeline(String path, MediaProbe probe, {required bool video}) — The one-file timeline of [path] as [probe] measured it, for a clip or a sound.

`lib/src/logging_engine.dart`

class LoggingEngine — Wraps any [TimelineEngine] and logs every member’s start and end, the first frame, stalls, the clock, the scrub, each play’s summary when it ends, the export’s progress and every native event, so that no engine can sk…
- LoggingEngine(this.inner, {AppLog? log}) — [inner] logged through [log], else the application log.
- final TimelineEngine inner — The engine every member is passed to.
- static const stallUs — A gap between presentations longer than this while playing is a stall (§19.9).

`lib/src/time.dart`

function int frameAt(Duration t, int fpsNum, int fpsDen) — The frame a time [t] falls in at [fpsNum]/[fpsDen]: floor(t × fpsNum / fpsDen + 1e-9).
function Duration frameStart(int n, int fpsNum, int fpsDen) — When frame [n] starts at [fpsNum]/[fpsDen], rounded up to the next whole microsecond.

`lib/src/timeline.dart`

enum TrackKind — The kind of a lane: the one picture track, or an audio kind.
- values: picture, speech, music, effects
enum ItemKind — The kind of an item: a video clip, a still, black, or a sound.
- values: video, image, black, audio
class EngineTimeline — One timeline an engine plays or exports: flat, fully resolved, with no project, stem or draft in it.
- const EngineTimeline({ required this.id, required this.revision, required this.fpsNum, required this.fpsDen, required this.width, required this.hei… — A timeline; [validate] says whether an engine may play it.
- final String id — The scene’s identity, opaque to the engine.
- final int revision — Raised by every change; an engine drops work for an older one.
- final int fpsNum, fpsDen — The frame rate as a fraction: 24/1, 24000/1001.
- final int width, height — The picture size in pixels.
- final int sampleRate — The mix’s sample rate in Hz.
- final int channels — The mix’s channel count.
- final Duration duration — The end of the last picture item.
- final List<EngineTrack> tracks — Exactly one picture track, and any number of audio lanes of each kind.
- final List<EngineMarker> markers — The beats.
- final List<EngineSubtitle> subtitles — The lines burnt over the picture, in the scene’s order.
- final EngineSubtitleStyle subtitleStyle — The one look of every subtitle.
- factory EngineTimeline.fromJson(Map<String, Object?> json, {String Function(String source)? source}) — The timeline read from [json], each item’s source passed through [source] (a manifest’s relative path made absolute); a wrong or missing required key is an [EngineException] bad_key naming the key.
- Map<String, Object?> toJson() — The timeline in the manifest’s JSON, snake_case keys.
- List<TimelineIssue> validate() — Every rule this timeline breaks, one [TimelineIssue] each; empty when an engine may play it.
class TimelineIssue — One rule a timeline breaks: its code, and the track and item it was found at where there is one.
- const TimelineIssue(this.code, {this.track, this.item}) — An issue with [code] at [track] and [item].
- final String code — The rule broken.
- final int? track, item — Where it was found: the track’s and the item’s index.
- Map<String, Object?> toJson() — The issue as JSON, for the log.
class EngineTrack — One lane; its gain is the default level of its kind (speech 0 dB, music −12 dB, effects −6 dB).
- const EngineTrack({required this.kind, required this.gainDb, required this.items}) — A lane of [kind] at [gainDb] with its [items].
- final TrackKind kind — Picture, or an audio kind.
- final double gainDb — The lane’s level in dB.
- final List<EngineItem> items — In timeline order.
- Map<String, Object?> toJson() — The lane in the manifest’s JSON.
class EngineItem — One item on a track: source from sourceIn, placed at at for length.
- const EngineItem({ required this.kind, this.source, this.sourceIn = Duration.zero, required this.at, required this.length, this.withOwnSound = fals… — An item of [kind] at [at] for [length].
- final ItemKind kind — Video, image, black or audio.
- final String? source — An absolute local path; null only for black.
- final Duration sourceIn — Where in the source it starts.
- final Duration at — Where on the timeline it starts.
- final Duration length — How long it lasts on the timeline; it is cut at at + length.
- final bool withOwnSound — A video item whose own sound is mixed in at the speech level.
- Map<String, Object?> toJson() — The item in the manifest’s JSON.
class EngineMarker — A beat: a position and a label, drawn, never played.
- const EngineMarker({required this.at, required this.label}) — A marker at [at] named [label].
- final Duration at — Its place on the timeline.
- final String label — What the beat says.
- Map<String, Object?> toJson() — The marker in the manifest’s JSON.
class EngineSubtitle — A subtitle: a text burnt over the picture from [at] for [length].
- const EngineSubtitle({required this.at, required this.length, required this.text}) — [text] shown from [at] for [length].
- final Duration at — Where on the timeline it appears: a frame’s start.
- final Duration length — How long it shows; it is gone at the frame that starts at at + length.
- final String text — The words as the person typed them; a newline is a line break.
- Map<String, Object?> toJson() — The subtitle in the manifest’s JSON.
class EngineSubtitleStyle — The look of every subtitle of a timeline: one font family and one size in pixels at the picture’s height.
- const EngineSubtitleStyle({this.font = defaultFont, this.size = defaultSize}) — [font] at [size].
- static const defaultFont — The font where none is said: one the application bundles.
- static const defaultSize — The size where none is said, in pixels at the picture’s height.
- final String font — The font family’s name.
- final int size — The size in pixels at the picture’s height.