SPB Git

Repository Public

RECORDING_PIPELINE.md 3.8 KB

# 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 logs resume(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 interruption and 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.

Files main
Menu

Theme