Adaptive Transcriber

Local-first dual-ASR verbatim transcription skill with automated conflict alignment and minimal-edit arbitration.

简体中文 | English

Adaptive Transcriber runs two independent speech-to-text (ASR) backends on the same audio/video recording. It automatically aligns the outputs, highlights discrepancies (especially high-risk entities like numbers, dates, negation, and legal terms), cuts conflict audio clips, and applies minimal-edit arbitration to produce high-integrity verbatim transcripts.

Highlights

• Dual-ASR Cross-Checking: Eliminates single-model hallucinations by comparing outputs across independent ASR architectures (Whisper vs. SenseVoice / Paraformer).
• Local-First & Privacy Preserving: Prefers on-device inference without sending audio to the cloud. API keys are never required when local models are available.
• Anti-Paraphrase Engine: Guarantees verbatim integrity. The finalization engine rejects paraphrasing or stylistic edits and enforces strict evidence attribution.
• Risk-Aware Alignment: Automatically detects phonetic and grammatical divergence across numbers, dates, amounts, negation markers, and legal antonyms.
• Zero-Dependency DOCX & Multi-Export: Generates .md, .srt (subtitles), .docx (Word document assembled via stdlib OpenXML), and provenance-tracked .json.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Input Audio/Video                      │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                       Audio Pipeline                        │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │   Backend Probe & Route │────▶│ Audio Normalization   │  │
│  │  (local-first / fallback│     │ (FFmpeg 16kHz mono)   │  │
│  └─────────────────────────┘     └───────────────────────┘  │
└──────────────────────────────┬──────────────────────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
     ┌───────────────────┐           ┌───────────────────┐
     │   ASR Backend A   │           │   ASR Backend B   │
     │  (e.g. Whisper)   │           │ (e.g. SenseVoice) │
     └─────────┬─────────┘           └─────────┬─────────┘
               └───────────────┬───────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   Alignment & Diff Engine                   │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │ Greedy Window Alignment │────▶│ Risk Flags Detector   │  │
│  │ (Status: agree/conflict)│     │ (nums, dates, legal)  │  │
│  └─────────────────────────┘     └───────────┬───────────┘  │
└──────────────────────────────────────────────┼──────────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 LLM / Host Agent Decision                   │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │ Conflict Audio Clips    │────▶│ Minimal-Edit Arbitrate│  │
│  │ (FFmpeg time slice)     │     │ (Paraphrase Rejected) │  │
│  └─────────────────────────┘     └───────────┬───────────┘  │
└──────────────────────────────────────────────┼──────────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    Multi-Format Export                      │
│        [ .md ]       [ .srt ]       [ .docx ]       [ .json]│
└─────────────────────────────────────────────────────────────┘

Quick Install

Prerequisites

• Python 3.10+
• ffmpeg installed and available in your PATH

1. Install Backends

Choose and install the backends suitable for your workflow:

# Local Whisper (OpenAI)
pip install -U openai-whisper

# Local SenseVoice (Alibaba FunASR)
pip install -U funasr

# Cloud Paraformer (Optional Alibaba Cloud SDK)
pip install -U dashscope

(Optional) Cloud fallback keys should remain in your local environment:

export GROQ_API_KEY='your_groq_api_key'
export DASHSCOPE_API_KEY='your_dashscope_api_key'

Quick Start

1. Probe Available Backends

Verify which local models and cloud providers are ready:

python3 scripts/probe_backends.py

2. Run Transcription Pipeline

Execute probe, dual-ASR transcription, time alignment, and conflict clip slicing in one step:

python3 scripts/run_pipeline.py path/to/audio.m4a --out-dir work --policy auto --language zh

• --policy auto: Prefers local Whisper + SenseVoice; falls back to cloud only when needed.
• --policy local-only: Strictly restricts transcription to on-device models.
• --policy cloud-only: Uses cloud providers (Groq + Alibaba DashScope).

3. Arbitrate and Finalize

When work/review.json contains conflicts, the host AI agent or user writes work/decisions.json, then finalizes:

python3 scripts/finalize_transcript.py work/review.json --decisions work/decisions.json --out-prefix work/final_transcript

Generated outputs:

• work/final_transcript.md — Formatted Markdown transcript.
• work/final_transcript.srt — Timestamped subtitle file.
• work/final_transcript.docx — Word document for office distribution.
• work/final_transcript.json — Structured JSON preserving both ASR candidates and arbitration provenance.

Scope & Non-Goals

Adaptive Transcriber is purpose-built for verbatim fidelity and cross-verification.

• Do Not Use For: Live/streaming transcription, standalone speaker diarization, polished meeting minutes or summaries, or Feishu/Lark 妙记 integration.

Testing

Run the automated test suite:

python3 -m unittest discover -s tests -v

License

This project is licensed under the MIT License.