Buzz API完全参考：开发者必备的接口调用手册
项目地址: https://gitcode.com/gh_mirrors/buz/buzz 1. 核心架构概览
Buzz作为基于OpenAI Whisper的本地音频转录/翻译工具，其API架构采用分层设计，主要包含以下核心模块：
1.1 核心API组件说明
| 组件 | 作用 | 关键方法 |
|---|---|---|
| TranscriptionModel | 模型配置与管理 | get_local_model_path(), is_available() |
| TranscriptionOptions | 转录参数配置 | - |
| FileTranscriptionTask | 转录任务定义 | - |
| FileTranscriber | 转录执行引擎 | transcribe(), stop() |
| TranscriptionService | 数据库交互服务 | create_transcription(), update_transcription_progress() |
2. 模型管理API
2.1 模型初始化与配置
from buzz.model_loader import TranscriptionModel, ModelType, WhisperModelSize
# 初始化Whisper模型
model = TranscriptionModel(
model_type=ModelType.WHISPER,
whisper_model_size=WhisperModelSize.BASE,
hugging_face_model_id="" # Whisper模型不需要此项
)
# 初始化Hugging Face模型
hf_model = TranscriptionModel(
model_type=ModelType.HUGGING_FACE,
whisper_model_size=None,
hugging_face_model_id="openai/whisper-base"
)
# 检查模型可用性
if not model.is_available():
# 下载模型
from buzz.model_loader import ModelDownloader
downloader = ModelDownloader(model=model)
downloader.run()
# 获取模型路径
model_path = model.get_local_model_path()
2.2 支持的模型类型
from enum import Enum
class ModelType(Enum):
WHISPER = "whisper"
WHISPER_CPP = "whispercpp"
HUGGING_FACE = "huggingface"
FASTER_WHISPER = "fasterwhisper"
OPEN_AI_WHISPER_API = "openaiapi"
class WhisperModelSize(Enum):
TINY = "tiny"
BASE = "base"
SMALL = "small"
MEDIUM = "medium"
LARGE = "large"
3. 转录任务API
3.1 创建转录任务
from buzz.transcriber.transcriber import (
FileTranscriptionTask, FileTranscriptionOptions,
TranscriptionOptions, Task, OutputFormat
)
# 配置转录参数
transcription_options = TranscriptionOptions(
model=model,
task=Task.TRANSCRIBE, # 或Task.TRANSLATE
language="zh", # None表示自动检测
initial_prompt="以下是中文语音识别",
word_level_timings=True, # 启用词级时间戳
openai_access_token="your_token_here" # OpenAI API模型需要
)
# 配置文件转录选项
file_options = FileTranscriptionOptions(
file_paths=["audio1.mp3", "audio2.wav"],
url=None, # 如果是URL转录则设置此项
output_formats={OutputFormat.SRT, OutputFormat.TXT}
)
# 创建任务
task = FileTranscriptionTask(
file_path="audio1.mp3",
url=None,
model_path=model_path,
transcription_options=transcription_options,
file_transcription_options=file_options,
output_directory="/path/to/output"
)
3.2 任务执行与管理
from buzz.file_transcriber_queue_worker import FileTranscriberQueueWorker
# 创建任务队列
worker = FileTranscriberQueueWorker()
# 添加任务
worker.add_task(task)
# 启动工作线程
worker.start()
# 取消任务
task_id = task.id # 获取任务ID
worker.cancel_task(task_id)
# 停止工作线程
worker.stop()
4. CLI命令行API
4.1 基本命令格式
# 基本语法
buzz add [OPTIONS] [file1 file2 ...]
4.2 常用命令示例
4.2.1 基础转录
# 使用默认模型转录音频文件
buzz add audio.mp3
# 指定模型大小和语言
buzz add -s medium -l zh audio.mp3
# 同时输出多种格式
buzz add --srt --vtt --txt audio.mp3
4.2.2 使用不同模型类型
# 使用Faster Whisper模型
buzz add -m fasterwhisper -s large audio.mp3
# 使用Hugging Face模型
buzz add -m huggingface --hfid openai/whisper-large audio.mp3
# 使用OpenAI API
buzz add -m openaiapi --openai-token your_token audio.mp3
4.2.3 高级选项
# 添加初始提示词和词级时间戳
buzz add -p "技术会议记录" -w audio.mp3
# 指定输出目录
buzz add -d ./transcripts audio1.mp3 audio2.mp3
# 批量处理URL
buzz add https://example.com/audio1.mp3 https://example.com/audio2.mp3
4.3 完整选项说明
Options:
-t, --task <task> 任务类型: transcribe/translate (默认: transcribe)
-m, --model-type <type> 模型类型: whisper/whispercpp/huggingface/fasterwhisper/openaiapi (默认: whisper)
-s, --model-size <size> 模型大小: tiny/base/small/medium/large (默认: tiny)
--hfid <id> Hugging Face模型ID (仅用于huggingface类型)
-l, --language <code> 语言代码 (如: zh, en, fr)
-p, --prompt <prompt> 初始提示文本
-w, --word-timestamps 启用词级时间戳
--openai-token <token> OpenAI API令牌
-d, --output-directory <dir> 输出目录
--srt 输出SRT格式
--vtt 输出VTT格式
--txt 输出TXT格式
--hide-gui 隐藏GUI界面
5. 转录结果处理API
5.1 转录结果结构
from typing import List, TypedDict
class Segment(TypedDict):
id: int
seek: int
start: float # 开始时间(秒)
end: float # 结束时间(秒)
text: str # 转录文本
tokens: List[int]
temperature: float
avg_logprob: float
compression_ratio: float
no_speech_prob: float
words: List[dict] # 词级时间戳(如果启用)
5.2 处理转录结果
# 假设transcriber是一个已完成转录的FileTranscriber实例
segments = transcriber.transcribe()
# 遍历结果
for segment in segments:
print(f"[{segment['start']:.2f} -> {segment['end']:.2f}]: {segment['text']}")
# 如果有词级时间戳
if 'words' in segment:
for word in segment['words']:
print(f" [{word['start']:.2f}]: {word['word']}")
# 保存为文件
from buzz.transcriber.file_transcriber import FileTranscriber
FileTranscriber.write_output(
path="output.srt",
segments=segments,
output_format=OutputFormat.SRT
)
6. 数据库交互API
6.1 转录任务管理
from buzz.db.service.transcription_service import TranscriptionService
from buzz.db.dao.transcription_dao import TranscriptionDAO
from buzz.db.dao.transcription_segment_dao import TranscriptionSegmentDAO
# 初始化服务
transcription_service = TranscriptionService(
transcription_dao=TranscriptionDAO(),
transcription_segment_dao=TranscriptionSegmentDAO()
)
# 创建转录记录
transcription_id = transcription_service.create_transcription(task)
# 更新任务进度
transcription_service.update_transcription_progress(
id=transcription_id,
progress=0.5 # 50%进度
)
# 完成转录并保存结果
transcription_service.update_transcription_as_completed(
id=transcription_id,
segments=segments # 从transcribe()获取的结果
)
# 获取转录片段
segments = transcription_service.get_transcription_segments(transcription_id)
7. 异常处理与错误码
7.1 常见异常类型
class CommandLineError(Exception):
"""命令行参数错误"""
class ModelDownloadError(Exception):
"""模型下载错误"""
class TranscriptionError(Exception):
"""转录过程错误"""
7.2 错误处理示例
try:
# 执行转录任务
segments = transcriber.transcribe()
except TranscriptionError as e:
# 记录错误
transcription_service.update_transcription_as_failed(
id=transcription_id,
error=str(e)
)
# 显示错误信息
from buzz.dialogs import show_model_download_error_dialog
show_model_download_error_dialog(parent=main_window, error=str(e))
8. 高级功能API
8.1 实时转录API
from buzz.recording import Recorder
from buzz.transcriber.recording_transcriber import RecordingTranscriber
# 初始化录音机
recorder = Recorder(input_device_index=0)
# 初始化实时转录器
transcriber = RecordingTranscriber(
transcription_options=transcription_options,
input_device_index=0,
sample_rate=16000,
model_path=model_path
)
# 开始录音和转录
recorder.start_recording()
transcriber.start()
# 处理转录结果
@transcriber.next_transcription.connect
def on_next_transcription(text: str):
print("实时转录结果:", text)
# 停止转录
transcriber.stop()
recorder.stop_recording()
8.2 音频翻译API
from buzz.translator import Translator
# 初始化翻译器
translator = Translator(
transcription_options=transcription_options,
advanced_settings_dialog=None
)
# 启动翻译器
translator.start()
# 加入待翻译文本
transcript = "Hello, how are you today?"
translator.enqueue(transcript, transcript_id=1)
# 接收翻译结果
@translator.translation_available.connect
def on_translation_available(translation: str, transcript_id: int):
print(f"翻译结果: {translation}")
# 停止翻译器
translator.stop()
9. 最佳实践与性能优化
9.1 模型选择建议
| 模型类型 | 优势 | 适用场景 |
|---|---|---|
| Whisper | 平衡速度和准确性 | 一般用途 |
| Faster Whisper | 速度快，内存占用低 | 实时应用 |
| Whisper.cpp | 极致性能优化 | 资源受限环境 |
| Hugging Face | 模型多样性 | 定制化需求 |
| OpenAI API | 无需本地资源 | 临时或低频次使用 |
9.2 性能优化技巧
# 1. 合理设置模型参数
transcription_options = TranscriptionOptions(
model=model,
task=Task.TRANSCRIBE,
language="zh",
initial_prompt="", # 不需要时清空提示词
word_level_timings=False, # 不需要时禁用词级时间戳
)
# 2. 批量处理任务
worker = FileTranscriberQueueWorker()
for file in large_file_list:
task = create_task(file) # 创建任务
worker.add_task(task)
worker.start()
# 3. 进度更新优化
def on_task_progress(progress: Tuple[int, int]):
# 限制更新频率
current_time = time.time()
if current_time - last_update_time > 0.5: # 每0.5秒更新一次
update_ui(progress)
last_update_time = current_time
10. API集成示例
10.1 完整转录流程示例
def full_transcription_workflow(audio_path, output_dir):
# 1. 初始化模型
model = TranscriptionModel(
model_type=ModelType.FASTER_WHISPER,
whisper_model_size=WhisperModelSize.MEDIUM,
)
# 2. 检查并下载模型
if not model.is_available():
downloader = ModelDownloader(model=model)
downloader.run()
model_path = model.get_local_model_path()
# 3. 创建转录选项
transcription_options = TranscriptionOptions(
model=model,
task=Task.TRANSCRIBE,
language="zh",
initial_prompt="技术会议记录，包含专业术语",
word_level_timings=True,
)
# 4. 创建任务
file_options = FileTranscriptionOptions(
file_paths=[audio_path],
output_formats={OutputFormat.SRT, OutputFormat.TXT}
)
task = FileTranscriptionTask(
file_path=audio_path,
model_path=model_path,
transcription_options=transcription_options,
file_transcription_options=file_options,
output_directory=output_dir
)
# 5. 执行转录
worker = FileTranscriberQueueWorker()
worker.add_task(task)
worker.run() # 阻塞执行，直到完成
# 6. 获取结果
segments = worker.get_completed_task_result(task.id)
return segments
# 运行转录流程
segments = full_transcription_workflow(
audio_path="meeting.mp3",
output_dir="./transcripts"
)
11. 部署与集成指南
11.1 项目集成步骤
- 安装依赖
# 通过源码安装
git clone https://gitcode.com/gh_mirrors/buz/buzz
cd buzz
pip install .
- 初始化应用
from buzz.widgets.application import Application
# 创建应用实例
app = Application(sys.argv)
# 解析命令行参数
from buzz.cli import parse_command_line
parse_command_line(app)
# 运行应用
sys.exit(app.exec())
11.2 作为库集成
# 在你的项目中导入Buzz API
from buzz.model_loader import TranscriptionModel, ModelType
from buzz.transcriber.file_transcriber import FileTranscriber
def transcribe_audio(audio_path):
# 配置模型
model = TranscriptionModel(
model_type=ModelType.WHISPER,
whisper_model_size=WhisperModelSize.BASE
)
# 确保模型可用
if not model.is_available():
# 处理模型不可用情况
return None
# 创建转录任务
task = FileTranscriptionTask(
file_path=audio_path,
model_path=model.get_local_model_path(),
transcription_options=TranscriptionOptions(
model=model,
language="zh"
)
)
# 执行转录
transcriber = FileTranscriber(task=task)
return transcriber.transcribe()
12. API参考速查表
12.1 核心类与方法
| 类/模块 | 关键方法 | 描述 |
|---|---|---|
| TranscriptionModel | get_local_model_path() | 获取模型本地路径 |
| is_available() | 检查模型是否可用 | |
| ModelDownloader | run() | 下载模型 |
| FileTranscriptionTask | - | 转录任务数据结构 |
| FileTranscriber | transcribe() | 执行转录 |
| stop() | 停止转录 | |
| FileTranscriberQueueWorker | add_task() | 添加任务到队列 |
| cancel_task() | 取消任务 | |
| run() | 启动工作线程 | |
| TranscriptionService | create_transcription() | 创建转录记录 |
| update_transcription_progress() | 更新任务进度 | |
| get_transcription_segments() | 获取转录片段 |
12.2 常用枚举值
# 任务类型
class Task(Enum):
TRANSCRIBE = "transcribe" # 转录
TRANSLATE = "translate" # 翻译
# 输出格式
class OutputFormat(Enum):
SRT = "srt" # SRT字幕
VTT = "vtt" # WebVTT字幕
TXT = "txt" # 纯文本
13. 常见问题与解决方案
13.1 模型下载失败
# 解决方案: 手动指定下载源或代理
from buzz.model_loader import ModelDownloader
downloader = ModelDownloader(model=model)
# 设置自定义下载URL(如适用)
downloader.custom_model_url = "https://example.com/models/whisper-base.bin"
downloader.run()
13.2 大型音频处理
# 解决方案: 分段处理
def process_large_audio(file_path, chunk_size=300): # 5分钟片段
from pydub import AudioSegment
audio = AudioSegment.from_file(file_path)
chunks = []
for i in range(0, len(audio), chunk_size * 1000):
chunk = audio[i:i+chunk_size*1000]
chunk_path = f"temp_chunk_{i//1000}.mp3"
chunk.export(chunk_path, format="mp3")
chunks.append(chunk_path)
# 分别转录每个片段
results = []
for chunk in chunks:
results.extend(transcribe_audio(chunk))
return results
通过本API手册，开发者可以全面了解Buzz的核心功能和接口调用方式，快速集成音频转录和翻译能力到自己的应用中。无论是构建桌面应用、命令行工具还是集成到更大的系统中，Buzz提供的API都能满足各种场景需求。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
