claude-code-skills-reference/transcript-fixer/SKILL.md

name, description

name

description

transcript-fixer

Corrects speech-to-text (ASR/STT) transcription errors in meeting notes, lecture recordings, interviews, and voice memos through dictionary-based rules and AI corrections. This skill should be used when users mention 'transcript', 'ASR errors', 'speech-to-text', 'STT mistakes', 'meeting notes', 'dictation', 'homophone errors', 'voice memo cleanup', or when working with .md/.txt files containing Chinese/English mixed content with obvious transcription errors.

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.

When to Use This Skill

Activate this skill when:

• Correcting speech-to-text (ASR) transcription errors in meeting notes, lectures, or interviews
• Building domain-specific correction dictionaries for repeated transcription workflows
• Fixing Chinese/English homophone errors, technical terminology, or names
• Collaborating with teams on shared correction knowledge bases
• Improving transcript accuracy through iterative learning

Quick Start

Initialize (first time only):

uv run scripts/fix_transcription.py --init
export GLM_API_KEY="<api-key>"  # Obtain from https://open.bigmodel.cn/

Correct a transcript in 3 steps:

# 1. Add common corrections (5-10 terms)
uv run scripts/fix_transcription.py --add "错误词" "正确词" --domain general

# 2. Run full correction pipeline
uv run scripts/fix_transcription.py --input meeting.md --stage 3

# 3. Review learned patterns after 3-5 runs
uv run scripts/fix_transcription.py --review-learned

Output files:

• meeting_stage1.md - Dictionary corrections applied
• meeting_stage2.md - AI corrections applied (final version)

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

Workflow Checklist

Copy and customize this checklist for each transcript:

### Transcript Correction - [FILENAME] - [DATE]
- [ ] Validation passed: `uv run scripts/fix_transcription.py --validate`
- [ ] GLM_API_KEY verified: `echo $GLM_API_KEY | wc -c` (should be >20)
- [ ] Domain selected: [general/embodied_ai/finance/medical]
- [ ] Added 5-10 domain-specific corrections to dictionary
- [ ] Tested Stage 1 (dictionary only): Output reviewed at [FILENAME]_stage1.md
- [ ] Stage 2 (AI) completed: Final output verified at [FILENAME]_stage2.md
- [ ] Learned patterns reviewed: `--review-learned`
- [ ] High-confidence suggestions approved (if any)
- [ ] Team dictionary updated (if applicable): `--export team.json`

Core Commands

# Initialize (first time only)
uv run scripts/fix_transcription.py --init
export GLM_API_KEY="<api-key>"  # Get from https://open.bigmodel.cn/

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

# Run full pipeline (dictionary + AI corrections)
uv run scripts/fix_transcription.py --input file.md --stage 3 --domain general

# Review and approve learned patterns (after 3-5 runs)
uv run scripts/fix_transcription.py --review-learned
uv run scripts/fix_transcription.py --approve "错误" "正确"

# Team collaboration
uv run scripts/fix_transcription.py --export team.json --domain <domain>
uv run scripts/fix_transcription.py --import team.json --merge

# Validate setup
uv run scripts/fix_transcription.py --validate

Database: ~/.transcript-fixer/corrections.db (SQLite)

Stages:

• Stage 1: Dictionary corrections (instant, zero cost)
• Stage 2: AI corrections via GLM API (1-2 min per 1000 lines)
• Stage 3: Full pipeline (both stages)

Domains: general, embodied_ai, finance, medical (prevents cross-domain conflicts)

Learning: Approve patterns appearing ≥3 times with ≥80% confidence to move from expensive AI (Stage 2) to free dictionary (Stage 1).

See references/workflow_guide.md for detailed workflows and references/team_collaboration.md for collaboration patterns.

Bundled Resources

Scripts

• fix_transcription.py - Main CLI for all operations
• examples/bulk_import.py - Bulk import example (runnable with uv run scripts/examples/bulk_import.py)

References

Load as needed for detailed guidance:

• workflow_guide.md - Step-by-step workflows, pre-flight checklist, batch processing
• quick_reference.md - CLI/SQL/Python API quick reference
• sql_queries.md - SQL query templates (copy-paste ready)
• troubleshooting.md - Error resolution, validation
• best_practices.md - Optimization, cost management
• file_formats.md - Complete SQLite schema
• installation_setup.md - Setup and dependencies
• team_collaboration.md - Git workflows, merging
• glm_api_setup.md - API key configuration
• architecture.md - Module structure, extensibility
• script_parameters.md - Complete CLI reference
• dictionary_guide.md - Dictionary strategies

Validation and Troubleshooting

Run validation to check system health:

uv run scripts/fix_transcription.py --validate

Healthy output:

✅ Configuration directory exists: ~/.transcript-fixer
✅ Database valid: 4 tables found
✅ GLM_API_KEY is set (47 chars)
✅ All checks passed

Error recovery:

1. Run validation to identify issue
2. Check components:
   • Database: sqlite3 ~/.transcript-fixer/corrections.db ".tables"
   • API key: echo $GLM_API_KEY | wc -c (should be >20)
   • Permissions: ls -la ~/.transcript-fixer/
3. Apply fix based on validation output
4. Re-validate to confirm

Quick fixes:

• Missing database → Run --init
• Missing API key → export GLM_API_KEY="<key>"
• Permission errors → Check ownership with ls -la

See references/troubleshooting.md for detailed error codes and solutions.