Audio-Transkriber

Lokales, datenschutzkonformes Tool für Audio-Transkription, Speaker-Diarization und semantisches Post-Processing auf macOS.

Kurzbeschreibung (für GitHub-Repository)

Lokales Transkriptions-Tool mit WhisperX (MPS), Speaker-Diarization und optionalem Ollama-Post-Processing für Summary und Action Items.

Was das Tool macht

• Transkribiert Audio-Dateien lokal (kein Cloud-Zwang)
• Unterstützt Speaker-Diarization für Sprechertrennung
• Erstellt Exporte als JSON, Markdown und TXT
• Ergänzt bei Bedarf Ollama-basierte Summary + Action Items
• Legt Ergebnisse pro Lauf in separaten Output-Ordnern ab

Voraussetzungen

• macOS (Apple Silicon empfohlen)
• Python 3.10+
• ffmpeg installiert (brew install ffmpeg)
• Optional für Post-Processing: lokales Ollama

Schnellstart

1. Repository klonen und ins Verzeichnis wechseln.
2. Launcher ausführbar machen und starten.

chmod +x scripts/launch_audio_transkriber.command
./scripts/launch_audio_transkriber.command

3. UI im Browser öffnen: http://127.0.0.1:8501

Stoppen:

./stop_audio_transkriber.command

Typischer Ablauf in der UI

1. Audio-Datei hochladen (.wav, .mp3, .m4a).
2. Optional Sprache setzen (auto-detect, de, en).
3. Transkription starten.
4. Optional Ollama-Post-Processing ausführen (Summary + Action Items).
5. Exporte im Output-Ordner prüfen.

Output und Ordnerstruktur

• Laufzeitdaten (nicht für Git): data/output/, data/processed/
• Exporte pro Lauf in eigenen Session-Unterordnern unter data/output/
• Typische Artefakte:
  • *.json (strukturierte Segmente + Metadaten)
  • *.md (Frontmatter + Summary + Transkript)
  • *.txt (Summary + Transkript)

Security-Hinweise

• Upload-Dateinamen werden beim Speichern in temporäre Dateien sanitisiert.
• Der Launcher bevorzugt reproduzierbare Basis-Dependencies aus requirements.lock.txt.
• Laufzeit- und Launcher-Logs liegen unter data/logs/ und sind für Git ausgeschlossen.

Häufige Probleme

• command not found bei Start/Stop:

chmod +x scripts/install_shell_commands.sh
./scripts/install_shell_commands.sh

• Ollama nicht erreichbar:

  • In der UI: Ollama-Status aktualisieren oder Ollama starten
  • Alternativ im Terminal: ./scripts/start_ollama.command

• Port 8501 belegt:

AUDIO_TRANSKRIBER_PORT=8502 ./scripts/launch_audio_transkriber.command

Dokumentation

• Nutzung (macOS/Launchpad): docs/usage/macos-launchpad-start.md
• Projekt-Manifest: docs/project-manifest-audio-transkriber-v1-0.md
• ADR-001: docs/adr/ADR-001_local-first-transcription-stack-whisperx-mps-ollama.md
• ADR-002: docs/adr/ADR-002_ollama-availability-ui-and-service-start-strategy.md
• Struktur-Blueprint: docs/architecture/project-structure.md
• Feature-Erweiterungen: docs/architecture/feature-expansion-proposals.md

Distribution (Maintainer)

B) Python-Package (PyPI)

• Packaging-Metadaten sind in pyproject.toml hinterlegt.
• Lokaler Build-Test:

python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*.whl dist/*.tar.gz

• Publish erfolgt automatisiert über GitHub Actions Workflow .github/workflows/publish-pypi.yml bei Tag-Push (v*).
• Für Veröffentlichung auf PyPI wird empfohlen, Trusted Publishing für das Repository in PyPI zu konfigurieren.

C) macOS-App-Artefakt für GitHub Releases

• Workflow .github/workflows/release-macos-app.yml baut beim GitHub-Release (published) ein macOS-App-Bundle.
• Das Artefakt wird als ZIP (Audio-Transkriber-macOS-<tag>.zip) an das Release angehängt.
• Aktuell ohne Code Signing/Notarization (lokaler Use-Case / Gatekeeper-Warnung möglich).