refactor: extract AudioEngineManager, PostProcessingPipeline, ASREngineFactory from RecordingManager (#13)

Split the RecordingManager "God Class" (530 lines, 7 responsibilities) into
focused subsystems while keeping RecordingManager as a thin FSM coordinator:

- AudioEngineManager: AVAudioEngine lifecycle, tap installation, buffer→samples
  conversion, audio level calculation
- PostProcessingPipeline: coordinates TermNormalizer → ITN → CSC → Punctuation →
  CloudRewrite in sequence
- ASREngineFactory: creates/initializes ASR engine instances (Paraformer, QwenASR,
  DualEngine) and loads supporting models

RecordingManager is reduced from 530 to ~190 lines, owning only the FSM state
machine and delegating all work to the extracted subsystems.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ZhaoChaoqun

Sources/ASREngineFactory.swift

@@ -0,0 +1,254 @@
+import Foundation
+import os
+
+private let logger = Logger(subsystem: "com.typeless.app", category: "ASREngineFactory")
+
+/// Creates and initializes ASR engine instances based on the selected model type.
+///
+/// Encapsulates all model-loading logic (Streaming Paraformer, QwenASR, Dual Engine)
+/// and their supporting models (punctuation, CSC, ITN).
+///
+/// Thread safety:
+/// - `createEngine(for:pipeline:recognitionQueue:)` is async and called from a Task
+///   spawned on stateQueue. It writes to `pipeline` properties which are safe because
+///   no other code touches them during initialization (FSM is in `.initializing` state).
+enum ASREngineFactory {
+
+    /// Result of engine creation, containing the engine and a TermNormalizer.
+    struct Result {
+        let engine: (any ASREngine)?
+        let termNormalizer: TermNormalizer?
+    }
+
+    /// Creates an ASR engine for the given model type, also loading supporting models
+    /// (punctuation, CSC, ITN, TermNormalizer) into the provided pipeline.
+    ///
+    /// - Parameters:
+    ///   - modelType: Which ASR model to load.
+    ///   - pipeline: The post-processing pipeline to configure with supporting models.
+    ///   - recognitionQueue: The serial queue used by the ASR engine for decoding.
+    /// - Returns: The created ASR engine (nil on failure) and TermNormalizer.
+    static func createEngine(
+        for modelType: ASRModelType,
+        pipeline: PostProcessingPipeline,
+        recognitionQueue: DispatchQueue
+    ) async -> Result {
+        logger.info("开始加载语音识别模型 (\(modelType.displayName, privacy: .public))")
+
+        // Clear previous pipeline state
+        pipeline.reset()
+
+        var engine: (any ASREngine)?
+
+        switch modelType {
+        case .streamingParaformer:
+            engine = await createStreamingParaformer(pipeline: pipeline, recognitionQueue: recognitionQueue)
+        case .qwenASR:
+            engine = await createQwenASR(pipeline: pipeline, recognitionQueue: recognitionQueue)
+        case .dualEngine:
+            engine = await createDualEngine(pipeline: pipeline, recognitionQueue: recognitionQueue)
+        }
+
+        // Load TermNormalizer (shared by all engines)
+        let termNormalizer = TermNormalizer()
+        if termNormalizer != nil {
+            logger.info("TermNormalizer 词典加载成功")
+        } else {
+            logger.warning("TermNormalizer 词典加载失败，跳过专有名词标准化")
+        }
+        pipeline.termNormalizer = termNormalizer
+
+        return Result(engine: engine, termNormalizer: termNormalizer)
+    }
+
+    // MARK: - Streaming Paraformer
+
+    private static func createStreamingParaformer(
+        pipeline: PostProcessingPipeline,
+        recognitionQueue: DispatchQueue
+    ) async -> (any ASREngine)? {
+        guard SherpaOnnxManager.shared.isStreamingParaformerDownloaded(),
+              let paths = SherpaOnnxManager.shared.getStreamingParaformerPath() else {
+            logger.warning("Streaming Paraformer 模型未下载")
+            return nil
+        }
+
+        let itnFstPath = await loadITNFst()
+
+        guard let recognizer = SherpaOnnxOnlineRecognizer(
+            encoderPath: paths.encoderPath,
+            decoderPath: paths.decoderPath,
+            tokensPath: paths.tokensPath,
+            ruleFstsPath: itnFstPath
+        ) else {
+            logger.error("Streaming Paraformer 模型加载失败")
+            return nil
+        }
+
+        let engine = StreamingParaformerEngine(
+            recognizer: recognizer, recognitionQueue: recognitionQueue
+        )
+        logger.info("Streaming Paraformer 模型加载成功")
+
+        // Load CSC + punctuation post-processing modules
+        await loadPunctuation(into: pipeline)
+        loadCSC(into: pipeline)
+
+        return engine
+    }
+
+    // MARK: - QwenASR
+
+    private static func createQwenASR(
+        pipeline: PostProcessingPipeline,
+        recognitionQueue: DispatchQueue
+    ) async -> (any ASREngine)? {
+        guard SherpaOnnxManager.shared.isQwenASRModelDownloaded(),
+              let modelDir = SherpaOnnxManager.shared.getQwenASRModelDir() else {
+            logger.warning("QwenASR 模型未下载")
+            return nil
+        }
+
+        guard let recognizer = QwenASRStreamRecognizer(modelDir: modelDir) else {
+            logger.error("QwenASR 流式模型加载失败")
+            return nil
+        }
+
+        let engine = QwenASREngine(
+            recognizer: recognizer, recognitionQueue: recognitionQueue
+        )
+        logger.info("QwenASR 流式模型加载成功")
+
+        // Load standalone ITN for post-processing
+        if let itnFstPath = await loadITNFst() {
+            pipeline.itn = SherpaOnnxITN(ruleFsts: itnFstPath)
+            if pipeline.itn != nil {
+                logger.info("ITN 模型加载成功")
+            } else {
+                logger.warning("ITN 模型初始化失败")
+            }
+        }
+
+        return engine
+    }
+
+    // MARK: - Dual Engine
+
+    private static func createDualEngine(
+        pipeline: PostProcessingPipeline,
+        recognitionQueue: DispatchQueue
+    ) async -> (any ASREngine)? {
+        // 1. Load Streaming Paraformer
+        guard SherpaOnnxManager.shared.isStreamingParaformerDownloaded(),
+              let paths = SherpaOnnxManager.shared.getStreamingParaformerPath() else {
+            logger.warning("Dual Engine: Streaming Paraformer 模型未下载")
+            return nil
+        }
+
+        let itnFstPath = await loadITNFst()
+
+        guard let parafoRecognizer = SherpaOnnxOnlineRecognizer(
+            encoderPath: paths.encoderPath,
+            decoderPath: paths.decoderPath,
+            tokensPath: paths.tokensPath,
+            ruleFstsPath: itnFstPath
+        ) else {
+            logger.error("Dual Engine: Streaming Paraformer 模型加载失败")
+            return nil
+        }
+
+        let paraformerEngine = StreamingParaformerEngine(
+            recognizer: parafoRecognizer, recognitionQueue: recognitionQueue
+        )
+        logger.info("Dual Engine: Streaming Paraformer 加载成功")
+
+        // 2. Load QwenASR (for offline precise transcription)
+        guard SherpaOnnxManager.shared.isQwenASRModelDownloaded(),
+              let modelDir = SherpaOnnxManager.shared.getQwenASRModelDir() else {
+            logger.warning("Dual Engine: QwenASR 模型未下载")
+            return nil
+        }
+
+        guard let qwenRecognizer = QwenASRStreamRecognizer(modelDir: modelDir) else {
+            logger.error("Dual Engine: QwenASR 模型加载失败")
+            return nil
+        }
+        logger.info("Dual Engine: QwenASR 加载成功")
+
+        // 3. Create dual engine
+        let engine = DualEngineASR(
+            paraformerEngine: paraformerEngine,
+            qwenRecognizer: qwenRecognizer
+        )
+        logger.info("Dual Engine: 初始化完成")
+
+        // 4. Load standalone ITN for post-processing
+        if let itnFstPathForPostProcess = await loadITNFst() {
+            pipeline.itn = SherpaOnnxITN(ruleFsts: itnFstPathForPostProcess)
+            if pipeline.itn != nil {
+                logger.info("Dual Engine: ITN 模型加载成功")
+            }
+        }
+
+        return engine
+    }
+
+    // MARK: - Supporting Model Loaders
+
+    private static func loadPunctuation(into pipeline: PostProcessingPipeline) async {
+        if let punctPath = SherpaOnnxManager.shared.getPunctuationModelPath() {
+            pipeline.punctuator = SherpaOnnxPunctuation(modelPath: punctPath)
+            if pipeline.punctuator != nil {
+                logger.info("标点模型加载成功")
+            }
+        } else {
+            logger.info("标点模型未下载，正在下载...")
+            await withCheckedContinuation { continuation in
+                SherpaOnnxManager.shared.downloadPunctuationModel(progress: { progress in
+                    logger.debug("标点模型下载: \(progress, privacy: .public)")
+                }, completion: { success, error in
+                    if success, let punctPath = SherpaOnnxManager.shared.getPunctuationModelPath() {
+                        pipeline.punctuator = SherpaOnnxPunctuation(modelPath: punctPath)
+                        logger.info("标点模型下载并加载成功")
+                    } else {
+                        logger.error("标点模型下载失败: \(error ?? "未知错误", privacy: .public)")
+                    }
+                    continuation.resume()
+                })
+            }
+        }
+    }
+
+    private static func loadCSC(into pipeline: PostProcessingPipeline) {
+        if let paths = SherpaOnnxManager.shared.getCSCModelPath() {
+            pipeline.corrector = ChineseSpellingCorrector(modelPath: paths.modelPath, vocabPath: paths.vocabPath)
+            if pipeline.corrector != nil {
+                logger.info("CSC 纠错模型加载成功")
+            } else {
+                logger.warning("CSC 纠错模型加载失败")
+            }
+        } else {
+            logger.info("CSC 纠错模型未下载，跳过")
+        }
+    }
+
+    private static func loadITNFst() async -> String? {
+        if let fstPath = SherpaOnnxManager.shared.getITNFstPath() {
+            return fstPath
+        }
+
+        logger.info("ITN FST 模型未下载，正在下载...")
+        return await withCheckedContinuation { continuation in
+            SherpaOnnxManager.shared.downloadITNFst(progress: { progress in
+                logger.debug("ITN FST 下载: \(progress, privacy: .public)")
+            }, completion: { success, error in
+                if success, let fstPath = SherpaOnnxManager.shared.getITNFstPath() {
+                    continuation.resume(returning: fstPath)
+                } else {
+                    logger.error("ITN FST 下载失败: \(error ?? "未知错误", privacy: .public)")
+                    continuation.resume(returning: nil)
+                }
+            })
+        }
+    }
+}

Sources/AudioEngineManager.swift

@@ -0,0 +1,114 @@
+import Foundation
+import AVFoundation
+import os
+
+private let logger = Logger(subsystem: "com.typeless.app", category: "AudioEngineManager")
+
+/// Manages AVAudioEngine lifecycle: setup, tap installation, start/stop, and buffer-to-samples conversion.
+///
+/// Thread safety:
+/// - `start()` and `stop()` are called from `stateQueue` (via RecordingManager side effects).
+/// - The `installTap` callback fires on an internal Core Audio thread; the `onSamples` closure
+///   must handle its own synchronization.
+final class AudioEngineManager {
+
+    /// Callback invoked with 16kHz Float32 mono samples from the microphone.
+    /// Called on a Core Audio thread — callers must dispatch to appropriate queues.
+    var onSamples: (([Float]) -> Void)?
+
+    /// Callback invoked with normalized audio level (0.0–1.0).
+    /// Called on the main queue.
+    var onAudioLevel: ((Float) -> Void)?
+
+    private var audioEngine: AVAudioEngine?
+
+    // MARK: - Public API
+
+    /// Creates a new AVAudioEngine, installs a tap, and starts capturing audio.
+    /// Called from stateQueue.
+    func start() {
+        let engine = AVAudioEngine()
+        self.audioEngine = engine
+
+        let inputNode = engine.inputNode
+        let inputFormat = inputNode.outputFormat(forBus: 0)
+
+        let targetSampleRate: Double = 16000
+        guard let targetFormat = AVAudioFormat(
+            commonFormat: .pcmFormatFloat32,
+            sampleRate: targetSampleRate,
+            channels: 1,
+            interleaved: false
+        ) else {
+            logger.error("无法创建目标音频格式")
+            return
+        }
+
+        guard let converter = AVAudioConverter(from: inputFormat, to: targetFormat) else {
+            logger.error("无法创建音频转换器")
+            return
+        }
+
+        inputNode.installTap(onBus: 0, bufferSize: 4096, format: inputFormat) { [weak self] buffer, _ in
+            guard let self = self else { return }
+            guard let samples = self.extractSamples(buffer: buffer, converter: converter, targetFormat: targetFormat) else {
+                return
+            }
+
+            // Calculate RMS audio level and notify UI
+            if let onAudioLevel = self.onAudioLevel {
+                var sum: Float = 0
+                for s in samples { sum += s * s }
+                let rms = sqrt(sum / max(Float(samples.count), 1))
+                let db = 20 * log10(max(rms, 1e-6))
+                let normalized = max(0, min(1, (db + 50) / 50))
+                DispatchQueue.main.async {
+                    onAudioLevel(normalized)
+                }
+            }
+
+            self.onSamples?(samples)
+        }
+
+        do {
+            try engine.start()
+            logger.info("音频引擎已启动")
+        } catch {
+            logger.error("启动音频引擎失败: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    /// Removes the tap, stops the engine, and releases resources.
+    /// Called from stateQueue.
+    func stop() {
+        audioEngine?.inputNode.removeTap(onBus: 0)
+        audioEngine?.stop()
+        audioEngine = nil
+        logger.info("音频引擎已停止")
+    }
+
+    // MARK: - Private
+
+    /// Converts an AVAudioPCMBuffer to 16kHz Float32 mono samples.
+    private func extractSamples(buffer: AVAudioPCMBuffer, converter: AVAudioConverter, targetFormat: AVAudioFormat) -> [Float]? {
+        let ratio = targetFormat.sampleRate / buffer.format.sampleRate
+        let outputFrameCapacity = AVAudioFrameCount(Double(buffer.frameLength) * ratio)
+        guard let outputBuffer = AVAudioPCMBuffer(pcmFormat: targetFormat, frameCapacity: outputFrameCapacity) else { return nil }
+
+        var error: NSError?
+        let inputBlock: AVAudioConverterInputBlock = { _, outStatus in
+            outStatus.pointee = .haveData
+            return buffer
+        }
+
+        converter.convert(to: outputBuffer, error: &error, withInputFrom: inputBlock)
+
+        if let error = error {
+            logger.error("音频转换错误: \(error.localizedDescription, privacy: .public)")
+            return nil
+        }
+
+        guard let floatData = outputBuffer.floatChannelData else { return nil }
+        return Array(UnsafeBufferPointer(start: floatData[0], count: Int(outputBuffer.frameLength)))
+    }
+}