Repository Public
1// SP Notes iOS2// File: Core/Audio/VoiceRecorder.swift3// Description: Voice recording: the `AudioRecording` protocol (so the state machine is tested with a fake), the system recorder4// (AVAudioRecorder, AAC m4a mono 44.1 kHz, audio session with interruption and route-change handling), the5// microphone permission, and the observable state machine the screens use (idle → recording ⇄ paused → stopped).6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import AVFoundation10import Foundation11import Observation12import UIKit1314// MARK: - Permission1516enum MicrophonePermission: Equatable, Sendable {17 case undetermined, granted, denied18 /// Parental controls or a device profile forbid the microphone: Settings cannot change it.19 case restricted20}2122@MainActor23protocol MicrophoneAuthorizing {24 var status: MicrophonePermission { get }25 /// Asks the user (only shows the system alert the first time). Returns the status afterwards.26 func request() async -> MicrophonePermission27}2829@MainActor30struct SystemMicrophoneAuthorizer: MicrophoneAuthorizing {31 var status: MicrophonePermission {32 switch AVCaptureDevice.authorizationStatus(for: .audio) {33 case .authorized: return .granted34 case .denied: return .denied35 case .restricted: return .restricted36 case .notDetermined: return .undetermined37 @unknown default: return .denied38 }39 }4041 func request() async -> MicrophonePermission {42 guard status == .undetermined else { return status }43 _ = await AVAudioApplication.requestRecordPermission()44 return status45 }46}4748// MARK: - Recorder protocol4950/// What was recorded.51struct RecordedAudio: Equatable, Sendable {52 var fileURL: URL53 /// Seconds.54 var duration: Double55 var startedAt: Date56}5758enum RecorderEvent: Equatable, Sendable {59 /// A phone call, Siri, an alarm: the system took the audio session. The recorder is paused; the file is kept.60 case interruptionBegan61 case interruptionEnded(shouldResume: Bool)62 /// The input in use went away (AirPods removed, headset unplugged).63 case inputLost64 /// The encoder failed; what was written so far is kept.65 case encodingFailed66}6768enum RecorderError: LocalizedError, Equatable {69 case permissionDenied, cannotStart(String), notRecording70 var errorDescription: String? {71 switch self {72 case .permissionDenied: return String(localized: "SP Notes n’a pas accès au microphone.")73 case .cannotStart(let reason): return String(localized: "L’enregistrement n’a pas pu démarrer (\(reason)).")74 case .notRecording: return String(localized: "Aucun enregistrement en cours.")75 }76 }77}7879/// A recorder of one file at a time. Implemented by `SystemAudioRecorder`; faked in the unit tests.80@MainActor81protocol AudioRecording: AnyObject {82 var onEvent: ((RecorderEvent) -> Void)? { get set }83 /// Seconds recorded so far (pauses excluded).84 var currentTime: Double { get }85 /// Average power of the input in dBFS (-160 … 0), sampled now.86 func averagePower() -> Float87 func start(to url: URL) throws88 func pause()89 /// False when the system refused (the session is still taken by a call).90 func resume() -> Bool91 /// Finishes the file. Returns its duration in seconds.92 func stop() -> Double93 /// Stops and deletes the file.94 func cancel()95}9697/// The format of every recording of the app.98enum AudioFormat {99 static var settings: [String: Any] {100 [AVFormatIDKey: kAudioFormatMPEG4AAC, AVSampleRateKey: 44_100, AVNumberOfChannelsKey: 1,101 AVEncoderBitRateKey: 64_000, AVEncoderAudioQualityKey: AVAudioQuality.high.rawValue]102 }103}104105// MARK: - System recorder106107/// AVAudioRecorder behind `AudioRecording`. AAC in an m4a container, mono, 44.1 kHz, 64 kbit/s: about 0.5 MB per minute, a108/// format the server's transcription engine and every platform read.109@MainActor110final class SystemAudioRecorder: NSObject, AudioRecording, AVAudioRecorderDelegate {111 nonisolated static var settings: [String: Any] { AudioFormat.settings }112113 var onEvent: ((RecorderEvent) -> Void)?114 private var recorder: AVAudioRecorder?115 private var observers: [NSObjectProtocol] = []116117 var currentTime: Double { recorder?.currentTime ?? 0 }118119 func averagePower() -> Float {120 guard let recorder, recorder.isRecording else { return -160 }121 recorder.updateMeters()122 return recorder.averagePower(forChannel: 0)123 }124125 func start(to url: URL) throws {126 let session = AVAudioSession.sharedInstance()127 do {128 // playAndRecord: the same session plays the note back afterwards; the speaker rather than the receiver; Bluetooth headsets allowed129 try session.setCategory(.playAndRecord, mode: .default, options: [.defaultToSpeaker, .allowBluetoothHFP])130 try session.setActive(true)131 let recorder = try AVAudioRecorder(url: url, settings: Self.settings)132 recorder.delegate = self133 recorder.isMeteringEnabled = true134 guard recorder.prepareToRecord(), recorder.record() else { throw RecorderError.cannotStart("AVAudioRecorder") }135 self.recorder = recorder136 } catch let error as RecorderError {137 throw error138 } catch {139 throw RecorderError.cannotStart(error.localizedDescription)140 }141 observe()142 }143144 func pause() { recorder?.pause() }145146 func resume() -> Bool {147 guard let recorder else { return false }148 try? AVAudioSession.sharedInstance().setActive(true)149 return recorder.record()150 }151152 func stop() -> Double {153 guard let recorder else { return 0 }154 let clock = recorder.currentTime155 let url = recorder.url156 recorder.stop()157 finish()158 // the finished file is the truth (the player and the scrubber read it); the recorder's clock is the fallback159 let written = (try? AVAudioPlayer(contentsOf: url))?.duration ?? 0160 return written > 0 ? written : clock161 }162163 func cancel() {164 guard let recorder else { return }165 recorder.stop()166 recorder.deleteRecording()167 finish()168 }169170 private func finish() {171 recorder = nil172 observers.forEach(NotificationCenter.default.removeObserver)173 observers = []174 try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)175 }176177 private func observe() {178 let center = NotificationCenter.default179 observers.append(center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) { [weak self] note in180 let type = (note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt).flatMap(AVAudioSession.InterruptionType.init(rawValue:))181 let options = AVAudioSession.InterruptionOptions(rawValue: note.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0)182 MainActor.assumeIsolated {183 guard let self else { return }184 switch type {185 case .began: self.recorder?.pause(); self.onEvent?(.interruptionBegan)186 case .ended: self.onEvent?(.interruptionEnded(shouldResume: options.contains(.shouldResume)))187 default: break188 }189 }190 })191 observers.append(center.addObserver(forName: AVAudioSession.routeChangeNotification, object: nil, queue: .main) { [weak self] note in192 let reason = (note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt).flatMap(AVAudioSession.RouteChangeReason.init(rawValue:))193 guard reason == .oldDeviceUnavailable else { return }194 MainActor.assumeIsolated { self?.recorder?.pause(); self?.onEvent?(.inputLost) }195 })196 }197198 nonisolated func audioRecorderEncodeErrorDidOccur(_ recorder: AVAudioRecorder, error: Error?) {199 Task { @MainActor in self.onEvent?(.encodingFailed) }200 }201}202203// MARK: - Level meter (pure)204205/// Turns the recorder's dBFS power into what a meter draws.206enum LevelMeter {207 /// Below this the meter shows silence.208 static let floor: Float = -50209210 /// 0 … 1 from an average power in dBFS; a square-root curve so speech uses the upper half of the bar.211 static func normalized(power: Float) -> Float {212 guard power.isFinite, power > floor else { return 0 }213 let linear = min(1, (power - floor) / -floor)214 return linear.squareRoot()215 }216217 /// One step of the envelope follower: rises fast, falls slowly (no flicker between syllables).218 static func smoothed(previous: Float, target: Float, attack: Float = 0.6, release: Float = 0.3) -> Float {219 let factor = target > previous ? attack : release220 return min(1, max(0, previous + (target - previous) * factor))221 }222223 /// Appends a level to the history shown as bars, keeping the last `capacity`.224 static func appending(_ level: Float, to history: [Float], capacity: Int) -> [Float] {225 var next = history226 next.append(min(1, max(0, level)))227 if next.count > capacity { next.removeFirst(next.count - capacity) }228 return next229 }230}231232// MARK: - State machine233234/// The recorder the screens observe. Owns one recording at a time.235@MainActor236@Observable237final class VoiceRecorderModel {238 enum Phase: Equatable {239 case idle240 case requestingPermission241 /// The microphone is refused (`restricted`: Settings cannot change it).242 case denied(restricted: Bool)243 case recording244 case paused(PauseReason)245 case stopped(RecordedAudio)246 case failed(String)247 }248249 enum PauseReason: Equatable { case user, interruption, inputLost, background }250251 static let historyCapacity = 48252253 private(set) var phase: Phase = .idle254 /// Seconds recorded.255 private(set) var elapsed: Double = 0256 /// Smoothed input level 0 … 1.257 private(set) var level: Float = 0258 /// The last levels, oldest first (the bars of the meter).259 private(set) var history: [Float] = []260261 @ObservationIgnored private let recorder: any AudioRecording262 @ObservationIgnored private let authorizer: any MicrophoneAuthorizing263 @ObservationIgnored private let makeURL: () throws -> URL264 @ObservationIgnored private var fileURL: URL?265 @ObservationIgnored private var startedAt = Date()266 @ObservationIgnored private var ticker: Task<Void, Never>?267 @ObservationIgnored private var backgroundObserver: NSObjectProtocol?268 /// How often the meter samples; nil = no timer (the unit tests call `tick()` themselves).269 @ObservationIgnored private let sampling: Duration?270271 init(recorder: any AudioRecording, authorizer: any MicrophoneAuthorizing, sampling: Duration? = .milliseconds(50),272 makeURL: @escaping () throws -> URL = { try MediaTemp.newFileURL(named: VoiceRecorderModel.filename(for: Date())) }) {273 self.recorder = recorder274 self.authorizer = authorizer275 self.sampling = sampling276 self.makeURL = makeURL277 recorder.onEvent = { [weak self] in self?.handle($0) }278 // No background audio mode: iOS suspends the app soon after it leaves the foreground and the capture would stop without279 // notice. The recording is paused explicitly instead, and kept; the user resumes when back.280 backgroundObserver = NotificationCenter.default.addObserver(forName: UIApplication.didEnterBackgroundNotification, object: nil, queue: .main) { [weak self] _ in281 MainActor.assumeIsolated { self?.appDidEnterBackground() }282 }283 }284285 /// The system recorder with the system permission.286 static func system() -> VoiceRecorderModel { VoiceRecorderModel(recorder: SystemAudioRecorder(), authorizer: SystemMicrophoneAuthorizer()) }287288 static func filename(for date: Date) -> String {289 let formatter = DateFormatter()290 formatter.locale = Locale(identifier: "en_US_POSIX")291 formatter.dateFormat = "yyyy-MM-dd HH.mm.ss"292 return "Mémo vocal \(formatter.string(from: date)).m4a"293 }294295 var isActive: Bool {296 switch phase {297 case .recording, .paused: return true298 default: return false299 }300 }301302 /// The recording, once stopped.303 var result: RecordedAudio? { if case .stopped(let audio) = phase { return audio } else { return nil } }304305 /// Asks for the microphone if needed, then records. Never throws: a refusal or a failure is a phase the screen shows.306 func start() async {307 guard !isActive, phase != .requestingPermission else { return }308 var permission = authorizer.status309 if permission == .undetermined {310 phase = .requestingPermission311 permission = await authorizer.request()312 }313 switch permission {314 case .granted: break315 case .restricted: phase = .denied(restricted: true); return316 case .denied, .undetermined: phase = .denied(restricted: false); return317 }318 do {319 let url = try makeURL()320 try recorder.start(to: url)321 fileURL = url322 startedAt = Date()323 elapsed = 0; level = 0; history = []324 phase = .recording325 startTicker()326 } catch {327 phase = .failed(error.localizedDescription)328 }329 }330331 func pause() { pause(.user) }332333 private func pause(_ reason: PauseReason) {334 guard phase == .recording else { return }335 recorder.pause()336 elapsed = recorder.currentTime337 level = 0338 phase = .paused(reason)339 stopTicker()340 }341342 func resume() {343 guard case .paused = phase else { return }344 // a call still in progress refuses the session: the recording stays paused, nothing is lost345 guard recorder.resume() else { phase = .paused(.interruption); return }346 phase = .recording347 startTicker()348 }349350 /// Finishes the file. Returns the recording (also in `phase`), nil when nothing was being recorded.351 @discardableResult352 func stop() -> RecordedAudio? {353 guard isActive, let fileURL else { return nil }354 stopTicker()355 let reported = recorder.stop()356 let duration = reported > 0 ? reported : elapsed357 let audio = RecordedAudio(fileURL: fileURL, duration: duration, startedAt: startedAt)358 elapsed = duration359 level = 0360 phase = .stopped(audio)361 return audio362 }363364 /// Throws the recording away (or the stopped file) and goes back to idle.365 func discard() {366 stopTicker()367 if isActive { recorder.cancel() }368 if let fileURL { MediaTemp.discard(fileURL) }369 fileURL = nil370 elapsed = 0; level = 0; history = []371 phase = .idle372 }373374 /// Back to idle keeping the file (it was handed to a note).375 func reset() {376 guard !isActive else { return }377 fileURL = nil378 elapsed = 0; level = 0; history = []379 phase = .idle380 }381382 /// The permission may have changed in Settings while the app was away.383 func refreshPermission() {384 if case .denied = phase, authorizer.status == .granted || authorizer.status == .undetermined { phase = .idle }385 }386387 /// One sample of the meter and of the clock.388 func tick() {389 guard phase == .recording else { return }390 elapsed = recorder.currentTime391 level = LevelMeter.smoothed(previous: level, target: LevelMeter.normalized(power: recorder.averagePower()))392 history = LevelMeter.appending(level, to: history, capacity: Self.historyCapacity)393 }394395 private func handle(_ event: RecorderEvent) {396 switch event {397 case .interruptionBegan:398 // the recorder is already paused by the system: only the state follows399 if phase == .recording { elapsed = recorder.currentTime; level = 0; phase = .paused(.interruption); stopTicker() }400 case .interruptionEnded:401 break // never resumed automatically: the user decides (the other party may still be on the line)402 case .inputLost:403 if phase == .recording { elapsed = recorder.currentTime; level = 0; phase = .paused(.inputLost); stopTicker() }404 case .encodingFailed:405 // what was written is kept: the user gets the partial recording rather than nothing406 if isActive { stop() }407 }408 }409410 private func appDidEnterBackground() { pause(.background) }411412 private func startTicker() {413 guard let sampling else { return }414 ticker?.cancel()415 ticker = Task { [weak self] in416 while !Task.isCancelled {417 try? await Task.sleep(for: sampling)418 guard let self, !Task.isCancelled else { return }419 self.tick()420 }421 }422 }423424 private func stopTicker() { ticker?.cancel(); ticker = nil }425}426