filmopen_format

A snapshot

This specification is a copy of docs/software/packages/filmopen_format.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 FilmOpen file format as pure Dart, and nothing else: the filename grammar (stems.dart), documents (entity.dart), the index and resolution — resolve, pickAt, nameOf, forViewer — (project.dart), epochs, kinds, character age, diagnostics codes, the manifest, short names, copy-left (copy_left.dart), the script’s one list — the children entry grammar, what a reader reports about an entry, the five edits of the list — withChildAdded, withChildrenAdded, withChildRemoved, withChildrenRemoved, withChildMoved —, the numbers an application gives what it creates and what a cue belongs to — (children.dart), the one walk of the script as a viewer sees it, with what is not in it, its lists read from a working version a reader names (script_outline.dart), a scene’s cast — its entries read or not read, and the edits that keep what an entry holds — (scene_cast.dart), the flat JSON rows, the ProjectSource interface with its in-memory implementation, canonical JSON (json_document.dart), the model catalogue’s platform files with its index’s platform listings (platform_file.dart) — where a credential may go, its hosts and on each the paths its file allows, the path made plain first (refuseCredentials) — whose problems are codes, never thrown.

pure Dart. 62 files, 13,444 lines under lib/; 680 tests in 62 files. Barrel: lib/filmopen_format.dart.

Depends on

Nothing of FilmOpen.

Used by

filmopen_account, filmopen_app, filmopen_assistant_ui, filmopen_automation, filmopen_browser, filmopen_cloud, filmopen_compare, filmopen_dictation, filmopen_drive, filmopen_engine_mlt, filmopen_engine_mpv, filmopen_exchange, filmopen_fdx, filmopen_forms, filmopen_insertion, filmopen_insertion_ui, filmopen_jobs_ui, filmopen_keys, filmopen_l10n, filmopen_media, filmopen_media_ui, filmopen_platform, filmopen_plugin_dev, filmopen_plugin_host, filmopen_plugins, filmopen_plugins_ui, filmopen_prompt_ui, filmopen_recorder, filmopen_relay, filmopen_render, filmopen_render_ui, filmopen_sharing, filmopen_state, filmopen_store, filmopen_support, filmopen_sync, filmopen_test_support, filmopen_text_ui, filmopen_timeline, filmopen_timeline_ui, filmopen_tree, filmopen_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/account_problem.dart

• enum AccountAuthProblem — Why a step of the sign-in failed, as a code.
  • values: codeInvalid, rateLimited, identityTaken, storageUnavailable, browserUnavailable, callbackUnavailable, sessionExpired, failed, unavailable

lib/src/allocated_id.dart

• class AllocatedId — A hidden identity allocated under an author’s owner handle (§5.2).
  • final String owner — The allocating handle’s owner, a username of up to 32 characters (§5.6), never its workspace part.
  • final int number — The positive decimal suffix, without leading zeros.
  • static const int maxNumber — The greatest suffix the ten-digit allocated-id grammar permits.
  • String get value — The canonical segment <owner>-<number>.
  • static AllocatedId? parse(String text) — Reads an allocated id, splitting its owner at the last hyphen.
  • factory AllocatedId.of(String owner, int number) — Constructs an id for a valid owner and a suffix within the ten-digit bound.

lib/src/allocation.dart

• function String nextEpochId(String owner, AllocationInventory inventory) — Gives the owner’s next epoch identity without reserving or writing it.
• function String nextOutfitId(String owner, String character, AllocationInventory inventory,) — Gives the owner’s next outfit identity for this character without writing it.

lib/src/allocation_inventory.dart

