filmopen_timeline_ui

A snapshot

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

A scene’s timeline dock (Software Specification §9.1, §19.15): composed by the scene’s page beneath its tabs, narrow by default, slid up to show the fixed tracks — picture (a clip that spans blocks drawn in the boxes it covers, after their own clips), speech, music, sound effects, beats, subtitles — with the player, its transport, the one edit (a block’s output duration) and the exports (MP4 through the engine, OTIO in Dart). The tracks fit the scene and zoom from their ruler, and their view follows the playhead; the block open in the scene’s script is the highlighted box, and a press in the dock puts the timeline in charge of it — the block under the playhead opens in the script, through filmopen_state’s script focus.

Flutter. 12 files, 3,425 lines under lib/; 112 tests in 12 files. Barrel: lib/filmopen_timeline_ui.dart.

Depends on

• filmopen_engine — uses EngineEvent, EngineException, EngineOutcome, ExportSettings, TimelineEngine, TrackKind
• filmopen_format — uses Beat, BlockEdit, Entity, FilmProject, Subtitle, blockLogName, blocksOf, projectKeyOf, withBlockChanged
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_platform — uses MonitorWindow
• filmopen_state — uses DraftChange, DraftChangeKind, LifecycleHook, NavIndex, OpenDrafts, PageAccess, SceneMediaEnd, Settings, navIndexProvider, sceneMediaProvider, sceneTimelineProvider, scriptFocusProvider, scriptFocusRequestProvider, settingsProvider, timelineChargeProvider, timelineEngineProvider
• filmopen_store — uses AppLog
• filmopen_timeline — uses DurationReason, PictureKind, SceneTimeline, TimedLayout, TimedMark, TimelineBlock, TimelineDiagnostic, TimelineFormat, writeOtio
• filmopen_ui — uses EmptyState, buildTheme, showMessageOn
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, file_selector.

Used by

filmopen_app, filmopen_browser

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/monitor_view.dart — only MonitorPlayer, MonitorView, MonitorViews, monitorPlayerProvider, monitorWindowProvider

• variable final monitorWindowProvider — The door to the picture’s window; the app’s own, a stand-in in tests.
• variable final monitorPlayerProvider — The open dock’s player, which the picture’s window shows; null while no dock is open.
• class MonitorPlayer — Which dock’s player the picture’s window shows: the dock opened last, until it goes.
  • void show(ScenePlayer player) — [player]’s dock opened: the window shows it.
  • void release(ScenePlayer player) — [player]’s dock went: the window shows nothing, unless another dock’s player has taken its place.
• class MonitorViews — The app’s root: the implicit view shows [app], any other view the runner adds a [MonitorView] (§9.1).
  • const MonitorViews({super.key, required this.app, @visibleForTesting this.views}) — [app] in the implicit view.
  • final Widget app — The app’s own page tree.
  • final Iterable<FlutterView> Function()? views — The views to show, where a test gives them; the platform’s otherwise.
• class MonitorView — The picture’s window: the open dock’s picture on black, its transport beneath (§9.1).
  • const MonitorView({super.key}) — The window’s page.

lib/src/timeline_dock.dart — only TimelineDock, TimelineDockFrame

• class TimelineDockFrame — An entity’s page with, where it is a scene’s, the timeline docked beneath it (§9.1).
  • const TimelineDockFrame({super.key, required this.page, this.project, this.scene, this.editable = false}) — [page], with the dock on [scene] of [project] beneath it where [scene] is given.
  • final Widget page — The page above the dock.
  • final FilmProject? project — The open film and the scene version on screen; no dock where [scene] is null.
  • final Entity? scene
  • final bool editable — Whether the viewer may change [scene]: the page’s [PageAccess.editable].
• class TimelineDock — A scene’s timeline dock: a handle to drag it up, one narrow row by default, the tracks when it is slid up (§9.1).
  • const TimelineDock({ super.key, required this.project, required this.scene, required this.editable, required this.pageHeight, }) — The dock on [scene] beneath a page [pageHeight] tall with it; [editable] says whether the one edit may be made.
  • final FilmProject project — The open film, whose draft of [scene] the one edit is written through.
  • final Entity scene — The scene version on screen.
  • final bool editable — Whether the viewer may change [scene]: the page’s [PageAccess.editable].
  • final double pageHeight — The height the page and the dock share.
  • static const double narrowHeight — The narrow dock: its handle and one row.
  • static const double handleHeight — The handle’s strip at the dock’s top.
  • static const double pictureBelow — The room below the open dock’s picture.
  • static Size pictureIn(double height, double width) — The open dock’s picture in a room [height] tall and [width] wide: the room’s height at 16:9, capped at half the dock’s width (§9.1).

Internal

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

• lib/src/edit.dart: EditOutcome, setOutputDuration
• lib/src/export.dart: ExportKind, ExportPickFailed, pickExportPath, Function, exportFiles, ExportEnd, ExportRun, exportOtio, mp4Run, exportBlock, runExport, ExportDialog, +2
• lib/src/platform.dart
• lib/src/platform_io.dart: platformLimit, platformPlayLimit, writeTextFile, existingFiles
• lib/src/platform_stub.dart: platformLimit, platformPlayLimit, writeTextFile, existingFiles
• lib/src/player.dart: ScenePlayer
• lib/src/tracks.dart: TimelineTracks, _shortestOf, _TimelineTracksState, BeatsDrawn, _badgeWidth, _markWidth, fileName, _Ruler, _PictureBox, _SoundBox, _MarkBox, _PastBadge, +3
• lib/src/transport.dart: Transport, _TransportState, clockText, PicturePane
• lib/src/words.dart: reasonText, diagnosticText, positionGlyph, firstWords, _partsOf, markText, markBoxText