From shortcut
to delivered text.

0Read the trace

Scope: a successful live dictation with sounds enabled and automatic paste. The native audio detail is the current macOS AVAudioPlayer implementation. The AVAudioEngine experiment is not part of this flow. Other outcomes and draft mode are covered in section 6.

1Inspect the trace waterfall

Select a bar or diamond to see its exact boundaries, PostHog mapping, and limitations. Gray and dashed bars show supporting work; they are not all real named spans.

2The actual desktop sequence

Startup branches overlap. On a normal stop, recorder closure permits transcript resolution while WAV closure and audio restoration can continue. Storage finishes before automatic delivery is staged.

3What reaches PostHog

Event: transcription_completed_v2. Ten named phase durations, a separate session duration, and four offset fields can be emitted. Fields are conditional on which work ran and finished in time; a missing field is not zero.

3.1 · Durations and offsets

3.2 · Chunk aggregates and descriptive fields

3.3 · The flattened event for this mock session

All numbers below are illustrative and match the waterfall. Routine identity/system properties are omitted. Notice that pasted_offset_ms can exceed session_duration_ms because native confirmation may arrive after the lifecycle reaches idle.

4The local delay we measured

This is separate evidence from the illustrative waterfall: a recording in the installed desktop app's local log on this M4 Max, 23 September 2026 at 13:21:41 IST. Its time origin here is the native RPC dispatch, not T0 or shortcut press. The installed app was reporting 1.12.0.

In that capture startup: getUserMedia 83.9 ms, AudioContext resume 36.2 ms, first-frame wait 28.7 ms. Those renderer operations overlap the native sound path.

5What the current event cannot tell us

6Branches and trace-flush rules

7Source map

Paths are relative to /Users/z/exa9/@amical/amical. This document describes revision 097ffe4; local experimental results were collected on 23 September 2026.

8Proposed spans: evidence before implementation

PROPOSAL ONLY · NO TELEMETRY ADDED

The earlier list was too broad to treat every item as an established >20 ms bottleneck. Below, measured slow work, concrete waits, and lower-priority diagnostic candidates are distinguished explicitly. Existing span names stay unchanged; new names follow the same dotted namespace and hyphenated operation convention.

“Not measured separately” means unknown, not zero. The log contains no “Dictation trace” debug records, so missing v2 phase values cannot be recovered from it. No number from the illustrative waterfall is used in these tables. A faster CPU does not shorten the audio file, remove the 32 ms frame size, or determine backend latency.

The existing session root is retained as the lifecycle envelope. It starts at T0 and ends at idle; outstanding native responses and other obligations can end after it. Parent and child intervals overlap, so their durations must not be added.

9Names and clocks — simplified contract

Measure existing operations first. Native RPCs are measured entirely in main. Native code, response contracts, and generators are unchanged. Internal playback/mute subphases are deferred until later analysis justifies them.

9.1 · Interval attributes

name              dotted namespace + hyphenated operation
span_id           unique within the event
parent_span_id    logical parent
process           main | renderer
start_offset_ms   epoch start timestamp − session-open epoch timestamp
duration_ms       elapsed milliseconds
status            ok | failed | interrupted
chunk_index       present for repeated chunk work

9.2 · Clock sources

Cross-process starts use Date.now() Unix-epoch milliseconds. Main and renderer share the machine's wall clock, so their offsets need no clock mapping. Local performance.now() and existing Effect timers supply elapsed durations where already used. Existing synthetic main spans can use Date differences.

start_offset_ms = startedAtMs − sessionStartMs

Renderer timing batches contain only phase name, epoch start, and elapsed duration for completed operations. The original cached-config query is retained. There is no clock-sync endpoint, uncertainty metadata, clock-change correction, or native timing payload.

9.3 · Measurement scope

• The session anchor remains session open, not physical shortcut press. Early provider warmup can have a negative offset.
• Native RPC duration includes transport, scheduling, playback and mute work inside that RPC. It does not isolate those internal parts.
• A helper reply does not establish acoustic silence or visible text insertion in another application.
• The local measurements in sections 4 and 8 remain historical evidence, not results from this change. Unmeasured internal work remains unmeasured.

10Implemented v2 attributes

The event remains transcription_completed_v2. It contains the selected main/renderer span durations and start offsets, with existing field meanings preserved. For native operations, it contains caller-observed RPC timing only.

10.1 · Payload contract

trace_spans holds the interval attributes in section 9. trace_points holds name, offset_ms, and process. The implicit root, identified by trace_root_span_id, starts at offset 0 and ends at session_duration_ms. Logical children can finish after the lifecycle returns to idle.

{
  "trace_schema_version": 1,
  "trace_offset_anchor": "session_open",
  "trace_root_span_id": "root-example",
  "trace_spans": [
    {
      "span_id": "phase-example",
      "parent_span_id": "root-example",
      "name": "native.start-recording.rpc",
      "process": "main",
      "start_offset_ms": 5,
      "duration_ms": 248.1,
      "status": "ok"
    }
  ],
  "trace_points": [
    {
      "name": "lifecycle.recording-stopping",
      "offset_ms": 3000,
      "process": "main"
    }
  ],
  "native_start_recording_rpc_start_offset_ms": 5,
  "native_start_recording_rpc_duration_ms": 248
}

10.2 · Flat duration / start-offset pairs

24 September trim: retained 12 additional spans for microphone/device startup, audio readiness, native start/stop RPCs, the recorder start gate, provider warmup, and context capture. Removed admission checks/queue, capture lock/config read, worklet load/flush, teardown/context close, VAD reset, recorder final-frame wait, WAV write/finalize, and metadata-write timers. Existing aggregate timings remain. The candidate audit in section 8 is historical; this table is the current field list.

These selected spans also have top-level properties for percentile queries. The first recorded instance supplies the flat pair; individual instances remain in trace_spans.

Additional intervals in trace_spans include transcription.session-setup, transcription.provider-transcribe, and completed VAD work and lock waits. Existing VAD/provider aggregates and materialize_duration_ms retain their previous names and scope.

New point properties: recording_stopping_offset_ms (lifecycle entering stopping) and first_accepted_frame_offset_ms (main admits first PCM). Settings: dictation_sounds_enabled and system_audio_mute_enabled.

10.3 · Coverage and limits

• Native startRecording and stopRecording use their original requests and responses. Main records call start and elapsed time. No native subphase timestamps are returned.
• The 12 selected additional spans are kept even when fast. Added operation timers record successful completions; a failed operation has no duration for that operation. Existing failure reporting and lifecycle spans remain. Completed VAD/provider work and lock waits are retained above 20 ms, capped at 64 per session with a dropped count. Full-session aggregates remain available.
• Completed startup timings piggyback existing renderer reports, including completed steps before a later capture failure. First-frame reports and the final completion batch are nonblocking. Capture cleanup is not timed. Format metadata sent with audio is retained as its latest value, not expanded into per-frame trace points.
• The existing 15 s telemetry grace bounds late reports after lifecycle idle. Incomplete obligations are listed without fabricated completion times.
• Paste confirmation retains its existing meaning: native acknowledgement, not observed insertion.
• No transcript, audio, clipboard/window text, device identifier, email or credential is added to these timing properties.