filmopen_platform

A snapshot

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

Where the application meets the operating system and the bundle: the bundled sample and the seed library as a ProjectSource (asset_source.dart), the on-disk copy of bundled assets, the application’s own folders (app_paths*.dart: logs, the shared library, preferences, and on a phone the projects folder, with the two doors projectsInAppFolder and folderDialogsAvailable), the file browser (reveal*.dart), the one door for links the operating system hands the app (incoming_links.dart, the device’s through app_links in device_incoming_links*.dart), the microphone behind a seam (audio_source.dart, the device’s own in device_audio_source*.dart), and the seams for provider keys: the credential store (credential_store.dart, the device’s own in device_credential_store*.dart) and the key verifier (key_verifier.dart), each unavailable until an entrypoint installs another.

Flutter. 40 files, 3,358 lines under lib/; 120 tests in 15 files. Barrel: lib/filmopen_platform.dart.

Depends on

• filmopen_format — uses AssetMedia, FilmProject, MediaLocation, OverlayProjectSource, PlatformFile, ProjectSource
• filmopen_store — uses AppLog, LogLevel

Third-party: app_links, flutter_secure_storage, path_provider, record, flutter_webrtc, url_launcher.

Used by

filmopen_account, filmopen_app, filmopen_assistant_ui, filmopen_device, filmopen_dictation, filmopen_drive, filmopen_forms, filmopen_keys, filmopen_media_ui, filmopen_plugin_host, filmopen_recorder, filmopen_sharing, filmopen_state, filmopen_support, filmopen_timeline_ui

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/app_paths_stub.dart

• variable const bool hasAppFiles — Whether this platform keeps application files on disk.
• function void configureSynopsisSandboxHome(String home) — Refuses Windows inspection folder configuration on unsupported platforms.
• function void useTestLogDirectory(String? folder) — For tests only: the web keeps no log folder, so there is nothing to redirect.
• getter bool get projectsInAppFolder — The web keeps no projects on disk at all: a project lives for the session.
• getter bool get folderDialogsAvailable — The web has no folder dialog.
• function Future<String> projectsDirectory()
• function Future<String?> documentsDirectory() — The person’s own documents folder as the operating system names it: where New project proposes to make a project on a computer when it knows no better place (Software Specification §9.2).
• function Future<String> logDirectory()
• function Future<String> reportsDirectory()
• function Future<String> syncDirectory() — The web has no durable sync journal folder.
• function Future<String> jobsDirectory()
• function Future<String> newSampleFolder({String? keep}) — A new folder for one opening of the bundled sample; not available on the web, which keeps its sample in memory.
• function Future<String> logFilePath()
• function Future<String> developerLogPath()
• function String? readEnvironment(String name)
• getter bool get isDesktop — The web is no desktop: it runs no plug-in at all.
• function Future<void> appendDeveloperLine(String path, String line)
• variable const mostDeveloperLog
• function Future<String> usageDirectory()
• function Future<String> pluginDataDirectory()
• function Future<String> libraryDirectory()
• function Future<String?> preferencesFilePath()
• function String? logLevelFromEnvironment()

lib/src/asset_disk_stub.dart

• function String? bundledAssetDiskPath(String key) — No disk on this platform.

lib/src/asset_source.dart

• class AssetProjectSource — A folder bundled as Flutter assets: the sample project or the seed copy of the shared library.
  • const AssetProjectSource(this.assetDirectory, {this.label = 'Sample'})
  • final String assetDirectory — e.g. assets/sample/the-cartographer
  • Future<OverlayProjectSource> snapshot({required String label}) — The web’s sample: a writable session over the bundled project, kept in memory.
  • Future<SampleFolderSource> extract({required String label, String? keep}) — The bundled project extracted into a new folder and opened there as a session copy.
• class SampleFolderSource — The bundled sample extracted to [folder] and opened from it.
  • SampleFolderSource(this._files, {required this.folder, required this.label})
  • final String folder — Where the sample was extracted.
• class JsonAssetSource — The stock plug-ins as one staged JSON asset: every file by its path, with the plug-ins repository’s ref and commit it was staged from (scripts/stage_plugins.py).
  • JsonAssetSource(this.asset, {this.label = 'plugins', Future<String> Function(String asset)? load})
  • final String asset — e.g. plugins/stock.json
  • Future<String?> get ref — The ref the plug-ins were staged from, such as origin/dev.
  • Future<String?> get commit — The commit the plug-ins were staged from.
• function Future<String> readBundledText(String asset) — A bundled text asset by its full path (assets/models/models.json), read afresh.

