filmopen_dictation

A snapshot

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

Dictation on a text box, as Software Specification §9.6 describes it.

Flutter. 15 files, 4,405 lines under lib/; 144 tests in 19 files. Barrel: lib/filmopen_dictation.dart.

Depends on

• filmopen_format — uses Catalogue, ExactDecimal, Money, MoneyBasis, UsageBasis, UsageOperation, UsagePurpose, UsageRecord, UsageStatus, newUsageId, usageRecordTime
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_platform — uses AudioDevice, AudioFormat, AudioRecording, AudioSource, AudioSourceUnavailable, CredentialStore, CredentialStoreUnavailable
• filmopen_state — uses CreditFunding, ExitTasks, FundingResult, FundingUnavailable, LiveDictation, MicrophoneGranted, MicrophoneOccupied, MicrophoneOwner, MicrophoneOwnership, NavIndex, PluginCatalogueView, ProviderFunding, Settings, SpeechProvider, appVersionProvider, catalogueProvider, kFilmOpenDomain, kTranscriptionOperation, navIndexProvider, pluginRouteLine, projectProvider, providerFundingProvider, settingsProvider, settingsTabProvider, speechProviderOf
• filmopen_store — uses AppLog, LogLevel, UsageLog, UsageLogUnavailable
• filmopen_ui — uses EditableTextSelection, EditableTextTarget, ProvisionalTextEdit, SectionCard, ShortNameBox, ShortNameField, TextEditGeneration, TextEditOutcome, showMessage
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, stream_channel, web_socket_channel.

Used by

filmopen_account, filmopen_app, filmopen_assistant_ui, filmopen_browser, filmopen_forms, filmopen_support, filmopen_tree

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

• class DictationLook — How every microphone of the app looks and behaves, decided here and nowhere else (Software Specification §9.6).
  • static const tabStop — Whether the microphone is a Tab stop: it is not, so Tab goes from box to box and the microphone is a click away.
  • static bool get available — Whether this build shows a microphone at all: not the web, which keeps no keys.
• function Widget dictateShortName(BuildContext context, ShortNameBox box, {required String identifier, UsagePurpose? purpose}) — A [ShortNameField]’s suffix: the microphone for the box, following the box’s own rules (§9.6).
• class DictateButton — The microphone at the right of a text box, capturing one inline insertion (§9.6).
  • const DictateButton({ super.key, required this.target, this.enabled = true, this.webBuild = kIsWeb, }) — Places the shared microphone on an editable box without configuring its look.
  • final DictationTarget target — The box and its existing input and usage rules.
  • final bool enabled — Whether the box can be typed into now.
  • final bool webBuild — Whether this is the web build, which shows no microphone.

lib/src/dictation_controller.dart

• typedef typedef DictationTurn — One turn of a dictation’s speech: [key] names it across the dictation’s sessions, and [text] is what it says so far.
• class DictationStretch — The words of one commit of a dictation, once they have come (Software Specification §9.6).
  • const DictationStretch({required this.commit, required this.text})
  • final int commit
  • final String text
• enum DictationPhase — Where a dictation is (Software Specification §9.6).
  • values: idle, connecting, listening, stopped, ended, failed
