Content & Media Creation · daymade/claude-code-skills

transcript-fixer

Name: transcript-fixer
Author: daymade/claude-code-skills

Corrects speech-to-text transcription errors with dictionary rules and Claude's built-in AI (no external API key required); Native AI Correction is the default, Stage 1 alone is incomplete, and Stage 3 API is only for automation without Claude Code. Builds personalized correction databases, loads person-name ASR variants from the configured global people roster, and reads per-domain contexts for homophones. Before correcting a person name, the agent must consult both the global roster and the owning project's identity roster; project rosters are not auto-loaded, and occurrence frequency is never identity evidence. Use for ASR/STT output with recognition errors, homophones, garbled technical terms, person-name errors, or mixed Chinese/English, and for cleaning transcripts when the user only says "fix this transcript," "clean up these meeting notes," or mentions a garbled name.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandInstall DepsNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Two-stage correction loop: Stage 1 applies known corrections in batches using deterministic dictionary rules; Native AI Correction (built into Claude/Codex, requiring no external key) reads the entire text to fix one-off errors and crystallizes reusable corrections; Stage 3 API is dedicated solely to agent-less automation.

daymade-audio/transcript-fixer/SKILL.md

1. Stage 1 applies deterministic, already-known corrections. 2. Native AI Correction reads the complete transcript, fixes one-off errors, verifies uncertain entities, and compounds reusable fixes.

What happens here: "Transcript fixing" is decoupled into two tiers—deterministic rigid rules (reproducible, auditable) and LLM semantic judgment (one-off errors, entity verification), enforcing "Native AI Correction is the default. Stage 1 alone is incomplete" to prevent claiming a transcript is clean after merely running dictionary replacements.

Personalized correction database: SQLite (~/.transcript-fixer/corrections.db) stores dictionaries, context rules, people rosters, and review queues; the directory is permissions-guarded with chmod 0o700 and config with 0o600, while domain context files adhere to the ~/.transcript-fixer/contexts/<domain>.md convention.

daymade-audio/transcript-fixer/scripts/core/defaults.py

# Filesystem security CONFIG_DIR_MODE: Final[int] = 0o700 CONFIG_FILE_MODE: Final[int] = 0o600

config.py defaults to Path.home()/'.transcript-fixer'/corrections.db, contexts/, data/, logs/, cache/, with directories set to chmod 0o700 upon creation; features schema version v2.0 (schema.sql) + migration CLI (--migration). The database acts as a vehicle that improves with use: confirmed corrections are crystallized by domain.

Person-name correction gate: Before altering a person's name, the agent must cross-reference both the global people roster and the project's explicit identity roster; the roster strictly stores ASR variants, project rosters are never auto-loaded, and frequency is never accepted as identity evidence.

daymade-audio/transcript-fixer/SKILL.md

Before correcting any person name, directly read both the configured global people roster and the owning project's explicit identity roster or alias ledger. … Never use occurrence frequency as identity evidence.

Implementation detail: Stage 1 only automatically loads 'ASR variant' entries from the global roster (near commands.py/1330: roster_path = os.getenv('TRANSCRIPT_FIXER_PEOPLE_ROSTER') or config…people_roster_path); bare surnames combined with titles like "Teacher/Director/General Manager" are rejected during loading and when executing --add/--import (even with --force).

Safe mode + multi-layer matching defense: By default, only low-risk rules are automatically applied, while medium- and high-risk items are deferred to *_needs_review.md and the persistent review queue; matching-phase three-tier checks (superset, common word boundary, and standard word boundary) reject inappropriate matches.

daymade-audio/transcript-fixer/SKILL.md

Safe mode is the Stage 1 default: low-risk rules apply; medium/high-risk matches defer to `*_needs_review.md` and the persistent review queue. `Applied: 0` is a valid result, not proof that the transcript is clean.

SKILL.md cites word boundary examples: ASCII letters adjacent to characters are treated as substrings within longer words ('Cloud' in 'iCloud' is not modified, whereas numbers do not prevent modification so 'cloud3' is still corrected); CJK strings are segmented via dictionary, and matches are rejected only when all components are multi-character words spanning across boundaries.

Review queue + local dashboard: Queue entries follow {file, line, original, suggested, kind, context, evidence}; review-dashboard/server.py serves FastAPI at 127.0.0.1:8767, establishing a read-only connection to the same SQLite database so both the CLI and human reviewers share an identical source of truth.

daymade-audio/transcript-fixer/scripts/review-dashboard/server.py

