filmopen_timeline

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

A scene’s timeline, derived from its file and its project and never stored whole (Software Specification §19.12–§19.14).

pure Dart. 5 files, 1,701 lines under lib/; 50 tests in 4 files. Barrel: lib/filmopen_timeline.dart.

Depends on

filmopen_engine — uses EngineException, EngineItem, EngineSubtitle, EngineSubtitleStyle, EngineTimeline, EngineTrack, ItemKind, MediaProbe, TrackKind, frameStart
filmopen_format — uses Beat, Entity, FilmProject, MediaEntry, MediaPlaces, MediaSpans, ScriptBlock, Subtitle, blockMediaGroups, blocksOf, entriesIn, mediaContainerKey, spansAllowed
filmopen_media — uses MediaStore, PlayableFile, ProjectMedia
filmopen_store — uses AppLog
filmopen_test_support (dev) — uses nothing by name the digest could see

Used by

filmopen_engine_mlt, filmopen_engine_mpv, filmopen_state, 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/lay_timed.dart`

class TimedMark — One beat or subtitle as laid: its place in its block’s list, and its start and length in seconds from the block’s start.
- const TimedMark(this.index, this.item, this.start, this.length) — A mark of [item], the [index]th of its block, from [start] for [length] seconds.
- final int index — Its place in the block’s list.
- final T item — The beat or the subtitle.
- final double start, length — Seconds from the block’s start, and how long it lasts.
class TimedLayout — A block’s beats or subtitles laid out: the marks inside it, those that would start past its end, and why.
- const TimedLayout({required this.marks, required this.past, required this.total, required this.atEnd}) — A layout of the values given.
- final List<TimedMark<T>> marks — The marks inside the block, in order.
- final List<TimedMark<T>> past — The marks that would start past the block’s end: not drawn, not shown, named by the block’s +N.
- final double total — The seconds they ask for together: their duration_sec, those without one counting nothing.
- final bool atEnd — Whether those without a duration_sec had nothing left to share and were laid at the block’s end, of no length.
function TimedLayout<T> layTimed<T>(List<T> items, num? Function(T item) duration, num seconds) — [items] laid in order from the block’s start over its [seconds], [duration] giving each one’s duration_sec.

`lib/src/otio.dart`

class ManifestItem — One file placed by the export: the timeline’s frames it fills and the source’s frames it takes (§15.5).
- const ManifestItem({ required this.file, required this.block, required this.lane, required this.timelineIn, required this.timelineOut, required thi… — An item of [file] for [block] on [lane].
- final String file — The absolute local path.
- final String? block — The block whose media it is.
- final String lane — The track’s name in the export: Picture, Clip sound, Speech, Music, Music 2, Effects …
- final int timelineIn, timelineOut, sourceIn, sourceOut — Frames at the project’s rate, in inclusive, out exclusive.
- Map<String, Object?> toJson() — The item as the manifest’s JSON.
class ReportEntry — One thing the export says about itself: a code and where (§15.5).
- const ReportEntry(this.code, {this.block, this.group, this.file, this.field, this.frames}) — An entry with [code].
- final String code — What is reported.
- final String? block, group, file, field — Where: the block, group, file and format field, and the frames concerned.
- final int? frames — How many frames, for held_last_frame.
- Map<String, Object?> toJson() — The entry as the report’s JSON.
class SceneExport — What a scene’s export writes: the OTIO file’s text, its manifest and its report.
- const SceneExport({required this.otio, required this.manifest, required this.report}) — An export of the values given.
- final String otio — The .otio file’s JSON text.
- final List<ManifestItem> manifest — Every file placed, in track order.
- final List<ReportEntry> report — What the export says about itself.
function SceneExport writeOtio(SceneTimeline timeline, {AppLog? log}) — [timeline] as one OTIO Timeline.1 (§15.5): a video track and one audio track per lane — the clips’ own sound, the speech, then each music and effects lane — on the same frames as its [SceneTimeline.toEngineTimeline]…

`lib/src/rules.dart`

variable const defaultBlockSeconds — The seconds a block lasts where nothing else says (§19.12).
function MediaEntry? entryInUse(Iterable<MediaEntry> entries) — The entry in use in a group (Project Specification §9.0): the first usable favourite, else the first usable, in file order.
enum DurationReason — Why a block lasts what it does: the code [blockOutputDuration] gives it, and the log says.
- values: set, clip, speech, asked, fallback
- const DurationReason(this.code)
- final String code — The reason as the log writes it.
function ({num seconds, DurationReason reason}) blockOutputDuration(ScriptBlock block, {int? clipMs, int? speechMs}) — The seconds a block lasts in the scene’s output, and why (Project Specification §10.3).
enum PictureKind — What a block’s picture is made of.
- values: clip, stills, black
class BlockPicture — A block’s picture: its kind and the entries it shows.
- const BlockPicture(this.kind, {this.clip, this.first, this.last}) — A picture of [kind] from the entries given.
- final PictureKind kind — Clip, stills or black.
- final MediaEntry? clip — The clip shown, for [PictureKind.clip].
- final MediaEntry? first — The first frame, for [PictureKind.stills]; the whole block where [last] is null, else its first half.
- final MediaEntry? last — The last frame, shown for the block’s second half, where both frames exist.
function BlockPicture blockPicture({MediaEntry? clip, MediaEntry? first, MediaEntry? last}) — A block’s picture (Software Specification §19.12): its clip in use; else its first frame for the whole block, or the first frame for the first half and the last frame for the second where both exist; else black.

`lib/src/scene_timeline.dart`

typedef typedef SourceResolver — Turns a media entry, and the piece of media it names in the project, into an absolute local path, or null where no local file answers (§19.13).
typedef typedef MediaProber — Measures a local file — its duration and, for a picture, its frame rate — or null where it cannot (the engine’s probe, §19.13).
variable const laneGainDb — The default level of each audio kind, in dB: speech forward, music and effects beneath.
function int nearestFrame(num seconds, int fpsNum, int fpsDen) — The frame nearest to [seconds] at [fpsNum]/[fpsDen], ties toward the later (Project Specification §11.3).
class TimelineDiagnostic — Something the build noticed and played around: a code, and the block, group and file it concerns.
- const TimelineDiagnostic(this.code, {this.block, this.group, this.file, this.field}) — A diagnostic with [code].
- final String code — What was noticed.
- final String? block, group, file, field — The block, group, file reference and format field concerned, where there is one.
- Map<String, Object?> toJson() — The diagnostic as the log and the report write it.
class TimelineFormat — The project’s delivery format as the timeline uses it (Project Specification §8.5).
- const TimelineFormat({ this.fpsNum = 24, this.fpsDen = 1, this.width = 1920, this.height = 1080, this.audioRate = 48000, this.subtitleFont = defaul… — A format of the values given.
- static const defaultSubtitleFont — The subtitles’ font where the project names none: a font the application bundles.
- static const defaultSubtitleSize — The subtitles’ size in pixels at the output’s height where the project gives none.
- final int fpsNum, fpsDen — The frame rate as a fraction.
- final int width, height — The picture size in pixels.
- final int audioRate — The mix’s sample rate in Hz.
- final String subtitleFont — The subtitles’ font family, format.subtitles.font (§8.5).
- final int subtitleSize — The subtitles’ size in pixels at the output’s height, format.subtitles.size.
- static (TimelineFormat, List<TimelineDiagnostic>) of(Map<String, dynamic>? project) — The format [project]’s format says, each value it does not say the default with a default_format diagnostic: 24 fps, 1920×1080, 48 kHz, subtitles in Noto Sans at 48 px.
- Duration at(int n) — When frame [n] starts: the engine’s [frameStart] at this rate.
class TimelineSource — One entry in use and where it plays from: its group, its local path (null: missing) and its measured length.
- const TimelineSource({ required this.group, required this.entry, this.path, this.measured, this.probed = false, this.fpsNum, this.fpsDen, }) — A source of [group] for [entry].
- final String group — The block media group it came from (§10.3).
- final MediaEntry entry — The entry in use.
- final String? path — An absolute local path, or null where no local file answers.
- final Duration? measured — The measured length: the record’s, else the entry’s, else the engine’s probe; null where none says.
- final bool probed — Whether [measured] came from the engine’s probe.
- final int? fpsNum, fpsDen — The source’s own frame rate, where its probe gave one; null otherwise.
class TimelineBlock — One block on the timeline: its frames, its output duration and why, its picture and its speech.
- const TimelineBlock({ required this.id, required this.index, required this.startFrame, required this.endFrame, required this.seconds, required this… — A block of the scene’s script on the timeline.
- final String? id — Its bl_<n>, null for a block the file gives none.
- final int index — Its place in the script.
- final int startFrame, endFrame — Its first frame, and the first frame after it: every boundary quantised once (§11.3).
- final num seconds — Its output duration before quantisation, and why.
- final DurationReason reason — Why it lasts [seconds].
- final PictureKind picture — What its picture is.
- final TimelineSource? clip, first, last — The picture’s sources: its clip, or its first and last frames, as [picture] uses them.
- final TimelineSource? speech — Its voice line in use.
- int get halfFrame — The frame its first still gives way to its last, where both are shown.
class TimelineSound — A music or sound-effect entry, or a spanning clip, on the timeline: its kind, its lane among that kind, its frames.
- const TimelineSound({ required this.kind, required this.block, required this.source, required this.startFrame, required this.endFrame, required thi… — A sound of [kind] from [block] on [lane].
- final TrackKind kind — [TrackKind.music] or [TrackKind.effects]; [TrackKind.speech] for a spanning clip, whose sound plays at a clip’s.
- final String block — The block that holds the entry.
- final TimelineSource source — What plays.
- final int startFrame, endFrame — Where it starts and the first frame after it.
- final int lane — Its lane among the sounds of its kind: a second wherever two overlap (§19.2).
class TimelineSubtitle — One subtitle as it is burnt: its block, its place in the block’s subtitles, its text and its frames.
- const TimelineSubtitle({ required this.block, required this.index, required this.text, required this.startFrame, required this.endFrame, }) — A subtitle of [block], the [index]th of it, from [startFrame] to the first frame after it, [endFrame].
- final String? block — Its block’s bl_<n>, null for a block the file gives none.
- final int index — Its place in the block’s subtitles.
- final String text — The words, as the person typed them.
- final int startFrame, endFrame — Its first frame, and the first frame after it, inside its block’s.
class SceneTimeline — A scene’s timeline, derived from its file and never stored whole (Software Specification §19.13).
- const SceneTimeline({ required this.id, required this.revision, required this.format, required this.blocks, required this.sounds, required this.dia… — A timeline of the values given; [build] makes one from a scene.
- final String id — The scene’s version stem.
- final int revision — The provider’s counter, raised on every rebuild.
- final TimelineFormat format — The project’s format.
- final List<TimelineBlock> blocks — The blocks in script order.
- final List<TimelineSound> sounds — The music and sound effects, in the order their blocks hold them.
- final List<TimelineDiagnostic> diagnostics — What the build noticed.
- final List<TimelineSound> clipSpans — The clips that span blocks (Project Specification §10.3), from their block’s start to the end of the last block they cover, each on a lane of its own where two overlap; a silent one keeps its lane and plays no sound.
- final List<TimelineSubtitle> subtitles — The subtitles burnt over the picture, in script order.
- final Map<int, TimedLayout<Beat>> beatLayouts — Each block’s beats laid over its seconds, by the block’s index: what the dock draws (§19.15).
- final Map<int, TimedLayout<Subtitle>> subtitleLayouts — Each block’s subtitles laid over its seconds, by the block’s index: the layout [subtitles] are burnt from.
- int get endFrame — The first frame after the last block.
- int lanesOf(TrackKind kind) — The number of lanes of [kind]: one for speech where any block speaks, one per overlap for music and effects.
- TimelineSound? coverOf(TimelineBlock block) — The spanning clip whose picture [block] shows where its own clip does not: the nearest one that started before it and has not ended; null where none covers it.
- int ownClipEnd(TimelineBlock block) — The first frame after [block]’s own clip stops showing: its start without a clip, its end where the clip spans or nothing measured it, else where the clip ends; past it, a covering clip shows (§10.3).
- ({int from, int into, bool held})? resumeOf(TimelineBlock block) — Where the clip covering [block] shows in it: from the frame [ownClipEnd] gives, resumed [into] frames into its source — the frames since its own block’s start, no later than [lastStartOf] its source, [held] where that…
- int? lastStartOf(TimelineSource source) — The latest project frame a piece of [source] may start at and still hold a decoded frame: a frame of the slower of the source’s rate and the project’s before its measured end, 100 ms where its rate is unknown — the so…
- static Future<SceneTimeline> build(FilmProject project, Entity scene, { required SourceResolver resolve, MediaProber? probe, int revision = 0, AppL… — The timeline of [scene] in [project], logged step by step (timeline.build.*, §19.9).
- static SourceResolver storeResolver(FilmProject project, MediaStore store, {AppLog? log}) — A resolver through the project’s media store (ProjectMedia.open → MediaStore.open): a file’s path, or null for a URL, a reference no file answers and media held only as bytes.
- static Future<Map<String, String>> inputsOf(FilmProject project, Entity scene, MediaStore store, { AppLog? log, }) — What a build of [scene] in [project] is made of, by part, each as text (§19.13): blocks the scene’s script blocks (their ids, text, durations, cues and media), scene_media the scene’s own media (which hide a block…
- EngineTimeline toEngineTimeline() — The scene as one [EngineTimeline] at its [revision]: one picture track without holes, the speech lane, and the music and effects lanes in the order their first entry appears, at their default gains (§19.13).
- int speechEnd(TimelineBlock block) — Where [block]’s voice line stops: its measured end, cut at the block’s end.