Skip to content

Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more

10.9 KB
Raw Blame
import Foundation

/// One reconciler owns all media queries and commands. Recording events update
/// intent synchronously; they never wait for media control or delay first PCM.
@MainActor
final class MediaPlaybackService {
    static let shared = MediaPlaybackService(transport: MediaPlaybackProcessTransport())

    private struct Session {
        let id: Int
        var mayPause: Bool
    }

    private let transport: any MediaPlaybackTransport
    private let settle: @Sendable () async -> Void
    private let now: @Sendable () -> TimeInterval
    private var session: Session?
    private var revision: UInt64 = 0
    private var attemptedSession: Int?
    private var pausedTarget: MediaPlaybackSnapshot?
    private var worker: Task<Void, Never>?
    private var suspendedUntil: TimeInterval = 0
    private var isShuttingDown = false

    init(
        transport: any MediaPlaybackTransport,
        settle: @escaping @Sendable () async -> Void = {
            try? await Task.sleep(nanoseconds: 150_000_000)
        },
        now: @escaping @Sendable () -> TimeInterval = { ProcessInfo.processInfo.systemUptime }
    ) {
        self.transport = transport
        self.settle = settle
        self.now = now
    }

    func recordingStarted(sessionID: Int, enabled: Bool) {
        guard !self.isShuttingDown else { return }
        self.session = enabled ? Session(id: sessionID, mayPause: true) : nil
        self.revision &+= 1
        self.log("recording_started session=\(sessionID) enabled=\(enabled)")
        self.wake()
    }

    /// Prevent a slow query from issuing pause after the hotkey is released.
    /// A previously confirmed pause stays owned until transcription finishes.
    func recordingStopped(sessionID: Int) {
        guard self.session?.id == sessionID else { return }
        self.session?.mayPause = false
        self.revision &+= 1
        self.log("recording_stopped session=\(sessionID)")
        self.wake()
    }

    /// An older transcription finishing cannot resume a newer recording's media.
    func sessionFinished(sessionID: Int) {
        guard self.session?.id == sessionID else { return }
        self.session = nil
        self.revision &+= 1
        self.log("session_finished session=\(sessionID)")
        self.wake()
    }

    func beginShutdown() {
        guard !self.isShuttingDown else { return }
        self.isShuttingDown = true
        self.session = nil
        self.revision &+= 1
        self.wake()
    }

    func shutdown() async {
        self.beginShutdown()
        await self.waitUntilSettled()
    }

    /// Also used by deterministic tests; no continuous observer or polling task.
    func waitUntilSettled() async {
        while let worker = self.worker {
            await worker.value
        }
    }

    private func wake() {
        guard self.worker == nil else { return }
        self.worker = Task { await self.reconcile() }
    }

    private func reconcile() async {
        while true {
            let observedRevision = self.revision
            if let session = self.session {
                if session.mayPause, self.attemptedSession != session.id {
                    self.attemptedSession = session.id
                    await self.pause(sessionID: session.id)
                }
            } else if let target = self.pausedTarget {
                await self.resume(target: target)
            }
            guard observedRevision != self.revision else {
                self.worker = nil
                return
            }
        }
    }

    private func canPause(_ sessionID: Int) -> Bool {
        self.session?.id == sessionID && self.session?.mayPause == true
    }

    private func pause(sessionID: Int) async {
        guard self.now() >= self.suspendedUntil else {
            self.log("pause_suppressed session=\(sessionID) reason=player_backoff")
            return
        }
        guard let before = await self.queryBeforePause(sessionID: sessionID) else { return }
        guard self.canPause(sessionID) else {
            self.log("pause_skipped session=\(sessionID) reason=stale_recording")
            return
        }
        if let owned = self.pausedTarget, owned.matches(before), before.isPlaying == false {
            self.log("pause_retained session=\(sessionID) reason=already_owned")
            return
        }
        // A player change or manual playback invalidates our previous ownership.
        self.pausedTarget = nil
        guard before.isPlaying == true else {
            self.log("pause_skipped session=\(sessionID) reason=not_known_playing")
            return
        }
        let result = await self.transport.send(.pause)
        self.logCommand(.pause, result: result, sessionID: sessionID)
        // Even a timed-out helper might have sent its command before exiting.
        // Observe state before deciding whether we own a pause to restore.
        if let paused = await self.verify(target: before, playing: false, context: "pause session=\(sessionID)") {
            self.pausedTarget = paused
            self.log("pause_verified session=\(sessionID)")
        } else {
            self.backOff(context: "pause session=\(sessionID)")
        }
    }