anchor guards, and audit logging stay the single source of truth — this UI never mutates the database itself. Agent (CLI) and human (this page) are equal writers of the same queue.

The minimal queue entry JSON (file is required, context is verbatim, line serves as the anchor, suggested is the key) is hardcoded in SKILL.md; adjudication CLI commands include --resolve-review, --decision accepted, --reanchor-review, and --list-review; the server binds strictly to 127.0.0.1 (host='127.0.0.1') without exposing endpoints to the local network.

AI-enhanced routing (agent-less): Routes to GLM only when Claude/Codex is unavailable—via the Anthropic-compatible endpoint open.bigmodel.cn/api/anthropic, authenticated by x-api-key at /v1/messages, utilizing model GLM-5.2 (fallback to GLM-5-turbo).

daymade-audio/transcript-fixer/scripts/core/defaults.py

API_PROVIDER: Final[str] = "GLM" DEFAULT_MODEL: Final[str] = "GLM-5.2" FALLBACK_MODEL: Final[str] = "GLM-5-turbo" API_BASE_URL: Final[str] = "https://open.bigmodel.cn/api/anthropic" AUTH_HEADER_NAME: Final[str] = "x-api-key"

ai_processor.py _process_chunk constructs url = f'{base_url}/v1/messages', sets headers containing anthropic-version and x-api-key, and executes synchronous POST requests via httpx; max_tokens is 8000, temperature is 0.3, and chunk size is 6000 characters. SKILL.md mandates that Stage 3 must not run inside Claude Code or Codex.

Evidence chain and closure contract: Corrections require from_text/to_text provenance and asr_note line-mask protection; --close-sidecars reports closed only when all queue lines are adjudicated, rules are deactivated, and the file contains zero pending items (exit 1 open / exit 2 blocked).

daymade-audio/transcript-fixer/SKILL.md

`--close-sidecars --input "<absolute-canonical-file>"` reports `closed`: every entry reads applied in the file (or the original form no longer appears anywhere in the ledger-masked transcript) or is answered by a decided queue row for this exact file

"The presence of a sidecar does not equal success", "pending lines represent a blocking state", and stats.pending_total == 0 is required prior to final output—transforming "high-quality / final draft" declarations into a computable state rather than a verbal assertion.

2Core Capabilities

01Stage 1 deterministic dictionary correction (--domain multi-domain union/--apply-domain/--dry-run/--json, including trap scans)

02Native AI full-pass correction (default path; Claude/Codex built-in models, requiring no external API key)

03Person-name correction gate: dual-lookup against global roster + project identity roster, variant matching, prohibition of frequency-based evidence, and prohibition of bare-name rules

04Domain context traps and vetoes: bare-word prohibition / dictionary-entry downgrade, confirmed-correct (do not fix) records, and --apply-all as explicit operator override

05Uncertainty item enqueueing + local review dashboard (--enqueue-review/--list-review/--resolve-review; server at 127.0.0.1:8767)

06Learning loop: harvest_corrections converts native-pass edits into candidate traps, --report-false-positive rollbacks, numerical consistency scans, and --scan-traps

07Agent-less Stage 3 API batch processing (GLM key; fix_transcript_enhanced.py, generates *_stage2.md requiring manual promotion)

08Audio forensics pipeline: fetch_minute_audio.py retrieves Feishu Minutes signed URLs via lark-cli + downloads via curl, performing timeline alignment verification

09Batch processing and partitioned cold review: native_review_packets (multi-file partitioning, JSON results, resume-from-break), git diff boundary validation

3External Dependencies

Kind	Dependency / Endpoint
network	open.bigmodel.cn（GLM/智谱，anthropic 兼容）
cli	uv / python3（PEP 723 入口，uv run）
package	httpx/filelock/aiofiles（ensure_deps 的共享 venv）
package	jieba / rapidfuzz（fix_transcription.py PEP 723 依赖，词边界/模糊匹配）
cli	lark-cli（飞书 CLI，音频取证；需已登录 profile）
cli	curl / ffprobe / sqlite3（工具链）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: fix_transcription.py and accompanying utility scripts in the same directory (via uv run)
scripts/ 或 SKILL.md: Declares dynamic installation of external language package dependencies
网络端点: Declares external network access: Stage 2/3 (agent-less API routing) issues POST requests to https://open.bigmodel.cn/api/anthropic/v1/
本地工作目录: File read/write operations and artifact outputs: directly edits user's source transcript files (in-place under Native mode) and produces *_stage1.md / *_changes.md / *

