filmopen_media_ui

A snapshot

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

Media tiles and their provenance, the file dialog by kind, the viewer and the platform player.

Flutter. 18 files, 1,863 lines under lib/; 96 tests in 12 files. Barrel: lib/filmopen_media_ui.dart.

Depends on

• filmopen_engine — uses EngineClock, EngineEvent, EngineException, EngineOutcome, EngineTimeline, MediaProbe, TimelineEngine, fileTimeline, frameStart
• filmopen_format — uses Catalogue, EntityType, ExactDecimal, FileMedia, FileNameParser, FilmProject, MediaKind, MediaStage, Pick, VersionStem, mediaExtensions, mediaFilePath, plainLine, projectKeyOf, projectSourceKey
• filmopen_media — uses LocalMediaStore, MediaChange, MediaChangeKind, MediaFact, MediaFetch, MediaFetchProblem, MediaFetchState, MediaFetchStatus, MediaProvenance, MediaStatus, MediaStore, Playable, PlayableBytes, PlayableFile, PlayableUrl, ProjectMedia
• filmopen_store — uses AppLog
• filmopen_platform — uses canRevealFiles, folderDialogsAvailable, revealInFileManager
• filmopen_ui — uses AppColors, DashedBorderPainter, EmptyState, imageProviderFor
• filmopen_l10n — uses nothing by name the digest could see

Third-party: file_selector.

Used by

filmopen_app, filmopen_browser, filmopen_forms, filmopen_insertion_ui, filmopen_prompt_ui, filmopen_render_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/file_kinds.dart

• function List<String> extensionsFor(Set<MediaKind> kinds) — The extensions a file dialog offers for [kinds], in the order of [mediaExtensions]; none for other, which no import names.

lib/src/file_picker_stub.dart

• variable const bool canChooseFiles — The web has no files of its own to name.
• function Future<List<String>> chooseMediaFiles(BuildContext context, {required Set<MediaKind> kinds}) — The platform’s file dialog, filtered to the extensions of [kinds], several files at a time; empty when the person cancels.

lib/src/folder_picker_stub.dart

• getter bool get canChooseFolder — The web has no folders of its own: a project made here lives in memory for the session, and so does its media.
• function Future<String?> chooseFolderPath(BuildContext context, {String? startAt})

lib/src/media_state.dart