    private func queryBeforePause(sessionID: Int) async -> MediaPlaybackSnapshot? {
        for attempt in 1...3 {
            guard self.canPause(sessionID) else { return nil }
            if let snapshot = await self.query(context: "before_pause session=\(sessionID) attempt=\(attempt)") {
                return snapshot
            }
            guard self.canPause(sessionID) else { return nil }
            if attempt < 3 { await self.settle() }
        }
        return nil
    }

    private func resume(target: MediaPlaybackSnapshot) async {
        // Retry a command only after fresh metadata confirms the same paused item.
        // Retain ownership while a new recording may inherit the pause.
        for attempt in 1...2 {
            guard let before = await self.queryBeforeResume() else {
                guard self.session == nil else { return }
                // Missing metadata is not evidence that our confirmed pause ended.
                // Allow one more bounded read cycle; never issue Play without a
                // matching paused item. Keep ownership for the next session/quit
                // event if the outage outlasts this recovery window.
                if !self.isShuttingDown, attempt < 2 {
                    await self.settle()
                    continue
                }
                self.log("resume_deferred reason=unknown_player ownership=retained")
                return
            }
            guard self.session == nil else {
                self.log("resume_skipped reason=new_recording")
                return
            }
            guard target.matches(before), before.isPlaying == false else {
                self.pausedTarget = nil
                self.log("resume_skipped reason=player_item_or_state_changed")
                return
            }
            let result = await self.transport.send(.play)
            self.logCommand(.play, result: result, sessionID: nil)
            if await self.verify(target: before, playing: true, context: "resume") != nil {
                self.pausedTarget = nil
                self.log("resume_verified")
                return
            }
            guard self.session == nil else { return }
            // Quit is best-effort within the app's overall termination deadline.
            // Do not add another command cycle while shutdown is in progress.
            if self.isShuttingDown || attempt == 2 {
                self.pausedTarget = nil
                self.backOff(context: "resume")
                return
            }
        }
    }

    private func queryBeforeResume() async -> MediaPlaybackSnapshot? {
        // Retain confirmed ownership across brief metadata outages. Retry reads,
        // never playback commands; give up after three bounded helper calls.
        for attempt in 1...3 {
            guard self.session == nil else { return nil }
            if let snapshot = await self.query(context: "before_resume attempt=\(attempt)") {
                return snapshot
            }
            guard self.session == nil else { return nil }
            if self.isShuttingDown { return nil }
            if attempt < 3 { await self.settle() }
        }
        return nil
    }

    private func verify(
        target: MediaPlaybackSnapshot, playing: Bool, context: String
    ) async -> MediaPlaybackSnapshot? {
        // Read at most twice; never retry a playback command blindly. This checks
        // reported state, not rendered video: Netflix can disagree with its UI.
        for attempt in 1...2 {
            if attempt > 1, self.isShuttingDown { break }
            await self.settle()
            guard let observed = await self.query(context: "verify_\(context) attempt=\(attempt)") else {
                continue
            }
            guard target.matches(observed) else {
                self.log("verification_failed context=\(context) reason=player_or_item_changed")
                return nil
            }
            if observed.isPlaying == playing { return observed }
        }
        self.log("verification_failed context=\(context) reason=state_not_confirmed")
        return nil
    }

    private func query(context: String) async -> MediaPlaybackSnapshot? {
        let started = self.now()
        let result = await self.transport.query()
        let elapsed = Int((self.now() - started) * 1000)
        switch result {
        case let .snapshot(snapshot):
            self.log(
                "query context=\(context) elapsedMs=\(elapsed) " +
                    "bundle=\(snapshot.bundleIdentifier) pid=\(snapshot.processID) " +
                    "playing=\(snapshot.isPlaying.map(String.init) ?? "unknown") " +
                    "hasTitle=\(snapshot.title != nil)"
            )
            return snapshot
        case let .unavailable(reason):
            self.log("query_unavailable context=\(context) elapsedMs=\(elapsed) reason=\(reason)")
            return nil
        }
    }

    private func backOff(context: String) {
        // A finite cooldown limits damage from hotkey spam against an unresponsive
        // player. The next recording after the cooldown performs a fresh query.
        self.suspendedUntil = self.now() + 10
        self.log("commands_suspended context=\(context) seconds=10")
    }

    private func logCommand(
        _ command: MediaPlaybackCommand, result: MediaPlaybackCommandResult, sessionID: Int?
    ) {
        let status: String
        switch result {
        case .helperCompleted: status = "helper_completed_player_unconfirmed"
        case let .failed(reason): status = "failed:\(reason)"
        }
        self.log("command=\(command.rawValue) session=\(sessionID.map(String.init) ?? "none") result=\(status)")
    }

    private func log(_ message: String) {
        DebugLogger.shared.info("MEDIA_CONTROL \(message)", source: "MediaPlaybackService")
    }
}