AI Docs Pipeline
ymazhar/ai-docs-pipeline
Converta áudio em documentação estruturada sem enviar gravações para a nuvem
Ver no GitHubPipeline local-first que converte áudio (reuniões, voice memos, palestras) em documentação Markdown estruturada usando whisper.cpp para transcrição offline e Claude para análise e síntese. Ideal para construir bases de conhecimento em texto versionado a partir de conteúdo falado.
Instalação
npx convez-ai ymazhar/ai-docs-pipeline1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Transformar gravações de reuniões em notas estruturadas
- Converter ditados de voz em Markdown versionado
- Construir base de conhecimento AI-ready a partir de palestras e entrevistas
- Criar documentação de pesquisa a partir de sessões gravadas
Veredito

Solução sólida e privada para pipeline áudio→docs com arquitetura clara (transcrição local + análise remota). Bem-documentada e pronta para produção, embora exija setup inicial de dependências (whisper.cpp, ffmpeg, Python).
README
A tradução para o português deste README ainda está na fila.
ai-docs-pipeline — turn audio recordings into AI-ready documentation
A local-first pipeline that converts spoken audio — meeting recordings, voice memos, interviews, lectures — into clean, structured Markdown documentation for your AI knowledge base. Speech is transcribed offline with whisper.cpp; the Claude API then turns each transcript into a structured analysis and a distilled, English-language doc.
audio → whisper.cpp → transcript/ → [Claude] → analysis/ → [Claude] → docs/
- transcript/ — raw speech-to-text transcription (source language)
- analysis/ — structured analysis of the conversation (source language)
- docs/ — distilled, reusable AI-facing documentation (always English)
The
transcript/,analysis/, anddocs/directories are gitignored — the pipeline writes them locally and they are yours to keep. This repo ships only the tooling.
Why use this?
If you think out loud, run a lot of meetings, or record voice notes, the knowledge lives in audio files nobody ever revisits. This tool gives you a repeatable way to convert speech into searchable, version-controlled Markdown that both humans and LLMs can read — without uploading your audio anywhere. Transcription is fully offline on your machine (macOS/Linux); only the de-identified text is sent to Claude for the analysis and documentation stages.
Use cases
- Meeting notes — turn Zoom / Google Meet / in-person recordings into clean docs.
- Voice-to-docs — dictate ideas and get structured Markdown back.
- AI knowledge base — build a folder of English docs your agents and RAG can index.
- Interviews & user research — transcribe and summarize sessions into findings.
- Lectures & talks — convert recordings into study notes or reference material.
Quick start
git clone --recurse-submodules https://github.com/ymazhar/ai-docs-pipeline
cd ai-docs-pipeline
# 1. Build whisper.cpp + download a model
cd whisper.cpp && cmake -B build && cmake --build build -j --config Release
bash models/download-ggml-model.sh medium && cd ..
# 2. ffmpeg (for non-WAV input)
brew install ffmpeg
# 3. Python deps + API key
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
cp .env.local.example .env.local # then add your ANTHROPIC_API_KEY
# 4. Create the pipeline folders, then drop audio into audio/<category>/
./.venv/bin/python pipeline.py --init # creates audio/ transcript/ analysis/ docs/
# 5. Run the full pipeline
./.venv/bin/python pipeline.py audio/
Full setup, usage, options, and the naming convention are documented in
CLAUDE.md.
How it works
The pipeline runs three idempotent stages — each output file is skipped if it already
exists (unless --force):
- Transcribe —
whisper.cppconverts audio (anyffmpeg-readable format) into a text transcript, fully offline. - Analyze — Claude reads the transcript and produces a structured analysis in the source language.
- Docs — Claude distills the analysis into reusable documentation, always in English.
You can start or stop at any stage with --from / --to, e.g. regenerate only the
docs from existing analysis.
Tech stack
- whisper.cpp — fast, offline, on-device speech recognition (no audio leaves your machine).
- Claude API (
claude-sonnet-4-6) — analysis and documentation generation with streaming. - Python 3.9+ — the orchestration in
pipeline.py/transcribe.py. - ffmpeg — audio format conversion.
FAQ
Does my audio get uploaded anywhere? No. Transcription is 100% local via whisper.cpp. Only the resulting text is sent to the Claude API for the analysis and docs stages.
What audio formats are supported?
Anything ffmpeg can read — .mp3, .m4a, .wav, .flac, and more. Non-WAV files
are converted to 16 kHz mono WAV automatically.
Do I need an Anthropic API key?
Only for the analysis and docs stages. You can run transcription alone with
transcribe.py and no API key.
Which whisper model should I use?
medium is the recommended default for mixed-language audio. Smaller models (base,
small) are faster; large is the most accurate. See the model table in
CLAUDE.md.
Does it work on Windows? It's built and tested on macOS/Linux. whisper.cpp itself supports Windows, but the helper scripts assume a Unix shell.
Roadmap
Planned scope for upcoming releases, tracked in GitHub issues:
- Pluggable LLM providers (#2) —
make the
analyze/docsstages provider-agnostic instead of being tied to Claude. Claude stays the default, with OpenAI-compatible APIs and local models selectable via configuration — no source changes required. - Skill generation & publishing (#3) —
an optional stage that packages
docs/output into self-describing, versioned skills (metadata header + index) that downstream agents, RAG pipelines, and LLM tools can import directly, with local and remote publish targets. - Windows support (#1) —
first-class Windows setup and execution without WSL: OS-agnostic paths and subprocess
handling, plus a dedicated Windows setup guide covering the venv,
ffmpeg, buildingwhisper.cpp, and model download.