lib/src/audio_source.dart

• class AudioFormat — What dictation asks of a microphone: 24 kHz, one channel, 16-bit PCM, little-endian, sent in frames of 100 ms.
  • static const sampleRate
  • static const channels
  • static const frameMilliseconds
  • static const frameBytes — The bytes of one frame: 2,400 samples of two bytes each.
• class AudioDevice — A microphone the system offers.
  • const AudioDevice(this.id, this.label)
  • final String id — The system’s id for it, which the preferences keep.
  • final String label — Its name, as the system gives it.
• class AudioSourceUnavailable — Why the microphone could not start, as a code.
  • const AudioSourceUnavailable(this.code)
  • final String code
• class PcmFramer — Cuts a stream of PCM chunks into frames of [AudioFormat.frameBytes].
  • const PcmFramer()
• class AudioRecording — A recording in progress.
  • Stream<Uint8List> get frames — Frames of [AudioFormat.frameBytes] bytes, the last of them possibly shorter.
  • Future<void> stop() — Stops the recording, which closes [frames].
• class AudioSource — Where dictation’s audio comes from.
  • const AudioSource()
  • static AudioSource current — The source in use: unavailable until an entrypoint installs another.
  • static void install(AudioSource source) — Makes [source] the one in use.
  • bool get isAvailable — Whether a recording can start at all.
  • Future<List<AudioDevice>> devices() — The microphones the system offers now.
  • Future<AudioRecording> start({String? deviceId}) — Starts recording from the device [deviceId], or from the system’s default where that is null or no longer offered.
• class UnavailableAudioSource — No microphone: every recording is refused as mic_unavailable.
  • const UnavailableAudioSource()
• class FakeAudioSource — A microphone for the tests and the agent build.
  • FakeAudioSource({this.frameEvery = const Duration(milliseconds: AudioFormat.frameMilliseconds), this.sound})
  • final int Function(int frame)? sound — How loud each frame of a recording is, by its place in the recording from 0.
  • static const offered — The devices it offers.
  • final Duration frameEvery — How often a frame comes.
  • String? failWith — A code the next start fails with, as a microphone switched off does.
  • int started — How many recordings started.
  • String? lastDevice — The device the last recording used: one of [offered], or null for the default.
  • bool get recording — Whether a recording is running now.
  • void failRecording(String code) — Fails the running recording with [code], as a microphone the system takes away does.

lib/src/background_transfers.dart

• enum HostStatus — How a request of [BackgroundTransfers] ended.
  • values: done, notSupported, failed
• class HostOutcome — What the platform answered to one request, with a safe code where it failed and the milliseconds it took.
  • const HostOutcome(this.status, {this.code, this.ms = 0}) — Records one answer.
  • final HostStatus status — How the request ended.
  • final String? code — A safe code where it failed: the channel’s own code, or missingPlugin.
  • final int ms — The milliseconds the request took.
• enum HostEvent — What the platform’s service reports of itself: it started, failed to start, ran out of its allowed time, or stopped.
  • values: started, failed, timeout, stopped
• class HostReport — One report of the platform’s service, with its milliseconds and, where they apply, the failed stage, a code (the exception’s type) with the exception’s message, and the reason of a stop.
  • const HostReport(this.event, {this.ms = 0, this.stage, this.code, this.message, this.reason}) — Records one report.
  • final HostEvent event — What happened.
  • final int ms — Milliseconds since the request (started, failed) or since the start (timeout, stopped).
  • final String? stage — The failed stage: notification or startForeground.
  • final String? code — The failure’s type.
  • final String? message — The failure’s message, as the exception gave it; null where it gave none.
  • final String? reason — Why it stopped: hidden, timeout, failed, destroyed or activityDestroyed.
• class BackgroundTransfers — Shows, updates and hides the platform’s host for background transfers (§6.14).
  • bool get supported — Whether this platform has a host at all; false answers every request [HostStatus.notSupported].
  • Future<HostOutcome> show({required String title, required String text, int? files, double progress = 0, required String channel}) — Starts the host, or updates it if it runs: [files] counted (null where no count is known) and [progress] 0–1.
  • Future<HostOutcome> update({required String title, required String text, int? files, double progress = 0}) — Changes what a running host shows.
  • Future<HostOutcome> hide() — Stops the host.
  • Stream<HostReport> get events — What the platform’s service reports of itself; an answer to [show] is the request accepted, its start this.
