# transcriber

**Repository Path**: bothlent_shenzhen/transcriber

## Basic Information

- **Project Name**: transcriber
- **Description**: 基于assemblyai sdk进一步封装，增加optimizer等特性。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

==============================================
              AssemblyAI STT Transcriber
==============================================

----------------------------------------------
1. 概述 (Overview)
----------------------------------------------

  目的 (Purpose)
  ─────────────
    提供基于 AssemblyAI SDK 的音频转写 Python 客户端，
    支持单文件转写、立体声双通道转写、批量转写，
    并对转写结果进行去重和分句优化。

  核心功能 (Core Features)
  ───────────────────────
    • 音频验证      - 验证文件格式、采样率(16kHz)、位深(16bit)
    • 单文件转写    - 转写 .wav/.mp3/.pcm 音频文件
    • 立体声转写    - 将两个 PCM 单通道合成立体声转写
    • 批量转写      - 一次性转写多个音频文件
    • 转写优化      - 去重(连续重复单词/n-gram)、分句(标点边界,≤100字)
    • 结果导出      - 输出原生 AssemblyAI JSON 格式

----------------------------------------------
2. 目录结构 (Directory Structure)
----------------------------------------------

transcriber/
│
├── python-client/                  # Python 客户端 (主要实现)
│   │
│   ├── assemblyai_stt/            # 核心转写包
│   │   ├── __init__.py            # 包入口，导出所有公开接口
│   │   ├── client.py              # AssemblyAIClient (高级接口)
│   │   ├── transcriber.py         # Transcriber + AudioValidator (底层转写)
│   │   ├── optimizer.py           # WordDeduplicator + UtteranceSplitter (优化器)
│   │   ├── models.py              # 数据模型定义
│   │   ├── exceptions.py          # 异常类定义
│   │   └── README.txt             # 模块说明文档
│   │
│   ├── test_transcriber.py        # 转写器单元测试
│   ├── test_e2e.py                # 端到端集成测试
│   ├── test_result.json           # 测试结果示例
│   │
│   ├── output/                    # 转写结果输出目录
│   │   ├── Rec_20260204T090752.s1-s2.json
│   │   ├── Rec_20260204T090752.s1-s2.txt
│   │   ├── Rec_20260204T090449.s1-s2.json
│   │   ├── Rec_20260204T090449.s1-s2.txt
│   │   └── Rec_20260204T100752.s1-s2.json
│   │
│   └── venv/                     # Python 虚拟环境 (依赖已隔离)
│
├── java-client/                   # Java 客户端 (待开发)
│   └── assemblyai_stt/
│       └── REAME.txt              # Java 模块占位符
│
├── assets/                        # 测试音频素材
│   ├── Rec_20260204T090449.s1-s2.wav   # 双通道 WAV 样本 (~99MB)
│   ├── Rec_20260204T090752.s1-s2.wav   # 双通道 WAV 样本 (~28MB)
│   └── Rec_20260204T100752.s1-s2.wav   # 双通道 WAV 样本 (~7MB)
│
├── .claude/                       # Claude Code 配置
│   └── settings.json
│
├── .gitignore                     # Git 忽略规则
├── README.txt                     # 项目根文档 (本文件)

----------------------------------------------
3. 快速开始 (Quick Start)
----------------------------------------------

  安装依赖
  ─────────
    cd python-client
    pip install assemblyai

  基本使用
  ─────────
    from assemblyai_stt import AssemblyAIClient

    client = AssemblyAIClient(api_key="YOUR_API_KEY")

    # 转写单个音频
    result = client.transcribe("path/to/audio.wav")

    # 立体声双通道转写
    result = client.transcribe_stereo("left.pcm", "right.pcm")

    # 批量转写
    results = client.transcribe_multiple(["file1.wav", "file2.wav"])

----------------------------------------------
4. 依赖关系图 (Dependency Graph)
----------------------------------------------

  AssemblyAIClient (高级接口)
        │
        ├──▶ Transcriber (底层转写)
        │         │
        │         └──▶ AudioValidator (验证器)
        │         │
        │         └──▶ assemblyai SDK (第三方)
        │
        └──▶ TranscriptOptimizer (优化器)
                  │
                  ├──▶ WordDeduplicator (去重)
                  │         └── 移除连续重复单词/n-gram
                  │
                  └──▶ UtteranceSplitter (分句)
                            └── 按标点分句 (≤100字/句)

==============================================