filmopen_insertion

A snapshot

This specification is a copy of docs/software/packages/filmopen_insertion.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

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

Media insertion, separate from storage and playback. This pure Dart package may depend on filmopen_jobs, filmopen_media, filmopen_store and filmopen_format, through their public barrels. It imports no state, forms, plug-in host or Flutter package. Consumers import only filmopen_insertion.dart.

pure Dart. 25 files, 3,946 lines under lib/; 264 tests in 33 files. Barrel: lib/filmopen_insertion.dart.

Depends on

• filmopen_jobs — uses JobAction, JobActionAck, JobCheckpoint, JobEngine, JobPersistence, JobPhase, JobRequest, JobResult, JobRun, JobUnavailable, JobView, JobViews, Produced, ProducedItem, ProducedValue, Producer, ProducerFailed, ProducerRun, ProducerState, refuseCredentialKeys
• filmopen_media — uses BytesInput, FileInput, LocalMediaStore, MediaInput, MediaRef, MediaStore, PlayableBytes, PlayableFile, PlayableUrl, ProjectMedia, StoreProblem, UrlInput
• filmopen_store — uses AppLog, Guards, LogLevel, PluginRun, ProjectWriter, WriteCancelled, WriteRecord
• filmopen_format — uses Author, BatchStem, Entity, EntityType, FileNameParser, FilmProject, MediaEntry, MediaKind, MediaSlot, MediaSpans, MediaStage, RenderBatch, ShortName, StaleFileException, TakeName, VersionStem, VoiceBinding, acceptedKindsFor, acceptsFile, blockMediaGroups, chargedFailureMark, documentPath, entryNaming, isDurableProjectKey, isMediaGroupName, mediaContainerKey, mediaExtensionOf, mediaFilePath, mediaKindOf, nextBatchId and 9 more
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: convert, crypto, http, image.

Used by

filmopen_app, filmopen_browser, filmopen_forms, filmopen_insertion_ui, filmopen_jobs_ui, filmopen_plugin_host, filmopen_prompt_ui, filmopen_render_ui, filmopen_state

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