• class UnsupportedBackgroundTransfers — A platform with no host for background transfers: every request is the intentional no-op.
  • const UnsupportedBackgroundTransfers() — The no-op.
• class ChannelBackgroundTransfers — Android’s foreground service through the channel filmopen/sync_host, which the app’s activity answers.
  • ChannelBackgroundTransfers() — An inert host; the channel is first used by [show].

lib/src/background_transfers_stub.dart

• function BackgroundTransfers createDeviceBackgroundTransfers() — The web has no host for background transfers (§6.14).

lib/src/credential_store.dart

• class CredentialHealth — What the store’s reads have shown (§6.7): whether it returned none or only some of the names it was given to keep, and which names read absent.
  • const CredentialHealth({this.emptyStore = false, this.partialStore = false, this.inventoryUnreadable = false, this.missing = const {}, this.absent…
  • final bool emptyStore — The store returned none of the names its inventory holds: writes are refused emptyStore until they read again or the person starts again.
  • final bool partialStore — The store returned some of the names its inventory holds and not others: writes are refused partialStore.
  • final bool inventoryUnreadable — The inventory file was there and could not be read: writes are refused inventoryUnreadable until the person starts again.
  • final Set<String> missing — The inventory’s names the store did not hold at the last check.
  • bool get refusing — Whether writes are refused, the store having lost names it was given to keep or its list unreadable.
  • final Set<String> absent — The names a read found absent this run — a key whose card must say missing — whether or not the inventory names them, until a read finds them or a write puts them back.
• class CredentialStore — The store in use is [current].
  • const CredentialStore()
  • static CredentialStore current — The store in use.
  • static void install(CredentialStore store) — Installs [store]; called by an entrypoint before the app runs.
  • bool get isAvailable — Whether the store can be used at all.
  • bool get isEphemeral — Whether what it holds ends with the app.
  • Future<String?> read(String name) — The value under [name], or null.
  • Future<void> write(String name, String value) — Replaces the value under [name].
  • Future<void> delete(String name) — Removes the value under [name], if any.
  • ValueListenable<CredentialHealth> get health — What the store’s reads have shown; a store with no inventory always reads healthy.
  • Future<void> resetInventory() — Forgets the names the store was given to keep, so that a store that lost them all takes a write again (§6.7).
• class CredentialStoreUnavailable — The store could not be used.
  • const CredentialStoreUnavailable([this.cause])
  • final String? cause — The type of the failure, when there was one.
• class UnavailableCredentialStore — The store of a build that installed none, and of the web build, which keeps no provider keys (§6.7): every call fails.
  • const UnavailableCredentialStore()
• class MemoryCredentialStore — A store in memory: the agent build’s and the tests’.
  • MemoryCredentialStore({Map<String, String>? values, this.failing = false})
  • final healthNotifier — What a test says the reads have shown.
  • int resets — How many times [resetInventory] was asked.
  • bool failing — Whether every call fails, as an unreadable store’s do.
  • int reads
  • int writes
  • int deletes
  • int get calls — Every call the store was asked, whatever it answered.
  • String? peek(String name) — What the store holds under [name], without counting as a call.

lib/src/device_audio_source_stub.dart

• function AudioSource createDeviceAudioSource() — No microphone on this platform.

lib/src/device_credential_store_stub.dart

• function CredentialStore createDeviceCredentialStore() — The web build keeps no provider keys (Software Specification §6.7).

lib/src/device_incoming_links_stub.dart

• function IncomingLinks createDeviceIncomingLinks() — The web’s page reads its own URL (Uri.base); no door is needed.

lib/src/device_webrtc_audio_peer_stub.dart — only createDeviceWebRtcAudioPeer

• function WebRtcAudioPeer createDeviceWebRtcAudioPeer() — Creates an inert unavailable peer for a platform without validated native audio.

lib/src/folder_watch.dart

• class FolderWatch — Hears the root-relative paths a folder’s watches report and, once they have been quiet for [quiet], hands the .json ones to [onSettled] at once.
  • FolderWatch(this.folder, List<Stream<String>> events, {required this.onSettled, this.quiet = const Duration(milliseconds: 400)}) — Listens to [events], one stream of root-relative paths per watched folder, for the folder at [folder].
  • final String folder — The project folder watched, as its source names it.
  • final void Function(Set<String> paths, Duration waited) onSettled — Called with the .json paths heard since the last call, and how long since the first of them was heard.
  • final Duration quiet — How long the folder must be quiet before what was heard is settled.
  • bool get stopped — Whether [stop] has run: nothing is heard or settled after it.
  • void stop(String reason, [String? message]) — Stops every watch and the timer, for [reason] — closed, another, gone, failed — logged with [message] and what was pending.

lib/src/folder_watch_stub.dart

• function FolderWatch? watchFolder(String folder, {required void Function(Set<String> paths, Duration waited) onSettled}) — Watches the project folder at [folder]; a platform with no folders to watch answers null (§6.1b).

lib/src/incoming_links.dart

• class IncomingLinks — The door in use is [current].
  • const IncomingLinks()
  • static IncomingLinks current — The door in use.
  • static void install(IncomingLinks links) — Installs [links]; called by an entrypoint before the app runs.
  • Future<Uri?> initial() — The link the app was started with, if any: the same answer to every caller, since the operating system is asked once.
  • Stream<Uri> get stream — Links arriving while the app runs.
• class UnavailableIncomingLinks — The door of a build that installed none, of the web (whose page reads its own URL) and of every test: nothing arrives.
  • const UnavailableIncomingLinks()
• class MemoryIncomingLinks — A door a test delivers to, as the operating system would.
  • MemoryIncomingLinks({this.initialLink})
  • final Uri? initialLink — The link the app is taken to have started with, if any.
  • int initialReads — How often the initial link was asked for: the card asks once.
  • void deliver(Uri uri) — Hands [uri] to whoever listens.
  • Future<void> dispose()

lib/src/key_verifier.dart

• enum KeyCheckOutcome — What a check found.
  • values: verified, rejected, couldNotCheck
• class KeyCheck — A check’s outcome, with a code for the log and the section.
  • const KeyCheck(this.outcome, this.code)
  • final KeyCheckOutcome outcome
  • final String code
• class KeyVerifier — The verifier in use is [current].
  • const KeyVerifier()
  • static KeyVerifier current — The verifier in use.
  • static void install(KeyVerifier verifier) — Installs [verifier]; called by an entrypoint before the app runs.
  • Future<KeyCheck> verify(PlatformFile platform, Map<String, String> values) — Checks [values], the stored credentials keyed by their ids, with [platform].
• class UnavailableKeyVerifier — The verifier of a build that installed none.
  • const UnavailableKeyVerifier()
• class StubKeyVerifier — The agent build’s and the tests’ verifier, which opens no socket.
  • const StubKeyVerifier()

lib/src/monitor_window.dart

• class MonitorWindow — The door to the picture’s window: whether this build can open one, and whether one is open.
  • MonitorWindow(this.channel) — The door over [channel]; the app’s is [instance].
  • static final MonitorWindow instance — The app’s one door.
  • final MethodChannel channel — The channel the runner answers.
  • bool get checked — Whether [check] has had its answer.
  • String? unavailable — Why no window can be opened, as a code — platform where this platform has no runner for it, no_runner where the runner does not answer, else the runner’s own — or null where one can.
  • bool get isOpen — Whether the window is open: it has a view.
  • int? viewId — The open window’s Flutter view id, as the runner reported it; null while no window is open.
  • bool isFullScreen — Whether the window fills its screen.
  • int? focusedView — The view whose window last took the keyboard, as the runner said: the window’s view may be told before it is built, and asks here once it is.
  • String? openedBy, closedBy — How the open window was opened, and how the last close was asked — null where nobody here asked for it: the window’s own close.
  • Future<void> check() — Asks the runner once whether it can open the window, and starts hearing its events.
  • Future<bool> open({required String title, required String how}) — Opens the window titled [title]; [how] says what asked (button).
  • Future<void> close({required String how}) — Closes the window; [how] says what asked (escape, button, exit).
  • Future<void> fullScreen(bool on, {required String how}) — Makes the window fill its screen, or leaves full screen; [how] says what asked (key, button).

lib/src/reveal_stub.dart

• getter bool get canRevealFiles — Whether this platform has a file browser the app can open.
• function Future<bool> revealInFileManager(String path)

lib/src/voice_playback.dart

• class VoicePlayback — A native PCM16 mono 24kHz sink with a device-measured playback cursor.
  • Future<void> open() — Opens the device without playing or recording any audio.
  • Future<void> write(Uint8List pcm) — Queues at most one second of PCM for the current playback generation.
  • Future<int> position() — Reports frames actually consumed by the device since the last clear.
  • Future<int> clear() — Stops all buffered playback and returns the pre-reset device frame position.
  • Future<void> close() — Releases the output device and every buffer.
• class WindowsVoicePlayback — Windows waveOut playback through an isolated channel owned by this runner.
  • WindowsVoicePlayback() — Creates an inert sink; open is called only on the owner’s Start gesture.

lib/src/webrtc_audio_peer.dart

• enum WebRtcAudioDirection — The permitted media directions of an audio-only native peer.
  • values: sendOnly, sendReceive
• enum WebRtcAudioProblem — Closed diagnostic categories; the native message travels in the failure’s event detail.
  • values: unavailable, busy, closed, invalidOrder, offerFailed, answerFailed, iceTimeout, deviceUnmapped, captureFailed, outputFailed, connectionFailed, dataFailed, cleanupFailed
• class WebRtcAudioException — A native audio failure represented only by its closed category.
  • const WebRtcAudioException(this.problem) — Creates a failure without retaining the native exception.
  • final WebRtcAudioProblem problem — The safe category for the host to translate.
• enum WebRtcAudioEventKind — The lifecycle and device observations available to a voice controller.
  • values: connecting, connected, disconnected, inputEnabled, inputDisabled, remoteAudio, failed, closed, state, capture
• enum WebRtcAudioStateOf — The native object a [WebRtcAudioEventKind.state] observation reports on.
  • values: peer, ice, channel
• class WebRtcAudioEvent — A provider-neutral native audio observation.
  • const WebRtcAudioEvent(this.kind, {this.problem, this.of, this.state, this.detail}) — Creates an observation of [kind], a capture’s [detail] naming its input device.
  • final WebRtcAudioEventKind kind — The observed lifecycle transition.
  • final WebRtcAudioProblem? problem — The closed failure category, when this observation reports a failure.
  • final WebRtcAudioStateOf? of — For a [WebRtcAudioEventKind.state] observation, the native object that changed.
  • final String? state — For a [WebRtcAudioEventKind.state] observation, the native state’s name (connecting, open, failed, …).
  • final Map<String, Object?>? detail — For a [WebRtcAudioEventKind.capture] observation, its values: the input’s id, what the track reports, counts, codes and a failure’s native message.
• class WebRtcAudioPeer — Owns one audio-only peer while the host owns signaling and provider controls.
  • Stream<WebRtcAudioEvent> get events — Reports lifecycle changes without exposing native SDK objects.
  • Stream<String> get messages — Receives text from the optional ordered data channel, without interpreting it.
  • Future<String> createOffer({required WebRtcAudioDirection direction, String? dataChannelLabel}) — Negotiates audio and an optional ordered data channel without acquiring a microphone.
  • Future<void> sendText(String text) — Sends text only after the negotiated data channel has opened.
  • Future<void> acceptAnswer(String sdp) — Installs the answer once, after this peer has produced an offer.
  • Future<void> setInputEnabled(bool enabled, {String? deviceId}) — Acquires input explicitly, or releases capture before reporting disabled.
  • Future<void> selectOutput(String deviceId) — Requests the selected output device without claiming audible playback.
  • Future<void> close() — Fences new work and drains every owned resource, including late acquisitions.

Internal

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

• lib/src/app_paths_io.dart: useTestLogDirectory, configureSynopsisSandboxHome, _sandboxFolder, hasAppFiles, projectsInAppFolder, folderDialogsAvailable, isDesktop, projectsDirectory, documentsDirectory, logDirectory, reportsDirectory, jobsDirectory, +14
• lib/src/asset_disk_io.dart: bundledAssetDiskPath
• lib/src/background_transfers_io.dart: createDeviceBackgroundTransfers
• lib/src/credential_inventory.dart: CredentialInventory, MemoryCredentialInventory, FileCredentialInventory
• lib/src/device_audio_source_io.dart: createDeviceAudioSource, RecordAudioSource, _RecordRecording
• lib/src/device_credential_store_io.dart: createDeviceCredentialStore, SecureStorageBackend, _PluginBackend, DeviceCredentialStore
• lib/src/device_incoming_links_io.dart: createDeviceIncomingLinks, _DeviceIncomingLinks
• lib/src/device_webrtc_audio_peer_io.dart: createDeviceWebRtcAudioPeer, WebRtcAudioOwnership, NativeWebRtcAudioPeer
• lib/src/folder_watch_io.dart: watchFolder
• lib/src/monitor_window_io.dart: monitorPlatform
• lib/src/monitor_window_stub.dart: monitorPlatform
• lib/src/reveal_io.dart: canRevealFiles, revealInFileManager, _revealLinux, _launch
• lib/src/webrtc_audio_backend.dart: WebRtcAudioBackend, webRtcCaptureForm, SdkWebRtcAudioBackend