transcript-fixer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Transcript Fixer

转录文本修正工具

Correct speech-to-text transcription errors through dictionary-based rules, AI-powered corrections, and automatic pattern detection. Build a personalized knowledge base that learns from each correction.

通过基于字典的规则、AI驱动的修正以及自动模式检测来修正语音转文本的转录错误。构建可从每次修正中学习的个性化知识库。

When to Use This Skill

何时使用该工具

Correcting ASR/STT errors in meeting notes, lectures, or interviews
Building domain-specific correction dictionaries
Fixing Chinese/English homophone errors or technical terminology
Collaborating on shared correction knowledge bases

修正会议记录、讲座或采访中的ASR/STT错误
构建特定领域的修正字典
修复中英同音异义词错误或专业术语问题
协作构建共享的修正知识库

Prerequisites

前置条件

Python execution must use
uv
- never use system Python directly.

uv

is not installed:

bash

undefined

Python执行必须使用
uv
- 切勿直接使用系统Python。

若未安装

uv

：

bash

undefined

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

undefined

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

undefined

Quick Start

快速开始

Recommended: Use Enhanced Wrapper (auto-detects API key, opens HTML diff):

bash

undefined

推荐：使用增强版封装器（自动检测API密钥，打开HTML差异对比）：

bash

undefined

First time: Initialize database

首次使用：初始化数据库

uv run scripts/fix_transcription.py --init

Process transcript with enhanced UX

以增强用户体验处理转录文本

uv run scripts/fix_transcript_enhanced.py input.md --output ./corrected


The enhanced wrapper automatically:
- Detects GLM API key from shell configs (checks lines near `ANTHROPIC_BASE_URL`)
- Moves output files to specified directory
- Opens HTML visual diff in browser for immediate feedback

**Alternative: Use Core Script Directly**:

```bash

uv run scripts/fix_transcript_enhanced.py input.md --output ./corrected


增强版封装器会自动：
- 从Shell配置中检测GLM API密钥（检查`ANTHROPIC_BASE_URL`附近的行）
- 将输出文件移动到指定目录
- 在浏览器中打开HTML可视化差异对比，以便即时反馈

**替代方案：直接使用核心脚本**：

```bash

1. Set API key (if not auto-detected)

1. 设置API密钥（若未自动检测到）

export GLM_API_KEY="<api-key>" # From https://open.bigmodel.cn/

export GLM_API_KEY="<api-key>" # 从https://open.bigmodel.cn/获取

2. Add common corrections (5-10 terms)

2. 添加常用修正词条（5-10个）

uv run scripts/fix_transcription.py --add "错误词" "正确词" --domain general

3. Run full correction pipeline

3. 运行完整修正流水线

uv run scripts/fix_transcription.py --input meeting.md --stage 3

4. Review learned patterns after 3-5 runs

4. 运行3-5次后查看学习到的模式

uv run scripts/fix_transcription.py --review-learned


**Output files**:
- `*_stage1.md` - Dictionary corrections applied
- `*_stage2.md` - AI corrections applied (final version)
- `*_对比.html` - Visual diff (open in browser for best experience)

**Generate word-level diff** (recommended for reviewing corrections):
```bash
uv run scripts/generate_word_diff.py original.md corrected.md output.html

This creates an HTML file showing word-by-word differences with clear highlighting:

🔴
```
japanese 3 pro
```
→ 🟢
```
Gemini 3 Pro
```
(complete word replacements)
Easy to spot exactly what changed without character-level noise

uv run scripts/fix_transcription.py --review-learned


**输出文件**:
- `*_stage1.md` - 已应用字典修正
- `*_stage2.md` - 已应用AI修正（最终版本）
- `*_对比.html` - 可视化差异对比（在浏览器中打开以获得最佳体验）

**生成逐词差异对比**（推荐用于审核修正内容）：
```bash
uv run scripts/generate_word_diff.py original.md corrected.md output.html

该命令会生成一个HTML文件，显示逐词差异并带有清晰高亮：

🔴
```
japanese 3 pro
```
→ 🟢
```
Gemini 3 Pro
```
（完整词汇替换）
无需关注字符级别的冗余信息，轻松定位所有修改内容

