Merge pull request #15 from BuildWithAIs/feat/low-volume-enhancement-rebase

feat(audio): add low-volume enhancement mode

Author: yexia553

electron/main/README.md

@@ -4,7 +4,7 @@ Electron 主进程目录，负责窗口管理、IPC、录音流程、ASR/LLM 调
 
 ## 文件列表
 
-- `main.ts` - 应用入口；创建后台/设置/浮窗窗口、托盘菜单与 IPC 处理，协调 PTT 录音 → 转录 → LLM 润色 → 注入流程、会话取消与 FFmpeg 初始化（系统语言随窗口聚焦同步）。
+- `main.ts` - 应用入口；创建后台/设置/浮窗窗口、托盘菜单与 IPC 处理，协调 PTT 录音 → 转录 → LLM 润色 → 注入流程、会话取消与 FFmpeg 初始化，并向音频处理器注入 ASR/低音量模式配置（系统语言随窗口聚焦同步）。
 - `i18n.ts` - 主进程 i18next 初始化与语言切换，广播语言快照到各窗口。
 - `env.ts` - 运行时环境与资源路径解析（开发/生产）。
 - `config-manager.ts` - 使用 `electron-store` 持久化应用偏好、ASR 配置、LLM 润色开关与快捷键配置。

electron/main/__tests__/config-manager.test.ts

@@ -111,4 +111,23 @@ describe('ConfigManager', () => {
       enabled: false,
     })
   })
+
+  it('enables low volume mode by default for new installs', async () => {
+    const configManager = await createManager()
+    expect(configManager.getASRConfig().lowVolumeMode).toBe(true)
+  })
+
+  it('migrates existing users to low volume mode disabled', async () => {
+    seedData = {
+      asr: {
+        provider: 'glm',
+        region: 'cn',
+        apiKeys: { cn: 'legacy', intl: '' },
+        endpoint: '',
+        language: 'auto',
+      },
+    }
+    const configManager = await createManager()
+    expect(configManager.getASRConfig().lowVolumeMode).toBe(false)
+  })
 })

electron/main/__tests__/main.test.ts

@@ -42,7 +42,9 @@ const mockSendLanguageSnapshotToWindow = vi.hoisted(() => vi.fn())
 const mockT = vi.hoisted(() => vi.fn((key: string) => `t:${key}`))
 
 const mockGetAppConfig = vi.hoisted(() => vi.fn(() => ({ language: 'en', autoLaunch: true })))
