Repository Public License
1<!--2ORIX Audio3File: docs/architecture/background-audio.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Background and Locked-Screen Recording910> **Read this first.** No physical iPhone was available during development. Everything on this page is implemented with the APIs Apple documents for the purpose, and none of it has been observed on a device. Simulator testing cannot stand in for it.1112<p align="center"><img src="../assets/diagrams/background-lifecycle.svg" alt="Background recording lifecycle" width="820"></p>1314<details><summary>Mermaid source</summary>1516```mermaid17stateDiagram-v218 [*] --> Idle19 Idle --> Recording: start20 Recording --> Paused: pause21 Paused --> Recording: resume22 Recording --> Interrupted: system interruption23 Interrupted --> Recording: shouldResume, or user tap24 Recording --> Finishing: stop25 Paused --> Finishing: stop26 Interrupted --> Finishing: stop27 Finishing --> Idle: verified file in library28 Recording --> ProcessEnded: kill, crash, power loss29 ProcessEnded --> RecoveryOffer: next launch30 RecoveryOffer --> Idle: recover or discard31```32</details>3334## What makes it work3536| Requirement | Implementation |37|---|---|38| Permission to run in the background | `UIBackgroundModes` contains `audio` (`project.yml`) |39| An active record-capable session | `.playAndRecord`, activated before the engine starts |40| Files writable while locked | protection class *complete until first user authentication* on the library and capture folders and on each master |41| A visible indication | the system microphone indicator, plus a Live Activity |42| Time to finish after stop | a `UIApplication` background task around draining and encoding |4344The protection class matters. With the stricter *complete* class, iOS makes files unreadable and unwritable shortly after the device locks, and every write from a pocket would fail. The chosen class encrypts files at rest and unlocks them after the first unlock following a restart.4546## Lock Screen and Dynamic Island4748`ORIXAudioWidgets/RecordingLiveActivity.swift` presents the recording title, a status line, an elapsed-time display and two buttons. While recording, the time is a system-rendered timer counting up from `updatedAt − elapsed`, so it advances without the app pushing updates; while paused it is a fixed value. The buttons are `LiveActivityIntent`s — pause/resume and add marker — which iOS runs in the app's process. Activities left over from a terminated process are ended at launch.4950Apple offers no API for arbitrary microphone controls on the Lock Screen; a Live Activity with intents is the supported route, and that is all the app claims.5152## Interruptions5354On `AVAudioSession.interruptionNotification`:5556- **began** — capture pauses, a marker labelled "⚠︎ Interrupted" is written at the current position, the Live Activity shows the state. Everything captured so far is already on disk.57- **ended** — if the system includes `.shouldResume`, the session is reactivated and recording resumes; otherwise the app waits for the user and says so.5859On `mediaServicesWereResetNotification` the recording is stopped and saved up to that point.6061## What the app does not do6263- It does not record without a visible indicator.64- It does not use unsupported tricks to stay alive (silent audio playback, location updates and the like).65- It does not claim to survive force-quit, device shutdown or every interruption. When the process ends, the master on disk is offered for recovery at the next launch.6667## Device test plan6869To be run on a physical iPhone before any release; none of these has been done.70711. Record 60 minutes with the screen locked and the phone in a pocket; compare the file duration with a stopwatch.722. Receive a phone call during a recording; decline it; accept it; check the marker and the resumed audio.733. Trigger an alarm and a Siri request during a recording.744. Connect and disconnect wired headphones, AirPods and a USB microphone mid-recording.755. Use the Live Activity buttons from the Lock Screen and the Dynamic Island.766. Force-quit during a recording; relaunch; recover.777. Record until storage is nearly full.788. Measure battery drain per hour with the waveform visible and with the screen locked.79