useWhisper完全指南：如何用React Hook轻松实现实时语音转录功能

gitblog_00019

902人浏览 · 2026-06-21 09:09:08

gitblog_00019 · 2026-06-21 09:09:08 发布

useWhisper完全指南：如何用React Hook轻松实现实时语音转录功能

【免费下载链接】use-whisper React hook for OpenAI Whisper with speech recorder, real-time transcription, and silence removal built-in 项目地址: https://gitcode.com/gh_mirrors/us/use-whisper

useWhisper是一个强大的React Hook，专为OpenAI Whisper API设计，内置语音录制、实时转录和静音消除功能。它让开发者能够轻松地在React应用中集成专业级别的语音识别能力，无需深入了解复杂的音频处理细节。

🌟 为什么选择useWhisper？

useWhisper提供了一站式的语音转录解决方案，主要优势包括：

简单易用：作为React Hook，它可以无缝集成到你的组件中，几行代码即可实现语音转录功能
实时处理：支持实时流式转录，让用户体验更加流畅
智能静音消除：自动检测并移除录音中的静音部分，提高转录准确性
高度可配置：提供丰富的配置选项，满足不同场景需求
TypeScript支持：完整的类型定义，提供更好的开发体验

🚀 快速开始

安装步骤

首先，你需要通过npm或yarn安装useWhisper包：

npm install @chengsokdara/use-whisper
# 或者
yarn add @chengsokdara/use-whisper

基本使用示例

以下是一个简单的使用示例，展示如何在React组件中集成useWhisper：

import { useWhisper } from '@chengsokdara/use-whisper';

function VoiceTranscriber() {
  const {
    recording,
    transcript,
    startRecording,
    stopRecording,
    pauseRecording
  } = useWhisper({
    apiKey: 'your-openai-api-key',
    autoTranscribe: true,
    removeSilence: true
  });

  return (
    <div>
      <h2>语音转录器</h2>
      <button onClick={startRecording} disabled={recording}>
        开始录音
      </button>
      <button onClick={pauseRecording} disabled={!recording}>
        暂停录音
      </button>
      <button onClick={stopRecording} disabled={!recording}>
        停止录音
      </button>
      
      <div>
        <h3>转录结果:</h3>
        <p>{transcript.text}</p>
      </div>
    </div>
  );
}

⚙️ 配置选项详解

useWhisper提供了丰富的配置选项，让你可以根据需求自定义转录行为。主要配置项包括：

核心配置

选项	类型	默认值	描述
apiKey	string	''	OpenAI API密钥
autoStart	boolean	false	组件挂载后是否自动开始录音
autoTranscribe	boolean	true	是否自动进行转录
mode	'transcriptions' \| 'translations'	'transcriptions'	工作模式：转录或翻译
removeSilence	boolean	false	是否移除录音中的静音部分

高级配置

// 完整的配置类型定义
export type UseWhisperConfig = {
  apiKey?: string;
  autoStart?: boolean;
  autoTranscribe?: boolean;
  mode?: 'transcriptions' | 'translations';
  nonStop?: boolean;
  removeSilence?: boolean;
  stopTimeout?: number;
  streaming?: boolean;
  timeSlice?: number;
  whisperConfig?: WhisperApiConfig;
  onDataAvailable?: (blob: Blob) => void;
  onTranscribe?: (blob: Blob) => Promise<UseWhisperTranscript>;
}

Whisper API配置

你可以通过whisperConfig选项直接配置Whisper API的参数：

export type WhisperApiConfig = {
  model?: 'whisper-1' | string;
  prompt?: string;
  response_format?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
  temperature?: number;
  language?: string;
}

📝 Hook返回值

useWhisper Hook返回以下状态和方法：

export type UseWhisperReturn = {
  recording: boolean;          // 是否正在录音
  speaking: boolean;           // 是否检测到说话
  transcribing: boolean;       // 是否正在转录
  transcript: UseWhisperTranscript; // 转录结果
  pauseRecording: () => Promise<void>; // 暂停录音
  startRecording: () => Promise<void>; // 开始录音
  stopRecording: () => Promise<void>;  // 停止录音
}

转录结果对象包含：

blob: 录音的Blob对象
text: 转录的文本结果

💡 实用场景示例

1. 实时会议转录

function MeetingTranscriber() {
  const {
    transcript,
    startRecording,
    stopRecording
  } = useWhisper({
    apiKey: process.env.REACT_APP_OPENAI_KEY,
    autoTranscribe: true,
    streaming: true,
    timeSlice: 2000,
    removeSilence: true,
    whisperConfig: {
      language: 'en',
      response_format: 'text'
    }
  });

  return (
    <div className="meeting-transcriber">
      <h2>会议实时转录</h2>
      <div className="controls">
        <button onClick={startRecording}>开始会议转录</button>
        <button onClick={stopRecording}>结束转录</button>
      </div>
      <div className="transcript">
        <h3>会议记录:</h3>
        <pre>{transcript.text || '等待发言...'}</pre>
      </div>
    </div>
  );
}

2. 多语言翻译转录

function MultilingualTranscriber() {
  const [language, setLanguage] = useState('es');
  
  const {
    transcript,
    startRecording,
    stopRecording,
    recording
  } = useWhisper({
    apiKey: process.env.REACT_APP_OPENAI_KEY,
    mode: 'translations', // 使用翻译模式
    autoTranscribe: true,
    whisperConfig: {
      language,
    }
  });

  return (
    <div>
      <h2>多语言翻译转录</h2>
      <select value={language} onChange={(e) => setLanguage(e.target.value)}>
        <option value="es">西班牙语</option>
        <option value="fr">法语</option>
        <option value="de">德语</option>
        <option value="zh">中文</option>
      </select>
      
      <div className="controls">
        <button onClick={startRecording} disabled={recording}>开始</button>
        <button onClick={stopRecording} disabled={!recording}>停止</button>
      </div>
      
      <div className="result">
        <h3>翻译结果:</h3>
        <p>{transcript.text}</p>
      </div>
    </div>
  );
}

🛠️ 常见问题解决

API密钥安全

不要在客户端代码中直接暴露你的OpenAI API密钥。在生产环境中，建议通过后端服务器代理API请求：

// 安全的使用方式
const { transcript, startRecording, stopRecording } = useWhisper({
  // 不直接提供apiKey
  onTranscribe: async (blob) => {
    // 将音频blob发送到你的后端
    const formData = new FormData();
    formData.append('audio', blob, 'recording.mp3');
    
    const response = await fetch('/api/transcribe', {
      method: 'POST',
      body: formData
    });
    
    const result = await response.json();
    return { text: result.transcript, blob };
  }
});