SPB Git

Repository Public License

recording.md 4.1 KB

# Recording

# Session lifecycle

RecorderController moves through five states: idle, recording, paused, interrupted and finishing.

  1. 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.
  2. 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.
  3. 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.
  4. Stop. A background task is opened, the engine drains and closes the master, and the finalizer runs.

Elapsed time is derived from the audio itself, not from a wall clock, so it cannot drift from what was captured.

# The capture master

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:

  • nothing in the header is ever rewritten;
  • after any write, the bytes on disk are a complete CAF file;
  • a torn last write costs at most one partial frame, which CAFWriter.inspect ignores.

Sample 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.

# Finalization

RecordingFinalizer.finalize:

  1. inspects the master and refuses an empty one;
  2. 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;
  3. re-opens the result and compares its duration with the master's (tolerance: the larger of 0.25 s and 0.5 %);
  4. moves it into place, then deletes the master and sidecar.

If any step fails, the temporary file is removed and the master stays for recovery.

Preset Master Library file
Voice PCM 16-bit AAC-LC 64 kbps, 24 kHz, mono
Meeting PCM 16-bit AAC-LC 96 kbps, mono
Lecture PCM 16-bit AAC-LC 80 kbps, mono
Interview PCM 16-bit AAC-LC 96 kbps per channel
High Quality PCM 24-bit WAV, PCM 24-bit
Lossless PCM 24-bit Apple Lossless, 24-bit

AAC 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.

Disk 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.

# Recovery

At 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.

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.

# Limits

  • A recording does not keep running through a force-quit, a crash or a shutdown.
  • Up to two seconds of audio (the checkpoint interval) can be lost to a power failure.
  • Behaviour during real interruptions and on a locked device is untested on hardware; see background-audio.md.
Files main
Menu

Theme