• typedef typedef AudioProbe — What measuring a clip’s sound answered (§9.0): [audio] where it was measured, else null with the engine’s [code] and its [message] (unavailable where this platform has no engine).
• class InsertionBinding — Captured synchronously before submission can yield to another film/person.
  • InsertionBinding({ required this.project, required this.viewer, required this.guards, required this.locale, required this.store, this.maxBytes, thi…
  • final FilmProject project
  • final String projectKey
  • final Author? viewer
  • final Guards guards
  • final String locale
  • final MediaStore store
  • final int? maxBytes — The import cap: the web’s ([maxImportBytesWeb]), or null on the desktop, which has none.
  • final WriteRecord? record — Where the job’s writes are entered before the source is asked (§7.5): the app’s record, so that the next publication lays them over the index unread; null where no controller holds the film, as in a test’s fixture.
  • final Future<AudioProbe> Function(String path)? probeAudio — Measures whether the clip at a local path has sound, once at insertion (§9.0); null where this platform has no engine to measure with, and an entry then goes without audio.
  • ProjectWriter writer() — A writer of the captured film, as the person, entering its writes in [record].
  • String get fingerprint — Identity must match before a persisted job can resume.
• class InsertionPatchResult
  • const InsertionPatchResult(this.code, {this.json})
  • final String code
  • final Map<String, dynamic>? json — The document as the patch wrote it — the writer’s hand-back the caller’s holds accepted — never a draft snapshot; nothing is read for it.
  • bool get succeeded
• class InsertionEnvironment — The state adapter supplies these doors; insertion never imports the app.
  • InsertionBinding? capture() — The open film’s binding, or null where none is open; throws settingsLoading while the settings a binding takes are read again (§6.13).
  • Future<InsertionPatchResult> patchEntity(InsertionBinding binding, String stem, void Function(Map<String, dynamic>) change, { String? key, required…
  • Future<void> noticeWritten(String projectKey) — Tells the film [projectKey], where it is still open, that the job wrote: one publication with a listing, which lays the recorded writes over the index unread (§7.5).
  • DateTime now()

lib/src/insertion_service.dart

• class InsertionService — The application owns a service; pages only submit and observe their place.
  • factory InsertionService({ required JobEngine engine, required InsertionEnvironment environment, Map<String, Producer> producers = const {}, Durati…
  • static InsertionService current
  • Future<String> insert(InsertionTarget target, InsertionSource source, {void Function(String id)? onAccepted}) — Accepts one insertion and reports its job’s id to [onAccepted] once; an observer failure cannot undo an accepted job.
  • Future<String> submit(InsertionTarget target, InsertionSource source) — Submits as [insert] does, without the notification, and answers its job’s id; a refusal throws as [insert]’s does.
  • JobView? jobView(String id) — The view of job [id], read-only; null for a job this service does not know.
  • List<JobView> jobsFor(String placeKey)
  • JobViews get views
  • Future<JobActionAck> act(String id, JobAction action)
  • Future<void> restore(String projectKey)
  • void filmClosed(String projectKey) — Hears that film [projectKey] was closed, or another opened in its place: its jobs run on (§6.13), and the runtime logs the ones it holds, each with its phase.
  • Future<void> close({Duration grace = const Duration(seconds: 10)})
• class NoInsertionService
  • const NoInsertionService()

lib/src/insertion_source.dart — without isInsertionToken

• class InsertionSource — Runtime capabilities are deliberately separate from durable descriptions.
  • const InsertionSource()
  • SourceDescription describe()
• class FilesSource
  • FilesSource(Iterable<MediaInput> inputs)
  • final List<MediaInput> inputs
• variable const producerJobKind — The kind of the job a producer’s source makes — a render’s — which its tile reads to speak in a render’s words.
• variable const uploadJobKind — The kind of the job a person’s files make: an upload’s.
• class ProducerSource
  • ProducerSource(this.kind, Map<String, Object?> request)
  • final String kind
  • Map<String, Object?> get request
• class SourceDescription — Surviving description, not a promise that unstaged input survives a restart.
  • SourceDescription(this.kind, {this.producerKind, List<Map<String, Object?>> items = const []})
  • final String kind
  • final String? producerKind
  • final List<Map<String, Object?>> items
  • Map<String, Object?> toJson()
  • factory SourceDescription.fromJson(Map<String, Object?> json)

lib/src/insertion_target.dart

• class InsertionTarget — Where an insertion belongs, independent of whichever page is visible.
  • InsertionTarget({ required this.projectKey, required this.stem, required this.place, Set<MediaKind>? accepts, this.purpose = 'reference', })
  • final String projectKey
  • final String stem
  • final TargetPlace place
  • final Set<MediaKind> accepts
  • final String purpose
  • String get placeKey
  • Map<String, Object?> toJson()
  • factory InsertionTarget.fromJson(Map<String, Object?> json)
• class TargetPlace
  • const TargetPlace()
  • Map<String, Object?> toJson()
  • Object get identity
  • String? get group — The media group the place’s outputs become entries of; null where they become none.
  • factory TargetPlace.fromJson(Map<String, Object?> json)
• class SlotPlace — A place of an entity’s media: its outputs become entries of [slot]’s group, as one block, [first] putting it before what is there (Project Specification §9.0).
  • const SlotPlace(this.slot, {this.first = true})
  • final MediaSlot slot
  • final bool first
• class BlockPlace — A block’s media group (§10.3): its outputs become entries of [group] in the block [id] names, first.
  • BlockPlace(this.id, this.group, {this.spans})
  • final String id
  • final MediaSpans? spans — What the entries are to cover, chosen before the render or the upload; null for the group’s default.
• class TakesOnly
  • const TakesOnly()

lib/src/media_importer.dart — without ReplayInput, ReplayOutcome, ReplayMediaImporter

• function http.Client Function()? debugMediaHttpClient — The client an import of an address opens.
• variable const int maxImportBytesWeb — How big an import may be on the web: the app’s own policy, since a web session holds every upload whole in its memory.
• variable const int maxThumbnailSourceBytes — How large a picture may be before its thumbnail is not attempted.
• enum MediaImportProblem — Why an import was refused.
  • values: notMedia, empty, tooLarge, nameTaken, rootUnavailable, noViewer, badUrl, unreadable, recordNotWritten
• class MediaImportException — An import that did not happen, and why.
  • const MediaImportException(this.problem, {this.name})
  • final MediaImportProblem problem
  • final String? name — The name the person would recognise, where there is one.
• class ImportedMedia — What one import action did.
  • const ImportedMedia({required this.media, required this.batch, required this.items})
  • final List<ProjectMedia> media — The pieces of media, in the order the files were given.
  • final RenderBatch? batch — The batch record; null only for an import of nothing.
  • final List<Map<String, dynamic>> items — The items as they were written, for the caller and for tests.
  • List<String> get references — The references to add to the entity’s draft (§9.0), in order.
• class MediaImportCancelled — A person’s Stop, seen between the files of an import or between the chunks of one (§6.13).
  • const MediaImportCancelled()
• class MediaImporter — The one way media enters a project.
  • const MediaImporter({ required this.project, required this.store, required this.writer, this.now, this.maxBytes, this.keepForThumbnailBytes = maxTh…
  • final FilmProject project
  • final MediaStore store
  • final ProjectWriter writer — The writer that records the batch: a batch is a project file, so it is written where every project file is.
  • final DateTime Function()? now — The clock, for the batch id; a test’s own.
  • final int? maxBytes — The cap of this platform: [maxImportBytesWeb] on the web, null — none — on the desktop.
  • final int keepForThumbnailBytes — How much of a picture is held as it passes, for its thumbnail and its size.
  • final Future<AudioProbe> Function(String path)? probeAudio — The binding’s measure of a clip’s sound ([InsertionBinding.probeAudio]); null where there is none.
  • final Future<ChunkHasher> Function() startHasher — Starts one file’s hash: on a worker isolate where the platform has threads ([startChunkHasher]); a test’s own.
  • Future<ImportedMedia> import(Entity entity, List<MediaInput> inputs, { required Author? viewer, required List<String?> groups, PluginRun? run, bool… — Imports [inputs] as takes of [entity]’s version, in one batch.

lib/src/producer_failure.dart — only producerFailureCode, producerFailureOf

• function String producerFailureCode(String code) — The code a job keeps where its producer failed with [code]: the producer’s own as it is, marked so that a page tells it from the insertion’s own after it; a stop stays the job’s cancelled, and no code producerFailed.
• function String? producerFailureOf(String stateCode) — The producer’s own failure code a job’s [stateCode] keeps (producerFailureCode) — empty where it failed with none — or null where the code is none of the producer’s.

lib/src/stock_thumbnails.dart

• function Uint8List stockThumbnailFor(MediaKind kind) — The stock picture of a kind, at the thumbnail’s own size, as a JPEG.

lib/src/thumbnailer.dart

• variable const int thumbnailEdge — A thumbnail fits within this, in both directions, and is never enlarged: large enough to see an outfit.
• variable const int thumbnailQuality — JPEG quality: 80 normally, and 60 for a busy picture whose thumbnail comes out over [thumbnailBudgetBytes].
• variable const int thumbnailQualityWhenLarge
• variable const int thumbnailBudgetBytes
• variable const int thumbnailBackground — The grey a transparent picture is flattened on: the same in a light and a dark theme, so one thumbnail serves both.
• variable const int maxThumbnailPixels — The maximum number of source pixels the thumbnail decoder accepts.
• function Future<Uint8List?> makeThumbnail(Uint8List bytes) — The thumbnail of a picture, or null when the bytes are not one this build can decode (§6.3: a reader that has no thumbnail shows a placeholder, and never an error).
• function Uint8List? thumbnailOf(Uint8List bytes) — The thumbnail-making itself, as one function that can go to another thread whole.
• function (int, int)? imageDimensionsOf(Uint8List bytes) — The width and height of a picture without keeping it.

Internal

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

• lib/src/hash_worker.dart: ChunkHasher, InlineChunkHasher
• lib/src/hash_worker_io.dart: startChunkHasher, _work, _IsolateHasher
• lib/src/hash_worker_stub.dart: startChunkHasher
• lib/src/insertion_attach.dart: _producerOf, _reported, _whole, _Attachment
• lib/src/insertion_runtime.dart: _RestoreRefusal, _Film, RuntimeInsertionService, _AcknowledgementFailed, _MutationHeld, _Binding
• lib/src/insertion_view_projection.dart: _projectInsertionView, _InsertionRun, _ImportProgress
• lib/src/local_file.dart
• lib/src/local_file_io.dart: localReadChunkBytes, openLocalFile, localFileLength
• lib/src/local_file_stub.dart: openLocalFile, localFileLength
• lib/src/off_thread.dart
• lib/src/off_thread_io.dart: runOffThread
• lib/src/off_thread_stub.dart: runOffThread
• lib/src/thumbnail_worker_io.dart: thumbnailWorkerAvailable
• lib/src/thumbnail_worker_stub.dart: thumbnailWorkerAvailable