@mingxy/ocosay 1.0.0

package/src/core/backends/aplay-backend.ts

@@ -0,0 +1,160 @@
+/**
+ * Aplay Backend - Linux 平台音频播放后端
+ * 使用 ALSA 的 aplay 命令
+ */
+
+import { execFile, ChildProcess } from 'child_process'
+import { AudioBackend, AudioBackendEvents, BackendOptions } from './base'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { writeFileSync, unlinkSync, existsSync } from 'fs'
+
+// 白名单：只允许特定路径格式（禁止 - 防止命令注入）
+const SAFE_PATH_REGEX = /^[\w\/\.]+$/
+
+/**
+ * AplayBackend - Linux ALSA 音频播放后端
+ * 不支持真正的流式播放，需要先将数据写入临时文件
+ */
+export class AplayBackend implements AudioBackend {
+  readonly name = 'aplay'
+  readonly supportsStreaming = false
+  
+  private process?: ChildProcess
+  private tempFile?: string
+  private events?: AudioBackendEvents
+  private _started = false
+  private _paused = false
+  private _stopped = false
+  // P0-4: 缓冲所有chunk，等end()时一次性写入文件
+  private chunks: Buffer[] = []
+  private hasEnded = false
+  
+  constructor(options: BackendOptions = {}) {
+    this.events = options.events
+  }
+  
+  start(filePath: string): void {
+    if (this._started) return
+    
+    if (!SAFE_PATH_REGEX.test(filePath)) {
+      throw new Error(`Invalid file path: ${filePath}`)
+    }
+    
+    this.tempFile = filePath
+    this._started = true
+    this._stopped = false
+    
+    this.events?.onStart?.()
+    
+    // 启动播放进程
+    this.process = execFile('aplay', [filePath], (error) => {
+      if (this._stopped) return
+      
+      if (error) {
+        this.handleError(error)
+        return
+      }
+      
+      this._started = false
+      this.events?.onEnd?.()
+    })
+    
+    this.process.on('error', (error) => {
+      this.handleError(error)
+    })
+  }
+  
+  write(chunk: Buffer): void {
+    if (this._stopped) return
+    // P0-4: 缓冲所有chunk，等end()时一次性写入
+    this.chunks.push(chunk)
+  }
+  
+  end(): void {
+    if (this._stopped || this.hasEnded) return
+    this.hasEnded = true
+    
+    if (this.chunks.length === 0) return
+    
+    // P0-4: 所有chunk缓冲完毕后，一次性写入文件并播放
+    this.tempFile = join(tmpdir(), `ocosay-${Date.now()}.wav`)
+    writeFileSync(this.tempFile, Buffer.concat(this.chunks))
+    this.chunks = []
+    this.start(this.tempFile)
+  }
+  
+  pause(): void {
+    if (!this._started || this._paused || this._stopped) return
+    
+    if (this.process) {
+      try {
+        this.process.kill('SIGSTOP')
+        this._paused = true
+        this.events?.onPause?.()
+      } catch (e) {
+        // SIGSTOP 可能失败
+      }
+    }
+  }
+  
+  resume(): void {
+    if (!this._paused || this._stopped) return
+    
+    if (this.process) {
+      try {
+        this.process.kill('SIGCONT')
+        this._paused = false
+        this.events?.onResume?.()
+      } catch (e) {
+        // SIGCONT 可能失败
+      }
+    }
+  }
+  
+  stop(): void {
+    this._stopped = true
+    this._started = false
+    this._paused = false
+    
+    if (this.process) {
+      try {
+        this.process.kill('SIGTERM')
+      } catch (e) {
+        // 忽略错误
+      }
+      this.process = undefined
+    }
+    
+    this.cleanup()
+    this.chunks = []
+    this.hasEnded = false
+    
+    this.events?.onStop?.()
+  }
+  
+  setVolume(_volume: number): void {
+    // aplay 不支持命令行设置音量
+  }
+  
+  destroy(): void {
+    this.stop()
+  }
+  
+  private cleanup(): void {
+    if (this.tempFile && this.tempFile.startsWith(tmpdir())) {
+      try {
+        if (existsSync(this.tempFile)) {
+          unlinkSync(this.tempFile)
+        }
+      } catch (e) {
+        // 忽略清理错误
+      }
+      this.tempFile = undefined
+    }
+  }
+  
+  private handleError(error: Error): void {
+    this.events?.onError?.(error)
+  }
+}

