Repository Public
1// SP Notes Core2// File: Sources/SPNotesFeatures/Blocks/Audio/AudioBlockModel.swift3// Description: View model of a voice note (`audio` node): record / pause / resume / stop, hand-over or upload of the file,4// playback with seek and rate, the transcript (requested only by an explicit, paid action; polled; copied5// into the node by the client as API-NEXT-AI §6.2 says) and the AI summary. Every change of the node is6// handed to the editor through `onChange`: the editor saves the page, the server never edits it.7//8// Author: Simon-Pierre Boucher9// Contact: contact@spboucher.ai10import Foundation11import Observation12import SPNotesAPI13import SPNotesDocument14import SPNotesSync1516/// Pure helpers of the transcript (tested without audio).17public enum AudioTranscriptLogic {18 /// The segment being spoken at `time`: the last one that started; nil before the first or without segments.19 public static func activeIndex(_ segments: [TranscriptSegment], at time: Double) -> Int? {20 var best: Int?21 for (index, segment) in segments.enumerated() where segment.t <= time + 0.000_1 {22 if best == nil || segment.t >= segments[best!].t { best = index }23 }24 return best25 }2627 /// Where to seek for a segment: its start, clamped to the recording.28 public static func seekTime(_ segment: TranscriptSegment, duration: Double) -> Double {29 duration > 0 ? min(max(0, segment.t), duration) : max(0, segment.t)30 }3132 /// A transcript whose segments carry no timing (a text-only engine answers one segment at 0): seeking is useless.33 public static func hasTimings(_ segments: [TranscriptSegment]) -> Bool {34 segments.count > 1 || (segments.first?.t ?? 0) > 035 }3637 /// ISO 8601 in UTC with milliseconds, as ECMAScript's `toISOString()` (the form of `recordedAt` and `summary.at`).38 public static func timestamp(_ date: Date) -> String {39 let formatter = ISO8601DateFormatter()40 formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]41 formatter.timeZone = TimeZone(identifier: "UTC")42 return formatter.string(from: date)43 }4445 /// 0…1 position of a time in a recording.46 public static func fraction(time: Double, duration: Double) -> Double {47 duration > 0 ? min(1, max(0, time / duration)) : 048 }49}5051@Observable @MainActor52public final class AudioBlockModel {53 /// The recording side of the note.54 public enum Stage: Equatable, Sendable {55 /// Nothing recorded yet.56 case empty57 case recording58 case paused59 /// Recorded, the file is still only on this device (hand-over or upload failed, or is waiting for the user).60 case recorded61 case uploading62 /// The node has its attachment.63 case ready64 }6566 public enum Transcription: Equatable, Sendable {67 case none68 /// The request is being sent.69 case requesting70 /// The server is working; polled.71 case pending72 case done73 case failed(String)74 }7576 /// The node as it must be saved. Replaced by every action that changes it (then `onChange`).77 public private(set) var block: AudioBlock78 public private(set) var stage: Stage79 public private(set) var transcription: Transcription80 /// Seconds recorded so far.81 public private(set) var elapsed: Double = 082 public private(set) var inputLevel: Double = 083 /// The microphone was refused: explain where to allow it.84 public private(set) var permissionDenied = false85 public private(set) var isPlaying = false86 /// Seconds from the start of the playback position.87 public private(set) var position: Double = 088 public private(set) var playbackDuration: Double = 089 public private(set) var rate: Double = 190 /// Why the audio cannot be played (no file provider, download failed…); nil when playable or not tried.91 public private(set) var playbackFailure: FeatureFailure?92 public private(set) var isPreparingPlayback = false93 public var actionFailure: FeatureFailure?94 /// Ask for the summary with the transcript (one more model call on the server).95 public var wantsSummary = false96 public var onChange: ((AudioBlock) -> Void)?9798 public static let rates: [Double] = [0.75, 1, 1.25, 1.5, 2]99100 private let repository: AudioRepository101 private let pageId: String?102 private let recorder: any AudioRecording103 private let player: any AudioPlaying104 private let files: (any AudioFileProvider)?105 private let now: @Sendable () -> Date106 private let pollInterval: Duration107 private let pollTimeout: Duration108 private let tickInterval: Duration?109 private var recordingURL: URL?110 private var playerLoaded = false111 private var waitTask: Task<Void, Never>?112 private var ticker: Task<Void, Never>?113114 /// - Parameters:115 /// - block: the node to show; nil = a new voice note (nothing recorded yet).116 /// - pageId: the page the note belongs to (attachment owner).117 /// - files: the host's attachment files (playback of a stored note, offline-first hand-over of a recording).118 /// - tickInterval: refresh of the meters while recording or playing; nil = no timer (tests call `tick()`).119 public init(repositories: NotesRepositories, block: AudioBlock? = nil, pageId: String? = nil, files: (any AudioFileProvider)? = nil,120 recorder: (any AudioRecording)? = nil, player: (any AudioPlaying)? = nil, pollInterval: Duration = .seconds(2.5),121 pollTimeout: Duration = .seconds(600), tickInterval: Duration? = .milliseconds(120), now: @escaping @Sendable () -> Date = { Date() },122 onChange: ((AudioBlock) -> Void)? = nil) {123 repository = repositories.audio124 self.pageId = pageId125 self.files = files126 self.recorder = recorder ?? SystemAudioRecorder()127 self.player = player ?? SystemAudioPlayer()128 self.pollInterval = pollInterval129 self.pollTimeout = pollTimeout130 self.tickInterval = tickInterval131 self.now = now132 self.onChange = onChange133 var node = block ?? AudioBlock(attachmentId: "")134 if block == nil { node.attachmentId = nil }135 self.block = node136 stage = node.attachmentId == nil ? .empty : .ready137 transcription = Self.transcription(of: node)138 playbackDuration = node.duration139 self.player.onFinish = { [weak self] in self?.playbackFinished() }140 }141142 private static func transcription(of block: AudioBlock) -> Transcription {143 switch block.transcriptStatus {144 case .pending: return .pending145 case .done: return .done146 case .failed: return .failed("")147 default: return block.transcript.isEmpty ? .none : .done148 }149 }150151 // MARK: derived152153 public var segments: [TranscriptSegment] { block.transcript }154 public var activeSegmentIndex: Int? { isPlaying || position > 0 ? AudioTranscriptLogic.activeIndex(segments, at: position) : nil }155 public var summary: AudioSummary? { block.summary }156 public var hasAudio: Bool { stage == .ready || stage == .recorded || stage == .uploading }157 public var canRecord: Bool { stage == .empty }158 /// Transcription needs the attachment on the server.159 public var canTranscribe: Bool { stage == .ready && transcription != .requesting && transcription != .pending }160 public var isBusyTranscribing: Bool { transcription == .requesting || transcription == .pending }161 public var progress: Double { AudioTranscriptLogic.fraction(time: position, duration: playbackDuration) }162 public var title: String { block.title }163164 // MARK: load165166 /// A note whose transcript was left pending is asked once (a free read); nothing is ever requested here.167 public func load() async {168 guard stage == .ready, transcription == .pending, let id = block.attachmentId else { return }169 do {170 let state = try await repository.status(attachmentId: id)171 if state.isPending { startWaiting(id) } else { apply(state) }172 } catch {173 // The pending state stays on screen; the user can check again.174 actionFailure = FeatureFailure(error)175 }176 }177178 // MARK: recording179180 public func startRecording() async {181 guard stage == .empty else { return }182 actionFailure = nil183 guard await recorder.requestPermission() else {184 permissionDenied = true185 return186 }187 permissionDenied = false188 let url = FileManager.default.temporaryDirectory.appendingPathComponent("note-vocale-\(UUID().uuidString.lowercased()).m4a")189 do {190 try recorder.start(to: url)191 recordingURL = url192 elapsed = 0193 stage = .recording194 startTicker()195 } catch {196 actionFailure = FeatureFailure(kind: .other, message: L("L'enregistrement n'a pas pu démarrer. Vérifiez le micro."))197 }198 }199200 public func pauseRecording() {201 guard stage == .recording else { return }202 recorder.pause()203 elapsed = recorder.currentTime204 inputLevel = 0205 stage = .paused206 }207208 public func resumeRecording() {209 guard stage == .paused else { return }210 recorder.resume()211 stage = .recording212 startTicker()213 }214215 /// Ends the recording, then hands the file over (offline-first when the host provides it, upload otherwise).216 public func stopRecording() async {217 guard stage == .recording || stage == .paused else { return }218 let duration = recorder.stop()219 stopTicker()220 inputLevel = 0221 elapsed = duration222 block.duration = (duration * 100).rounded() / 100223 block.recordedAt = AudioTranscriptLogic.timestamp(now())224 if block.title.isEmpty { block.title = L("Note vocale") }225 playbackDuration = duration226 stage = .recorded227 await store()228 }229230 /// Throws the recording away (only before it became an attachment).231 public func discardRecording() {232 guard stage == .recorded || stage == .recording || stage == .paused else { return }233 if stage != .recorded { recorder.stop() }234 stopTicker()235 stopPlayback()236 if let recordingURL { try? FileManager.default.removeItem(at: recordingURL) }237 recordingURL = nil238 playerLoaded = false239 elapsed = 0240 inputLevel = 0241 position = 0242 playbackDuration = 0243 actionFailure = nil244 var fresh = block245 fresh.duration = 0246 fresh.recordedAt = nil247 block = fresh248 stage = .empty249 }250251 /// Hand-over or upload of the recorded file. Called by `stopRecording`; public for « Réessayer l'envoi ».252 public func store() async {253 guard stage == .recorded, let url = recordingURL else { return }254 stage = .uploading255 actionFailure = nil256 do {257 let id: String258 if let adopted = try await files?.adopt(recording: url, pageId: pageId) {259 id = adopted260 } else {261 id = try await repository.upload(fileURL: url, pageId: pageId, filename: "note-vocale.m4a", mimeType: "audio/mp4")262 }263 block.attachmentId = id264 stage = .ready265 onChange?(block)266 } catch {267 // The file stays on the device and on screen; nothing was lost.268 stage = .recorded269 actionFailure = FeatureFailure(error)270 }271 }272273 // MARK: playback274275 public func togglePlayback() async {276 if isPlaying {277 player.pause()278 position = player.currentTime279 isPlaying = false280 return281 }282 guard await preparePlayback() else { return }283 if playbackDuration > 0, position >= playbackDuration - 0.05 { player.seek(to: 0); position = 0 }284 player.rate = rate285 player.play()286 isPlaying = true287 startTicker()288 }289290 /// Opens the audio file (the fresh recording, or the attachment through the host's provider).291 @discardableResult292 public func preparePlayback() async -> Bool {293 if playerLoaded { return true }294 guard hasAudio else { return false }295 isPreparingPlayback = true296 defer { isPreparingPlayback = false }297 do {298 let url: URL299 if let recordingURL {300 url = recordingURL301 } else if let files, let id = block.attachmentId {302 url = try await files.localFileURL(attachmentId: id)303 } else {304 playbackFailure = FeatureFailure(kind: .other, message: L("La lecture n'est pas disponible ici : le fichier audio n'a pas été fourni."))305 return false306 }307 let duration = try player.load(url: url)308 if duration > 0 { playbackDuration = duration }309 playerLoaded = true310 playbackFailure = nil311 return true312 } catch let error as AudioEngineError {313 _ = error314 playbackFailure = FeatureFailure(kind: .other, message: L("Ce fichier audio ne peut pas être lu sur cet appareil."))315 return false316 } catch {317 playbackFailure = FeatureFailure(error)318 return false319 }320 }321322 /// Moves the playback position (works before the first play: the file is opened).323 public func seek(to time: Double) async {324 let target = min(max(0, time), playbackDuration > 0 ? playbackDuration : max(0, time))325 position = target326 guard await preparePlayback() else { return }327 player.seek(to: target)328 position = min(target, playbackDuration > 0 ? playbackDuration : target)329 }330331 public func seek(toFraction fraction: Double) async { await seek(to: min(1, max(0, fraction)) * playbackDuration) }332333 /// Tap on a transcript line: go there and play.334 public func seek(toSegment index: Int) async {335 guard segments.indices.contains(index) else { return }336 await seek(to: AudioTranscriptLogic.seekTime(segments[index], duration: playbackDuration))337 if !isPlaying, playerLoaded { await togglePlayback() }338 }339340 public func skip(_ seconds: Double) async { await seek(to: position + seconds) }341342 public func setRate(_ value: Double) {343 rate = min(2, max(0.5, value))344 player.rate = rate345 }346347 private func stopPlayback() {348 if isPlaying { player.pause() }349 isPlaying = false350 }351352 private func playbackFinished() {353 isPlaying = false354 position = playbackDuration355 stopTicker()356 }357358 // MARK: transcription359360 /// **Paid on the server.** Only called from the explicit button.361 public func requestTranscription(force: Bool = false) async {362 guard stage == .ready, let id = block.attachmentId, !isBusyTranscribing else { return }363 actionFailure = nil364 let previous = transcription365 transcription = .requesting366 do {367 let state = try await repository.transcribe(attachmentId: id, summarize: wantsSummary, force: force)368 if state.isPending {369 transcription = .pending370 block.transcriptStatus = .pending371 onChange?(block)372 startWaiting(id)373 } else {374 apply(state)375 }376 } catch {377 transcription = previous378 actionFailure = FeatureFailure(error)379 }380 }381382 /// Stops watching the job (the server finishes it anyway; « Vérifier » reads the result later, for free).383 public func stopWaiting() {384 waitTask?.cancel()385 waitTask = nil386 }387388 public var isWaiting: Bool { waitTask != nil }389390 /// Reads the state of the transcription once (free).391 public func checkTranscription() async {392 guard stage == .ready, let id = block.attachmentId else { return }393 actionFailure = nil394 do { apply(try await repository.status(attachmentId: id)) } catch { actionFailure = FeatureFailure(error) }395 }396397 /// For the tests: the end of the current polling.398 public func waitUntilSettled() async { await waitTask?.value }399400 private func startWaiting(_ id: String) {401 waitTask?.cancel()402 let repository = repository, interval = pollInterval, timeout = pollTimeout403 waitTask = Task { [weak self] in404 let result: Result<AudioTranscription, Error>405 do { result = .success(try await repository.waitForTranscription(attachmentId: id, interval: interval, timeout: timeout)) } catch { result = .failure(error) }406 guard !Task.isCancelled, let self else { return }407 self.waitTask = nil408 switch result {409 case .success(let state): self.apply(state)410 case .failure(let error):411 if !(error is CancellationError) { self.actionFailure = FeatureFailure(error) }412 }413 }414 }415416 /// Copies a state of the server into the node (API-NEXT-AI §6.2: the client writes the node).417 private func apply(_ state: AudioTranscription) {418 switch state.status {419 case TranscriptionStatus.pending:420 transcription = .pending421 if block.transcriptStatus != .pending { block.transcriptStatus = .pending; onChange?(block) }422 case TranscriptionStatus.done:423 let attrs = repository.nodeAttributes(from: state)424 block.transcript = attrs.transcript425 block.transcriptStatus = .done426 block.transcriptEngine = attrs.engine427 if block.duration <= 0, let duration = state.duration, duration > 0 {428 block.duration = duration429 if playbackDuration <= 0 { playbackDuration = duration }430 }431 if let summary = state.summary, let text = summary.text, !text.isEmpty {432 block[attr: "summary"] = .object([433 "text": .string(text),434 "decisions": .array((summary.decisions ?? []).map(JSONValue.string)),435 "tasks": .array((summary.tasks ?? []).map(JSONValue.string)),436 "model": summary.model.map(JSONValue.string) ?? .null,437 "at": summary.at.map { .string(AudioTranscriptLogic.timestamp($0)) } ?? .null,438 ])439 }440 transcription = .done441 // `done` with an error: the transcript is there, the summary could not be produced.442 if let error = state.error, !error.isEmpty, wantsSummary {443 actionFailure = FeatureFailure(kind: .server, message: L("La transcription est prête, mais le résumé n'a pas pu être produit."))444 }445 onChange?(block)446 case TranscriptionStatus.failed:447 transcription = .failed(state.error ?? "")448 block.transcriptStatus = .failed449 onChange?(block)450 default:451 transcription = block.transcript.isEmpty ? .none : .done452 }453 }454455 // MARK: title456457 public func setTitle(_ title: String) {458 let trimmed = title.trimmingCharacters(in: .whitespacesAndNewlines)459 guard trimmed != block.title else { return }460 block.title = trimmed461 if stage == .ready { onChange?(block) }462 }463464 // MARK: meters465466 /// Refreshes the elapsed time / input level / playback position from the engines.467 public func tick() {468 switch stage {469 case .recording:470 elapsed = recorder.currentTime471 inputLevel = recorder.level472 default: break473 }474 if isPlaying {475 if player.isPlaying { position = player.currentTime } else { playbackFinished() }476 }477 }478479 private func startTicker() {480 guard let tickInterval, ticker == nil else { return }481 ticker = Task { [weak self] in482 while !Task.isCancelled {483 try? await Task.sleep(for: tickInterval)484 guard let self, !Task.isCancelled else { return }485 self.tick()486 if self.stage != .recording, !self.isPlaying { self.ticker = nil; return }487 }488 }489 }490491 private func stopTicker() {492 guard stage != .recording, !isPlaying else { return }493 ticker?.cancel()494 ticker = nil495 }496497 /// Releases the engines when the detail closes (an unfinished recording is stopped and kept as `recorded`).498 public func close() {499 stopWaiting()500 ticker?.cancel()501 ticker = nil502 if stage == .recording || stage == .paused {503 let duration = recorder.stop()504 elapsed = duration505 block.duration = (duration * 100).rounded() / 100506 playbackDuration = duration507 stage = .recorded508 }509 stopPlayback()510 }511}512