• class MediaState — What a media’s border says, as one presentation value the tile and the viewer both draw.
  • const MediaState({ required this.code, required this.reason, required this.word, required this.sentence, required this.secondary, required this.bor…
  • final String code
  • final String? reason
  • final String word
  • final String sentence
  • final String? secondary
  • final StageBorder border
• function MediaState? mediaStateOf(AppLocalizations l10n, ThemeData theme, { MediaStage? stage, MediaStatus? status, bool unreviewed = false, List<MediaChang… — The state of a media from its [stage], [status], [unreviewed] and [changes] (MediaChange.after, first first); null where none of them says anything, so no box is drawn.
• function StageBorder unreviewedBorder(ThemeData theme) — The border of what waits to be picked or rejected (§9.3): dashed in the caution colour, the outline for a theme without the app’s colours.
• class MediaStateBox — A [MediaState] as a box: its border’s colour, width and dash around its word and its sentence (§9.3), the top line of a tile’s tooltip and of the viewer.
  • const MediaStateBox(this.state, {super.key, this.style})
  • final MediaState state
  • final TextStyle? style — The text’s style: the tooltip’s inside a tooltip, the surrounding one where null.

lib/src/media_tile.dart

• variable const double mediaTileEdge — The edge of a tile.
• variable const double mediaTileGap — The gap between tiles, and the edge a strip falls back to where two full-size tiles will not fit beside each other.
• variable const double mediaTileEdgeNarrow — The edge a row of tiles falls back to where two full-size tiles will not fit.
• function double mediaTileEdgeFor(double width) — The edge of the tiles in a row [width] wide: two to a row wherever two narrow ones fit and two full-size ones do not — a card in the narrow pane is about 240 px — and the full edge otherwise.
• class MediaTile — One piece of media as a square tile, opened by a tap in every mode.
  • const MediaTile({ super.key, required this.media, required this.project, required this.identifier, this.onTap, this.edge = mediaTileEdge, this.disa…
  • final ProjectMedia media
  • final FilmProject project
  • final String identifier — The tile’s identifier, unique on its page: media:<stem>:<group>:<n> on a place.
  • final VoidCallback? onTap
  • final double edge
  • final String? disabledReason — Why the tile cannot be opened, for its tooltip (§6).
  • final String? provenance — The provenance strip’s words ([provenanceText]); null draws no strip.
  • final bool favorite — Whether the version marks the entry a favourite: a star leads the strip.
  • final bool isNew — Whether the media arrived since the person last looked (§13.4 visited).
  • final bool archived — Whether the entry is archived: drawn dimmed, with the archive mark in place of New.
  • final String? note — The version’s note on the entry, for the tooltip.
  • final Widget? action — Drawn in the tile’s top corner: a place’s menu for it.
  • final String? busy — What a job still settling on it is doing, in the job’s words; null where none settles.
  • final MediaStage? stage — The stage its render was asked at, for the border; null for an upload and where the caller does not say.
  • final MediaStatus? status — Whether what it was rendered from changed since, as the caller computed it; null where it says nothing.
  • final bool unreviewed — Whether the render waits to be picked or deleted.
  • final List<String>? lines — What is known of it beyond the strip, one sentence a line, for the tooltip and the label.
  • final MediaState? state — Its status as the caller computed it with [mediaStateOf], the same value the viewer is given; null builds one from [stage], [status] and [unreviewed], with no reason.
  • final bool grouped — Whether a [MediaBatchFrame] round its batch draws the border and New: the tile draws neither (§9.3).
  • final Widget? leading — Drawn in the tile’s top-left corner: a place’s Pick check.
  • final Widget? trailing — Drawn at the tile’s lower right, above its strip: a place’s archive and trash.
• class MediaBatchFrame — One border round the unreviewed renders of a batch (§9.3), with New once above them where any is new.
  • const MediaBatchFrame({super.key, required this.children, this.isNew = false})
  • final List<Widget> children — The batch’s tiles, in the place’s order.
  • final bool isNew — Whether any of them arrived since the person last looked.
• class MediaTileButton — A small round control on a tile — the Pick check, archive, trash —, on the surface colour so it reads over any picture, with its [tooltip] and its [identifier]; drawn without a press where [onPressed] is null.
  • const MediaTileButton({ super.key, required this.identifier, required this.icon, required this.tooltip, this.color, this.onPressed, })
  • final String identifier — The control’s identifier, unique on its page: the tile’s own with .pick, .archive or .trash.
  • final IconData icon — The glyph drawn: the version row’s check, archive or unarchive, or the trash can.
  • final String tooltip — What the control does, or for a mark what it says: its tooltip and its label for a screen reader.
  • final Color? color — The icon’s colour; the surface’s text colour where null.
  • final VoidCallback? onPressed — What a press does; null makes the control a mark that says [tooltip] and does nothing, as the lit check.

lib/src/media_viewer.dart

• function Widget? Function(BuildContext context, ProjectMedia media, Playable playable, {required bool autoplay})? debugMediaPlayer — The player the viewer opens for a clip or a sound.
• function TimelineEngine Function()? mediaEngineFactory — The engine a clip or a sound plays through: the app’s main sets it to the factory the dock’s scenes play through (§19.16), so the pop-up and the dock share one backend; unset, a clip or a sound says Coming soon.
• function Future<void> showMediaViewer(BuildContext context, { required ProjectMedia media, required MediaStore store, String? provenance, String? note, Medi… — Opens [media].

lib/src/player/player_controls.dart

• class PlayerNow — What a player can say about itself at one moment.
  • const PlayerNow({required this.position, required this.duration, required this.playing})
  • final Duration position — Where the file has got to.
  • final Duration duration — How long the file is, or zero where the player cannot say.
  • final bool playing
• class PlayerControls — Play, pause, where in the file we are and how long it is.
  • const PlayerControls({ super.key, required this.now, required this.onPlay, required this.onPause, required this.onSeek, })
  • final PlayerNow now
  • final VoidCallback onPlay — Play from where the file is, or from the beginning where it has run out: pressing play must always play something.
  • final VoidCallback onPause
  • final Future<void> Function(Duration to) onSeek — Asked for once, when the finger lifts.

lib/src/player/player_rules.dart

• function double aspectRatioOrSquare(double reported) — The ratio to draw a picture at.
• function bool canSeek(Duration duration) — Whether the seek bar can be dragged at all.
• function bool hasRunOut({required Duration position, required Duration duration, required bool completed}) — Whether the file has already run out, so that pressing play must start it again rather than play nothing.
• function bool showsPlaying({required bool playing, required bool completed}) — Whether the file is playing, as the play and pause control shows it.
• function String clockText(Duration at) — m:ss, or h:mm:ss for anything an hour or longer.

lib/src/provenance.dart

• function String? provenanceText(AppLocalizations l10n, ProjectMedia media, {Catalogue? catalogue}) — The provenance strip’s words for [media], read from the record that made it and nothing else.
• function List<String> provenanceLines(AppLocalizations l10n, MediaProvenance provenance) — A placed render’s tooltip lines: when it was rendered, what changed since and when, when it was kept, and where the file and its record disagree (§6.9).
• function List<String> factLines(AppLocalizations l10n, MediaProvenance provenance) — A media’s facts as its tile’s tooltip says them: its length, then its size where both edges are known (§6.9).

lib/src/stage_border.dart

• typedef typedef StageBorder — A border: its colour, its width, and whether it is dashed.
• function StageBorder stageBorder(ThemeData theme, MediaStage? stage, bool outdated) — The border a thing of [stage] wears (§9.3): outdated red; else the stage — final green, draft green and dashed, prototype blue —; the outline for no stage, or a theme without the app’s colours.

Internal

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

• lib/src/file_picker_io.dart: canChooseFiles, chooseMediaFiles
• lib/src/folder_picker_io.dart: canChooseFolder, chooseFolderPath
• lib/src/player/media_player.dart
• lib/src/player/media_player_io.dart: canPlayMedia, mediaPlayerFor, _EnginePlayer, _Shows, _EnginePlayerState
• lib/src/player/media_player_stub.dart: canPlayMedia, mediaPlayerFor