package/src/core/backends/base.ts

@@ -0,0 +1,117 @@
+/**
+ * Audio Backend Interface
+ * 音频后端接口定义 - 统一各平台音频播放实现
+ */
+
+/**
+ * 音频后端接口
+ * 定义各平台音频后端必须实现的方法
+ */
+export interface AudioBackend {
+  /** 后端名称 */
+  readonly name: string
+  
+  /** 是否支持真正的流式播放（边收边播） */
+  readonly supportsStreaming: boolean
+  
+  /**
+   * 开始播放音频文件
+   * @param filePath 音频文件路径
+   */
+  start(filePath: string): void
+  
+  /**
+   * 写入音频数据块（用于流式播放）
+   * @param chunk 音频数据块
+   */
+  write(chunk: Buffer): void
+  
+  /**
+   * 结束写入，关闭流
+   */
+  end(): void
+  
+  /**
+   * 暂停播放
+   */
+  pause(): void
+  
+  /**
+   * 恢复播放
+   */
+  resume(): void
+  
+  /**
+   * 停止播放
+   */
+  stop(): void
+  
+  /**
+   * 获取当前播放位置（秒）
+   * 如果不支持返回 undefined
+   */
+  getCurrentTime?(): number | undefined
+  
+  /**
+   * 获取音频总时长（秒）
+   * 如果不支持返回 undefined
+   */
+  getDuration?(): number | undefined
+  
+  /**
+   * 设置音量
+   * @param volume 音量 0.0 - 1.0
+   */
+  setVolume?(volume: number): void
+  
+  /**
+   * 销毁后端，释放资源
+   */
+  destroy(): void
+}
+
+/**
+ * 音频后端事件回调接口
+ */
+export interface AudioBackendEvents {
+  /** 开始播放回调 */
+  onStart?: () => void
+  
+  /** 播放结束回调 */
+  onEnd?: () => void
+  
+  /** 错误回调 */
+  onError?: (error: Error) => void
+  
+  /** 暂停回调 */
+  onPause?: () => void
+  
+  /** 恢复回调 */
+  onResume?: () => void
+  
+  /** 停止回调 */
+  onStop?: () => void
+  
+  /** 进度回调（已写入字节数） */
+  onProgress?: (bytesWritten: number) => void
+}
+
+/**
+ * 后端配置选项
+ */
+export interface BackendOptions {
+  /** 音频格式 (mp3, wav, flac) */
+  format?: 'mp3' | 'wav' | 'flac'
+  
+  /** 采样率 (如 16000, 44100) */
+  sampleRate?: number
+  
+  /** 声道数 (1 = 单声道, 2 = 立体声) */
+  channels?: number
+  
+  /** 音量 0.0 - 1.0 */
+  volume?: number
+  
+  /** 事件回调 */
+  events?: AudioBackendEvents
+}