• class DictationController — One dictation’s microphone, transcription sessions, usage chains and timers (§9.6).
  • DictationController({ required DictationSetup setup, this.creditSetup, required this.language, required this.app, this.purpose, this.owner = 'dicta… — Creates a dictation lifecycle with an independent, nonsecret microphone owner kind.
  • final DictationSetup selected — The person’s chosen speech service, whose own key is read first (§9.6).
  • final DictationSetup? creditSetup — The catalogue’s OpenAI setup, on which a session opens on FilmOpen credit where [selected] has no key (§9.6).
  • DictationSetup get setup — The setup the session in use runs on: [creditSetup] where it fell back to OpenAI on credit, else [selected].
  • final String language — What the platform listens for: the app’s language.
  • final String app — The app’s version, which every record names (§6.7).
  • final UsagePurpose? purpose — The project, the entity and the box the text is for, which every record names; never the text.
  • final String owner — The nonsecret capture kind, independent of the Usage field or its identity.
  • String? get microphoneBusyOwner — The occupied owner’s captured kind, localized without exposing an arbitrary identifier.
  • String? get deviceId — The microphone chosen in the menu, or null for the system’s default.
  • final Duration noSpeechLimit — How long a session may hear no speech before it stops.
  • final Duration sessionLimit — How long the platform keeps a session open.
  • final Duration warningBefore — How long before [sessionLimit] the controller raises [nearLimit].
  • final Duration captureStopLimit — How long a recording’s stop is waited for: past it the stop is logged as failed and the microphone is released.
  • static ExactDecimal minutesOf(int frames) — [frames] of audio in minutes, to the six places §6.7 allows, rounded half up in whole numbers.
  • bool get capturing — Whether returned microphone capture is still awaiting a completed stop.
  • Future<void> get captureStopped — Completes when pending microphone starts and all returned captures have stopped or been released after a failed stop.
  • DictationPhase get phase — Where the dictation is.
  • String? get code — Why the dictation failed, or why its last session ended by itself (no_speech, time_limit, dropped).
  • bool get nearLimit — Whether the session is within [warningBefore] of its end.
  • bool get settled — Whether every turn committed has its final text.
  • bool get ending — Whether a session’s end has come while its last record is still being written (§9.6).
  • List<DictationTurn> get turns — Every turn so far, the earlier sessions’ first.
  • String get text — Every turn’s text so far, joined by a space.
  • ValueListenable<int> get commits — How many commits this dictation has sent — the device’s, a [cut]’s, a [stop]’s — each counted as it is sent, before any answer can come; and every turn the platform ended by itself while no commit waited, counted when…
  • ValueListenable<double> get level — The current frame’s loudness, 0..1 against the room’s level as the speech gate judges it: a quarter at the level it hears as speech, 1 at four times that.
  • Stream<DictationStretch> get stretches — For every count of [commits], in its order, the words that ended there, once they have come: each count is answered exactly once, with an empty text where nothing came.
  • Duration get audioSent — The audio sent, over every session of this dictation.
  • Money? get cost — What that audio costs at the catalogue’s price; null on FilmOpen credit, where the receipt alone says (§6.6).
  • bool get onCredit — Whether the session in use is on FilmOpen credit (§6.6).
  • Future<void> listen() — Starts a new session while preserving earlier text and joining an already pending start.
  • Future<void> stop() — Stops sending audio and joins physical microphone shutdown before releasing ownership.
  • void cut() — Ends the turn in progress, as [stop] does, and keeps the microphone on: the next frame begins the next turn.
  • Future<void> settle({Duration timeout = const Duration(seconds: 3)}) — Stops audio and waits at most [timeout] for the final text of every committed turn.
  • Future<void> resume() — Reacquires the microphone after cleanup in the same session and chain, or starts a new session.
  • Future<void> useDevice(String? device) — Records from [device] from now on, null being the system’s default.
  • Future<bool> close() — Ends text and Usage within a bounded wait and stops the microphone; repeated closes join the first.

lib/src/dictation_engine.dart

• variable const String kDictationEntryId — The catalogue entry the first engine transcribes with.
• variable const String kDictationPlatformId — The platform the first engine reaches its entry on: OpenAI directly, rather than through a router.
• class DictationEngine — A service dictation can transcribe with.
  • const DictationEngine({ required this.id, required this.entryId, required this.platformId, required this.shortName, required this.host, required th…
  • final String id — What the preference keeps and the log names.
  • final String entryId — The catalogue entry its sessions’ URL, model and price come from.
  • final String platformId — The platform the entry is reached on, whose key its provider plug-in keeps (speechProviderOf, §6.7).
  • final String shortName — The service’s compact brand, unchanged in every language.
  • final String host — The host its sessions open on, by which [EngineTranscriber] tells which messages a session speaks.
  • final Transcriber Function(ChannelConnector connect) transcriber — Its sessions’ messages, over connections the connector given makes.
• variable const openAiDictation — OpenAI’s gpt-live-transcribe, also the engine of an endpoint on no engine’s host.
• variable const xaiDictation — xAI’s grok-voice-transcribe-2.0, the default speech service.
• variable const dictationEngines — The engines, the one for an endpoint on no engine’s host first.
• variable final portalTranscriptionEndpoint — The website’s transcription pass-through, which speaks OpenAI’s own protocol both ways (§6.6, §9.6).
• function DictationEngine dictationEngineAt(Uri endpoint) — The engine whose host [endpoint] is on; OpenAI’s for [portalTranscriptionEndpoint], by name.
• class EngineTranscriber — The device’s transcriber, for lib/main.dart.
  • const EngineTranscriber(this.connect)
  • final ChannelConnector connect — How a connection is made: a WebSocket in the app.
• variable final dictationSelectedEngineProvider — The exact saved speech-service identifier, or Grok before a choice exists.
• variable final dictationEngineProvider — The selected known speech engine, or null for an unavailable saved identifier.

lib/src/dictation_engine_card.dart

• variable final dictationRouteProvider — The selected speech service’s metadata route, following dictation’s own-key and OpenAI-credit rule.
• class DictationEngineCard — Settings → Models chooses the speech service and opens its provider’s page through Configure.
  • const DictationEngineCard({super.key})

lib/src/dictation_settings_card.dart

• class DictationSettingsCard — The shared recording microphone is chosen here (Software Specification §9.4, §9.6).
  • const DictationSettingsCard({super.key, this.available}) — The card; [available] is for a test, else [DictationLook.available].
  • final bool? available — Whether this build shows a microphone at all.

lib/src/dictation_setup.dart

• class DictationSetup — What a dictation needs from the bundled catalogue.
  • const DictationSetup({ required this.entryId, required this.kind, required this.platformId, required this.modelId, required this.endpoint, required…
  • final String? platformName — The platform file’s full name, used where the engines are listed.
  • final String? shortName — The engine’s compact service brand ([DictationEngine.shortName]).
  • final String entryId — The entry’s id, which every usage record names.
  • final String kind — The entry’s kind (analysis), which every usage record names.
  • final String platformId — The platform whose endpoint and credential this setup uses.
  • final String modelId — The model the platform is asked for.
  • final Uri endpoint — Where a session opens: wss, on one of the platform file’s hosts.
  • final ExactDecimal pricePerMinute — What a minute of audio costs, in US dollars: the catalogue’s usd.
  • final String keychain — The name the key is stored under (filmopen/fo-openai/openai): the speech service’s provider plug-in owns it (§6.7).
  • final String credentialId — The field of the stored object that holds the key (key).
• variable final dictationSetupProvider — The selected service’s validated bundled setup, or null where it cannot be used.
• variable final dictationCreditSetupProvider — OpenAI’s validated setup, on which a dictation runs on FilmOpen credit where the chosen service has no key (§9.6).
• variable final dictationEngineSetupsProvider — Served speech-service setups and a null row for an unavailable selected identifier.
• function DictationSetup? dictationSetupFrom(Catalogue catalogue, {DictationEngine engine = openAiDictation}) — [DictationSetup] out of [catalogue] for [engine], the first by default: its entry, then its platform’s file.

lib/src/dictation_target.dart

• class DictationTarget — A text box a microphone can fill (Software Specification §9.6).
  • const DictationTarget({ required this.controller, required this.identifier, this.formatters = const [], this.maxLength, this.onChanged, this.purpos… — Binds a box’s controller, identity and existing input rules to its microphone.
  • final TextEditingController controller — The box’s text.
  • final EditableTextTarget? editable — The prose field’s captured-edit door, or null for a plain-controller adapter.
  • final FocusNode? focusNode — The box’s focus where the microphone stands beside the box rather than in it, which a press then focuses; none for a microphone inside its box, found through the box’s gesture delegate.
  • final String identifier — The box’s identifier: its microphone is <identifier>.dictate.
  • final List<TextInputFormatter> formatters — The box’s own input formatters, in the order it applies them.
  • final int? maxLength — The box’s length limit, in characters.
  • final ValueChanged<String>? onChanged — What the box does when its text changes, as typing calls it: the autosave, a field’s parsing.
  • final UsagePurpose? purpose — What the usage record says the text was for; the box’s identifier as the field where this is null.
  • final VoidCallback? onStart — Called as dictation opens on the box, before anything is heard.
  • final String? Function()? changed — Why the words must be dropped, asked before they go in (§9.6).
• class ControllerDictationTarget — Adapts a plain box without placing provisional words in its controller.
  • ControllerDictationTarget(this.target) — Observes external text edits while retaining the box’s existing commit rules.
  • final DictationTarget target — The consumer binding retained for this captured insertion attempt.
  • DictationResult? get lastResult — The commit’s room or formatter result, so the microphone can say why it was refused.
  • void dispose() — Invalidates captures and releases the listener when the microphone departs.
• enum DictationResult — What became of dictated text (§9.6).
  • values: applied, noRoom, nothingLeft
• function DictationResult applyDictation(DictationTarget target, String spoken) — Puts [spoken] into [target] through its formatters and length limit, telling the box as typing would.

lib/src/openai_transcriber.dart

• typedef typedef ChannelConnector — Opens a connection to [url] carrying [headers], or throws a [TranscriberConnectFailure].
• class TranscriberConnectFailure — A connection that did not open, with a code: ws_<status> for a refused handshake, timeout or connection.
  • const TranscriberConnectFailure(this.code)
  • final String code
• function Map<String, Object?> transcriptionSessionUpdate({required String model, required String language}) — The session’s configuration.
• function SessionRefusal? refusalOf(Object? error) — A platform error’s type, code, param and message, each where it is text, as it came.
• function Map<String, Object> audioAppend(Uint8List frame) — One frame of audio, as the platform takes it.
• class OpenAiTranscriber — Opens sessions with OpenAI through [connect].
  • OpenAiTranscriber(this.connect, {this.acceptTimeout = const Duration(seconds: 15)})
  • final ChannelConnector connect — How a connection is made: a WebSocket in the app, a channel controller in the tests.
  • final Duration acceptTimeout — How long the platform has to accept the session once connected.

lib/src/speech_gate.dart

• enum TurnEnd — How the audio since the last turn ends (Software Specification §9.6).
  • values: commit, clear, quiet
• typedef typedef GateStep — What the gate made of one frame: its level, whether it held speech, and how the audio ended with it, if it did.
• class SpeechGate — Decides on the device where the turns of speech end: gpt-live-transcribe takes no voice activity detection of its own, only commits.
  • SpeechGate({ this.quietToEnd = 8, this.speechToKeep = 2, this.longestTurn = 300, this.idleToClear = 100, this.loudness = 3, this.roomLeast = 50, th…
  • final int quietToEnd — Frames of quiet after speech that end a turn: 0.8 s.
  • final int speechToKeep — Frames of speech a turn needs to be committed: 0.2 s, a short name.
  • final int longestTurn — Frames after a turn’s first speech at which it ends without a pause: 30 s.
  • final int idleToClear — Frames of quiet, with no speech, after which their audio is cleared: 10 s.
  • final double loudness — How many times louder than the room a frame must be to count as speech.
  • final double roomLeast — The least the room’s level is taken to be, on the 16-bit scale, and where it starts.
  • final double roomRise — The most the room’s level rises in a frame: 3 %, about 2.6 dB a second.
  • final int rangeFrames — Frames whose range decides whether a voice holds the room down: 2 s.
  • final int evenAfter — Frames of speech from which a turn’s evenness is judged: 1 s.
  • final double variation — How many times louder than the quietest frame the loudest must be for the sound to be a voice.
  • static double levelOf(Uint8List frame) — The level of a frame of 16-bit little-endian PCM: the root of its samples’ mean square.
  • double get room — The room’s level now.
  • bool get pending — Whether the turn in progress holds speech that no commit has taken yet.
  • GateStep add(Uint8List frame) — Measures [frame], and says how loud it was, whether it held speech and how the audio ended with it, if it did.
  • TurnEnd? finish() — Ends the turn in progress where the audio stops — Stop, or the text being applied.
  • void reset() — Forgets the turn in progress and the recent frames, for audio that starts again; the room’s level is kept.

lib/src/transcriber.dart

• class TranscriptEvent — What a transcription session reports, in order.
  • const TranscriptEvent()
• class SessionOpened — The platform accepted the session, so audio may be sent and its minutes count.
  • const SessionOpened()
• class SpeechStarted — The platform heard speech begin (input_audio_buffer.speech_started), where it decides the turns itself.
  • const SpeechStarted()
• class TurnCommitted — The platform took the audio sent since the last turn as the turn [itemId] (input_audio_buffer.committed).
  • const TurnCommitted(this.itemId)
  • final String itemId
• class CommitRefused — The platform refused the last commit, having no audio to make a turn of.
  • const CommitRefused()
• class TurnText — Text of the turn [itemId].
  • const TurnText(this.itemId, this.text, {required this.completed, this.whole = false})
  • final String itemId
  • final String text
  • final bool completed
  • final bool whole — Whether [text], not yet [completed], is all of the turn so far rather than more of it.
• class TurnFailed — The platform could not transcribe the turn [itemId]; what arrived for it stays.
  • const TurnFailed(this.itemId)
  • final String itemId
• typedef typedef SessionRefusal — Why a platform turned a session down, in its own words: its error’s type, code and message, and the field it named — for the log (§6.7).
• class SessionEnded — The session is over.
  • const SessionEnded({required this.opened, this.code, this.refusal})
  • final bool opened
  • final String? code
  • final SessionRefusal? refusal
• class TranscriptionSession — One live session.
  • Stream<TranscriptEvent> get events — The session’s events, ending with one [SessionEnded].
  • void send(Uint8List frame) — Sends one frame of audio; a frame sent before the session opened, or after it ended, is dropped.
  • void commit() — Ends the turn the audio sent since the last one makes (input_audio_buffer.commit).
  • void clear() — Drops the audio sent since the last turn, which holds nothing worth transcribing (input_audio_buffer.clear).
  • Future<void> close() — Closes the connection; [events] then ends with [SessionEnded].
• variable const transcriptionOperationHeader — The header naming a dictation’s operation on FilmOpen credit, a v4 UUID: the website’s correlation, and every log line’s (§6.6).
• class Transcriber — Opens live transcription sessions.
  • const Transcriber()
  • static Transcriber current — The transcriber in use: unavailable until an entrypoint installs another.
  • static void install(Transcriber transcriber) — Makes [transcriber] the one in use.
  • bool get isAvailable — Whether a session can open at all.
  • TranscriptionSession open({required Uri endpoint, required String model, required Map<String, String> headers, required String language}) — Opens a session at [endpoint] for [model] whose upgrade carries [headers] as given, listening for [language] (an ISO 639-1 code: the app’s language).
• class UnavailableTranscriber — No transcriber: every session ends before it opens, as unavailable.
  • const UnavailableTranscriber()
• class TurnTexts — The text of a session, one text per turn in the order the turns started.
  • void apply(TurnText event) — Applies [event]: more text is added to its turn — or, sent [TurnText.whole], takes its turn’s place — until the turn completes, and a completion replaces its own turn’s text only.
  • String get text — Every turn’s text, in order, each trimmed and joined by a space.
• class ScriptedTranscriber — A transcriber for the tests and the agent build.
  • ScriptedTranscriber({this.script = const ['This is dictated text.'], this.framesPerTurn = 10, this.failWith})
  • final List<String> script — The turns’ final texts, repeated from the start when they run out.
  • final int framesPerTurn — Frames of audio per turn.
  • String? failWith — A code the next session ends with before it opens, as a refused key does.
  • final List<ScriptedSession> sessions — The sessions opened, newest last, for the tests.
• class ScriptedSession — A session of [ScriptedTranscriber].
  • final Uri endpoint — Where the session was opened.
  • final Map<String, String> headers — What the session’s upgrade carried.
  • final String language — The language the session was opened for.
  • int framesSent — Frames sent while the session was open.
  • int commits — Commits and clears asked for while the session was open.
  • int clears
  • void drop() — Ends the session as a dropped connection does.

lib/src/transcriber_stub.dart — only createDeviceTranscriber

• function Transcriber createDeviceTranscriber() — No transcriber on the web, which keeps no keys and shows no microphone (Software Specification §9.6).

lib/src/xai_transcriber.dart

• variable const xaiFormattedLanguages — The languages xAI writes numbers, currencies and units out for (its Supported languages, 18 September 2026).
• variable const xaiEndpointingMs — The silence after which xAI ends an utterance by itself, in milliseconds.
• function Uri xaiSessionUrl(Uri endpoint, {required String model, required String language}) — Where a session opens: [endpoint] with the session asked for in its query.
• class XaiTranscriber — Opens sessions with xAI through [connect].
  • XaiTranscriber(this.connect, {this.acceptTimeout = const Duration(seconds: 15)})
  • final ChannelConnector connect — How a connection is made: a WebSocket in the app, a channel controller in the tests.
  • final Duration acceptTimeout — How long the platform has to say it is ready once connected.

Internal

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

• lib/src/transcriber_io.dart: createDeviceTranscriber, connectWebSocket, _NoRedirects, connectFailureCode