-const mockGetASRConfig = vi.hoisted(() => vi.fn(() => ({ region: 'cn', apiKeys: {} })))
+const mockGetASRConfig = vi.hoisted(() =>
+  vi.fn(() => ({ provider: 'glm', region: 'cn', apiKeys: {}, lowVolumeMode: true })),
+)
 const mockGetLLMRefineConfig = vi.hoisted(() =>
   vi.fn(() => ({
     enabled: true,
@@ -231,7 +233,14 @@ describe('main startup', () => {
       openAtLogin: true,
       openAsHidden: true,
     })
-    expect(mockASRProviderCtor).toHaveBeenCalledWith({ region: 'cn', apiKeys: {} })
+    expect(mockGetASRConfig).toHaveBeenCalled()
+    expect(mockASRProviderCtor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        region: 'cn',
+        apiKeys: {},
+        lowVolumeMode: true,
+      }),
+    )
     expect(mockLLMProviderCtor).toHaveBeenCalledWith(
       {
         enabled: true,
@@ -245,6 +254,7 @@ describe('main startup', () => {
     expect(mockInitProcessor).toHaveBeenCalledWith(
       expect.objectContaining({
         getAsrProvider: expect.any(Function),
+        getASRConfig: expect.any(Function),
         initializeASRProvider: expect.any(Function),
         getLlmProvider: expect.any(Function),
         initializeLLMProvider: expect.any(Function),

electron/main/audio/README.md

@@ -6,6 +6,6 @@
 
 - `index.ts` - 音频模块统一导出。
 - `session-manager.ts` - 会话生命周期管理（开始/停止/取消）与 HUD 状态更新。
-- `processor.ts` - 音频处理流水线（保存、转码、ASR、LLM 润色、写历史、注入、清理，润色失败时回退原文）。
-- `converter.ts` - FFmpeg 初始化与 WebM → MP3 转换。
+- `processor.ts` - 音频处理流水线（保存、按低音量模式选择增益转码、ASR、LLM 润色、写历史、注入、清理，润色失败时回退原文）。
+- `converter.ts` - FFmpeg 初始化与 WebM → MP3 转换（支持可选 `gainDb` 音量增强）。
 - `__tests__/` - 音频会话与处理流水线测试。

electron/main/audio/__tests__/README.md

@@ -3,5 +3,5 @@
 主进程音频模块测试。
 
 - `session-manager.test.ts` - 录音会话开始/停止/取消与 HUD 交互。
-- `processor.test.ts` - 音频流水线（保存/转码/ASR/LLM 润色/注入/清理）与异常分支。
-- `converter.test.ts` - FFmpeg 初始化与音频格式转换成功/失败。
+- `processor.test.ts` - 音频流水线（保存/转码/低音量模式增益/ASR/LLM 润色/注入/清理）与异常分支。
+- `converter.test.ts` - FFmpeg 初始化、音频格式转换与可选增益滤镜分支。

electron/main/audio/__tests__/converter.test.ts

@@ -9,6 +9,7 @@ let lastCommand: {
     toFormat: ReturnType<typeof vi.fn>
     audioCodec: ReturnType<typeof vi.fn>
     audioBitrate: ReturnType<typeof vi.fn>
+    audioFilters: ReturnType<typeof vi.fn>
     on: ReturnType<typeof vi.fn>
     save: ReturnType<typeof vi.fn>
   }
@@ -21,6 +22,7 @@ const createCommand = () => {
     toFormat: vi.fn(() => chain),
     audioCodec: vi.fn(() => chain),
     audioBitrate: vi.fn(() => chain),
+    audioFilters: vi.fn(() => chain),
     on: vi.fn((event: string, handler: (err?: Error) => void) => {
       handlers[event] = handler
       return chain
@@ -97,6 +99,16 @@ describe('audio converter', () => {
 
     await expect(convertToMP3('/input.webm', '/output.mp3')).resolves.toBeUndefined()
     expect(lastCommand?.chain.save).toHaveBeenCalledWith('/output.mp3')
+    expect(lastCommand?.chain.audioFilters).not.toHaveBeenCalled()
+  })
+
+  it('applies gain filter when gainDb is provided', async () => {
+    const { convertToMP3 } = await loadConverter()
+
+    await expect(
+      convertToMP3('/input.webm', '/output.mp3', { gainDb: 10 }),
+    ).resolves.toBeUndefined()
+    expect(lastCommand?.chain.audioFilters).toHaveBeenCalledWith('volume=10dB')
   })
 
   it('rejects when ffmpeg conversion fails', async () => {

electron/main/audio/__tests__/processor.test.ts

@@ -77,6 +77,7 @@ describe('audio processor', () => {
     const { initProcessor, handleAudioData } = await loadProcessor()
     initProcessor({
       getAsrProvider: () => null,
+      getASRConfig: () => ({ provider: 'glm', region: 'cn', apiKeys: { cn: '', intl: '' } }),
       initializeASRProvider: vi.fn(),
     })
 
@@ -105,6 +106,12 @@ describe('audio processor', () => {
     const getAsrProvider = vi.fn(() => ({ transcribe }) as any)
     initProcessor({
       getAsrProvider,
+      getASRConfig: () => ({
+        provider: 'glm',
+        region: 'cn',
+        apiKeys: { cn: '', intl: '' },
+        lowVolumeMode: true,
+      }),
       initializeASRProvider: vi.fn(),
     })
 
@@ -115,7 +122,9 @@ describe('audio processor', () => {
     await vi.runAllTimersAsync()
     vi.useRealTimers()
 
-    expect(mockConvertToMP3).toHaveBeenCalled()
+    expect(mockConvertToMP3).toHaveBeenCalledWith(expect.any(String), expect.any(String), {
+      gainDb: 10,
+    })
     expect(transcribe).toHaveBeenCalled()
     expect(mockUpdateSession).toHaveBeenCalledWith({
       transcription: 'hello world',
@@ -149,6 +158,7 @@ describe('audio processor', () => {
 
     initProcessor({
       getAsrProvider: () => ({ transcribe }) as any,
+      getASRConfig: () => ({ provider: 'glm', region: 'cn', apiKeys: { cn: '', intl: '' } }),
       initializeASRProvider: vi.fn(),
     })
 
@@ -171,6 +181,7 @@ describe('audio processor', () => {
 
     initProcessor({
       getAsrProvider: () => null,
+      getASRConfig: () => ({ provider: 'glm', region: 'cn', apiKeys: { cn: '', intl: '' } }),
       initializeASRProvider: vi.fn(),
     })
 
@@ -208,6 +219,7 @@ describe('audio processor', () => {
 
     initProcessor({
       getAsrProvider: () => ({ transcribe }) as any,
+      getASRConfig: () => ({ provider: 'glm', region: 'cn', apiKeys: { cn: '', intl: '' } }),
       initializeASRProvider: vi.fn(),
       getLlmProvider: () =>
         ({
@@ -248,6 +260,7 @@ describe('audio processor', () => {
 
     initProcessor({
       getAsrProvider: () => ({ transcribe }) as any,
+      getASRConfig: () => ({ provider: 'glm', region: 'cn', apiKeys: { cn: '', intl: '' } }),
       initializeASRProvider: vi.fn(),
       getLlmProvider: () =>
         ({
@@ -267,4 +280,71 @@ describe('audio processor', () => {
     })
     expect(mockInjectText).toHaveBeenCalledWith('raw text')
   })
+
+  it('does not apply gain when low volume mode is disabled', async () => {
+    const { initProcessor, handleAudioData } = await loadProcessor()
+    const session = {
+      id: 'session-1',
+      startTime: new Date(),
+      status: 'recording',
+      duration: 1200,
+    }
+    mockGetCurrentSession.mockReturnValue(session)
+
+    const transcribe = vi.fn().mockResolvedValue({
+      text: 'hello world',
+      id: 't-5',
+      created: Date.now(),
+      model: 'glm',
+    })
+    initProcessor({
+      getAsrProvider: () => ({ transcribe }) as any,
+      getASRConfig: () => ({
+        provider: 'glm',
+        region: 'cn',
+        apiKeys: { cn: '', intl: '' },
+        lowVolumeMode: false,
+      }),
+      initializeASRProvider: vi.fn(),
+    })
+
+    await handleAudioData(Buffer.from('audio'))
+
+    expect(mockConvertToMP3).toHaveBeenCalledWith(expect.any(String), expect.any(String), {
+      gainDb: undefined,
+    })
+  })
+
+  it('applies default gain when low volume mode is undefined', async () => {
+    const { initProcessor, handleAudioData } = await loadProcessor()
+    const session = {
+      id: 'session-1',
+      startTime: new Date(),
+      status: 'recording',
+      duration: 1200,
+    }
+    mockGetCurrentSession.mockReturnValue(session)
+
+    const transcribe = vi.fn().mockResolvedValue({
+      text: 'hello world',
+      id: 't-6',
+      created: Date.now(),
+      model: 'glm',
+    })
+    initProcessor({
+      getAsrProvider: () => ({ transcribe }) as any,
+      getASRConfig: () => ({
+        provider: 'glm',
+        region: 'cn',
+        apiKeys: { cn: '', intl: '' },
+      }),
+      initializeASRProvider: vi.fn(),
+    })
+
+    await handleAudioData(Buffer.from('audio'))
+
+    expect(mockConvertToMP3).toHaveBeenCalledWith(expect.any(String), expect.any(String), {
+      gainDb: 10,
+    })
+  })
 })

electron/main/audio/converter.ts

@@ -17,6 +17,10 @@ import { t } from '../i18n'
 let ffmpeg: any
 let ffmpegInitialized = false
 
+export interface ConvertToMP3Options {
+  gainDb?: number
+}
+
 /**
  * 初始化 FFmpeg
  *
@@ -61,7 +65,11 @@ export function initializeFfmpeg(): void {
  * @returns Promise<void> - 转换完成时 resolve
  * @throws {Error} 转换失败时 reject
  */
-export function convertToMP3(inputPath: string, outputPath: string): Promise<void> {
+export function convertToMP3(
+  inputPath: string,
+  outputPath: string,
+  options?: ConvertToMP3Options,
+): Promise<void> {
   const conversionStartTime = Date.now()
   return new Promise((resolve, reject) => {
     // 确保 ffmpeg 已初始化
@@ -70,11 +78,17 @@ export function convertToMP3(inputPath: string, outputPath: string): Promise<voi
     console.log(`[Audio:Converter] Converting audio to MP3...`)
     console.log(`[Audio:Converter]   Input: ${inputPath}`)
     console.log(`[Audio:Converter]   Output: ${outputPath}`)
+    if (typeof options?.gainDb === 'number') {
+      console.log(`[Audio:Converter]   Gain: +${options.gainDb}dB`)
+    }
+
+    const command = ffmpeg(inputPath).toFormat('mp3').audioCodec('libmp3lame').audioBitrate('128k')
+
+    if (typeof options?.gainDb === 'number') {
+      command.audioFilters(`volume=${options.gainDb}dB`)
+    }
 
-    ffmpeg(inputPath)
-      .toFormat('mp3')
-      .audioCodec('libmp3lame')
-      .audioBitrate('128k')
+    command
       .on('end', () => {
         const duration = Date.now() - conversionStartTime
         console.log(`[Audio:Converter] ⏱️ Conversion completed in ${duration}ms`)

electron/main/audio/processor.ts

@@ -15,6 +15,7 @@
 import { app } from 'electron'
 import fs from 'fs'
 import path from 'node:path'
+import { LOW_VOLUME_GAIN_DB } from '../../shared/constants'
 import { updateOverlay, hideOverlay } from '../window/overlay'
 import { t } from '../i18n'
 import { historyManager } from '../history-manager'
@@ -23,6 +24,7 @@ import { convertToMP3 } from './converter'
 import { getCurrentSession, updateSession, clearSession } from './session-manager'
 import type { ASRProvider } from '../asr-provider'
 import type { LLMProvider } from '../llm-provider'
+import type { ASRConfig } from '../../shared/types'
 
 /**
  * 处理器外部依赖
@@ -31,6 +33,8 @@ import type { LLMProvider } from '../llm-provider'
 type ProcessorDeps = {
   /** 获取 ASR Provider 实例 */
   getAsrProvider: () => ASRProvider | null
+  /** 获取当前 ASR 配置 */
+  getASRConfig: () => ASRConfig
   /** 初始化 ASR Provider */
   initializeASRProvider: () => void
   /** 获取 LLM Provider 实例 */
@@ -87,8 +91,13 @@ export async function handleAudioData(buffer: Buffer): Promise<void> {
     console.log(`[Audio:Processor] ⏱️ File save: ${saveDuration}ms`)
 
     // Step 2: 转换为 MP3
+    const asrConfig = deps.getASRConfig()
+    const lowVolumeModeEnabled = asrConfig.lowVolumeMode ?? true
+    console.log(`[Audio:Processor] Low volume mode enabled: ${lowVolumeModeEnabled}`)
     const conversionStartTime = Date.now()
-    await convertToMP3(tempWebmPath, tempMp3Path)
+    await convertToMP3(tempWebmPath, tempMp3Path, {
+      gainDb: lowVolumeModeEnabled ? LOW_VOLUME_GAIN_DB : undefined,
+    })
     const conversionDuration = Date.now() - conversionStartTime
 
     // 检查取消

electron/main/config-manager.ts

@@ -29,6 +29,7 @@ const defaultConfig: AppConfig = {
       cn: '',
       intl: '',
     },
+    lowVolumeMode: true,
     // apiKey: '',  // Deprecated, removed from default
     endpoint: '',
     language: 'auto',
@@ -67,6 +68,17 @@ export class ConfigManager {
         this.store.delete('asr.apiKey' as any) // 迁移后删除旧字段
       }
     }
+
+    // 低音量模式迁移策略：
+    // - 新安装：defaultConfig 中已包含 lowVolumeMode=true，不处理
+    // - 旧用户升级：若 asr 存在但无该字段，则显式写入 false
+    if (
+      asrConfig &&
+      typeof asrConfig === 'object' &&
+      !Object.prototype.hasOwnProperty.call(asrConfig, 'lowVolumeMode')
+    ) {
+      this.store.set('asr.lowVolumeMode', false)
+    }
   }
 
   // 获取完整配置
@@ -101,6 +113,10 @@ export class ConfigManager {
     if (!config.region) {
       config.region = 'cn'
     }
+    // 确保 lowVolumeMode 存在
+    if (typeof config.lowVolumeMode !== 'boolean') {
+      config.lowVolumeMode = defaultConfig.asr.lowVolumeMode
+    }
     return config
   }