filmopen_engine_bench

A snapshot

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

The timeline engines’ bench (Software Specification §19.11): a Flutter app for Linux and Windows that drives any TimelineEngine, wrapped in LoggingEngine, through the fixture scene of scripts/make_timeline_fixture.py and writes bench-report.json and bench-report.md — each measure’s n, p50, p95 and max, its gate and pass, fail or not measured.

Flutter. 4 files, 1,115 lines under lib/; 29 tests in 4 files. Barrel: lib/filmopen_engine_bench.dart.

Depends on

• filmopen_engine — uses EngineClock, EngineException, EngineItem, EnginePresented, EngineSubtitle, EngineTimeline, EngineTrack, ExportSettings, FakeEngine, LoggingEngine, MediaProbe, TimelineEngine, frameAt, frameStart
• filmopen_engine_mlt — uses MltEngine, MltTexture
• filmopen_engine_mpv — uses MpvEngine
• filmopen_store — uses AppLog, LogLevel, MemoryLogSink, openFileLogSink

Used by

No package of FilmOpen.

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

• getter String get benchLockPath — The one lock of the bench and the builds: the OS byte-range lock on this file (scripts/with_bench_lock.py); FILMOPEN_BENCH_LOCK names another, which only the tests do.
• function Future<RandomAccessFile?> takeBenchLock({String? path, void Function(String? pid)? holder}) — Takes the bench lock at [path] without waiting; null, with the holder’s pid in [holder], when another process holds it.
• class BenchConfig — What a run is given: the engine’s name, the fixture’s media folder, the manifests, where the reports go.
  • const BenchConfig({ required this.engine, required this.fixtureDir, required this.repoRoot, required this.outDir, this.seed = 714, this.playMinutes… — A run’s configuration; the seed defaults to 714 and the sustained play to ten minutes.
  • final String engine, fixtureDir, repoRoot, outDir — The engine’s name, the media folder, the repository root and the report folder.
  • final int seed, playMinutes — The seed of the exact seeks, and the minutes of the sustained play.
  • final String? baselineDir — The release bundle of this bench without any engine plug-in, which the engine’s size is counted against.
  • final String? subtitlesFile — A JSON file of subtitles laid over the scene (withSubtitles), for measuring it with and without the overlay.
  • final String? fontsDir — The fonts folder an engine hands libass: the repository’s assets/fonts unless named (the bench’s own bundle holds none).
  • String get fonts — The fonts folder in use.
  • String get manifest — The scene’s manifest.
  • String get stress — The stress set’s manifest.
  • String get verifyScript — The fixture script, whose verify checks an export.
• function Map<String, Object?> withSubtitles(Map<String, Object?> manifest, Map<String, Object?> subtitles) — [manifest] with the subtitles of [subtitles] — an object of subtitles, subtitle_font and subtitle_size, as an EngineTimeline’s JSON has them, and nothing else (a [FormatException] otherwise) — so the scene is…
• class Measure — One line of the report.
  • Measure(this.name, {this.stats, this.value, required this.gate, required this.result, this.note}) — A measure named [name] against its [gate].
  • final String name — What was measured.
  • final Stats? stats — Its distribution, where it has one.
  • final Object? value — Its single value, where it has one.
  • final String gate — The gate it is judged by.
  • final String result — pass, fail or not measured.
  • final String? note — Why a result is what it is, where that is not plain.
  • Map<String, Object?> toJson() — The measure as the report’s JSON.
• class Bench — Runs the bench once; [capture] reads the code of the picture on screen, or is null where nothing can be read.
  • Bench(this.config, this.makeEngine, {required this.log, this.capture, this.onStage}) — A bench of [config] that builds its engines with [makeEngine].
  • final BenchConfig config — What the run is given.
  • final TimelineEngine Function() makeEngine — Builds a new engine; each stage takes its own.
  • final AppLog log — Where every line of the run goes.
  • final Future<(int, int)?> Function()? capture — Reads the code of the picture on screen; null, or a null answer, where nothing can be read.
  • final void Function(String stage, TimelineEngine? engine)? onStage — Told each stage and the engine it runs, so the window can show it.
  • final measures — The measures so far, in the run’s order.
  • Future<int> run() — The whole run; the exit code is 0 when it ran to the end (pass or fail is the report’s), 1 when refused or failed.
  • Future<void> stress() — The stress set: each file its own timeline, a refusal checked by its code, a play case played and observed (Software Specification §19.11).
  • Future<void> cancelAtHalf(TimelineEngine engine, EngineTimeline timeline) — One export of [timeline] cancelled once its progress reaches half way; not measured when it never did, since a job that ended or never got there proves nothing about cancelling one in flight.
  • Future<void> cycles(EngineTimeline timeline, {int count = 50}) — [count] cycles of prepare, play, twenty scrubs, replace, seek, export and dispose: no crash, no record of an older revision from the replace on, no process and no file left (Software Specification §19.11).
• function (int, int) expectedCode(Map<String, Object?> manifest, int n) — The (clip id, source frame) the manifest says timeline frame [n] shows, as make_timeline_fixture.py computes it.
• function EngineTimeline repeated(EngineTimeline t, Duration atLeast) — [t]’s items and subtitles repeated along a timeline at least [atLeast] long, one revision on: the 10-minute play is one timeline, never the player restarted.

lib/measures.dart

• class Stats — The n, p50, p95 and max of a list of milliseconds; nearest-rank percentiles.
  • const Stats(this.n, this.p50, this.p95, this.max) — Stats of [n] values.
  • final int n — How many values.
  • final double p50, p95, max — The median, the 95th percentile and the largest, in milliseconds.
  • factory Stats.of(Iterable<double> values) — The stats of [values]; all zero when there are none.
  • Map<String, Object?> toJson() — The stats as the report’s JSON, rounded to 0.01.
• function double? firstFrameMs(int fromUs, Iterable<EnginePresented> records) — Milliseconds from [fromUs] to the first record presented at or after it; null when none was.
• function List<double> requestLatenciesMs(Map<int, int> requestUs, Iterable<EnginePresented> records) — Each answered request’s latency (ms): from its stamp in [requestUs] to the first record whose request is it.
• function double longestGapMs(Iterable<int> instantsUs, {int? startUs, int? endUs}) — The longest interval (ms) between consecutive instants of [instantsUs] in order, from [startUs] to [endUs]: the longest stretch with no new frame on screen.
• function ({int shouldShow, int onTime}) onTime(List<EnginePresented> play, int fpsNum, int fpsDen, int firstFrame, int lastFrame) — How many frames of a play were on time, of those the timeline should have shown.
• function List<double> avOffsetsMs(Iterable<EnginePresented> records, int fpsNum, int fpsDen) — The software A/V offset (ms) of each record that carries the audio clock: audioUs − frameStart(frame).
• function (int, int)? readCode(List<int> rgba, int width, {required double left, required double top, required double square}) — The (clip id, frame) a 16-square code shows, read from RGBA pixels: [square] px squares along the top of the picture whose top-left corner is at ([left], [top]) in an image [width] px wide.

Internal

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

• lib/main.dart: engines, main, BenchApp, _BenchAppState