SPB Git

Repository Public License

recording.md 4.1 KB 66 lines markdown

1<!--2ORIX Audio3File: docs/architecture/recording.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Recording910## Session lifecycle1112`RecorderController` moves through five states: idle, recording, paused, interrupted and finishing.13141. **Start.** Microphone permission is requested if undetermined. Free space must exceed 128 MB. The audio session is activated, a `CaptureSidecar` (id, title, start time, preset, markers, participants, locale) is written beside the future master, the engine starts, and a Live Activity is requested.152. **While recording.** A 100 ms ticker publishes elapsed time, bytes written and the dropped-sample count. Markers are appended to the sidecar immediately, so they survive an interrupted session.163. **Pause / resume.** Pause flips a flag the tap checks; no audio is accepted, and elapsed time — which is frames accepted divided by the sample rate — stops with it. Resume reactivates the session and restarts the engine if the system had stopped it.174. **Stop.** A background task is opened, the engine drains and closes the master, and the finalizer runs.1819Elapsed time is derived from the audio itself, not from a wall clock, so it cannot drift from what was captured.2021## The capture master2223`CAFWriter` writes a Core Audio Format file: an 8-byte file header, a 32-byte audio description, and a data chunk whose size field is −1. The CAF specification defines −1 as "the data chunk extends to the end of the file". Consequences:2425- nothing in the header is ever rewritten;26- after any `write`, the bytes on disk are a complete CAF file;27- a torn last write costs at most one partial frame, which `CAFWriter.inspect` ignores.2829Sample formats: 16-bit integer for the AAC presets, 24-bit integer for High Quality and Lossless (32-bit float is supported and tested but not used by a preset). The 64-bit chunk sizes of CAF also avoid WAV's 4 GB limit for long sessions.3031## Finalization3233`RecordingFinalizer.finalize`:34351. inspects the master and refuses an empty one;362. reads it in chunks of 65 536 frames and encodes to the preset's format under a temporary name, resampling to 24 kHz for the Voice preset;373. re-opens the result and compares its duration with the master's (tolerance: the larger of 0.25 s and 0.5 %);384. moves it into place, then deletes the master and sidecar.3940If any step fails, the temporary file is removed and the master stays for recovery.4142| Preset | Master | Library file |43|---|---|---|44| Voice | PCM 16-bit | AAC-LC 64 kbps, 24 kHz, mono |45| Meeting | PCM 16-bit | AAC-LC 96 kbps, mono |46| Lecture | PCM 16-bit | AAC-LC 80 kbps, mono |47| Interview | PCM 16-bit | AAC-LC 96 kbps per channel |48| High Quality | PCM 24-bit | WAV, PCM 24-bit |49| Lossless | PCM 24-bit | Apple Lossless, 24-bit |5051AAC bit rates are snapped to the nearest rate the encoder reports as valid for that sample rate and channel count, and AAC output is capped at 48 kHz.5253Disk use during a session is that of uncompressed PCM: about 5.8 MB per minute for 48 kHz mono 16-bit, 17.3 MB per minute for 48 kHz stereo 24-bit. It is released when the encoded file is verified.5455## Recovery5657At launch and whenever the app becomes active, `RecordingRecovery.scan` lists masters in the capture folder that no running session owns. A master with no frames is removed silently. A master whose sidecar is missing is still offered, with a generic title and the file's creation date. The recorder screen shows a banner with the title, duration and size, and two choices: recover (finalize into the library, title prefixed with ↺) or discard.5859**Evidence.** In the simulator, the app was terminated while recording; at the next launch a 33-second, 9.8 MB capture was listed and recovered into the library. An automated test builds the same situation — an unclosed master with a torn final byte and a sidecar holding a marker — and checks duration, markers and clean-up.6061## Limits6263- A recording does not keep running through a force-quit, a crash or a shutdown.64- Up to two seconds of audio (the checkpoint interval) can be lost to a power failure.65- Behaviour during real interruptions and on a locked device is untested on hardware; see [background-audio.md](background-audio.md).66
Files main
Menu

Theme