package/src/core/backends/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Audio Backends - 多平台音频后端统一导出
+ */
+
+// 接口和类型
+export { AudioBackend, AudioBackendEvents, BackendOptions } from './base'
+
+// 各平台后端实现
+export { NaudiodonBackend } from './naudiodon-backend'
+export { AfplayBackend } from './afplay-backend'
+export { AplayBackend } from './aplay-backend'
+export { PowerShellBackend } from './powershell-backend'
+
+import { AudioBackend, BackendOptions } from './base'
+import { NaudiodonBackend } from './naudiodon-backend'
+import { AfplayBackend } from './afplay-backend'
+import { AplayBackend } from './aplay-backend'
+import { PowerShellBackend } from './powershell-backend'
+
+/**
+ * 后端类型枚举
+ */
+export enum BackendType {
+  NAUDIODON = 'naudiodon',
+  AFPLAY = 'afplay',
+  APLAY = 'aplay',
+  POWERSHELL = 'powershell',
+  AUTO = 'auto'
+}
+
+let naudiodonCache: any = null
+
+async function tryLoadNaudiodon(): Promise<any> {
+  if (naudiodonCache !== null) {
+    return naudiodonCache
+  }
+  try {
+    naudiodonCache = await import('naudiodon')
+    return naudiodonCache
+  } catch (e) {
+    naudiodonCache = false
+    return null
+  }
+}
+
+function isNaudiodonAvailable(): boolean {
+  try {
+    require.resolve('naudiodon')
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * 创建音频后端
+ * @param type 后端类型，默认 AUTO（自动选择）
+ * @param options 后端配置选项
+ * @returns 音频后端实例
+ */
+export function createBackend(type: BackendType = BackendType.AUTO, options: BackendOptions = {}): AudioBackend {
+  const platform = process.platform
+  
+  if (type !== BackendType.AUTO) {
+    return createBackendByType(type, options)
+  }
+  
+  if (isNaudiodonAvailable()) {
+    try {
+      const naudiodon = require('naudiodon')
+      if (naudiodon) {
+        return new NaudiodonBackend(options)
+      }
+    } catch (e) {}
+  }
+  
+  switch (platform) {
+    case 'darwin':
+      return new AfplayBackend(options)
+    case 'linux':
+      return new AplayBackend(options)
+    case 'win32':
+      return new PowerShellBackend(options)
+    default:
+      throw new Error(`Unsupported platform: ${platform}`)
+  }
+}
+
+function createBackendByType(type: BackendType, options: BackendOptions): AudioBackend {
+  switch (type) {
+    case BackendType.NAUDIODON:
+      return new NaudiodonBackend(options)
+    case BackendType.AFPLAY:
+      return new AfplayBackend(options)
+    case BackendType.APLAY:
+      return new AplayBackend(options)
+    case BackendType.POWERSHELL:
+      return new PowerShellBackend(options)
+    default:
+      throw new Error(`Unknown backend type: ${type}`)
+  }
+}
+
+export function supportsStreaming(type: BackendType): boolean {
+  if (type === BackendType.AUTO) {
+    return isNaudiodonAvailable()
+  }
+  return type === BackendType.NAUDIODON
+}
+
+export function getDefaultBackendType(): BackendType {
+  const platform = process.platform
+  
+  if (supportsStreaming(BackendType.AUTO)) {
+    return BackendType.NAUDIODON
+  }
+  
+  switch (platform) {
+    case 'darwin':
+      return BackendType.AFPLAY
+    case 'linux':
+      return BackendType.APLAY
+    case 'win32':
+      return BackendType.POWERSHELL
+    default:
+      return BackendType.NAUDIODON
+  }
+}

package/src/core/backends/naudiodon-backend.ts

@@ -0,0 +1,164 @@
+/**
+ * Naudiodon Backend - 基于 PortAudio 的跨平台音频播放后端
+ * 支持真正的流式播放（边收边播）
+ */
+
+import { AudioBackend, AudioBackendEvents, BackendOptions } from './base'
+
+class UnsupportedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UnsupportedError'
+  }
+}
+
+interface NaudiodonAudioOutput {
+  start(): void
+  write(chunk: Buffer): void
+  end(): void
+  quit(): void
+  on(event: string, callback: (error: Error) => void): void
+}
+
+interface Naudiodon {
+  new (options: {
+    sampleRate?: number
+    channels?: number
+    bitDepth?: number
+  }): NaudiodonAudioOutput
+}
+
+declare global {
+  interface NodeModule {
+    require(id: 'naudiodon'): Naudiodon
+  }
+}
+
+export class NaudiodonBackend implements AudioBackend {
+  readonly name = 'naudiodon'
+  readonly supportsStreaming = true
+  
+  private audioOutput?: NaudiodonAudioOutput
+  private events?: AudioBackendEvents
+  private _started = false
+  private _paused = false
+  private _stopped = false
+  private sampleRate: number
+  private channels: number
+  private volume = 1.0
+  private bytesWritten = 0
+  
+  constructor(options: BackendOptions = {}) {
+    this.sampleRate = options.sampleRate || 16000
+    this.channels = options.channels || 1
+    this.events = options.events
+    this.volume = options.volume ?? 1.0
+  }
+  
+  start(_filePath: string): void {
+    if (this._started) return
+    
+    try {
+      const naudiodon = require('naudiodon') as Naudiodon
+      const AudioOutput = naudiodon as unknown as { new(options: { sampleRate: number; channels: number; bitDepth: number }): NaudiodonAudioOutput }
+      
+      this.audioOutput = new AudioOutput({
+        sampleRate: this.sampleRate,
+        channels: this.channels,
+        bitDepth: 16
+      })
+      
+      this.audioOutput.on('error', (error: Error) => {
+        this.handleError(error)
+      })
+      
+      this.audioOutput.start()
+      this._started = true
+      this._stopped = false
+      
+      this.events?.onStart?.()
+    } catch (error: any) {
+      if (error.code === 'MODULE_NOT_FOUND') {
+        throw new Error('naudiodon is not installed. Run: npm install naudiodon')
+      }
+      throw error
+    }
+  }
+  
+  write(chunk: Buffer): void {
+    if (!this._started || this._stopped) return
+    
+    if (this.audioOutput) {
+      const adjustedChunk = this.adjustVolume(chunk)
+      this.audioOutput.write(adjustedChunk)
+      this.bytesWritten += chunk.length
+      this.events?.onProgress?.(this.bytesWritten)
+    }
+  }
+  
+  end(): void {
+    if (this.audioOutput) {
+      this.audioOutput.end()
+    }
+  }
+  
+  pause(): void {
+    if (!this._started || this._paused || this._stopped) return
+    throw new UnsupportedError('naudiodon backend does not support pause')
+  }
+  
+  resume(): void {
+    if (!this._paused || this._stopped) return
+    this._paused = false
+    this.events?.onResume?.()
+  }
+  
+  stop(): void {
+    this._stopped = true
+    this._started = false
+    this._paused = false
+    
+    if (this.audioOutput) {
+      try {
+        this.audioOutput.quit()
+      } catch (e) {
+        // 忽略退出错误
+      }
+      this.audioOutput = undefined
+    }
+    
+    this.bytesWritten = 0
+    this.events?.onStop?.()
+  }
+  
+  getCurrentTime(): number {
+    return this.bytesWritten / (this.sampleRate * this.channels * 2)
+  }
+  
+  getDuration?(): number | undefined {
+    return undefined
+  }
+  
+  setVolume(volume: number): void {
+    this.volume = Math.max(0, Math.min(1, volume))
+  }
+  
+  destroy(): void {
+    this.stop()
+  }
+  
+  private adjustVolume(chunk: Buffer): Buffer {
+    if (this.volume === 1.0) return chunk
+    
+    const adjusted = Buffer.alloc(chunk.length)
+    for (let i = 0; i < chunk.length; i += 2) {
+      const sample = chunk.readInt16LE(i) * this.volume
+      adjusted.writeInt16LE(Math.round(sample), i)
+    }
+    return adjusted
+  }
+  
+  private handleError(error: Error): void {
+    this.events?.onError?.(error)
+  }
+}