• class AllocationInventory — An immutable snapshot of allocated identities and project-version floors.
  • AllocationInventory({ Iterable<String> epochIds = const [], Map<String, num> nextEpochByOwner = const {}, Map<String, Set<String>> outfitIdsByChara… — Copies the inventory so later index changes cannot affect allocation.
  • final Set<String> epochIds — Every observed epoch token, including nonallocated spellings.
  • final Map<String, num> nextEpochByOwner — Each version author’s highest recorded next-epoch floor.
  • final Map<String, Set<String>> outfitIdsByCharacter — Outfit identity segments grouped by their complete character tag.
  • factory AllocationInventory.fromProject(FilmProject project) — Collects all versions and surviving references without changing the index.

lib/src/author.dart

• variable const stockPluginAuthor — The stock plug-ins’ author (§6.11): the plug-ins the application ships are written by this handle.
• class Author — An author handle: <owner>[.<workspace>] (specification §5.6).
  • const Author(this.owner, [this.workspace])
  • factory Author.parse(String handle) — Splits john123.locale-th into owner john123 and workspace locale-th.
  • final String owner
  • final String? workspace
  • String get handle
  • List<String> get segments — The filename segments this handle contributes, for naming checks.

lib/src/block_merge.dart

• enum BlockMergeProblem — Why a change to a scene’s blocks was refused; nothing of it was applied.
  • values: badArgs, unknownId, duplicateId, reserved, wrongShape
• class BlockMerge — What [mergeBlocks] made: the changed document and its counts, or the problem and the item that met it.
  • final Map<String, dynamic>? document — The document with the change applied, a copy; null where it was refused.
  • final BlockMergeProblem? problem — Why nothing was applied, or null.
  • final int? index — The position in the change of the item that was refused, where one was.
  • final int updated, removed, inserted — How many blocks the change updated, removed and inserted.
• function BlockMerge mergeBlocks(Map<String, dynamic> json, List<Object?> changes) — Applies [changes] to [json]’s blocks by id, in the order sent, to a copy (Software Specification §7.3).

lib/src/catalogue.dart

• class CatalogueProblem — A file of the catalogue that could not be read or used (§14.6).
  • const CatalogueProblem({required this.file, required this.code, this.field, this.message, this.unreadable = false})
  • final String file
  • final String code
  • final String? field
  • final String? message — The error’s text where a read threw, for the caller’s log.
  • final bool unreadable
• class Catalogue — The model catalogue as one reader reads it (Project Specification §14.6–§14.9).
  • const Catalogue({ this.listings = const [], this.platforms = const {}, this.entries = const {}, this.entryJson = const {}, this.problems = const []…
  • final List<CatalogueListing> listings — models.json’s platforms, in its order.
  • final Map<String, PlatformFile> platforms — The platform files that read, by the id their file declares.
  • final Map<String, CatalogueEntry> entries — The model entries that read, by id.
  • final Map<String, Map<String, dynamic>> entryJson — Each entry as its file holds it, for a platform hook that is handed the entry with the model’s id.
  • final List<CatalogueProblem> problems — What could not be read or used, as codes.
  • int get pendingCount — The platforms marked pending: listed, with no key and no run on them.
  • String? modelName(String id) — What a person calls model [id]: its entry’s name (§14.6), or null where no entry of that id names one.
  • static Future<Catalogue> read(Future<String> Function(String path) read) — Reads the catalogue through [read], which answers a file’s text by its path below the catalogue’s root.

lib/src/catalogue_entry.dart

• enum CatalogueEntryProblem — What is wrong with a catalogue entry, or with a row of it.
  • values: notJson, notObject, missingField, wrongType, badValue
• class CatalogueEntryIssue — A problem, and the field it is about (access[0].pricing[1].usd).
  • const CatalogueEntryIssue(this.problem, [this.field])
  • final CatalogueEntryProblem problem
  • final String? field
• class CataloguePrice — A price of an access row (§14.8): [usd] for one [per], [when] it applies.
  • const CataloguePrice({required this.usd, required this.per, this.when, this.match})
  • final ExactDecimal usd — US dollars for one [per], exactly as the entry writes the number.
  • final String per — The unit priced, such as minute or 1m_input_tokens.
  • final String? when — When this price applies, in the entry’s words.
  • final Map<String, String>? match — The exact parameter values this price requires, compared as text.
• class CatalogueAccess — How one platform serves an entry.
  • const CatalogueAccess({ required this.platform, required this.modelId, this.endpoint, this.variant, this.render = false, this.pricing = const [], t…
  • final String platform — The platform’s id (§14.9), such as openai.
  • final String? modelId — The platform’s name for the model (model_id); null where the row names none, as a local runtime’s row does.
  • final String? endpoint — Where the requests go, as the entry writes it.
  • final String? variant — Which of the platform’s ways of serving the entry this row is (std, pro), where it has several.
  • final bool render — Whether a render plug-in naming no models may serve this row.
  • final List<CataloguePrice> pricing — The prices of this row that could be read.
  • final String? placeholders — How this row’s prompt names its nth input picture (placeholders, Project Specification §14.7).
  • CataloguePrice? priceFor(String per) — The price of one [per], when exactly one row prices that unit.
• class CatalogueEntry — A catalogue entry, as far as a call needs it.
  • const CatalogueEntry({required this.id, required this.kind, required this.access})
  • final String id — The entry’s id, which a usage record names as its entry.
  • final String kind — The entry’s kind: text, image, video, tts, voice, music or analysis.
  • final List<CatalogueAccess> access — The access rows that could be read.
  • CatalogueAccess? accessOn(String platform) — The access row on [platform], when the entry has exactly one.
  • static ({CatalogueEntry? entry, List<CatalogueEntryIssue> issues}) read(String text) — Reads an entry’s [text].

lib/src/character_age.dart

• variable const List<String> characterKinds — The kind vocabulary of a character (Appendix A.1).
• function bool isBirthDate(String text) — Whether [text] is a birth_date: YYYY, YYYY-MM or YYYY-MM-DD, the month 01-12 and the day 01-31 (A.1).
• function int? ageAt(Map<String, dynamic> character) — The age shown for [character], one epoch’s file: the whole number, or N of the exact "N (YYYY)"; null for a phrase or nothing.
• function int? birthYearOf(Map<String, dynamic> character) — The year in birth_date (YYYY, YYYY-MM or YYYY-MM-DD), else the legacy "N (YYYY)" age.
• function ({Object? age, String decision, String? reason}) ageFromBirthDate(Map<String,dynamic> document, EpochDeclaration? epoch) — Fills a numeric age from the birth date and epoch year, or keeps the stored age with its reason (§9.1).
• enum AgeYearRefusal — Why a year of birth gives no age at an epoch (§9.1).
  • values: yearNoEpoch, yearAfterEpoch
• function ({String? value, AgeYearRefusal? refusal}) ageFromYear(int typedYear, EpochDeclaration? epoch) — The appearance.age a year of birth gives at [epoch], "N (YYYY)" with N the epoch’s year less [typedYear], or the reason it gives none.

lib/src/children.dart

• variable const String childrenKey — The key of the list, on a project file and on a folder.
• variable const Set<EntityType> childTypes — The types an entry may name (§8.5): a folder or a scene, and no other.
• enum ChildProblem — What a reader reports about an entry of children and never guesses at (§8.5).
  • values: childUntyped, childWrongType, childDuplicate
• class ChildEntry — One entry of a children list, as written and as read.
  • factory ChildEntry.of(EntityType type, String tag) — The entry a writer adds for a folder or a scene (§8.5): its short stem, which follows whatever version is in use.
  • factory ChildEntry.parse(String text) — Reads one entry.
  • final String text — The entry as the file writes it.
  • final EntityType? type — Folder or scene; null when the entry names neither ([problem] says why).
  • final String? tag — The short name the entry names; null with [type].
  • final VersionStem? pinned — The version a full reference pins (§6.2); null for a short stem.
  • final ChildProblem? problem — What a reader reports about this entry, if anything.
  • final String? prefix — The type token the entry starts with, when it has one: the argument of [ChildProblem.childWrongType].
  • bool get isPinned — Whether the entry names one version and no other (§6.2), where a short stem follows whatever version is in use.
  • bool get isReadable — Whether the entry names a folder or a scene, so that it can be looked up.
  • String? get shortStem — <type>_<tag>: the folder or scene the entry names, whatever version it pins.
  • String? get reference — What FilmProject.resolve takes (§6.1, §6.2): the full stem of a pinned entry, else the tag.
  • ChildEntry withProblem(ChildProblem problem) — This entry, reported as [problem].
• function List<ChildEntry> storyChildren(Map<String, dynamic> json) — The entries of [json]’s children, in the file’s order (§8.5).
• function Map<String, dynamic> withChildAdded(Map<String, dynamic> json, String entry, {int? index}) — [json] with [entry] added to its children at [index], or at the end.
• function Map<String, dynamic> withChildrenAdded(Map<String, dynamic> json, List<String> entries, {int? index}) — [json] with every one of [entries] added to its children from [index], or at the end, in the order given.
• function Map<String, dynamic> withChildRemoved(Map<String, dynamic> json, String entry, {int occurrence = 0}) — [json] without [entry] in its children.
• function Map<String, dynamic> withChildrenRemoved(Map<String, dynamic> json, List<String> entries) — [json] without any of [entries] in its children: each entry’s first listing of that exact text, taken out once.
• function String? danglingReason(ChildEntry entry, FilmProject project) — Why [entry] names nothing a reader draws (§8.5): missing where [project] has no file of that folder or scene, discarded where every version of it is set aside; null for anything else, an entry naming neither inclu…
• function Map<String, dynamic> withoutDanglingChildren(Map<String, dynamic> json, FilmProject project) — [json] without the entries of its children that [danglingReason] drops: the list as the reader shows it (§8.5), which an edit of the list — an add, a removal, a move — starts from.
• function Map<String, dynamic> withChildMoved(Map<String, dynamic> json, String entry, int index, {int occurrence = 0}) — [json] with [entry] moved to [index] of its children.
• function String nextSceneTag(FilmProject project) — The short name Add scene… proposes (§17).
• function String nextFolderTag(FilmProject project) — The short name Add folder… proposes (§17): f and the next number over the folders’ short names of that shape.
• function Set<String> takenChildTags(FilmProject project, EntityType type) — The short names of [type] — folder or scene — that are spoken for.
• variable const String folderTagPrefix — What a numbered folder’s short name starts with.
• function String nextNumberedTag(Iterable<String> tags, {String prefix = ''}) — [prefix] and one more than the highest number among the [tags] that are [prefix] and digits and nothing else.
• class CueOwner — What a cue belongs to (§11.2).
  • const CueOwner(this.type, this.reference, {required this.isNamed})
  • final EntityType type — [EntityType.folder] or [EntityType.scene].
  • final String reference — The folder or scene, as FilmProject.resolve takes it.
  • final bool isNamed — Whether the cue names its owner in folder or scene; false where its own short name decided.
  • String get tag — The short name of the folder or scene: the tag of a full reference of [type], or [reference] itself.
• function CueOwner? cueOwnerOf(Map<String, dynamic> json, {required String tag}) — What the cue [json], of short name [tag], belongs to (§11.2).

lib/src/content_check.dart

• variable final Map<String, Map<String, Object?>> fieldMapPatchDefs — The change view of [fieldMapDefs], each record named <name>_patch, as the assistant’s commands merge a change (Software Specification §7.3): at a merge boundary — the top of a document and every object reached t…
• function List<ShapeProblem> contentProblems(EntityType type, Object? content, {bool patch = false}) — Every path at which [content] breaks [type]’s record (Project Specification §18.3, Appendix A).
• function Map<String, Object?> contentKeysSchema(EntityType type) — [type]’s change view ([fieldMapPatchDefs]) at its top level, for a tool’s arguments.

lib/src/copy_left.dart

• variable const Set<String> uncopyableHeaderKeys — What copy-left never moves in any file.
• function Set<String> uncopyableKeys(Entity entity) — What copy-left never moves in [entity].
• function bool copyablePath(String path, {Set<String> uncopyable = uncopyableHeaderKeys}) — Whether copy-left may write [path] at all.
• class RowCopy — What one row of a comparison can copy.
  • const RowCopy()
• class CopyPaths — The ordinary case: the JSON paths this row owns.
  • const CopyPaths(this.paths)
  • final List<String> paths
• class CopyBlock — A scene’s block, addressed by its id (§13.3’s table).
  • const CopyBlock(this.id) — The block [id]; inserted, where the left has none, at the place mergeOrder draws it — a section’s << and the file’s <<<.
  • const CopyBlock.placed(this.id, {this.after}) — The block [id]; inserted, where the left has none, after the left’s block [after], or first where it is null — a row’s <, at the place the block diff drew its row (§9.3).
  • final String id
  • final bool placed — Whether the insertion’s place is [after] rather than mergeOrder’s.
  • final String? after — The left’s block id an insertion follows, null for the start; read only where [placed].
• class CopyMedia — The media card (§9.0): media and preview.
  • const CopyMedia()
• class NoCopy — A row with nothing to copy in any circumstance — a block with no id, which none of §13.3’s four cases can address.
  • const NoCopy()
• enum BlockCase — Which of §13.3’s four cases a block row is in.
  • values: same, replace, insert, delete
• function Object? valueAtPath(Map<String, dynamic> json, String path) — The value at a dotted path, or null when there is none.
• function bool hasPath(Map<String, dynamic> json, String path) — Whether the path is in the document, a key present and null included.
• function bool worthCopying(Object? value) — Whether the right version’s value at this path is something to move.
• function bool canWritePath(Map<String, dynamic> json, String path) — Whether a path can be written into this document without taking anything away.
• function bool blocksAreScript(Map<String, dynamic> json) — Whether this document’s blocks is a script: absent, empty, or a list of blocks.
• function void setPath(Map<String, dynamic> json, String path, Object? value) — Writes [value] at a dotted path, creating what is missing on the way.
• function Object? deepCopy(Object? value) — A value with nothing shared with the document it came from.
• function String canonicalJson(Object? value) — Two values compared by content rather than by key order.
• function List<Object?> blocksOf(Map<String, dynamic> json) — The blocks of a document as they are in the file.
• function Map<String, dynamic>? blockById(Map<String, dynamic> json, String id) — The block with that id, or null.
• function bool duplicateBlockId(Map<String, dynamic> json, String id) — Whether an id names more than one block in the same file.
• function BlockCase blockCase(Map<String, dynamic> left, Map<String, dynamic> right, String id) — Which case of §13.3’s block table this id is in, for the two documents.
• function List<Object?> blocksAfterCopy(Map<String, dynamic> left, Map<String, dynamic> right, String id, {bool placed = false, String? after}) — The blocks of [left] after copying the block [id] from [right] (§13.3).
• function List<String> pendingPaths(RowCopy copy, Map<String, dynamic> left, Map<String, dynamic> right, {Set<String> uncopyable = uncopyableHeaderKeys}) — The paths of this row the right version has and the left does not match.
• function bool canCopy(RowCopy copy, Map<String, dynamic> left, Map<String, dynamic> right, {bool mayDelete = true, Set<String> uncopyable = uncopyableHeader… — Whether this row offers a < at all.
• function void applyCopy(RowCopy copy, Map<String, dynamic> draft, Map<String, dynamic> right, {bool mayDelete = true, Set<String> uncopyable = uncopyableHea… — Applies one row’s copy to [draft], which must be the left version’s own working copy.
• function List<String> copiedKeys(Iterable<RowCopy> copies, Map<String, dynamic> left, Map<String, dynamic> right, { bool mayDelete = true, Set<String> uncop… — What a copy of these rows would write, as the keys the log and the message name (§9.5): a path, or blocks.<id> for a block.

lib/src/diagnostics.dart

• enum WarningKind — The kinds of warning a reader raises while opening a project.
  • values: segmentOutsideGrammar, duplicateStem, headerMissing, headerMismatch, fieldShouldBeString, fieldShouldBeObject, officialLacksTarget, duplicateOfficial, officialMissingFile, notJsonObject, invalidJson, duplicateKey, couldNotRead, noProjectFile, severalProjectTags, severalProjectAuthors, noManifest, manifestTagMismatch, libraryStemShadowed, libraryUnavailable, noEpochsDeclared, pickMissingFile, pickEpochMismatch, pickOtherEntity, officialWrongTarget, timestampUnreadable, duplicateMedia, mediaEntryUnreadable, mediaGroupReserved, renderWithoutRequest, officialDiscarded, pickDiscarded
• class ProjectWarning — Something a reader should tell the user about.
  • const ProjectWarning(this.kind, {this.args = const [], this.path})
  • final WarningKind kind
  • final List<String> args — Positional arguments, in the order the kind’s comment lists them.
  • final String? path — The file concerned, when there is one.
  • ProjectWarning withPath(String path)
• enum ProblemKind — Why a reference could not be resolved (§6.1).
  • values: noEntity, noEpoch, noEpochOrDefault, noFile, ambiguous
• class ResolutionProblem
  • const ResolutionProblem(this.kind, {required this.type, required this.reference, this.epoch, this.owners = const []})
  • final ProblemKind kind
  • final EntityType type
  • final String reference
  • final String? epoch
  • final List<String> owners

lib/src/entity.dart

• enum EntityOrigin — Which root a file came from.
  • values: project, library
• variable const Set<String> headerKeys — The header fields every entity file repeats from its filename (§7), plus the informational header fields.
• variable const Set<String> nonValueKeys — The keys a value view never shows as a row.
• function Set<String> nonValueKeysFor(EntityType type) — [nonValueKeys] for a file of [type].
• function String? stringField(Map<String, dynamic> json, String key) — A string field, or null when absent or not a string.
• function num? numField(Map<String, dynamic> json, String key) — A numeric field, or null when absent or not a number.
• function DateTime? parseInstant(String? text) — A timestamp as an instant (§1.4).
• class Entity — One versioned entity file: a library or spec entity.
  • const Entity({required this.stem, required this.path, required this.json, this.origin = EntityOrigin.project, this.rawText})
  • final VersionStem stem
  • final String? rawText — The file’s text as read, for optimistic concurrency.
  • final String path — Root-relative path with / separators.
  • final EntityOrigin origin
  • bool get isFromLibrary
  • bool get isDiscarded — Whether the version is set aside (§7): discarded is present, whatever its value.
  • final Map<String, dynamic> json — The complete document.
  • String get name
  • String? get forkedFrom
  • String? get versionLabel — A short word for this version in version lists — “goth”, “classic”.
  • String? get notes
  • String? get updated
  • String? get created
  • String? get kind
  • String? string(String key) — A string field, or null when absent or not a string.
  • List<String> stringList(String key) — The string entries of a list field: tags or full references.
  • List<Map<String, dynamic>> get blocks — The script blocks of a scene (§10.3); empty for other types.
  • List<ProjectWarning> get headerMismatches — Where the header disagrees with the filename (§7, §18.2).
  • List<ProjectWarning> get fieldTypeWarnings — Header fields present with the wrong JSON type.
  • List<ProjectWarning> get mediaWarnings — What the file’s media holds that no reader reads (§9.0): a repeated reference, an unreadable entry, a key that cannot name a group.
• function bool isEntityDeleted(Entity entity) — Whether [entity] is in the recycle bin: its own deleted is true (Project Specification §7).
• class OfficialPointer — <type>_<tag>[_<epoch>]_official.json — the project’s chosen version.
  • const OfficialPointer({ required this.stem, required this.path, required this.json, required this.official, this.setBy, this.setAt, this.note, this…
  • static OfficialPointer? fromJson(OfficialStem stem, String path, Map<String, dynamic> json, {String? rawText, EntityOrigin origin = EntityOrigin.pr… — Null when the file does not say which version is official.
  • final OfficialStem stem
  • final String path
  • final Map<String, dynamic> json — The complete document, for rewriting it without losing fields.
  • final String? rawText — The file’s text as read, for a write that must not clobber a change made meanwhile.
  • final EntityOrigin origin — Which root the pointer came from (§14.5).
  • bool get isFromLibrary
  • final String official — The full stem this pointer names.
  • final String? setBy
  • final String? setAt
  • final String? note
• class CommentaryEntry — One entry of a commentary file (§13.4).
  • const CommentaryEntry({ required this.on, this.at, this.rating, this.text, this.block, this.field, })
  • factory CommentaryEntry.fromJson(Map<String, dynamic> json)
  • final String on — A version stem or a media reference.
  • final String? at
  • final int? rating — 1, -1 or null.
  • final String? text
  • final String? block
  • final String? field
• class Commentary — cm_<type>_<tag>_<author>.json
  • const Commentary({ required this.stem, required this.path, required this.json, required this.entries, this.pick, this.pickedAt, this.visited, this.…
  • factory Commentary.fromJson(CommentaryStem stem, String path, Map<String, dynamic> json, {String? rawText})
  • final CommentaryStem stem
  • final String path
  • final Map<String, dynamic> json — The complete document, for rewriting it without losing fields.
  • final String? rawText — The file’s text as read (see [Entity.rawText]).
  • final Object? pick — The author’s pick as written (§13.4): a stem, or an object of stems keyed by epoch.
  • final Object? pickedAt — When the pick was made (§13.4 picked_at): an RFC 3339 UTC string, or an object keyed by epoch as [pick] is.
  • final Object? visited — When the author last had the entity’s media on screen (§13.4 visited), in [pickedAt]’s shapes: an RFC 3339 UTC string for an entity without epochs, or an object keyed by epoch.
  • final List<CommentaryEntry> entries
  • Author get author
  • String? pickStemAt(String? epoch) — The picked stem at [epoch] (null for entities without one).
  • String? pickTimeAt(String? epoch) — When the pick at [epoch] was made (§13.4), or null when the file does not say.
  • String? visitedAt(String? epoch) — When the author last looked at the entity’s media at [epoch] (§13.4), or null when the file does not say.
  • List<String> get pickStems — Every stem the file picks, at any epoch, for checks and display.
  • List<String> get pickTimes — Every time the file records for a pick, in either shape, for checks.
  • static String? epochOfStem(String stem) — The epoch a version or pointer stem names; null for other stems.
• class RenderItem — One item of a render batch (§12.2, Appendix A.10).
  • const RenderItem(this.json)
  • final Map<String, dynamic> json
  • int? get n
  • String get source
  • String get deliverable
  • String? get output
  • int? get durationMs
  • String? get status
  • String? get group — The group of the entity’s media the output was put in (§12.2); null where no group took it.
• class RenderRequestFacts — A render record’s request (§12.2): what was asked, the document’s keys as written.
  • const RenderRequestFacts(this.json)
  • final Map<String, dynamic> json
  • String? get renderId — The render job’s id.
  • String? get plugin — The plug-in’s version stem.
  • String? get model — The catalogue entry’s id.
  • String? get platform — The platform the render ran on.
  • media.MediaStage? get stage — The stage the person asked at.
  • String? get prompt — The prompt as sent.
  • Map<String, dynamic>? get params — The options by the catalogue’s names, the seed among them where one was sent.
  • bool? get seedRandom — Whether no seed was given, so that each render took a new one.
  • List<dynamic>? get inputs — The media given to the model, one reference each.
  • Map<String, dynamic>? get inputsByName — The same media by the catalogue’s input names.
  • RenderTreatment? get treatment — The visual treatment that applied, with where each leaf came from.
  • List<String> get sources — The version stems read beside the primary.
  • String? get purpose — What the render is for, in the target’s word.
  • String? get askedAt — When the person asked, as the file has it.
  • Map<String, dynamic>? get from — The take the render continued, as the record keeps it.
• class RenderBatch — rd_<id>_<author>.json
  • const RenderBatch({ required this.stem, required this.path, required this.json, required this.items, this.rawText, })
  • factory RenderBatch.fromJson(BatchStem stem, String path, Map<String, dynamic> json, {String? rawText})
  • final BatchStem stem
  • final String path
  • final Map<String, dynamic> json
  • final List<RenderItem> items
  • final String? rawText — The file’s text as it was read, which a later read of the index serves instead of reading the file again (§7.5).
  • String get id
  • Author get author
  • String get kind — render · import · plugin · manual
  • String? get status
  • String? get created
  • RenderRequestFacts? get request — What a render was asked (§12.2): a render record’s request; null for every other kind, and for a render record without one, which the loader reports.
  • media.MediaStage? get stage — The stage the render was asked at; null where the record has no request.
  • double? get costUsd — The record’s cost, cost_usd at its top (§12.2); null where none is known.
  • double get totalCostUsd — The record’s cost, 0 where none is known.
  • RenderItem? itemAt(int n) — The item whose n is [n] (§12.2), the first where a hand-written record repeats one; null for none.
• class Take — A media file discovered by name (§12.1).
  • const Take({required this.name, required this.path, this.media})
  • final TakeName name
  • final String path — The file name in the project’s flat media/ folder (§4.1).
  • final MediaLocation? media — Where the file can be loaded from; null when its source cannot show media.
  • Deliverable get deliverable
  • VersionStem get source

lib/src/entity_fields.dart

• variable final Map<String, PathValue> characterBoxes — Every box of the character form on a dotted path (A.1), and what each holds.
• variable final Map<String, PathValue> locationBoxes — Every box of the location form on a dotted path (§9.3, A.3), and what each holds.
• variable final Map<String, PathValue> outfitBoxes — Every box of the outfit form on a dotted path (A.2), and what each holds.
• variable final Map<String, PathValue> propBoxes — Every box of the prop form on a dotted path (A.3), and what each holds.
• variable const List<String> propKinds — A prop’s kinds (Project Specification A.3), in A.3’s order: the prop form’s chips and the new-prop dialog’s entries.
• variable const List<String> outfitConditions — An outfit’s conditions (Project Specification A.2), in A.2’s order: the outfit form’s chips.
• variable const List<String> garmentKeys — The keys of one garment (A.2), in the order its boxes are drawn; condition is prose here, not the outfit’s enum.
• variable const Map<String, String> fieldReferences — The text boxes that hold another entity’s tag, and what each points at: [fieldShapes] names them so.
• function String fieldShapes(EntityType type) — The lines a model reads for [type] (§6.11a): one path: shape per field — for a library form, the fields with widgets of their own first, then every box of the type’s map; for every other type a command writes, each…
• function String contentGuide() — The guide a write tool’s description carries to the fields and nested shapes a change may hold (§7.3).
• function List<String> promptNames(String record) — The prompt names a record’s prompts takes, in the record’s order — [record] a type’s two letters or a shared record’s name (block, visual_style) of [fieldMapDefs] — or none.
• function String? promptAdvice(EntityType type, String path) — For a refused prompt name at a change’s [path] of [type] (prompts.first_frame, blocks[0].prompts.voice), the sentence a model is told (§7.3): which records take that name, and the names this place takes; null for…

lib/src/entity_type.dart

• enum EntityCategory — The four families of file a project folder contains.
  • values: library, spec, commentary, renderBatch, set
• enum EntityType — Every two-letter type prefix the format defines.
  • values: project, character, outfit, location, prop, style, misc, document, model, platform, plugin, folder, scene, shot, cue, commentary, renderBatch, comp, session
  • const EntityType(this.prefix, this.category)
  • final String prefix
  • final EntityCategory category
  • static EntityType? fromPrefix(String prefix)
  • bool get hasEpoch — Library entities carry an epoch in their filename.
  • bool get isVersioned — Library and spec entities are versioned (_v<n>) and can be forked.
  • EntityType get parentType — The type a dotted tag nests under.
  • EntityType get containedType — The inverse of [parentType]: what a dotted tag of this type contains.
• enum Deliverable — Deliverable prefixes of take filenames (§5.5).
  • values: conceptSheet, storyboard, firstFrame, lastFrame, keyframe, clip, voice, music, sfx, ambience
  • const Deliverable(this.prefix, {this.isImage = false})
  • final String prefix
  • final bool isImage
  • String get token — The word a batch item’s deliverable and a picks key spell it with (§1.4, §12.2).
  • static Deliverable? fromPrefix(String prefix)

lib/src/epoch_seed.dart

• function ({EntityVersions? versions, String reason}) seedSourceFor(FilmProject project, EntityGroup group, Author? viewer) — Selects the default pick or the sole retained era, refusing ambiguity instead of guessing (§9.1).

lib/src/epochs.dart

• variable const String nextEpochKey — The project version’s own next-epoch high-water key.
• function num? readNextEpoch(Map<String, dynamic> json) — Reads a finite whole next-epoch floor, tolerating an integral double.
• function num encodeNextEpoch(String owner, Iterable<String> epochIds, { Map<String, dynamic>? previous, }) — Encodes the owner’s floor without lowering it or reusing a declared identity.
• class EpochDeclaration — One declared epoch.
  • const EpochDeclaration({required this.tag, this.label, this.year, this.order}) — Defines one immutable declaration without reserving its token.
  • final String tag — The token used in filenames, e.g. 30yo, post-war.
  • final String? label — A sentence for people: “After the war”.
  • final int? year — The calendar year the epoch stands for, when there is one.
  • final int? order — The declared position; readers order by it, then by appearance.
  • EpochDeclaration copyWith({String? label, bool clearLabel = false, int? year, bool clearYear = false, int? order}) — Copies the declaration, clearing label or year only when requested.
  • Map<String, Object?> toJson() — Encodes the declaration’s present label, order and year.
• function List<EpochDeclaration> declaredEpochs(Map<String, dynamic> projectJson) — The epochs a project file declares, in order.
• function Map<String, Object?> encodeEpochs(List<EpochDeclaration> epochs, {Map<String, dynamic>? previous}) — The epochs object to write for [epochs] in this order.
• function List<String> epochsDroppedInUse(Map<String, dynamic> before, Map<String, dynamic> after, Map<String, int> usage,) — The epochs [before] declares that [after] does not, and that files are at (§8.2).

lib/src/field_maps.dart

• variable const Map<String, Map<String, Object?>> fieldMapDefs — The shared records and one record per type, keyed by the type’s two letters, as a JSON Schema’s $defs.
• variable const List<EntityType> fieldMapTypes — The types a command creates or updates (Software Specification §7.3): create-entity’s, the project, and the shot, cue, model, platform and plug-in documents update-entity reaches.
• function Map<String, Object?>? fieldMap(EntityType type) — [type]’s record in [fieldMapDefs]; null for a type no command writes.
• function Map<String, Object?>? fieldMapAt(EntityType type, String path) — The schema at dotted [path] in [type]’s record, through objects’ properties and $ref; null where the record defines no such path.
• function PathValue boxValueAt(EntityType type, String path) — What a box holds at [path] of [type]’s record: a string a text box, a number a number box, a list of strings a lines box.
• function Map<String, PathValue> boxesOf(EntityType type, List<String> paths) — [paths], in their order, each with what its box holds, read from [type]’s record ([boxValueAt]).

lib/src/field_paths.dart

• enum PathValue — What a box holds at a path.
  • values: text, number, lines
• function bool pathFits(Map<String, dynamic> json, String path, PathValue kind) — Whether a box of [kind] can show and write [path] in [json] without losing anything.
• function bool canSetPathText(Map<String, dynamic> json, String path) — Whether [setPathText] would write text at [path] in [json], answered without writing.
• function String pathText(Map<String, dynamic> json, String path, PathValue kind) — The text a box of [kind] starts with.
• function void setPathText(Map<String, dynamic> json, String path, PathValue kind, String text) — [json] after a box of [kind] at [path] took [text]: trimmed.
• function num? numberText(String text) — The number [text] says, or null for text that is not a finite one.
• function void setPathValue(Map<String, dynamic> json, String path, Object? value) — [json] with [value] at [path], or without the key when [value] is null, and then without every object on the way that is left empty.

lib/src/flat_json.dart

• function Map<String, Object?> flattenJson(Map<String, dynamic> json, {Set<String> skip = const {}, String prefix = ''}) — A file’s JSON as one row per leaf path (§13.3): a nested object becomes dotted paths, a list stays whole as one value.
• function List<String> mergeOrder(List<String> left, List<String> right) — The row order of a comparison (§13.3).

lib/src/input_limits.dart

• function Set<String> mediaFormatsOf({String? mime, String? name}) — The formats a piece of media is, in the catalogue’s words (§14.8): what its [mime] type and its [name] each say.
• function List<String> inputFormatsOf(Object? spec) — The formats one input of an entry’s capabilities.inputs lists, lowercased, in its order.
• function num? inputMostMegabytes(Object? spec) — The size one input of an entry’s capabilities.inputs takes at most, in megabytes; null where it names none.
• function String? inputRefusal(Object? spec, {String? mime, String? name, int? bytes, int? lengthMs}) — Why the input [spec] describes does not take a piece of media — formats, max_mb, min_s, max_s — or null where it takes it.

lib/src/json_document.dart

• function Map<String, dynamic> decodeDocument(String text) — Decodes one JSON object, refusing anything else and any duplicate key.
• class NotJsonObjectException — Valid JSON whose root is not an object (§18.1).
  • const NotJsonObjectException() — The refusal, with the message not a JSON object.
• class DuplicateKeyException — Two entries of one object share a name (§18.1).
  • DuplicateKeyException(this.key)
  • final String key
• function Map<String, dynamic> copyDocument(Map<String, dynamic> json) — A deep copy, so an edit never reaches into the index’s own map.

lib/src/json_exact.dart

• function Object? decodeJsonExact(String text) — [text] decoded as jsonDecode decodes it, every number an [ExactDecimal].

lib/src/json_shape.dart

• class JsonShapeException — A schema that could not be read: an unknown keyword, a keyword of the wrong type, a $ref that resolves to nothing.
  • const JsonShapeException(this.at, this.problem)
  • final String at
  • final String problem — What is wrong, as a short code and its subject: unknown keyword format, unresolved $ref #/$defs/Nothing.
• enum ShapeProblemCode — What is wrong with a value, by a code: never a sentence.
  • values: missing, type, notInEnum, notConst, noShape, severalShapes, notAllowed, belowMinimum, aboveMaximum, tooFewItems, tooManyItems
• class ShapeProblem — One problem with a value: where it is and what it is.
  • const ShapeProblem(this.path, this.code, [this.expected, this.allowed])
  • final String path — The value’s place: '' for the whole value, seed, outputs[0].mime.
  • final ShapeProblemCode code
  • final Object? expected — What was expected, where the code has something to name: a type, the values of an enum, a constant, a bound.
  • final List<String>? allowed — For [ShapeProblemCode.notAllowed], the properties the object’s schema names, for an author told where else to write; outside [toString] and equality, which stay the code and the place.
• class JsonShape — A schema read and checked: what a value is held to.
  • static const keywords — The keywords this checker knows: the definition’s, and no others.
  • static const types — The seven types of JSON Schema’s type.
  • final String at — Where this schema is in its file, for a reader told what is wrong.
  • String? description — The description the file gives, for a reader.
  • static JsonShape parse(Object? schema, {String at = ''}) — Reads [schema] on its own, with no $defs to refer to.
  • String? get type — The type named, where one is.
  • Map<String, JsonShape> get properties — The properties an object schema names, in the file’s order.
  • List<String> get required — The names required lists.
  • JsonShape? get items — The schema of an array’s items, where one is given.
  • num? get minimum
  • num? get maximum
  • List<ShapeProblem> check(Object? value, {String path = ''}) — Every problem [value] has against this schema; empty where it is valid.
  • bool accepts(Object? value) — Whether [value] is valid.
• class ShapeLibrary — The shapes of one file’s $defs, by name, and every schema read against them.
  • ShapeLibrary(Map<String, Object?> defs) — [defs] is the file’s $defs as JSON.
  • Iterable<String> get names — The names of $defs, in the file’s order.
  • JsonShape? operator [](String name) — The shape named [name] in $defs, read on first use; null for none.
  • JsonShape shape(Object? schema, {String at = ''}) — Reads [schema], found at [at] in its file.

lib/src/json_values.dart

• function Object? frozenJson(Object? json) — [json] copied with every map and list in it unmodifiable, all the way down, whatever its caller does later.
• function bool sameJson(Object? a, Object? b) — Whether [a] and [b] hold the same JSON: maps by their entries in any order, lists item by item.

lib/src/manifest.dart

• variable const String projectManifestFileName — The fixed filename at the root of every project folder (§4.4).
• class SyncSettings — Where the film is kept in step for sharing, without machine paths or credentials.
  • const SyncSettings({required this.target, this.id, this.name})
  • final String target
  • final String? id
  • final String? name
  • Map<String, Object?> toJson()
  • static SyncSettings? fromJson(Object? json) — An absent, malformed or unknown target is not a sharing configuration.
• class ProjectManifest — The parsed manifest.
  • const ProjectManifest({ required this.path, required this.json, this.tag, this.note, this.sync, this.rawText, })
  • factory ProjectManifest.fromJson(String path, Map<String, dynamic> json, {String? rawText})
  • final String path — Project-relative path of the file; normally just the filename.
  • final Map<String, dynamic> json — The complete document, unknown fields included (§18.2).
  • final String? tag — The project tag the folder declares.
  • final String? note
  • final SyncSettings? sync — The shared target, where the manifest names one (§4.4).
  • final String? rawText — The file’s text as it was read.
  • static Map<String, Object?> template({required String tag, String? note}) — The document a writer creates for a new project (§18.3).

lib/src/media_names.dart

• variable const String documentsFolder — The flat folder of a project’s JSON documents (§4.1).
• variable const String mediaFolder — The flat folder of a project’s takes and reference files (§4.1).
• variable const String thumbnailsFolder — The folder that holds a project’s derived thumbnails (§4.2).
• enum ProjectArea — Where a project-relative path lies in the layout (§4.1).
  • values: root, documents, media, thumbnails, other
• function ({ProjectArea area, String name, bool nested}) projectAreaOf(String path) — The area’s name, the file’s name, and whether it is below another folder.
• function String documentPath(String fileName) — The project-relative path of a document by its file name (§4.1).
• function String mediaFilePath(String fileName) — The project-relative path of a media file by its name (§4.1).
• function bool isMediaFileName(String name) — Whether a local media reference names one file, never another folder (§6.3).
• enum MediaKind — What a media file is, by its extension (§6.3).
  • values: image, video, audio, other
• variable const Map<MediaKind, Set<String>> mediaExtensions — The extensions accepted for each kind.
• function MediaKind mediaKindOf(String nameOrPath) — The kind of a file name, a path or a reference: the lower-cased text after its last dot.
• function String? mediaExtensionOf(String nameOrPath) — The extension of a name or path, lower-cased and without its dot.
• function Deliverable? uploadPrefixFor(MediaKind kind, EntityType type) — The deliverable prefix an upload takes.
• function TakeName uploadTakeFor({ required Deliverable deliverable, required VersionStem source, required String batchId, required Author uploader, required… — The name an upload is written under (§5.4, §12.3): <purpose>_<source stem>_r<id>_<uploader>_<n>.<ext>.
• function String takeFileName(TakeName take) — The file name of a take: its stem and its extension.
• function List<TakeName?> uploadTakesFor({ required VersionStem source, required String batchId, required Author uploader, required List<String> fileNames, }) — The names one upload action writes, in the order the files were given (§5.4, §12.3).
• function String nextBatchId(DateTime at, {Set<String> taken = const {}}) — The batch id of an import: eight lower-case hex digits of the second the import began (§5.2, §12.3).
• function String? thumbnailPathFor(String reference) — Where the thumbnail of a media reference lives (§6.3).

lib/src/media_paths.dart

• class PathParts — A path split into the part that names its root and the folders under it.
  • const PathParts(this.root, this.segments)
  • final String root
  • final List<String> segments
  • bool get isAbsolute
• function PathParts splitPath(String path, {required bool windows}) — Splits a path on either separator, resolving . and ...

lib/src/media_refs.dart

• variable const String mediaContainerKey — The key of an entity’s media container (§9.0).
• variable const Map<EntityType, Map<String, Set<MediaKind>>> entityMediaPlaces — Each type’s places (§9.0), in the order its media card shows them, with the kinds each takes.
• variable const Map<EntityType, Map<String, String>> entityPlacePrompts — The prompt each place of [entityMediaPlaces] is rendered from, its kind under prompts (§9.0): a type’s reference pictures its reference, its sheets its sheet, a character’s voice samples its voice.
• function String? placePromptKind(EntityType type, String? group) — The kind of the prompt [type]’s place [group] is rendered from ([entityPlacePrompts]), or null where it has none.
• variable const Map<String, String> mediaTokenGroups — The group each media token’s word names (§5).
• function bool isReservedGroup(String name) — Whether [name] is preview or media, which are never a group’s name (§9.0).
• function bool isMediaGroupName(String name) — Whether [name] can name a group: a lowercase snake_case word that is not reserved (§1.4, §9.0).
• function Set<MediaKind> acceptedKindsFor(String group) — The kinds a group takes (§9.0, §10.3): what a place’s file dialog, drop and address accept.
• function bool acceptsFile(Set<MediaKind> kinds, String name) — Whether a place that takes [kinds] takes the file [name] names, as an upload, a drop or an address: a picture, a clip or a sound of one of [kinds].
• enum MediaStage — The stage a render was asked at (§12.2, §9.0): prototype, draft or final, the file’s words.
  • values: prototype, draft, finalCut
  • const MediaStage(this.token)
  • final String token — The word a file writes.
  • static MediaStage? fromToken(Object? value) — The stage [value] names, or null for anything else.
• function MediaStage renderStageOf(Map<String, dynamic>? json) — The stage a version’s renders are asked at (§9.0).
• class MediaEntry — One entry of a group (§9.0): the media it names, the batch item that made it, and what the version decides about it.
  • factory MediaEntry({ required String reference, String? batch, int? item, bool favorite = false, bool archived = false, bool deleted = false, Strin… — A new entry: reference first, then what is given, a cleared flag and a blank note left out.
  • static MediaEntry? fromJson(Object? json) — The entry [json] is, or null where it is not an object with a non-empty string reference.
  • String get reference — A media reference (§6.3): a take’s stem, a file name in media/, or an address.
  • String? get batch — The stem of the batch record that made it, rd_<id>_<author>; null for a file no record describes.
  • int? get item — The n of the item in [batch] that made it.
  • bool get favorite — Favoured by the version: present in the file only as true.
  • bool get archived — Kept but not shown, nor offered to a model, by default (§9.0): present in the file only as true.
  • bool get deleted — Deleted: never shown, and never offered to a model (§9.0).
  • String? get note — The person’s words about it; a blank note reads as none.
  • int? get durationMs — The media’s length in milliseconds, 0 for a still (§9.0); null where unknown.
  • int? get width — The media’s width in pixels; null where unknown.
  • int? get height — The media’s height in pixels; null where unknown.
  • bool? get audio — Whether a clip has sound, as measured once at insertion (§9.0); null where it was not measured, and its sound then plays where the file has one.
  • MediaStage? get stage — The stage its render was asked at; null for an upload.
  • MediaSpans? get spans — The blocks or the extent a block’s media covers (§9.0, §10.3); null where it covers its block alone, a wrong shape included.
  • bool get unreviewed — A render not yet kept or rejected: present in the file only as true.
  • bool get usable — Whether a person may use it (§9.0): kept or still unreviewed; only [deleted] or [archived] is not usable.
  • String? get keptAt — When it was kept: shown with the entry, and the order that decides a group’s latest kept entry.
  • Map<String, Object?> get extra — Every key the core does not read, in the file’s order.
  • MediaEntry withFlags({bool? favorite, bool? archived, bool? deleted, String? note, bool? unreviewed, String? keptAt}) — This entry with a flag, the note or [keptAt] changed, each key keeping its place.
  • Map<String, dynamic> toJson() — The entry as a file writes it, reference first.
• function List<String> mediaGroupsOf(Map<String, dynamic> json) — The container’s group names, in file order (§9.0).
• class MediaPlaces — A document’s first places and the index of each block id, from one walk of it, for [entriesIn] (§9.0, §10.3).
  • MediaPlaces.of(Map<String, dynamic> json) — The places of [json] as it is now.
• function List<MediaEntry> entriesIn(Map<String, dynamic> json, String group, {String? block, MediaPlaces? places}) — The readable entries of [group], in order (§9.0): the entity’s, or with [block] the first block of that id’s.
• function MediaEntry? entryNaming(Map<String, dynamic> json, String reference) — The entry that names [reference] where the document reads it, or null.
• function bool isArchived(Map<String, dynamic> json, String reference) — Whether the document keeps [reference] archived: hidden from a place and from a model by default (§9.0).
• function bool isDeleted(Map<String, dynamic> json, String reference) — Whether the document’s entry for [reference] is deleted (§9.0).
• function List<String> liveReferencesOf(Map<String, dynamic> json) — Every reference the document names in a live entry — read and not deleted — in file order (§9.0).
• function bool arrivedAfter(FilmProject project, MediaEntry entry, DateTime? since) — Whether [entry] arrived after [since] (§13.4): the batch it names was created later.
• function Take? takeNamed(FilmProject project, String reference) — The take [reference] names in [project], by its stem or its file name; null for a file placed by hand, an address, or a take the folder does not hold (§6.3).
• function bool isViewersTake(Take take, Author? viewer) — Whether [take] is [viewer]’s own (§9.0): its renderer is the viewer, or a workspace of theirs (§5.6), as a plug-in’s render under <viewer>.<tag> is.
• function List<String> documentsNamingTake(FilmProject project, Take take) — The stems of the documents of [project] that name [take], by its stem or its file name, in an entry not deleted.
• function MediaInsertionResult withEntriesInserted(Map<String, dynamic> json, String group, Iterable<MediaEntry> entries, {bool first = false, MediaKind Func… — [json] with [entries] put into [group], each whose reference no group of the document holds (§9.0).
• function MediaInsertionResult withEntryAttributes(Map<String, dynamic> json, String group, String reference, {bool? favorite, bool? archived, bool? deleted,… — [json] with the entry of [reference] in [group] — the entity’s, or with [block] that block’s — given a flag, a note or its review (§9.0, §10.3).
• enum VoiceKeepProblem — Why a voice could not be kept in a document (§9.1).
  • values: noSample, wrongShape
• class VoiceKept — A copied document and the outcome of keeping a voice in it ([withVoiceKept]); a problem leaves it as it was.
  • const VoiceKept({required this.json, required this.changed, this.problem}) — An outcome.
  • final Map<String, dynamic> json
  • final bool changed
  • final VoiceKeepProblem? problem
• function VoiceKept withVoiceKept(Map<String, dynamic> json, String reference, { required String voiceId, String? provider, String? auditionText, }) — Keeps the live voice sample [reference] as [voiceId] in a copy of [json] (§9.1).
• function MediaInsertionResult withEntriesReordered(Map<String, dynamic> json, String group, List<String> references, {String? block}) — [json] with the readable entries of [group] — the entity’s, or with [block] that block’s — in the order [references] gives (§9.0).
• function List<ProjectWarning> mediaWarnings(Map<String, dynamic> json) — What the loader reports of a document’s media (§9.0, §18.2): a reference named twice, an entry that cannot be read, a key of media that cannot name a group, and a media that is not an object.
• function List<String> mediaCopyKeys(Map<String, dynamic> left, Map<String, dynamic> right) — What copying the media card from [right] would write into [left] (§13.3): media.<group> for each group that gains an entry or a flag, then preview where the right’s differs, then a character’s `voice.active_refere…
• function void copyMediaInto(Map<String, dynamic> left, Map<String, dynamic> right) — Copies the media card from [right] into [left] (§13.3), as [mediaCopyKeys] names it.

lib/src/media_slot.dart

• enum MediaSlotKind — The two ways a caller may name where media goes.
  • values: group, path
• class MediaSlot — An immutable destination for media.
  • factory MediaSlot.group(String name) — A group of the container (§9.0): a lowercase snake_case word that is not reserved.
  • factory MediaSlot.path(String path) — Dot-separated object keys, without array-index traversal, outside the container.
  • factory MediaSlot.fromJson(Map<String, dynamic> json) — Reads an explicit discriminator; any other slot, refs or voice among them, is refused.
  • final MediaSlotKind kind
  • final String operand — The group’s name, or the path.
  • String? get group — The group’s name; null for a path.
  • Map<String, dynamic> toJson()
• enum MediaSlotProblem — A container, an array or a path on the way has another JSON shape.
  • values: wrongShape
• class MediaInsertionResult — A copied document and the outcome of a change to its media.
  • const MediaInsertionResult({required this.json, required this.changed, this.problem})
  • final Map<String, dynamic> json
  • final bool changed
  • final MediaSlotProblem? problem

lib/src/money.dart

• variable const moneyScale — How many fractional digits a money object’s amount has (§6.7: scale).
• class ExactDecimal — An exact decimal number, [unscaled] ÷ 10^[scale].
  • ExactDecimal(this.unscaled, this.scale) — [unscaled] ÷ 10^[scale], where [scale] is not negative.
  • static final zero — Zero.
  • final BigInt unscaled — The digits, without the decimal point.
  • final int scale — How many of [unscaled]’s digits are fractional.
  • static ExactDecimal? parse(String text) — The exact value of a JSON number’s [text] (RFC 8259 §6), or null for text that is not one.
  • static ExactDecimal? parsePlain(String text, {required int maxFraction}) — A value written with no sign and no exponent, and with at most [maxFraction] fractional digits (2.5), or null.
  • bool get isNegative — Whether this is below zero.
  • ExactDecimal operator +(ExactDecimal other) — The exact sum.
  • ExactDecimal operator *(ExactDecimal other) — The exact product.
  • ExactDecimal roundTo(int digits) — This value to [digits] fractional digits, rounded half away from zero (§6.7).
  • ExactDecimal ceilTo(int digits) — This value to [digits] fractional digits, its magnitude rounded away from zero.
  • bool fits(int digits) — Whether rounding to [digits] fractional digits loses nothing.
  • String toFixed(int digits) — The text with exactly [digits] fractional digits, rounded half away from zero.
• enum MoneyBasis — Where a money object’s amount came from (§6.7).
  • values: provider, price, estimate, charged
• class Money — A money object (§6.7).
  • Money(ExactDecimal amount, this.currency, this.basis) — [amount] rounded half away from zero to twelve fractional digits.
  • factory Money.atPrice(ExactDecimal price, ExactDecimal units, String currency) — The catalogue’s [price] for one unit times [units] (§6.7: basis price).
  • static Money? reported(ExactDecimal cost, String currency) — A cost the platform reported, as a provider cost, or null where §6.7 says the record uses the price instead.
  • final ExactDecimal amount — The amount, to twelve fractional digits.
  • final String currency — The platform’s billing currency: USD for every platform of the first version.
  • final MoneyBasis basis — Where [amount] came from.
  • static Money? fromJson(Object? json) — A money object as a record holds it, or null for one that is not.
  • Map<String, Object> toJson() — The object a record holds (§6.7).

lib/src/natural_compare.dart

• function int naturalCompare(String a, String b) — Numeric-aware string ordering (§10.1 “natural tag order”).

lib/src/plain_text.dart

• function String plainLine(String value, {int max = 120}) — [value] as one plain line: its controls, line breaks and direction marks out, its spaces collapsed, and cut to [max] characters with an ellipsis.

lib/src/platform_file.dart

• enum PlatformProblem — What is wrong with a catalogue file.
  • values: notJson, notObject, missingField, wrongType, unknownValue, badUrl, idMismatch, hostNotListed, unknownPlaceholder, noCredentials, pathNotAllowed
• class PlatformIssue — One problem, with the field or placeholder it concerns.
  • const PlatformIssue(this.problem, [this.field])
  • final PlatformProblem problem
  • final String? field — The dotted field, or the placeholder, the problem names.
• enum CredentialRefusal — Why a request carrying a platform’s credentials may not go where it was pointed (§14.9).
  • values: insecure, host, badPath, path
• enum PlatformKind — §14.9’s kind.
  • values: remote, local, weights
• enum PlatformAuthKind — §14.9’s auth.kind.
  • values: apiKey, oauth, token, none
  • const PlatformAuthKind(this.spelling)
  • final String spelling — The value written in the file (§1.4).
• class PlatformCredential — One field of what a user copies from the platform.
  • const PlatformCredential({required this.id, required this.label, required this.secret, this.prefix})
  • final String id — The field’s name in the stored value and in auth.header’s placeholder.
  • final String label — The platform’s word for it.
  • final bool secret — Whether a box hides what is typed into it.
  • final String? prefix — How the platform’s values start, where it says so.
• class PlatformAuth — How the platform’s credentials are sent and kept.
  • const PlatformAuth({required this.kind, this.header, this.env, this.keychain})
  • final PlatformAuthKind kind
  • final String? header — The header, with placeholders naming credential ids: Authorization: Key <key>.
  • final String? env — The environment variable the vendor’s own SDKs read.
  • final String? keychain — The name the credentials are kept under in the device’s credential store.
• class PlatformVerify — A documented request that checks a key without running a model.
  • const PlatformVerify({required this.method, required this.url, this.rejected = usualRejections})
  • static const usualRejections — The statuses with which a platform refuses a key, where its file names none (§14.9).
  • final String method
  • final Uri url
  • final Set<int> rejected — The HTTP statuses with which this platform refuses a key (rejected, §14.9).
• class PlatformOauth — The platform’s signed-in route, alongside its existing key authentication.
  • const PlatformOauth({required this.authorizationEndpoint, required this.tokenEndpoint, required this.revocationEndpoint, required this.issuer, requ… — Keeps the validated sign-in configuration from the platform file.
  • final Uri authorizationEndpoint — The browser’s authorization address.
  • final Uri tokenEndpoint — The code exchange and refresh address.
  • final Uri revocationEndpoint — The refresh-token revocation address.
  • final String issuer — The issuer required in the returned ID token.
  • final List<String> scopes — The scopes requested by sign-in.
  • final String requiredScope — The scope required before storing a signed-in account.
  • final String clientId — The public client identifier used for authorization.
  • final Map<String, String> params — Additional authorize parameters, with the installation’s bare UUID substituted.
  • final Map<String, String> tokenParams — Extra code-exchange and refresh fields, with the installation UUID substituted.
  • final bool sendsOutputCap — Whether a signed-in completion sends the model’s output cap.
  • final String label — The plan’s name shown beside its route.
  • final String redirectPath — The loopback callback path; absent configuration uses the root path.
  • final String? callbackOrigin — The browser origin allowed to deliver a cross-origin loopback callback, where declared.
• class PlatformFile — One platform file, as §14.9 defines it.
  • final String id
  • final String name
  • final PlatformKind kind
  • final Uri baseUrl
  • final List<String> hosts — Every host a request carrying the credentials may go to, in lower case.
  • final Map<String, List<String>> paths — Where, on a host, such a request may go (§14.9).
  • final PlatformAuth auth
  • final PlatformOauth? oauth — The optional signed-in route, independent of [auth]’s kind.
  • final Map<String, String> headers — Other headers every request needs.
  • final List<PlatformCredential> credentials
  • final PlatformVerify? verify
  • final Uri? signupUrl
  • final Uri? billingUrl
  • final Uri? keysUrl
  • final Uri? pricingUrl
  • final String? guide — The guide’s route below a documentation site: docs/platforms/fal.
  • final Uri? docs
  • bool mayReceiveCredentials(Uri uri, {String? rawPath, bool resolved = false}) — Whether a request carrying the credentials may go to [uri] (§14.9).
  • CredentialRefusal? refuseCredentials(Uri uri, {String? rawPath, bool resolved = false}) — Why a request carrying the credentials may not go to [uri], or null where it may (§14.9).
  • static bool isWildcardHost(String entry) — Whether [entry] of hosts stands for the hosts a provider makes per deployment: *. and a domain of two labels or more, such as *.salad.cloud (§14.9).
  • static bool isPlainPath(String path) — Whether [path] is one this reader will make plain, and match (§14.9).
  • ({String name, String value})? authHeader(Map<String, String> values) — The header auth.header names, each placeholder filled from [values].
  • static PlatformParse parse(String text, {String? listedAs}) — Reads a platform file.
• class PlatformParse — A platform file read, or why it could not be used.
  • final PlatformFile? file — The platform, or null when an issue makes it unusable.
  • final List<PlatformIssue> issues
• class CatalogueListing — A platform as models.json lists it (§14.6).
  • const CatalogueListing({ required this.id, required this.file, required this.name, required this.kind, this.pending = false, this.obstacles = const…
  • final String id
  • final String file — The platform file, relative to models.json.
  • final String name
  • final String kind
  • final bool pending — Marked with a status: an application offers no key and no run on it.
  • final List<String> obstacles — What stands in the way of supporting it.
• class PlatformListings — models.json’s platforms, in the order it lists them, and what could not be read of it.
  • const PlatformListings(this.listings, this.issues)
  • final List<CatalogueListing> listings
  • final List<PlatformIssue> issues
  • static PlatformListings parse(String text) — Reads models.json’s platforms (§14.6).

lib/src/project.dart

• class EntityVersions — Every version, by every author, of one entity at one epoch.
  • EntityVersions({required this.type, required this.tag, this.epoch})
  • final EntityType type
  • final String tag
  • final String? epoch
  • final List<Entity> all — Every version the folder holds here, the discarded included; the loader adds to this list.
  • List<Entity> get versions — The retained versions: every one not discarded (§6.1), read-only.
  • List<Entity> get discarded — The versions set aside with discarded (§7), read-only.
  • String get key
  • void sort() — Authors sorted by handle; versions sorted by number within an author.
  • static int compareVersions(Entity a, Entity b) — The stable order of versions everywhere: by author handle, then number.
  • Set<Author> get authors
  • Set<String> get owners — The owners (first handle segments) with a version here.
  • Entity? highestBy(Author author) — The author’s working copy: their highest version not discarded (§13.1).
  • Entity? highestOfAllBy(Author author) — The author’s highest version of all, the discarded included: what allocation counts from (§13.1).
  • Entity? highestByOwner(String owner) — The highest retained version of any author whose owner is [owner].
• class EntityGroup — One entity: every epoch, every author, every version, sharing a tag.
  • EntityGroup({required this.type, required this.tag})
  • final EntityType type
  • final String tag
  • final Map<String?, EntityVersions> byEpoch — Keyed by epoch; spec entities use the single key null.
  • String get key
  • List<String?> get epochs
  • Iterable<Entity> get allVersions — Every retained version, at every epoch (selection’s set, §6.1).
  • Iterable<Entity> get everyVersion — Every version at every epoch, the discarded included: what an existence check reads.
  • bool get hasRetained — Whether any version is retained: an entity whose every version is discarded is shown nowhere (§7), its files kept on disk.
  • String get name — A display name: the first version’s name, since versions of one entity normally agree.
  • EntityVersions versionsAt(String? epoch)
  • bool get isFromLibrary — Every version came from the shared library (§14.5): nothing of this entity is in the project folder.
• class FilmProject — An opened project: the index of every file the folder holds.
  • FilmProject({ required this.source, this.manifest, this.librarySource, required this.entitiesByStem, required this.groupsByKey, required this.offic…
  • final ProjectSource source
  • final ProjectManifest? manifest — The filmopen-project.json at the root (§4.4), or null when the folder has none.
  • final ProjectSource? librarySource — The shared library of models, platforms and plugins (§14.5) that was indexed alongside the project, if any.
  • final Map<String, Entity> entitiesByStem — Every versioned entity by full stem, e.g. ch_main-hero_30yo_john123_v2.
  • final Map<String, EntityGroup> groupsByKey — Every entity by group key, e.g. ch_main-hero.
  • final Map<String, OfficialPointer> officialsByKey — Official pointers by versions key, e.g. ch_main-hero_30yo.
  • final List<Commentary> commentaries
  • final List<RenderBatch> batches
  • final List<Take> takes
  • late final Map<String, Take> takesByStem — Every take by its stem, the first [takes] lists where two share one (§6.3).
  • final List<SetRecord> sets — The pending sets and their history (§12.7).
  • final List<String> otherFiles — Files the project layout or grammar does not describe.
  • final Set<String> thumbnailPaths — The project’s thumbnails (§4.2).
  • final List<ProjectWarning> warnings
  • final List<Entity> projectCandidates — Every pj version in the folder, in stable order.
  • final Entity? selectedProject — The pj version this view works from (§4.1).
  • final Entity? projectOfRecord — The project file of record (§4.1): the one the official pj pointer names, else the sole author’s.
  • bool get needsProjectChoice — Several project authors and nothing official: the reader asks (§4.1).
  • FilmProject withSelectedProject(Entity project) — The same index working from another project version.
  • SetRecord? pendingOf(EntityType type, Author? viewer) — The [viewer]’s pending record of [type] (§12.7), or null.
  • List<SetRecord> historyOf(EntityType type) — Every record of [type] that is no author’s pending one, newest first (§12.7).
  • String get label
  • String? diskPathOf(Entity entity) — The absolute path of an entity’s file on this machine, for the file browser; null when it is not on disk.
  • String get name
  • bool get canWrite — Whether files can be written where this project lives.
  • bool get isSessionCopy — A writable source with no disk root: a sample overlay or memory project.
  • ProjectKind? get kind — The selected project’s kind (§8.1), or null when it declares none the reader knows.
  • List<EpochDeclaration> get declaredEpochList — The epochs the selected project declares, in their order (§8.2).
  • EpochDeclaration? get soleUnusedEpoch — The sole declared epoch when no indexed file explicitly uses its token (§8.2).
  • String get defaultEpoch — The epoch an implicit reference falls back to (§6.1): the first declared epoch, else the reserved token default.
  • String? epochLabel(String epoch) — The label the project gives an epoch, if any.
  • Map<String, int> get epochUsage — How many files are at each epoch token (§8.2), so a reader can say whether an epoch may be dropped.
  • static Set<String> epochsOf(Entity entity) — The epoch tokens [entity] is at, as [epochUsage] counts them: its filename’s, else its content’s epoch, its location_epoch, and every cast or props entry’s.
  • List<String?> sortedEpochs(Iterable<String?> epochs) — [epochs] in the project’s declared order.
  • bool isDirector(Author? author) — Whether [author] is one of the project’s directors (§8.3).
  • List<String> get directorHandles — The owners contributors gives role: "director", in the file’s order.
  • Commentary? commentaryBy(EntityGroup group, Author author) — The commentary file [author] keeps about [group], if any (§13.4).
  • String? pickedStem(EntityVersions versions, Author? viewer) — The stem [viewer] picks at [versions]’ epoch (§13.4 pick).
  • String? ownPickStem(EntityVersions versions, Author author) — The pick [author]’s own commentary file records at [versions]’ epoch.
  • static String trackingStem(EntityVersions versions) — The pick value that means “the official version, whichever it is” (§13.4).
  • Pick? pickAt(EntityVersions versions, Author? viewer) — The version in use for the viewer among [versions] — the pick (§6.1 step 2).
  • Pick? officialPickAt(EntityVersions versions) — §6.1 step 2 for a file an official pointer names: official, else the sole owner’s highest (step 3), and nothing else.
  • Pick? inUseFor(EntityVersions versions, Author? viewer, {Entity? referencing}) — The version a reference held by [referencing] lands on: the viewer’s world ([pickAt]).
  • Pick? pickBeside(Entity entity, Author? viewer) — The pick at [entity]’s epoch, for the header.
  • bool isPickOf(Entity entity, Author? viewer) — Whether [entity] carries the check for [viewer]: it is the version in use and something the author said put it there.
  • bool hasNoPick(EntityVersions versions, Author? viewer) — Nothing is in use here and the reader cannot choose: several owners, nothing official, no pick.
  • String nameOf(EntityGroup group, Author? viewer, {Entity? referencing}) — An entity’s name as the version in use says it.
  • FilmProject forViewer(Author? viewer) — The same index with the project version the viewer’s pick names.
  • EntityGroup? group(EntityType type, String tag)
  • List<EntityGroup> groupsOf(EntityType type) — Groups of one type in natural tag order.
  • List<EntityGroup> retainedGroupsOf(EntityType type) — The groups of [type] with a retained version, in [groupsOf]’s order: what the tree, a list or a chooser offers.
  • List<EntityGroup> childGroups(EntityType type, String parentTag) — Direct children of a dotted tag among groups of [type].
  • OfficialPointer? officialPointer(EntityType type, String tag, String? epoch)
  • Entity? officialEntity(EntityType type, String tag, String? epoch) — The entity an official pointer names, if it exists and is not discarded.
  • bool isOfficial(Entity entity) — Exact inspection of the pointer: whether it names [entity], discarded or not.
  • Resolution resolve(EntityType type, String reference, { String? epoch, bool epochIsExplicit = false, Author? viewer, Entity? referencing, }) — Resolves a short reference (a tag) or a full reference (a stem) to one entity file, following §6.1.
  • List<Take> takesFor(EntityGroup group) — Every take rendered for any version of the entity [group] (§12.1).
  • List<Commentary> commentaryFor(EntityGroup group) — Every commentary file about [group], from every author.
  • RenderBatch? batch(String stem)
  • Map<EntityType, int> groupCounts({EntityOrigin origin = EntityOrigin.project}) — Counts per type, for the overview, leaving out a group wholly discarded.
• enum PickReason — Why a version is the one in use (§6.1 step 2), for tooltips.
  • values: picked, tracksOfficial, official, own, soleOwner
• class Pick — The version in use at one epoch, and why.
  • const Pick(this.entity, this.reason, {this.staleSince})
  • final Entity entity
  • final PickReason reason
  • final OfficialPointer? staleSince — Set when the project made another version official after the viewer picked this one (§13.2).
  • bool get isStale
  • bool get showsCheck — Whether an application marks this version with a check.
• class Resolution — The outcome of resolving one reference.
  • const Resolution({required this.reference, this.entity, this.fellBack = false, this.problem})
  • final String reference
  • final Entity? entity
  • final bool fellBack — The implicit epoch had no file and default was used instead.
  • final ResolutionProblem? problem — Why the reference is unresolved; null when clean.
  • bool get isResolved

lib/src/project_key.dart

• function String projectKeyOf(FilmProject project) — The key of the film [project] is a version of.
• function String projectSourceKey(ProjectSource source) — The key of the film [source] holds.
• function String canonicalRootPath(String path) — [path] as one spelling of itself, so that two spellings of one folder are one key.
• function bool isDurableProjectKey(String key) — Whether [key] — one of [projectSourceKey]’s — still names the same film next run.
• function String folderNameOf(String path) — The folder’s own name in [path]: the last segment, either separator ending one.

lib/src/project_kind.dart

• enum ProjectKind — What the film is, as a word for people, for the OMC mapping and for a website (§8.1).
  • values: shortFilm, film, miniSeries, series
  • const ProjectKind(this.name)
  • final String name — The value written in the file.
  • static ProjectKind? fromName(String? name) — The kind a file declares.
• variable const List<String> recommendedGenres — The genres a project is offered (Appendix A.9).

lib/src/project_source.dart

• class ProjectSource — A folder on disk, the bundled sample, or an in-memory map for tests.
  • String get label — A short name for the title bar: the folder name, or “Sample”.
  • String? get rootPath — The absolute folder path, when the source is a folder on disk.
  • Future<List<String>> listPaths() — Every file under the root, recursively, as root-relative paths.
  • Future<String> readText(String relativePath) — The UTF-8 text of one file.
  • MediaLocation? locate(String relativePath) — Where a media file can be loaded from, or null when this source cannot show media.
  • String? diskPath(String relativePath) — The absolute path of one file on this machine’s disk, for showing it in the file browser.
  • bool get canWrite — Whether [writeText] and [deleteFile] work here.
  • Future<void> writeText(String relativePath, String text, {String? expectedText, bool create = false}) — Writes [text] as UTF-8 to a root-relative path, creating or replacing the file.
  • Future<void> deleteFile(String relativePath, {String? expectedText}) — Removes one file, checking [expectedText] the same way.
  • Future<Uint8List> readBytes(String relativePath) — The bytes of one file: a picture, a clip, a thumbnail.
  • Future<int?> fileLength(String relativePath) — The size of one file in bytes, or null when there is no such file.
  • Future<void> writeBytes(String relativePath, Stream<List<int>> bytes, {int? length, bool create = false}) — Writes [bytes] to a root-relative path, streaming rather than held in memory.
• class StaleFileException — The file changed on disk since it was read (or already exists where a new file was to be created).
  • const StaleFileException(this.path)
  • final String path
• class MediaLocation — How the UI reaches a media file.
  • const MediaLocation()
• class AssetMedia — A Flutter asset key, e.g. assets/sample/the-cartographer/media/x.png.
  • const AssetMedia(this.key)
  • final String key
• class FileMedia — An absolute path on the local disk.
  • const FileMedia(this.path)
  • final String path
• class BytesMedia — Bytes held in memory: a session copy of the sample, a project the web preview made, a fixture.
  • const BytesMedia(this.bytes)
  • final Uint8List bytes
• class MemoryProjectSource — A project held in memory: path → text.
  • MemoryProjectSource(this.files, { this.label = 'In memory', Map<String, Uint8List>? binaries, })
  • final Map<String, String> files
  • final Map<String, Uint8List> binaries — The files that are not text: pictures, clips, thumbnails (§4.2).
• class OverlayProjectSource — A source that reads through [base] and keeps every write in memory.
  • OverlayProjectSource(this.base, {String? label})
  • final ProjectSource base
  • final MemoryProjectSource written — What has been written here since the session began.
  • final Set<String> removed — What has been deleted here: a path that is in [base] but gone.

lib/src/prompt_context.dart

• class PromptContextReference — A prompt context’s requested reference, its resolution and the values its caller logs.
  • const PromptContextReference(this.entity, this.data) — Records the resolved [entity], or none, with the request and outcome in [data].
  • final Entity? entity — The version to hand to the writer and use for picture candidates, absent where unresolved.
  • final Map<String, Object?> data — The request and outcome, or the diagnostic for an unassigned outfit’s absent wearer.
• function List<PromptContextReference> promptContext(FilmProject project, Entity source, {Iterable<String> blockIds = const [], Author? viewer}) — Resolves a scene’s block context, a character’s default outfit or an outfit’s wearer.

lib/src/prompts.dart

• variable const promptsKey — The key of a holder’s prompts, keyed by kind (§9.0).
• variable const promptCreatedKey — The key of the instant a prompt was written (§9.0): the writer stamps it.
• variable const promptPluginKey — The key of the tag of the plug-in that wrote a prompt (§9.0), absent when a person wrote it.
• variable const promptWriterKey — The key of the id of the plug-in’s writer that wrote a prompt (§9.0), saved beside [promptPluginKey]: the pair names the writer; absent when a person wrote it.
• function bool isPromptStampPath(String path) — Whether the dotted [path] names a prompt’s created, plugin or writer (prompts.<kind>.created, at any depth): what the writer stamps and who wrote it, no person’s words (§9.0).
• class PromptPath — Where one prompt object of a document stands: its dotted [path] — within the document, or within the block whose id is [block] — and its [kind].
  • const PromptPath(this.path, this.kind, {this.block})
  • final String path — The dotted path of the prompt object, from the document’s top or, for a block’s, from the block’s.
  • final String kind — The kind the prompt is keyed by: reference, sheet, voice, first_frame, last_frame, treatment, or one this app does not know, listed as it is.
  • final String? block — The id of the block that holds it, or null for one of the document’s own.
• function List<PromptPath> promptPaths(Map<dynamic, dynamic> document) — The prompt objects [document] holds (§9.0): prompts.<kind> at its top, visual_style.prompts.<kind>, and each block’s prompts.<kind> by the block’s id — every object under a prompts object, of a kind known or n…
• function Map<String, Map<dynamic, dynamic>> blocksById(Map<dynamic, dynamic> document) — The blocks of [document] by id, the first block of each id: where [promptAt] finds a block’s prompt.
• function Map<String, dynamic>? promptAt(Map<dynamic, dynamic> document, PromptPath at, {Map<String, Map<dynamic, dynamic>>? blocks}) — The prompt object at [at] in [document], or null where it holds none there; a block’s is looked up in [blocks], [document]’s [blocksById], where the caller has it.
• function Map<String, dynamic> documentApartFromPromptTimes(Map<String, dynamic> document) — [document] with every prompt’s created (§9.0) set aside, for a comparison: what was stamped is not content.
• enum PromptState — What a prompt is against its holder (§9.0).
  • values: empty, current, outdated
• function PromptState promptStateOf(Map<dynamic, dynamic>? prompt, String? holderUpdated) — What [prompt] is against [holderUpdated], its holder’s updated — the file’s for a prompt at the top or of the treatment, the block’s for a block’s (§9.0): [PromptState.empty] when positive is blank or absent; [Pro…

lib/src/recycle_bin.dart

• function bool isGroupDeleted(FilmProject project, EntityGroup group, Author? viewer) — Whether [group] is in the recycle bin for [viewer] everywhere: at every epoch it has, the version in use is deleted.

lib/src/reference_analysis.dart

• variable const pictureLeaves — The leaves a description of a picture writes: texts, but appearance.marks, a list of texts.
• variable const recordingLeaves — The leaves a description of a recording writes: how the voice sounds, never the voice speech uses (voice.provider_bindings) or the sample in use (voice.active_reference), which a description does not name.
• variable const analysisTextMost — The most characters one text a description writes may hold; a longer one refuses the description.
• class AnalysisChanges — What a description would write: its leaves by dotted path and the clothing it saw, or why none is taken.
  • const AnalysisChanges(this.leaves, {this.clothing, this.refused}) — A description’s changes; [refused] names what no leaf may take, and then nothing is written.
  • final Map<String, Object> leaves — The leaves it writes, each a text or, for appearance.marks, a list of texts.
  • final String? clothing — The clothing a picture showed, as prose, which joins the character’s appearance notes.
  • final String? refused — The path of what the description said that no leaf may take — a value of another type, a text too long or holding a control character, a word of no vocabulary — where it said one.
  • bool get isEmpty — Whether it tells nothing a character could take.
• function AnalysisChanges analysisChanges(String kind, Map<String, Object?> fields) — What a description of [kind] (image, audio) answered as [fields], in the document’s spelling, as the leaves it writes (the plug-in interface’s CharacterPicture and VoiceHeard).
• function String? unexpectedLeaf(Map<String, Object?> fields, Set<String> leaves, [String prefix = '']) — The first path of [fields], in its order, that is none of [leaves] nor an object on the way to one: what a projection’s answer names beside what it takes (§18.3).
• function ({Map<String, dynamic> json, bool changed, List<String> paths, String? refused}) withAnalysisApplied(Map<String, dynamic> json, AnalysisChanges cha… — A copied document with [changes] written, the leaves whose value that changed ([paths], the notes once) and whether anything did; or, where one of them cannot be written without taking away what the document holds — a…
• function List<MediaEntry> uploadsIn(FilmProject project, Map<String, dynamic> json, String group, MediaKind kind) — The live entries of [group] a person uploaded that are [kind] media, the most recent first (§12.3): each named by an import’s record, newest created first — of two in one second, the later record’s, whose id counts…

lib/src/reference_codec.dart

• enum ReferenceKind — The five kinds of canonical prose references, independent of filename types.
  • values: character, location, epoch, prop, media
  • String get prefix — The canonical two-letter prefix of this reference kind; a media token’s is only its identifiers’, never written.
• class ReferenceTarget — The kind and exact id a prose reference names, without resolving a version.
  • const ReferenceTarget(this.kind, this.id) — Creates a target whose id is checked when canonical source is encoded.
  • final ReferenceKind kind — The reference’s kind, separate from the filename entity enum.
  • final String id — The exact tag or epoch token, never normalized or replaced.
• class ReferenceToken — A parsed mention with its original UTF-16 source range and optional knowledge annotation.
  • final ReferenceTarget target — The exact kind and id parsed from source, including an unknown target.
  • final int start — The inclusive UTF-16 offset of the mention’s at sign.
  • final int end — The exclusive UTF-16 offset after the longest valid id prefix.
  • final bool? isKnown — Whether the supplied knowledge check recognizes the target, or null when unassessed.
• class ReferenceCodec — The pure codec for canonical mentions and shorthand, retaining their source ranges.
  • static List<ReferenceToken> parse(String text, { bool Function(ReferenceTarget target)? isKnown, }) — Parses mentions in source order, annotating unknown targets without replacing them.
  • static String encode(ReferenceTarget target) — Encodes a valid target exactly as canonical source, refusing an invalid id.

lib/src/render_treatment.dart

• class RenderTreatment — The visual treatment a render was made with, frozen: the leaves that applied and each one’s document.
  • RenderTreatment({required Map<String, Object?> visualStyle, Map<String, String> sources = const {}}) — A treatment; [visualStyle], never empty, and [sources], each a document’s stem, are copied and frozen.
  • final Map<String, Object?> visualStyle — The leaves that applied, as A.11 names them.
  • final Map<String, String> sources — The document each leaf came from, by the leaf’s dotted path: look.grain → fo_coast_maria_v2.
  • static bool isDocumentStem(String stem) — Whether [stem] names a document, as a source must.
  • Map<String, Object?> toJson() — The treatment as a request and a batch item hold it.
  • static RenderTreatment? fromJson(Object? json) — A treatment as [toJson] wrote it, or null for anything else: no visual_style object or an empty one, or a source that is not a document’s stem.

lib/src/scene_card.dart

• class SceneCard — What a production’s board says about one scene, read from the scene’s own file (§10.2).
  • const SceneCard({ required this.heading, required this.number, required this.interior, required this.exterior, required this.time, required this.sy… — A card of the facts given; [SceneCard.of] reads them from a scene’s file.
  • final String heading — The slug line as the screenplay writes it, such as `INT.
  • final String number — The production’s scene number, where the screenplay numbered its scenes.
  • final bool interior — Whether the slug line says the scene plays inside: INT, or both.
  • final bool exterior — Whether the slug line says the scene plays outside: EXT, or both.
  • final String time — The time of day the file gives in its time, as written: DAY, NIGHT, CONTINUOUS; empty where it gives none, which nothing reads from the slug line in its place.
  • final String synopsis — The first words of the scene: its synopsis where it has one, else its first action.
  • final List<String> cast — The scene’s cast, by tag, in the order the file lists them.
  • final int elements — How many props and other production resources the scene names.
  • final String eighths — The page eighths a production schedules by, where the source gave them: 5/8.
  • double get pages — How many pages the scene runs to, as a number, from the eighths the source gave.
  • bool get isNight — Whether the time of day reads as night, by the words a slug line uses for it.
  • static SceneCard of(Entity scene) — Reads the board’s facts from a scene’s file.

lib/src/scene_cast.dart

• variable const castKey — The key a scene lists its characters under.
• variable const castCharacterKey — The key of a cast entry that names the character, by short name.
• function List<Map<String, dynamic>>? castOf(Map<String, dynamic> json) — The entries of [json]’s cast, each a copy all the way down.
• function List<String> castCharacters(List<Map<String, dynamic>> cast) — The short names [cast] lists, in its order.
• function void writeCast(Map<String, dynamic> json, List<Map<String, dynamic>> cast) — Writes [cast] into [json]: the list, or no key at all where it is empty, which is how the app removes a key.
• function List<Map<String, dynamic>> castWithCharacters(List<Map<String, dynamic>> cast, Iterable<String> characters) — [cast] as the short names [characters] say it, in their order — what an agent types, one per line.
• function List<Map<String, dynamic>> castWithAdded(List<Map<String, dynamic>> cast, String character) — [cast] with [character] added at the end, as the name alone; unchanged where an entry names it already.
• function List<Map<String, dynamic>> castWithoutAt(List<Map<String, dynamic>> cast, int index) — [cast] without the entry at [index]; unchanged where there is none.
• function List<Map<String, dynamic>> castWithEpochAt(List<Map<String, dynamic>> cast, int index, String? epoch) — [cast] with the entry at [index] at [epoch] — the character’s own, where it differs from the scene’s (§10.2), or without the key where [epoch] is null or empty, which means as the scene.
• function List<Map<String, dynamic>> castWithOutfitAt(List<Map<String, dynamic>> cast, int index, String? outfit) — [cast] with the entry at [index] wearing [outfit], an outfit’s short name (§10.2), or without the key where [outfit] is null or empty, which means the character’s default_outfit.

lib/src/script_block.dart

• variable const nextBlockKey — The scene’s key for the number the next new block takes (§10.3).
• variable const beatPositions — The places a beat takes against its block’s dialogue (§10.3); a block without dialogue gives its beats none.
• class Beat — One beat of a block (§10.3): an instruction that guides the block’s video prompt, in the order the block lists it.
  • const Beat({this.position, this.description, this.duration, this.extra = const {}}) — A beat holding the values given.
  • final String? position — One of [beatPositions], or null where the block has no dialogue; another string is kept as written.
  • final String? description — What happens, such as looks down at his folded hands.
  • final num? duration — The seconds the beat takes, duration_sec, above zero; null where none is given.
  • final Map<String, dynamic> extra — Every other key, as the file had it, in its order.
  • static Beat? fromJson(Object? value) — The beat [value] holds, or null where it is not one.
  • Map<String, dynamic> toJson() — The beat as a file holds it: position, description, duration_sec, then [extra].
  • Beat copyWith({Object? position = _keep, Object? description = _keep, Object? duration = _keep}) — This beat with the values given changed; a value passed as null removes it.
• class Subtitle — One subtitle of a block (§10.3): a line of text burnt over the picture, in the order the block lists it.
  • const Subtitle({this.position, this.text, this.duration, this.extra = const {}}) — A subtitle holding the values given.
  • final String? position — One of [beatPositions], or null where the block has no dialogue; another string is kept as written.
  • final String? text — The words shown, as the person typed them; a newline is a line break.
  • final num? duration — The seconds the subtitle is shown, duration_sec, above zero; null where none is given.
  • final Map<String, dynamic> extra — Every other key, as the file had it, in its order.
  • static Subtitle? fromJson(Object? value) — The subtitle [value] holds, or null where it is not one.
  • Map<String, dynamic> toJson() — The subtitle as a file holds it: position, text, duration_sec, then [extra].
  • Subtitle copyWith({Object? position = _keep, Object? text = _keep, Object? duration = _keep}) — This subtitle with the values given changed; a value passed as null removes it.
• class ScriptBlock — One block of a scene’s script (§10.3).
  • const ScriptBlock({ this.id, this.character, this.dialogue, this.direction, this.action, this.duration, this.outputDuration, this.beats, this.subti… — A block holding the values given; an empty block where none are.
  • final String? id — bl_<n>, or null for a block the file gives none (§10.3).
  • final String? character — The one speaker: a character’s short name, or null where nobody speaks.
  • final String? dialogue — What the speaker says.
  • final String? direction — The note for the actor: the screenplay’s parenthetical, with Fountain’s extensions at its head.
  • final String? action — What happens.
  • final num? duration — The seconds the writer asks for, duration_sec; null is auto.
  • final num? outputDuration — The seconds the scene’s output gives the block, output_duration_sec, set by a person or the assistant; null where the timeline’s rule decides (§10.3).
  • final List<Beat>? beats — The block’s beats in their order, beats; null where the key is absent.
  • final List<Subtitle>? subtitles — The block’s subtitles in their order, subtitles; null where the key is absent.
  • final String? lang — The block’s language, a BCP 47 tag, where it differs from the project’s.
  • final String? updated — When the block’s text last changed (§10.3), as the writer stamps it; null for a block unchanged since it was written.
  • final Map<String, dynamic> extra — Every other key, as the file had it, in its order.
  • static ScriptBlock? fromJson(Object? value) — The block [value] holds, or null where it is not one.
  • Map<String, dynamic> toJson() — The block as a file holds it: id first, then the keys it holds, then [extra].
  • ScriptBlock copyWith({ Object? id = _keep, Object? character = _keep, Object? dialogue = _keep, Object? direction = _keep, Object? action = _keep,… — This block with the values given changed; a value passed as null removes it.
  • bool get isEmpty — Whether the block holds none of the three texts — dialogue, direction, action.
• variable const blockTextKeys — The keys of a block whose change moves its updated (§10.3): its text, its beats, its subtitles and its prompts, and not its media or output_duration_sec.
• function Map<String, dynamic> documentApartFrom(Map<String, dynamic> document, { Set<String> keys = const {}, Set<String> blockKeys = const {}, }) — [document] without the [keys] at its top and the [blockKeys] of every block of its script (§7, §10.3), for a comparison; nothing of it is kept.
• function bool sameDocumentApartFrom(Map<String, dynamic> a, Map<String, dynamic> b, { Set<String> keys = const {}, Set<String> blockKeys = const {}, }) — Whether documents [a] and [b] say the same once the [keys] at their top and the [blockKeys] of every block of their script are set aside (§7, §10.3).
• function Map<String, dynamic> documentApartFromTimes(Map<String, dynamic> document) — [document] without the times the writer stamps — the file’s updated, each block’s and each prompt’s created (§9.0) — for a comparison.
• function bool sameApartFromTimes(Map<String, dynamic> a, Map<String, dynamic> b) — Whether [a] and [b] say the same apart from the times the writer stamps: the file’s updated, each block’s and each prompt’s created.
• function int? blockNumber(String? id) — The number in a bl_<n> id, or null for any other id.
• function String blockLogName(String? id, int index) — The name a usage record and a warning give the block at [index]: its id where that is bl_<n>, else #<place> from 1 (§10.3).
• function int nextBlockNumber(Map<String, dynamic> json) — The number the next new block of [json] takes (§10.3).
• function String nextBlockId(Map<String, dynamic> json) — The id the next new block of [json] takes: bl_<nextBlockNumber>.
• function void withNextBlockRaised(Map<String, dynamic> json, int number) — Raises [json]’s next_block past [number], so that [number] is never given out again in this file.
• enum ScriptEditProblem — Why a change to a scene’s blocks was not made; the document is then as it was.
  • values: wrongShape, noEntry, notABlock
• class BlockEdit — What a change to a scene’s blocks did: the id it gave a block, or the problem that stopped it.
  • const BlockEdit.done({this.id, this.changed = true}) — A change made; [id] is the id a block took where the change gave one.
  • const BlockEdit.refused(ScriptEditProblem this.problem) — A change refused; nothing was written.
  • final String? id — The id the change gave a block: the new block’s, or an id-less block’s first.
  • final bool changed — Whether the document changed; false where the change asked for what was there.
  • final ScriptEditProblem? problem — Why nothing was done, or null.
  • bool get done — Whether the change was made, or asked for what was there: no [problem].
• function BlockEdit withBlockAdded(Map<String, dynamic> json, {Map<String, dynamic>? block, int? at}) — Puts [block], or an empty block, into [json]’s blocks at [at] under the next number (§10.3).
• function BlockEdit withBlockRemoved(Map<String, dynamic> json, int at) — Removes the entry at [at] from [json]’s blocks and keeps the next number where it was (§10.3).
• function BlockEdit withBlockNumbered(Map<String, dynamic> json, int at) — Gives the block at [at] in [json]’s blocks its number where it has none, as its first change would (§10.3).
• function BlockEdit withBlockChanged(Map<String, dynamic> json, int at, ScriptBlock Function(ScriptBlock block) apply) — Writes [apply]’s answer over the block at [at] in [json]’s blocks, without retired keys.
• function BlockEdit withBlockPrompt(Map<String, dynamic> json, String blockId, String kind, Map<String, dynamic>? prompt) — Sets the prompt of [kind] of the block whose id is [blockId] in [json] to [prompt] — removing it, and a prompts it leaves empty, for null — and nothing else (§10.3): the block’s other keys stay as they were.
• function BlockEdit withBlocksReordered(Map<String, dynamic> json, int from, int to) — Moves the entry at [from] of [json]’s blocks so that it ends at position [to]; every id stays.
• function BlockEdit withBeatAdded(Map<String, dynamic> json, int at, {String? position}) — Appends a beat to the block at [at] in [json]’s blocks (§10.3).
• function BlockEdit withBeatChanged(Map<String, dynamic> json, int at, int k, Beat Function(Beat beat) apply) — Writes [apply]’s answer over beat [k] of the block at [at] in [json]’s blocks; noEntry where there is no beat [k].
• function BlockEdit withBeatRemoved(Map<String, dynamic> json, int at, int k) — Removes beat [k] of the block at [at] in [json]’s blocks, and beats with its last; noEntry where there is none.
• function BlockEdit withBeatsReordered(Map<String, dynamic> json, int at, int from, int to) — Moves beat [from] of the block at [at] in [json]’s blocks so that it ends at [to]; noEntry where either is not there.
• function BlockEdit withSubtitleAdded(Map<String, dynamic> json, int at, {String? position}) — Appends a subtitle to the block at [at] in [json]’s blocks (§10.3).
• function BlockEdit withSubtitleChanged(Map<String, dynamic> json, int at, int k, Subtitle Function(Subtitle subtitle) apply) — Writes [apply]’s answer over subtitle [k] of the block at [at] in [json]’s blocks.
• function BlockEdit withSubtitleRemoved(Map<String, dynamic> json, int at, int k) — Removes subtitle [k] of the block at [at] in [json]’s blocks.
• function BlockEdit withSubtitlesReordered(Map<String, dynamic> json, int at, int from, int to) — Moves subtitle [from] of the block at [at] in [json]’s blocks so that it ends at [to].
• function num? beatsTotal(ScriptBlock block) — The sum of [block]’s beats’ seconds, or null where no beat gives any.
• function ({int count, num? total}) beatsSummaryOf(Object? entry) — How many beats the block [entry] holds and their seconds ([beatsTotal]); none for an entry that is not a block.
• function num? subtitlesTotal(ScriptBlock block) — The sum of [block]’s subtitles’ seconds, or null where no subtitle gives any.
• function ({int count, num? total}) subtitlesSummaryOf(Object? entry) — How many subtitles the block [entry] holds and their seconds ([subtitlesTotal]), none for a non-block entry.
• function Set<String> blockIdsUsedTwice(Map<String, dynamic> json) — The ids more than one entry of [json]’s blocks gives (§13.3).
• function List<String> blockIdsOf(Map<String, dynamic> json) — The id each of [json]’s blocks gives, in file order; a block without a string id gives none.
• function List<String> coverageFrom(List<String> ids, String owning, String through) — The consecutive ids from [owning] through [through] in [ids], a block media’s coverage (§10.3); empty where either is missing or [through] stands before [owning].
• function bool coverageIntact(List<String> ids, List<String> blocks) — Whether the ids in [ids] from [blocks]’ first to its last are exactly [blocks] (§10.3).
• function Set<String> speakersIn(Map<String, dynamic> json) — The characters a scene names, each once: those its cast lists, then its blocks’ speakers.
• function Entity? speakerOf(FilmProject project, Entity scene, Map<String, dynamic> json, String tag, {Author? viewer}) — The character a scene’s speaker [tag] is, as the scene’s own reference to it (§6.1, §10.2); null where it resolves to none.
• function String speakerName(FilmProject project, Entity scene, Map<String, dynamic> json, String tag, {Author? viewer}) — The name a scene’s speaker [tag] is shown by: the name of the character [speakerOf] finds; else the name the character goes by for [viewer]; else [tag] as written.
• enum BlockSummaryPart — Which text a block’s condensed line shows.
  • values: dialogue, action, direction, empty
• typedef typedef BlockSummary — A block’s condensed line: the speaker and the dialogue, else the action, else the direction, else nothing; the speaker shown with the dialogue, the direction or nothing, never beside an action.
• function BlockSummary blockSummary(ScriptBlock block) — The parts of [block]’s condensed line (§10.3): the speaker beside the dialogue, the direction or an empty block.
• typedef typedef DirectionParts — A direction’s two parts: Fountain’s extensions at its head, and the note that follows them.
• function DirectionParts splitDirection(String? direction) — A block’s direction split into Fountain’s extensions at its head and the note that follows them.
• function String blockLineOf(Object? entry) — One block as one line of text, as a comparison’s row shows it.

lib/src/script_diff.dart

• enum DiffKind — What a row of [scriptDiff] says of its block.
  • values: same, replace, added, removed, movedOut, movedIn
• class DiffRow — One row of the block diff, with the block’s row id on each side that has a cell in it.
  • const DiffRow(this.kind, {this.leftId, this.rightId}) — A row of [kind] with a cell on each side that has a row id.
  • final DiffKind kind — What the row says of its block.
  • final String? leftId — The left’s row id, null where the left’s cell is blank.
  • final String? rightId — The right’s row id, null where the right’s cell is blank.
  • String get display — The row id the row is shown under.
• function List<DiffRow> scriptDiff(Map<String, dynamic> left, Map<String, dynamic> right) — The rows of [left]’s and [right]’s blocks, by the longest common subsequence of their row ids.
• function List<String> blockRowIds(Map<String, dynamic> json) — The row id of each entry of [json]’s blocks, in order: the one rule a comparison and View name block rows by.

lib/src/script_outline.dart

• class ScriptRow — One row of the script: an entry of a children list, as written.
  • const ScriptRow({ required this.entry, required this.listedIn, required this.index, required this.occurrence, required this.depth, this.siblings =…
  • final ChildEntry entry — The entry as written, with the problem the walk found in it.
  • final Entity? listedIn — The file whose children holds the entry — the project file, or the version of a folder that is drawn.
  • final int index — The entry’s place in that list, and which of the equal entries it is (0 is the first): what the list’s edits take.
  • final int occurrence
  • final int siblings — How many rows that list draws: its entries without the dropped ones, for Move down’s end. 0 for a row no list holds.
  • final int depth — How deep the row sits: 0 for an entry of the project file.
  • final EntityGroup? group — The folder or scene the entry names, when the project has one.
  • final Resolution? resolution — What looking the entry up gave; null for an entry that names neither a folder nor a scene.
  • final bool isCycle — The folder lists itself through some path (§8.5).
  • final List<ScriptRow> children — What a folder holds, in its order.
  • final Entity? contents — The version whose children [children] are: the viewer’s working version of an unpinned folder where the reader gives one ([scriptOutline]’s workingOf), else the version drawn.
  • Entity? get entity — The version drawn: the one in use for the viewer, or the one pinned.
  • bool get hasProblem — Whether a reader flags the row.
  • bool get isDeleted — Whether the version drawn is in the recycle bin (§7): the row keeps its place for browsing, and what consumes the script skips it, what a deleted folder holds taking its place.
  • bool get isFolder
  • Iterable<ScriptRow> get withDescendants — This row and every row beneath it, depth-first, as they are drawn.
• class ScriptOutline — The script, and what is not in it.
  • const ScriptOutline({required this.root, required this.script, required this.unfiled, this.dropped = const []})
  • final Entity? root — The project file whose children is the top of the script — the viewer’s working version where the reader gives one ([scriptOutline]’s workingOf), else the one in use; null while the reader has not chosen one (§4.1).
  • final List<ScriptRow> script — The project file’s entries, in its order.
  • final List<ScriptRow> unfiled — Every folder and scene of the project that no children list of the versions drawn names (§8.5: not in the script).
  • Iterable<ScriptRow> get scriptRows — Every row of the script, depth-first, as drawn.
  • Iterable<ScriptRow> get unfiledRows — Every row under not in the script, depth-first, as drawn.
• function bool folderIsOrHolds(FilmProject project, ChildEntry moved, String destination, {Author? viewer}) — Whether the folder [moved] names is, or holds at any depth, [destination].
• function ScriptOutline scriptOutline(FilmProject project, {Author? viewer, Entity? Function(EntityVersions versions)? workingOf}) — Walks the script of [project] as [viewer] sees it.
• function List<ScriptRow> childRowsOf(FilmProject project, Entity parent, {Author? viewer}) — The rows of one file’s children, as that one list gives them.
• function List<ScriptRow> folderOutline(FilmProject project, Entity folder, {Author? viewer}) — Every row beneath the folder version [folder], followed into its subfolders: that version’s own script.
• function List<EntityGroup> cueGroupsOf(FilmProject project, EntityType type, String tag, {Author? viewer}) — The cues that belong to the folder or scene [type] and [tag] (§11.2), in natural order of their short names.
• function Map<String, List<EntityGroup>> cueGroupsByOwner(FilmProject project, {Author? viewer}) — Every cue by the group key of the folder or scene it belongs to (§11.2), each owner’s in natural order.

lib/src/server_address.dart

• class ServerAddress — The address of a server a user runs or chooses, as a server setting holds it.
  • static ServerAddress? parse(String text) — [text] as an address, or null for anything that is not one.
  • String get text — The normalised text, which is what is stored and what ctx.settings hands the plugin.
  • String get origin — The scheme, the host and the port, for a comparison.
  • String get scheme
  • String get host
  • int get port — The port the address names, or the scheme’s own where it names none.
  • bool get isThisComputer — This computer: 127.0.0.0/8, ::1, localhost and any name under it, with or without a rooting dot.
  • bool get isPrivate — This computer, or an address that cannot leave the user’s own network.
  • Uri? resolve(String path) — [path] joined to the base path, the query kept.
  • bool sameAddress(Uri other) — Whether [other] is still the address the person typed.
  • bool sameOrigin(Uri other) — Whether [other] has the same scheme, host and port: what a redirect may stay within, before [sameAddress] asks about the base path too.

lib/src/set_record.dart

• class SetRecord — One pending set’s record: a comp, an assistant session or a render queue (§12.7).
  • const SetRecord({required this.stem, required this.path, required this.json, required this.items, this.rawText}) — A record of its parts, as [SetRecord.fromJson] makes it.
  • factory SetRecord.fromJson(BatchStem stem, String path, Map<String, dynamic> json, {String? rawText}) — The record a file holds; [items] keeps every object of items and drops anything else in the list.
  • final BatchStem stem — The record’s stem, whose type is the record’s.
  • final String path — The file’s path in the project.
  • final Map<String, dynamic> json — The whole document as read, unknown members included.
  • final List<Map<String, dynamic>> items — Every object of items, read as written.
  • final String? rawText — The file’s text as read, which a write passes as expectedText (§6.2).
  • EntityType get type — The record’s type: comp, session or render batch.
  • String get id — The record’s id, its filename’s middle segment.
  • Author get author — The record’s author, from its filename.
  • String? get kind — The record’s kind: comp, session or queue, an unknown word as written.
  • String? get status — The record’s status in its type’s own words (§12.7), an unknown word as written.
  • String? get created — When the record was first written, as the file has it.
  • static String pendingStatusOf(EntityType type) — The status in which a record of [type] is its author’s pending set: open for a session, pending otherwise.
  • bool get isPending — Whether this record is in its type’s pending status.
  • int get nextItem — The next item’s n (§12.7), never at or below an n already taken.
  • static List<String> ownMembersOf(EntityType type) — The top-level members of [type]’s own (§12.7), as the getters below read them.
  • String? get title — A comp’s title (§12.7).
  • String? get description — A comp’s description (§12.7).
  • String? get visibility — A comp’s visibility: public or private.
  • Map<String, dynamic>? get posted — A comp’s post, {at, url, revision}, once posted.
  • Map<String, dynamic>? get error — The last failed post’s {code, at, detail}, kept while the comp is pending again.
  • String? get started — When an assistant session started (§12.7).
  • String? get ended — When an assistant session ended.
  • String? get summary — An assistant session’s own summary of what it did.
  • String? get run — The app run’s command session.
  • String? get assistantSession — The host’s id of the assistant’s session.
  • String? get assistant — The selected assistant’s id.
  • String? get action — The catalog action’s id the session’s chat opened with (§12.7); absent on a record from before it was kept.
  • String? get entity — The entity a field’s or form section’s action opened at, as its exchange id (ch_julius_now); absent otherwise.
  • static int newestFirst(SetRecord a, SetRecord b) — Newest first by created, a record without a readable created last, equal instants by stem (§12.7).

lib/src/short_name.dart

• enum ShortNameProblem — Why a typed short name is not a segment.
  • values: empty, invalidCharacters, badStart, tooShort, tooLong, reserved, tooManyDots
• class ShortName — The segment and handle rules, with an opaque UUID exception for entity tags.
  • static const int maxLength — The hard limit of §5.2.
  • static const int maxHandlePartLength — The hard limit of a handle’s workspace part (§5.6); the owner part is a username.
  • static const int minUsernameLength — The shortest username (§5.6).
  • static const int maxUsernameLength — The longest username (§5.6), the segment bound.
  • static final RegExp usernamePattern — A person’s username, on the app’s side and the website’s: [a-z0-9][a-z0-9-]{2,31} (§5.6).
  • static const String reservedOwner — The owner handle reserved for official pointers (§5.2), never an author’s.
  • static final RegExp pattern — The segment grammar: [a-z0-9][a-z0-9-]{0,31}.
  • static bool isValid(String value) — Whether [value] is one segment of at most 32 characters.
  • static bool isUuid(String value) — Whether a tag segment is a canonical UUID imported from another format (§5.2).
  • static bool isValidOrAllocated(String value) — Whether [value] is a segment or an allocated id, whose owner may make it up to 43 characters (§5.2).
  • static bool isValidTag(String value) — Whether a tag consists of segments, allocated ids or UUIDs, without relaxing handles (§5.2).
  • static ShortNameProblem? validate(String value) — The first problem with [value], or null when it is a segment.
  • static bool isDeviceName(String value) — Whether [value] is a Windows device name.
  • static ShortNameProblem? validateUsername(String value) — The first problem with [value] as a person’s username (§5.6), or null when it is one.
  • static ShortNameProblem? validateHandle(String value) — The first problem with [value] as an author handle (§5.6).
  • static String normalise(String raw) — The nearest segment to free text.

lib/src/spans.dart

• enum SpansShape — Which of the two shapes a spans takes (§10.3).
  • values: blocks, until
• class MediaSpans — A block’s media entry’s spans (§10.3): the blocks it covers, or the extent it plays over.
  • factory MediaSpans.blocks(List<String> blocks) — Covers [blocks], from the owning block on; an empty list or an empty id is refused.
  • factory MediaSpans.untilBlock(String id) — Plays until the block [id]; an empty id is refused.
  • factory MediaSpans.untilSeconds(num seconds) — Plays for [seconds], any finite number greater than zero, written as given.
  • static const endOfScene — Plays until the end of the scene: music’s and sound effects’ default.
  • static MediaSpans? fromJson(Object? value) — The spans [value] holds, or null where it holds anything but exactly one of the two shapes.
  • final List<String>? blocks — The blocks covered, in file order; null for an extent.
  • final String? untilBlock — The block it plays until; null otherwise.
  • final num? untilSeconds — The seconds it plays for; null otherwise.
  • final bool untilEndOfScene — Whether it plays until the end of the scene.
  • SpansShape get shape — Which shape it takes.
  • Map<String, Object?> toJson() — The object a file writes.
• class BlockMediaGroup — What a block’s media group takes, what it allows of spans, and what a new entry of it is given (§10.3).
  • const BlockMediaGroup({required this.kinds, this.allowed = const {}, this.defaultSpans})
  • final Set<MediaKind> kinds — The kinds of media the group holds: what its place’s file dialog, drop and render accept.
  • final Set<SpansShape> allowed — The shapes an entry of the group may take; none means the owning block alone.
  • final MediaSpans? defaultSpans — The spans a new entry is written with; null for none.
• variable const Map<String, BlockMediaGroup> blockMediaGroups — A block’s six media groups in their order (§10.3).
• function MediaSpans? spansAllowed(MediaSpans? spans, String group) — [spans] where [group] allows its shape, else null; an unknown group allows nothing.

lib/src/stems.dart

• class ParsedName — Result of parsing one filename.
  • const ParsedName()
  • List<String> get segments — The name segments a reader checks against the grammar of §5.2.
• class VersionStem — A versioned entity file: library or spec entity.
  • const VersionStem({ required this.type, required this.tag, required this.author, required this.v, this.epoch, })
  • final EntityType type
  • final String tag
  • final String? epoch
  • final Author author
  • final int v
  • String get stem — The filename without extension, e.g. ch_main-hero_30yo_john123_v2.
  • String get versionsKey — The part shared by every version of this entity at this epoch, e.g. ch_main-hero_30yo.
  • String get groupKey — The part shared by every epoch and version of this entity, e.g. ch_main-hero.
• class OfficialStem — <type>_<tag>[_<epoch>]_official.json
  • const OfficialStem({required this.type, required this.tag, this.epoch})
  • final EntityType type
  • final String tag
  • final String? epoch
  • String get versionsKey
• class CommentaryStem — cm_<type>_<tag>_<author>.json
  • const CommentaryStem({ required this.targetType, required this.tag, required this.author, })
  • final EntityType targetType
  • final String tag
  • final Author author
  • String get groupKey
• class BatchStem — <type>_<id>_<author>.json: a render batch (rd), a comp (cp) or an assistant session (as) (§5.4).
  • const BatchStem({required this.id, required this.author, this.type = EntityType.renderBatch})
  • final String id
  • final Author author
  • final EntityType type — The record’s type: [EntityType.renderBatch], [EntityType.comp] or [EntityType.session].
  • String get stem
• class TakeName — <deliverable>_<source stem>_r<id>_<renderer>_<n>.<ext>
  • const TakeName({ required this.deliverable, required this.source, required this.batchId, required this.renderer, required this.n, required this.ext…
  • final Deliverable deliverable
  • final VersionStem source
  • final String batchId
  • final Author renderer
  • final int n
  • final String extension
  • String get stem
  • String get batchStem — The batch record that produced this take.
• class UnknownName — A file the grammar does not describe.
  • const UnknownName(this.path)
  • final String path
• function String entityGroupKey(EntityType type, String tag)
• function String entityVersionsKey(EntityType type, String tag, String? epoch)
• class FileNameParser — Parses filenames by the grammar of §5.4.
  • static const String reservedOwner — The owner handle reserved for official pointers (§5.2); never an author.
  • static ParsedName parseStem(String stem) — Parses a stem with no extension, as found in references ("forked_from": "ch_main-hero_30yo_john123_v1").
  • static ParsedName parse(String path) — Parses a project-relative path or a bare filename.
  • static List<ProjectWarning> namingWarnings(ParsedName name) — Reports segments outside the grammar, exempting allocated tag and epoch ids and UUID tag segments (§5.2).

lib/src/usage_estimate.dart

• function CatalogueAccess? pricedAccess(CatalogueEntry? entry, String platform, Map<String, Object?> params) — The access row a call on [platform] is priced by.
• enum PriceBasis — How the catalogue chose a price, or why a total remains unknown.
  • values: match, when, least, unmatched, none, partial
• function ({ExactDecimal? price, PriceBasis basis}) pricePer(CatalogueAccess row, String per, Map<String, Object?> params) — The price of one [per] on [row] and how the call’s [params] selected it.
• function Money? usageEstimate(CatalogueEntry? entry, String platform, { Map<String, Object?> params = const {}, int characters = 0, void Function(PriceBasis… — The catalogue’s price for a call as asked (§6.7, started): the least the call can cost.
• function Money? usagePrice(CatalogueEntry? entry, String platform, Map<String, ExactDecimal> units, { Map<String, Object?> params = const {}, void Function(… — What [units] a call used cost at the catalogue’s price (§6.7, basis price), where that is one answer.

lib/src/usage_record.dart

• variable const usageRecordVersion — The version of the record this code reads and writes.
• enum UsageStatus — Where a call is (§6.7, One call’s records).
  • values: started, submitted, running, succeeded, failed, canceled, unknown
• enum UsageBasis — Where a record’s cost came from (§6.7, basis): a money object’s own basis, or nothing known.
  • values: estimate, price, provider, charged, pending, unknown
  • static UsageBasis of(Money money) — The basis a cost of [money]’s kind has.
• enum UsageProblem — Why a line of a month file is skipped (§6.7, Reading).
  • values: notRecord, badField, unknownVersion
• variable const computeSessionEntry — The entry a compute session’s records name (§6.7, §6.15): a server’s time, which no catalogue entry prices.
• variable const conversationEntry — The entry a native conversation’s records name (§6.7): the conversation model, which no catalogue entry prices.
• variable const conversationCaptionsEntry — The entry of a conversation’s captions (§6.7): its input transcription, a chain beside the conversation’s.
• variable const unknownUsageEntry — The entry of a use that asked no model (§6.7): a plug-in’s check, an action or a request of its own, which the record’s purpose.plugin names instead.
• variable const chargedFailureMark — What marks a render’s failure code where a paid service took one of its requests, so that it may have been charged whatever it came to (§6.7): its job keeps charged.<code>, and its tile says so beside the code.
• function String chargedFailure(String code) — [code] as a render’s failure keeps it where a paid service took one of its requests ([chargedFailureMark]).
• function (String, bool) unmarkedFailure(String code) — A render’s failure [code] as it was, and whether it is marked as possibly charged ([chargedFailure]).
• class UsageUnits — The units a record can hold (§6.7, units).
  • static const counts — Units counted, written as JSON integers.
  • static const measures — Units measured, written as decimal strings with at most [measureDigits] fractional digits.
  • static const measureDigits — How many fractional digits a measure may have.
  • static const ofPlugin — The units as the plug-in API’s Usage names them, each with the record’s name for it.
  • static String? invalid(Map<String, ExactDecimal> units) — The first unit in [units] a record cannot hold, or null.
• class UsageOperation — One operation a call made on FilmOpen credit, by the id both the app and the portal hold (§6.6, §6.7).
  • const UsageOperation(this.id, {this.chargedCents, this.receipt, this.request})
  • final String id — The operation’s UUID, shared with the portal.
  • final int? chargedCents — What the portal’s settled receipt charged, in cents; null while it has not settled.
  • final String? receipt — The portal’s id for the settled receipt — its settlement row — where it gave one.
  • final String? request — The provider’s own id for the request the operation carried, where its answer gave one.
  • bool get settled — Whether the portal’s receipt has settled.
  • Map<String, Object> toJson() — The operation as a record’s operations hold it: status settled with its charged_cents, else pending.
  • static UsageOperation? fromJson(Object? json) — An operation as a record holds it, or null for one that is not.
• class UsagePurpose — What a call was for (§6.7, purpose).
  • const UsagePurpose({this.project, this.target, this.field, this.plugin})
  • final String? project
  • final String? target
  • final String? field
  • final String? plugin — For a plug-in’s call: <plug-in stem>/<hook>.
  • Map<String, String> toJson()
  • static UsagePurpose? fromJson(Object? json) — A purpose as a record holds it, or null for one that is not an object of strings.
• class UsageLine — One line of a month file, read (§6.7, Reading).
  • const UsageLine()
• class UsageRecordLine — A line that holds a record.
  • const UsageRecordLine(this.record)
  • final UsageRecord record
• class SkippedUsageLine — A line skipped, and why.
  • const SkippedUsageLine(this.problem, {this.field, this.chain})
  • final UsageProblem problem
  • final String? field — For [UsageProblem.badField], the field at fault.
  • final String? chain — For [UsageProblem.unknownVersion], the chain to skip whole: the record’s ref, else its id.
• class UsageRecord — One usage record (§6.7, A record).
  • UsageRecord({ required String id, required DateTime at, required UsageStatus status, String? ref, required String device, String? user, required St… — A record.
  • final String id — A random UUID, version 4, in lower case ([newUsageId]).
  • final DateTime at — When this record was written: UTC, to the millisecond.
  • final UsageStatus status
  • final String? ref — The id of the chain’s first record; null on the first record itself.
  • final String device — The id in the usage folder’s device.json.
  • final String? user — The filmopen.ai user id, when signed in.
  • final String app — The version of the app that wrote this record.
  • final String platform — The catalogue’s platform id.
  • final String route — direct on a copied key, filmopen.ai on credit, or token-only plan and local.
  • final String entry — The catalogue entry’s id.
  • final String? variant
  • final String kind — The entry’s kind.
  • final String modelId — The platform’s name for the model.
  • final UsagePurpose? purpose
  • final String? request — The platform’s request, job or session id.
  • final String? key — The copied key’s last four characters, or the slot/program/server setting on plan or local.
  • final String? label — The plan’s account or platform label, or the local platform’s name.
  • final Map<String, ExactDecimal> units
  • final Money? estimate — The cost expected before the call, on started; null where nothing prices the call as asked.
  • final Money? cost — What the call has cost so far, or in all.
  • final UsageBasis? basis — Where [cost] came from; [UsageBasis.unknown] where the call cost something nobody says, with no cost.
  • final String? error — A short code of the app’s own, never a platform’s message.
  • final List<UsageOperation> operations — The operations on FilmOpen credit the call’s end accounts for, each with its settled charge, in the order they ended (§6.6); empty on a person’s own key.
  • static UsageLine parse(String line) — Reads one line of a month file (§6.7, Reading): a record, or why the line is skipped.
  • UsageRecord next({ required String id, required DateTime at, required UsageStatus status, required String app, String? error, String? request, Stri… — The chain’s next record (§6.7, Later records).
  • Map<String, Object> toJson() — The record as its line holds it, in version 2’s order of fields.
  • String toLine() — The record’s line, without its line feed.
• function DateTime usageRecordTime(DateTime now, {DateTime? latest}) — When the chain’s next record is written (§6.7, Later records).
• function String newUsageId([Random? random]) — A new record id (§6.7): a random UUID, version 4, in lower case.
• function String usageMonth(DateTime at) — The month file a record goes to, by its own at in UTC (§6.7, Files): 2026-09.

lib/src/usage_totals.dart

• enum UsageBucket — Where a chain’s money goes in the totals (§6.7, Totals).
  • values: spent, pending, possiblyCharged
• class UsageChain — One call’s records (§6.7, Which record counts): a first record and every record whose ref names it.
  • final String id — The chain’s first record’s id, which every later record names in ref.
  • final List<UsageRecord> records — The chain’s records in the order that decides which counts: by at, then by id.
  • static List<UsageChain> of(Iterable<UsageRecord> records, {Set<String> skipped = const {}}) — The chains of [records], leaving out every chain [skipped] names.
  • UsageRecord get counted — The record that counts: the latest at, and on a tie the greater id.
  • UsageRecord? get first — The chain’s first record, while the log still holds it.
  • DateTime get countedAt — When the chain counts: its first record’s at, or its earliest record’s when the first is missing.
  • bool get costUnknown — Whether the call ran up a cost nobody knows (§6.7, basis unknown), or has not ended and started with no estimate, nothing pricing it: counted apart, as a call, and never as money or as free.
• class UsageTotal — A line of the totals: one month, one platform and one currency.
  • const UsageTotal({ required this.month, required this.platform, required this.currency, required this.spent, required this.pending, required this.p…
  • final String month — The month, as its file is named: 2026-09.
  • final String platform
  • final String currency
  • final ExactDecimal spent — Spent.
  • final ExactDecimal pending — Estimates pending, or possibly charged.
  • final ExactDecimal possiblyCharged — Estimates possibly charged, for calls the platform says do not exist.
  • final int costUnknown — How many calls cost something nobody knows ([UsageChain.costUnknown]), on the month’s line for the platform: the one in their estimate’s currency where there is one.
• function List<UsageTotal> usageTotals(Iterable<UsageChain> chains) — The totals of [chains] by month, platform and currency, newest month first.

lib/src/visual_style.dart

• variable const visualStyleKey — The key of a project’s or a folder’s profile.
• variable const visualStyleLeaves — The leaves of a visual treatment (A.11), by dotted path under [visualStyleKey], with the tokens of each that is a vocabulary’s; a leaf with none is a text, but palette, a list of colours.
• variable const treatmentPromptLeaves — The treatment’s primary leaves (A.11), in the order a render’s prompt takes them, each with the words that name it there — English, whatever the app’s language, since the prompt is the model’s (§8.7).
• variable const styleSharedLeaves — The leaves a Style (A.7) shares with a treatment, which a scene’s Style brings to what applies to it (§8.7).
• variable const paletteMost — The most colours a palette holds (A.11).
• variable final paletteColour — A colour of a palette: #rrggbb.
• function bool isPalette(List<Object?> colours) — Whether [colours] make a palette (A.11): at most [paletteMost], each a text #rrggbb once trimmed.
• function Map<String, Object> styleLeavesOf(Object? profile) — The leaves [profile] holds that a reader takes (A.11), by dotted path: absent ones — a null, an empty text or an empty list (§13.3) — and a value of another shape left out; a palette taken whole, lowercased, or not at…
• class ComposedTreatment — A treatment composed for an entity (§8.7): each leaf that applies with the stem of the document it came from.
  • const ComposedTreatment(this.leaves, this.sources, {this.ambiguous = false}) — A composition of [leaves], each from [sources]; [ambiguous] where the entity’s place in the script is.
  • final Map<String, Object> leaves — The leaves that apply, by dotted path.
  • final Map<String, String> sources — The stem of the document each leaf came from, by its dotted path.
  • final bool ambiguous — Whether the entity’s place in the script is ambiguous — listed twice, or under a folder listed twice or under itself — so that no folder’s profile applied (§8.7).
  • bool get isEmpty — Whether nothing applies.
  • Map<String, Object?> get profile — The leaves as a visual_style object, objects nested by their paths.
• function ComposedTreatment treatmentFor(FilmProject project, Entity entity, { Author? viewer, ScriptOutline? outline, bool withOwn = true, }) — What applies to [entity] (§8.7), as [viewer] reads the film: the project’s profile, each folder’s that holds it from the outermost in, its own where it is a folder ([withOwn]), then the Style a scene names — leaf by l…
• function ({List<Entity> folders, bool ambiguous}) scriptPlaceOf(ScriptOutline outline, EntityType type, String tag) — Where [type] [tag] stands in the script: the folders that hold it, outermost first, and whether its place is ambiguous — listed more than once, or beneath a folder listed more than once or under itself.
• function String composePrompt(String own, String? treatment, {Map<String, Object> leaves = const {}}) — The prompt a render is asked with (§8.7): [own], the entity’s, first; then each primary leaf of [leaves] that holds words, as Camera: …, in [treatmentPromptLeaves]’ order; then [treatment]’s words — each part trimme…
• function AnalysisChanges styleChanges(Map<String, Object?> fields) — A picture’s described treatment as checked leaves under [visualStyleKey].

lib/src/vocabulary.dart

• variable const List<String> locationKinds — A location’s kind (§9.3, A.3).
• variable const List<String> folderKinds — A folder’s kind (§10.1, A.5): a word for people, plug-ins and an export, and never a rule.
• variable const List<String> characterGenders — A character’s appearance.gender (A.1): what the app writes; a file’s other word is read as it is.
• variable const List<String> voicePitches — A character’s voice.pitch (A.1).
• variable const List<String> voicePaces — A character’s voice.pace (A.1).
• variable const List<String> timesOfDay — A location’s default time_of_day (A.3), the scene’s time vocabulary (A.5).

lib/src/voice_samples.dart

• variable const String voiceSamplesGroup — The group a character’s voice samples are in (§9.0).
• function bool isVoiceId(Object? value) — Whether [value] is an id a platform gives a voice or a preview of one: 1 to 128 letters, digits, _ and -.
• function bool isVoicePlatform(Object? value) — Whether [value] names a platform as the catalogue does: elevenlabs.
• class VoiceBinding — A voice sample’s provenance (§9.1): the platform it came from, the voice it was kept as, the preview it was.
  • VoiceBinding({required this.provider, this.voiceId, this.generatedVoiceId}) — A binding; each id, where given, of [isVoiceId]’s grammar.
  • final String provider — The platform tag the sample came from: elevenlabs.
  • final String? voiceId — The persistent voice id the sample was kept as, which speech takes.
  • final String? generatedVoiceId — The id of the temporary preview the sample was.
  • static VoiceBinding? fromJson(Object? json) — The binding [json] is, or null where it is not one: an object whose provider names a platform and whose ids are of the grammar, none required.
  • Map<String, Object?> toJson() — The binding as an entry writes it.
  • VoiceBinding keptAs(String id) — This binding kept as [id]: the preview it was, now a voice of its platform.
• function VoiceBinding? voiceBindingOf(MediaEntry entry) — The binding [entry] carries (§9.1), or null where it carries none it can read.
• function String? activeVoiceIdFor(Map<String, dynamic> json, String platform) — The voice [json]’s character speaks with on [platform] (§9.1): voice.provider_bindings’ id for it, or null.
• function MediaEntry? activeVoiceSample(Map<String, dynamic> json) — The live voice sample voice.active_reference names (§9.1), archived or not; null where it names none, which a reader ignores, never taking another sample in its place.
• function List<MediaEntry> voicePreviews(Map<String, dynamic> json) — The voice samples of [json] that are previews not yet kept (§9.1): live, shown, their binding naming a preview and no voice, in the group’s order.
• function bool isPreviewOnly(Map<String, dynamic> json, String id) — Whether [id] is only a preview’s in [json]: a voice sample’s binding names it as the preview it was and no sample was kept as it.