SPB Git

Repository Public

RECORDING_PIPELINE.md 3.8 KB 50 lines markdown

1<!--2SP Lecture Studio3File: docs/RECORDING_PIPELINE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Recording pipeline89```10MicrophoneSource (AVAudioEngine tap, mono downmix, host time per buffer)11        │ buffer, hostTime12RecordingEngine ──► SegmentedAudioWriter ──► media/audio-…-NNNNN.caf (closed every 10/30/60 s, SHA-256, manifest checkpoint)13        │               └ returns the timeline time of the buffer's first sample14        ├─► RecordingClock.anchor(host, timeline)          the one clock for every stream15        ├─► AutoPauseEngine.ingest(level)                  opt-in policies16        ├─► envelope (10 ms RMS / peak)                    waveform, silence detection17        └─► bufferTap                                      optional on-device phrase spotting18UI events (page, stroke, erase, pointer, viewport, marker) ──► RecordingEngine.record ──► EventLogWriter (append, fsync ≤ 1 s)19CameraRecorder (AVCaptureMovieFileOutput, 5 s fragments) ──► media/camera-…mov, start stamped with the recording clock20```21- **Pause**: the clock freezes at the end of the written audio, the open segment is closed (so everything is finalized before22  waiting), a `pause(reason)` event is logged. **Resume** logs `resume(gapSeconds)`, writes the pre-roll (the last 0.3 s heard23  before resuming, configurable) and restarts the clock on the first pre-roll buffer.24- **Stop** closes files, writes `sessionEnd`, the manifest and the waveform cache. A session stopped immediately leaves no trace.25- **Checkpoints**: the manifest is rewritten atomically when a session starts, at every finalized segment, at every pause and at stop.26- **Route / format change** (headset, Bluetooth): the engine restarts on the new route and a new segment starts at the new sample27  rate; the reader resamples per segment. **Interruption** (call, Siri): the session is paused with reason `interruption` and never28  resumes by itself.29- **Low disk**: warning under 1 GB, automatic pause (everything finalized) under 200 MB. **Thermal / battery**: warnings only.30- **Sleep**: idle timer disabled on iOS, `beginActivity(.idleDisplaySleepDisabled…)` on macOS while a session is open.31- **PDF-only mode**: with the microphone denied the same pipeline runs without audio (events on the host clock, silent track on export).3233## Automatic pause and stop (all off by default)34| Policy | Trigger | What happens |35|---|---|---|36| 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 |37| Inactivity | no voice **and** no slide/ink interaction for N s | countdown; any activity cancels it |38| Maximum duration | recorded time reaches the limit | countdown; "continue" snoozes 15 min |39| End time | wall clock reaches the chosen time | countdown; "continue" snoozes 15 min |40| End phrase / retake phrase | recognized on device, only if the language model is installed | short countdown / a retake marker |41At the end of a countdown the session is **paused** (default) or stopped and saved (option). Manual pause freezes every timer.42Every decision is written to the event log as an `auto` event (policy, action, detail): that is the audit log.4344## Crash recovery45On opening a project, `ProjectRecovery` runs when a session has no end date, a segment is not finalized, or a media file is not in the46manifest. It probes each file by decoding it, patches a CAF header whose data size was never written (8 header bytes only),47re-attaches readable segments in order, closes the session, and reports what it found. Unreadable files are kept and listed.48It only states what can be decoded: the recovered duration equals the decodable frames. Tested with a copy of the on-disk state49mid-recording and with a recorder process killed by SIGKILL.50
Files main
Menu

Theme