Audit Notes: Categorized under standard classification: Touches plaintext credentials—Stage 2/3 reads GLM_API_KEY/ANTHROPIC_API_KEY environment variables or plaintext API keys from ~/.transcript-fixer/config.json (mitigated by file mode 0o600 and directory mode 0o700); fetch_minute_audio accesses user Feishu login sessions via lark-cli; ensure_deps dynamically installs third-party packages from PyPI. While the default Native/Stage 1 path operates completely offline without credentials (local SQLite and direct editing only), the API routing, forensic fetching, and dependency installation place the overall skill in the Orange tier; outbound network traffic targets official Zhipu endpoints (predictable) and Feishu.

5Second-Pass Verification

[ok] SQLite 数据库与 0o700/0o600 权限 — defaults.py CONFIG_DIR_MODE=0o700/CONFIG_FILE_MODE=0o600；config.py DatabaseConfig/PathConfig __post_init__ 逐目录 mkdir+chmod；默认路径 Path.home()/'.transcript-fixer'/corrections.db。
[ok] 凭证读取面（GLM/ANTHROPIC key 与 config.json） — config.py from_env 读 GLM_API_KEY/ANTHROPIC_API_KEY/ANTHROPIC_BASE_URL；from_file 读 config.json api.api_key；get_config 全局 env 覆盖 file。无其他 key/token 读取。
[ok] 网络调用点仅 open.bigmodel.cn（+dashboard 本机） — ai_processor.py _process_chunk url=f'{base_url}/v1/messages' httpx POST；全目录 https?:// 扫描无其他外发端点；astral.sh 仅 ensure_deps 报错文案。
[ok] 人名门禁（roster 双读/频率非证据） — commands.py 715-719/1330-1333 roster_path = getenv('TRANSCRIPT_FIXER_PEOPLE_ROSTER') or config…people_roster_path 存在；SKILL.md 操作契约原文存在；Stage1 只加载全局 ASR 变体。
[ok] Safe mode 与 defer 行为 — SKILL.md『Safe mode is the Stage 1 default』；commands.py 1401 附近『Stage 1 defaults to conservative safe mode: only auto-apply low-risk』代码注释相符。
[ok] review queue 结构（file/line/original/suggested/kind/context/evidence） — SKILL.md 最小条目 JSON 逐字段存在；review_queue.py 以 sqlite 实现（--init 后 db 必须存在）。
[ok] dashboard 只读连库且仅本机 — server.py _connect_ro 用 'file:{DB_PATH}?mode=ro'；uvicorn.run(host='127.0.0.1', port=PORT)；docstring『never mutates the database itself』。
[ok] fetch_minute_audio 网络/CLI 行为 — lark-cli minutes +download --url-only → json 取 download_url → curl -sSL --noproxy '*' 下载；LARK_CLI_NO_PROXY=1 防代理带走凭证。

6Verdict & Scenarios

Transforms transcript correction into a closed-loop data product: SQLite dictionaries, rosters, queues, and audits combine with learning loops (harvest/learning engine) to increase accuracy over time under complete auditability.

Anti-hallucination and anti-overconfidence discipline serve as the core moat: visible garble is preferred over fluent wrong guesses, promotions require verbatim quotes, and pending items strictly block final draft claims.

Ultra-conservative handling of names and identities: source-side tagging priority, dual-roster gating, and rejection of frequency-as-evidence—tailored specifically for the highest-risk scenarios in ASR name corruption.

Zero external dependencies on the default path (Native AI + local SQLite); touches GLM keys only during explicit agent-less automation—balancing free out-of-the-box usage with broad scalability.

Computable quality assertions: verifiable closure conditions in --close-sidecars, pending_total==0 validation, and degraded flags prevent declaring transcripts "fixed" without programmatic proof.

Best for: Best suited for: Rigorous cleaning workflows for Chinese or mixed Chinese/English ASR transcripts (meeting minutes, interviews, podcasts, lectures), especially for teams with high rates of name/terminology errors requiring long-term accumulation of correction libraries; "high-fidelity final draft" demands backed by transcript-fixer review queues and human-in-the-loop workflows; and automated long-document pipelines requiring batching and partitioned cold review.

Not for: Not suitable for: Users seeking one-off lightweight cleanup without initializing the ~/.transcript-fixer database and rosters; host environments lacking uv or Python; high-risk naming scenarios expecting "fully automated fixes without human verification" (name gating strictly demands human/evidence adjudication); and workflows treating Stage 3 as the default path inside Claude Code (strictly forbidden by SKILL.md; Native AI is the default).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload transcript-fixer.tar.gz

sha256: 1621eed101bbd789…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.