Recording pipeline
text
MicrophoneSource (AVAudioEngine tap, mono downmix, host time per buffer)
│ buffer, hostTime
RecordingEngine ──► SegmentedAudioWriter ──► media/audio-…-NNNNN.caf (closed every 10/30/60 s, SHA-256, manifest checkpoint)
│ └ returns the timeline time of the buffer's first sample
├─► RecordingClock.anchor(host, timeline) the one clock for every stream
├─► AutoPauseEngine.ingest(level) opt-in policies
├─► envelope (10 ms RMS / peak) waveform, silence detection
└─► bufferTap optional on-device phrase spotting
UI events (page, stroke, erase, pointer, viewport, marker) ──► RecordingEngine.record ──► EventLogWriter (append, fsync ≤ 1 s)
CameraRecorder (AVCaptureMovieFileOutput, 5 s fragments) ──► media/camera-…mov, start stamped with the recording clock- Pause: the clock freezes at the end of the written audio, the open segment is closed (so everything is finalized before
waiting), a
pause(reason)event is logged. Resume logsresume(gapSeconds), writes the pre-roll (the last 0.3 s heard before resuming, configurable) and restarts the clock on the first pre-roll buffer. - Stop closes files, writes
sessionEnd, the manifest and the waveform cache. A session stopped immediately leaves no trace. - Checkpoints: the manifest is rewritten atomically when a session starts, at every finalized segment, at every pause and at stop.
- Route / format change (headset, Bluetooth): the engine restarts on the new route and a new segment starts at the new sample
rate; the reader resamples per segment. Interruption (call, Siri): the session is paused with reason
interruptionand never resumes by itself. - Low disk: warning under 1 GB, automatic pause (everything finalized) under 200 MB. Thermal / battery: warnings only.
- Sleep: idle timer disabled on iOS,
beginActivity(.idleDisplaySleepDisabled…)on macOS while a session is open. - PDF-only mode: with the microphone denied the same pipeline runs without audio (events on the host clock, silent track on export).
Automatic pause and stop (all off by default)
| Policy | Trigger | What happens |
|---|---|---|
| Silence | no voice for N s (threshold with 6 dB hysteresis and 0.6 s hangover so quiet word endings are not cut) | a suggestion banner; never an action |
| Inactivity | no voice and no slide/ink interaction for N s | countdown; any activity cancels it |
| Maximum duration | recorded time reaches the limit | countdown; "continue" snoozes 15 min |
| End time | wall clock reaches the chosen time | countdown; "continue" snoozes 15 min |
| End phrase / retake phrase | recognized on device, only if the language model is installed | short countdown / a retake marker |
| At the end of a countdown the session is paused (default) or stopped and saved (option). Manual pause freezes every timer. | ||
Every decision is written to the event log as an auto event (policy, action, detail): that is the audit log. |
Crash recovery
On opening a project, ProjectRecovery runs when a session has no end date, a segment is not finalized, or a media file is not in the
manifest. It probes each file by decoding it, patches a CAF header whose data size was never written (8 header bytes only),
re-attaches readable segments in order, closes the session, and reports what it found. Unreadable files are kept and listed.
It only states what can be decoded: the recovered duration equals the decodable frames. Tested with a copy of the on-disk state
mid-recording and with a recorder process killed by SIGKILL.