Example Session

示例流程

Input transcript (

meeting.md

今天我们讨论了巨升智能的最新进展。
股价系统需要优化，目前性能不够好。

After Stage 1 (

meeting_stage1.md

今天我们讨论了具身智能的最新进展。  ← "巨升"→"具身" corrected
股价系统需要优化,目前性能不够好。  ← Unchanged (not in dictionary)

After Stage 2 (

meeting_stage2.md

今天我们讨论了具身智能的最新进展。
框架系统需要优化，目前性能不够好。  ← "股价"→"框架" corrected by AI

Learned pattern detected:

✓ Detected: "股价" → "框架" (confidence: 85%, count: 1)
  Run --review-learned after 2 more occurrences to approve

输入转录文本 (

meeting.md

今天我们讨论了巨升智能的最新进展。
股价系统需要优化，目前性能不够好。

阶段1后 (

meeting_stage1.md

今天我们讨论了具身智能的最新进展。  ← "巨升"→"具身" 已修正
股价系统需要优化,目前性能不够好。  ← 未修改（不在字典中）

阶段2后 (

meeting_stage2.md

今天我们讨论了具身智能的最新进展。
框架系统需要优化，目前性能不够好。  ← "股价"→"框架" 由AI修正

检测到学习模式:

✓ 检测到: "股价" → "框架"（置信度: 85%, 出现次数: 1）
  再出现2次后运行--review-learned以确认

Core Workflow

核心工作流

Three-stage pipeline stores corrections in

~/.transcript-fixer/corrections.db

Initialize (first time):

uv run scripts/fix_transcription.py --init

Add domain corrections:

--add "错误词" "正确词" --domain <domain>

Process transcript:
```
--input file.md --stage 3
```
Review learned patterns:
```
--review-learned
```
and
```
--approve
```
high-confidence suggestions

Stages: Dictionary (instant, free) → AI via GLM API (parallel) → Full pipeline Domains:

general

embodied_ai

finance

medical

, or custom names including Chinese (e.g.,

火星加速器

具身智能

) Learning: Patterns appearing ≥3 times at ≥80% confidence move from AI to dictionary

See

references/workflow_guide.md

for detailed workflows,

references/script_parameters.md

for complete CLI reference, and

references/team_collaboration.md

for collaboration patterns.

三阶段流水线将修正内容存储在

~/.transcript-fixer/corrections.db

中：

初始化（首次使用）:

uv run scripts/fix_transcription.py --init

添加特定领域修正词条:

--add "错误词" "正确词" --domain <domain>

处理转录文本:
```
--input file.md --stage 3
```
审核学习到的模式:
```
--review-learned
```
并
```
--approve
```
高置信度建议

阶段: 字典修正（即时、免费）→ 基于GLM API的AI修正（并行）→ 完整流水线领域:

general

、

embodied_ai

、

finance

、

medical

，或包含中文的自定义名称（如

火星加速器

、

具身智能

） 学习机制: 出现≥3次且置信度≥80%的模式将从AI库迁移到字典库

详细工作流请参阅

references/workflow_guide.md

，完整CLI参考请参阅

references/script_parameters.md

，协作模式请参阅

references/team_collaboration.md

。

Critical Workflow: Dictionary Iteration

关键工作流：字典迭代

MUST save corrections after each fix. This is the skill's core value.

After fixing errors manually, immediately save to dictionary:

bash

uv run scripts/fix_transcription.py --add "错误词" "正确词" --domain general

See

references/iteration_workflow.md

for complete iteration guide with checklist.

每次修正后必须保存词条。这是本工具的核心价值。

手动修正错误后，立即将其保存到字典：

bash

uv run scripts/fix_transcription.py --add "错误词" "正确词" --domain general

完整迭代指南及检查清单请参阅

references/iteration_workflow.md

。

AI Fallback Strategy

AI fallback策略

When GLM API is unavailable (503, network issues), the script outputs

[CLAUDE_FALLBACK]

marker.

Claude Code should then:

Analyze the text directly for ASR errors
Fix using Edit tool
MUST save corrections to dictionary with
```
--add
```

当GLM API不可用时（503错误、网络问题），脚本会输出

[CLAUDE_FALLBACK]

标记。

此时Claude Code应：

直接分析文本中的ASR错误
使用编辑工具修正
必须通过
```
--add
```
将修正内容保存到字典

Database Operations

数据库操作

MUST read
references/database_schema.md
before any database operations.

Quick reference:

bash

undefined

在进行任何数据库操作前，必须阅读
references/database_schema.md
。

快速参考：

bash

undefined

View all corrections

查看所有修正词条

sqlite3 ~/.transcript-fixer/corrections.db "SELECT * FROM active_corrections;"

Check schema version

检查架构版本

sqlite3 ~/.transcript-fixer/corrections.db "SELECT value FROM system_config WHERE key='schema_version';"

undefined

sqlite3 ~/.transcript-fixer/corrections.db "SELECT value FROM system_config WHERE key='schema_version';"

undefined

Stages

阶段说明

Stage	Description	Speed	Cost
1	Dictionary only	Instant	Free
2	AI only	~10s	API calls
3	Full pipeline	~10s	API calls

阶段	描述	速度	成本
1	仅使用字典	即时	免费
2	仅使用AI	~10秒	API调用费用
3	完整流水线	~10秒	API调用费用

Bundled Resources

捆绑资源

Scripts:

```
ensure_deps.py
```
- Initialize shared virtual environment (run once, optional)
```
fix_transcript_enhanced.py
```
- Enhanced wrapper (recommended for interactive use)
```
fix_transcription.py
```
- Core CLI (for automation)
```
generate_word_diff.py
```
- Generate word-level diff HTML for reviewing corrections
```
examples/bulk_import.py
```
- Bulk import example

References (load as needed):

Critical:
```
database_schema.md
```
(read before DB operations),
```
iteration_workflow.md
```
(dictionary iteration best practices)

Getting started:

installation_setup.md

glm_api_setup.md

workflow_guide.md

Daily use:

quick_reference.md

script_parameters.md

dictionary_guide.md

Advanced:

sql_queries.md

file_formats.md

architecture.md

best_practices.md

Operations:
```
troubleshooting.md
```
,
```
team_collaboration.md
```

脚本:

```
ensure_deps.py
```
- 初始化共享虚拟环境（运行一次，可选）
```
fix_transcript_enhanced.py
```
- 增强版封装器（推荐交互式使用）
```
fix_transcription.py
```
- 核心CLI工具（用于自动化）
```
generate_word_diff.py
```
- 生成逐词差异对比HTML以审核修正内容
```
examples/bulk_import.py
```
- 批量导入示例

参考文档（按需加载）:

关键文档:
```
database_schema.md
```
（数据库操作前必读）、
```
iteration_workflow.md
```
（字典迭代最佳实践）

入门指南:

installation_setup.md

、

glm_api_setup.md

、

workflow_guide.md

日常使用:

quick_reference.md

、

script_parameters.md

、

dictionary_guide.md

高级内容:

sql_queries.md

、

file_formats.md

、

architecture.md

、

best_practices.md

运维相关:
```
troubleshooting.md
```
、
```
team_collaboration.md
```

Troubleshooting

故障排除

Verify setup health with

uv run scripts/fix_transcription.py --validate

. Common issues:

Missing database → Run
```
--init
```
Missing API key →
```
export GLM_API_KEY="<key>"
```
(obtain from https://open.bigmodel.cn/)
Permission errors → Check
```
~/.transcript-fixer/
```
ownership

See

references/troubleshooting.md

for detailed error resolution and

references/glm_api_setup.md

for API configuration.

使用

uv run scripts/fix_transcription.py --validate

验证设置是否正常。常见问题：

缺失数据库 → 运行
```
--init
```
缺失API密钥 →
```
export GLM_API_KEY="<key>"
```
（从https://open.bigmodel.cn/获取）
权限错误 → 检查
```
~/.transcript-fixer/
```
的所有权

详细错误解决请参阅

references/troubleshooting.md

，API配置请参阅

references/glm_api_setup.md

。