audio-transkriber 0.1.0
Local-first transcription and semantic analysis tool
Requires Python: >=3.10

# 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.

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

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

Stoppen:

```bash
./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:

```bash
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:

```bash
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:

```bash
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).