Files
2026-11-16 16:29:32 +01:00

516 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SjAudioSearch
Lokale Suchmaschine für Hörspiele, Hörbücher und andere Audiosammlungen.
SjAudioSearch liest einen kompletten Audioordner rekursiv ein, transkribiert alle
Dateien lokal mit **faster-whisper** und durchsucht anschließend sämtliche
Transkripte. Die Suche funktioniert auch dann, wenn man sich nur ungefähr an
einen Satz erinnert oder wenn Whisper Wörter falsch erkannt hat.
```
Gesucht: "Der Schlüssel liegt im alten Haus"
Transkript: "Der Schlüssel befindet sich in dem alten Haus."
Ergebnis: Ähnlichkeit 89 %, Zeitstempel 00:42:13, Kontext 50 Wörter davor/danach
```
Es werden **keine Cloud-Dienste und keine kostenpflichtigen APIs** verwendet.
Alles läuft lokal: Transkription, Datenbank, Volltextsuche und Kontextaufbau.
---
## Funktionsumfang
- Rekursiver Scan von MP3, WAV, FLAC, M4A, OGG, OPUS und WMA
- Änderungserkennung über Dateigröße und Änderungszeit (SHA256 nur bei Bedarf)
- Duplikaterkennung über Inhalts-Hash
- Lokale Transkription mit faster-whisper/CTranslate2, Modell wird nur einmal geladen
- Fortsetzbare Warteschlange, Fehler einer Datei stoppen den Lauf nicht
- SQLite-Datenbank mit FTS5-Volltextindex, Trigramm-Index und Wort-Zeitstempeln
- Fuzzy-Suche mit RapidFuzz und Sliding-Window-Vergleich über Segmentgrenzen
- Fallback-Suche auch ohne FTS-Treffer (wichtig bei komplett falsch erkannten Wörtern)
- Kontext mit 50 Wörtern vor und nach dem Treffer, Zeitstempel aus der Originaldatei
- Wiedergabe der Fundstelle über `ffplay`, `mpv` oder `vlc`
- GPU-Diagnose inklusive tatsächlich unterstützter Compute Types
- Automatischer CPU-Fallback
---
## Voraussetzungen
| Komponente | Anforderung |
| --- | --- |
| Betriebssystem | Linux (getestet: CachyOS/Arch, Kernel 7.3), Windows/macOS mit CPU-Fallback möglich |
| Python | 3.10 bis 3.13 (getestet mit 3.13.15) |
| GPU | optional; getestet mit NVIDIA GTX 1070 Ti |
| NVIDIA-Treiber | ≥ 525 für CUDA 12 (getestet: 580.196.07) |
| ffmpeg/ffplay | optional, für Wiedergabe und einige WMA-Codecs |
| Freier Speicher | large-v3 benötigt ca. 3 GB, small ca. 0,5 GB |
> **Python 3.14 wird derzeit nicht unterstützt**, weil für CTranslate2/faster-whisper
> keine passenden Wheels verfügbar sind. Unter CachyOS/Arch ist `python3.13`
> installiert und kann direkt verwendet werden.
---
## Installation
```bash
cd /pfad/zu/sjaudiosearch
# Isolierte Umgebung mit Python 3.13
python3.13 -m venv .venv
source .venv/bin/activate
# Projekt + Abhängigkeiten installieren (inkl. CUDA-12-Laufzeit)
pip install -e ".[cuda]"
# Alternativ rein auf der CPU:
# pip install -e .
```
### Arch Linux (AUR)
Das Projekt bringt ein `PKGBUILD` mit, das SjAudioSearch systemweit unter
`/usr` installiert:
```bash
makepkg -si
```
Die CUDA-Laufzeit wird über die offiziellen NVIDIA-Pip-Pakete installiert
(`nvidia-cublas-cu12`, `nvidia-cudnn-cu12`). Es ist **keine systemweite
CUDA-Installation** und kein Eingriff in `/etc/ld.so.conf` nötig.
### Feste Versionen
| Paket | Version |
| --- | --- |
| faster-whisper | 1.2.1 |
| ctranslate2 | 4.9.0 |
| av (PyAV) | 16.1.0 (siehe Hinweis unten) |
| typer | 0.29.1 |
| rich | 15.0.0 |
| rapidfuzz | 3.14.6 |
| mutagen | 1.48.1 |
| pytest | 9.2.0 |
| nvidia-cublas-cu12 | 12.9.3.13 |
| nvidia-cudnn-cu12 | 9.28.1.4 |
**Warum PyAV 16.1.0?** faster-whisper 1.2.1 ruft `av.open(..., metadata_errors="ignore")`
auf. PyAV 17+ hat dieses Argument entfernt, wodurch jede Transkription mit
`TypeError: open() got an unexpected keyword argument 'metadata_errors'`
abbrechen würde. 16.1.0 ist die neueste Version, die beides erfüllt:
kompatibel zu faster-whisper und mit Wheels für Python 3.13.
---
## GPU-Konfiguration (GTX 1070 Ti / Pascal)
Die GTX 1070 Ti ist eine Pascal-Karte mit **Compute Capability 6.1**. Sie hat
keine FP16-/BF16-Tensor-Cores. Deshalb gilt:
- **`compute_type = int8_float32`** ist der bevorzugte Modus.
- **FP16 und BF16 werden nie automatisch verwendet.**
- Falls `int8_float32` nicht gemeldet wird, wird `float32` versucht, danach `int8`.
- Ist CUDA nicht nutzbar, läuft die Transkription automatisch auf der CPU.
Die verfügbaren Compute Types werden zur Laufzeit über CTranslate2 ermittelt,
nicht geraten:
```bash
sjaudiosearch diagnose
```
Verifiziertes Ergebnis auf diesem System:
```
NVIDIA GeForce GTX 1070 Ti
Treiber 580.196.07
CUDA (Treiber) 13.0
VRAM 8192 MB
Compute Capability 6.1
CUDA-Geräte 1
Compute Types (CUDA) float32, int8, int8_float32
Compute Types (CPU) float32, int16, int8, int8_float32
Verwendet cuda / int8_float32
FP16/BF16 nicht verwendet
```
### CUDA-Bibliotheken ohne Systemeingriff
CTranslate2 linkt dynamisch gegen `libcublas.so.12` und `libcudnn.so.9`. Die
Pip-Pakete legen diese Bibliotheken unter
`.venv/lib/python3.13/site-packages/nvidia/.../lib` ab, wo der dynamische
Linker sie nicht von allein findet. SjAudioSearch lädt sie deshalb beim Start
mit `ctypes` und `RTLD_GLOBAL` vor (`sjaudiosearch/system/gpu.py`,
`ensure_cuda_libraries`). Das ist kein Hack an Systemdateien, sondern eine
lokale, nachvollziehbare Initialisierung.
### Modellspeicher
| Modell | Download | VRAM (int8_float32) |
| --- | --- | --- |
| large-v3 (Default) | ca. 3,4 GB | ca. 1,5–2 GB |
| medium | ca. 1,5 GB | ca. 1 GB |
| small | ca. 0,5 GB | ca. 0,5 GB |
| base | ca. 0,15 GB | ca. 0,2 GB |
Die Modelle landen in `./data/models` (konfigurierbar über
`transcription.model_dir`).
### CPU-Fallback
Ohne GPU oder bei einem CUDA-Fehler:
```bash
sjaudiosearch transcribe --device cpu --compute-type int8
```
Das Programm wechselt auch automatisch auf die CPU, wenn das Laden im
GPU-Modus fehlschlägt, und informiert darüber im Terminal. Die CPU ist
deutlich langsamer; die Ergebnisse sind identisch.
---
## Ersteinrichtung
1. Konfiguration prüfen (optional anpassen):
```bash
cat config.toml
```
2. Systemdiagnose ausführen:
```bash
sjaudiosearch diagnose
```
3. Datenbank und Logs werden beim ersten Befehl automatisch angelegt.
Relative Pfade in `config.toml` werden relativ zur Konfigurationsdatei
aufgelöst. Eine andere Konfiguration lässt sich mit `--config` oder der
Umgebungsvariable `SJAUDIOSEARCH_CONFIG` verwenden. Ohne eigene Konfiguration
wird zusätzlich `~/.config/sjaudiosearch/config.toml` und
`/etc/sjaudiosearch/config.toml` durchsucht; nach einer systemweiten
Installation landen Datenbank und Logs in `~/.local/share/sjaudiosearch`.
---
## Erster Scan
```bash
sjaudiosearch scan "/home/user/Music/Hoerspiele"
```
Ausgabe: gefundene Dateien, neue/geänderte/unveränderte Dateien, Duplikate und
Dateien mit Problemen. Fehlerhafte Dateien werden mit Status `error` gespeichert
und im Log protokolliert.
Erneutes Scannen ist günstig: unveränderte Dateien werden nur über Größe und
Änderungszeit geprüft. Hashes werden im Modus `auto` nur berechnet, wenn
Duplikate möglich sind.
---
## Erste Transkription
```bash
# Standard: large-v3, CUDA, int8_float32, Deutsch
sjaudiosearch transcribe
# Weniger VRAM / schneller Test
sjaudiosearch transcribe --model small
# Nur 10 Dateien, bereits fertige erneut verarbeiten
sjaudiosearch transcribe --limit 10 --force
# Andere Sprache oder automatische Erkennung
sjaudiosearch transcribe --language en
sjaudiosearch transcribe --language auto
```
Während des Laufs werden aktuelle Datei, Fortschritt, Dauer, Fehler und die
durchschnittliche Geschwindigkeit angezeigt. Der Status jeder Datei wird
dauerhaft gespeichert. Nach einem Abbruch oder Neustart macht
`sjaudiosearch transcribe` an der letzten Stelle weiter.
---
## Erste Suche
```bash
sjaudiosearch search "Der Schlüssel liegt im alten Haus"
```
Optionen:
```bash
sjaudiosearch search "..." --limit 50 --min-score 70 --context-words 50
sjaudiosearch search "..." --language de
sjaudiosearch search "..." --json
sjaudiosearch search "..." --verbose
```
Jeder Treffer enthält Dateiname, vollständigen Pfad, Ähnlichkeit (0–100 %),
Start-/Endzeit, 50 Wörter Kontext davor und danach sowie die Fundstelle selbst.
Der Ähnlichkeitswert ist eine Vergleichsbewertung, **keine statistische
Wahrscheinlichkeit**.
---
## CLI-Befehlsübersicht
| Befehl | Zweck |
| --- | --- |
| `sjaudiosearch diagnose` | Systembericht: GPU, CUDA, Compute Types, FTS5, Player |
| `sjaudiosearch scan <ordner>` | Ordner rekursiv scannen, neue/geänderte Dateien vormerken |
| `sjaudiosearch transcribe` | Transkriptionswarteschlange abarbeiten |
| `sjaudiosearch search "<text>"` | Fuzzy-Suche über alle Transkripte |
| `sjaudiosearch status` | Anzahl Dateien, Status, Spieldauer, Datenbankgröße, Modell |
| `sjaudiosearch list` | Bekannte Dateien auflisten (`--status`, `--search`, `--limit`) |
| `sjaudiosearch info <ID>` | Details zu Datei und Transkript |
| `sjaudiosearch play <ID> --time 120` | Datei ab 120 s abspielen (ffplay/mpv/vlc) |
| `sjaudiosearch retry` | Fehlgeschlagene Transkriptionen zurücksetzen |
| `sjaudiosearch reindex` | Suchindex aus vorhandenen Transkripten neu aufbauen |
| `sjaudiosearch remove <ID>` | Datei aus dem Index entfernen (Original bleibt erhalten) |
| `sjaudiosearch check` | Datenbank, FTS5, Trigramme und Pfade prüfen |
`--version` zeigt die Programmversion. `--config` wählt eine andere TOML-Datei.
---
## Konfiguration
`config.toml` (vollständig kommentiert im Projekt):
```toml
[transcription]
model = "large-v3"
device = "cuda"
compute_type = "int8_float32"
language = "de" # "auto" für automatische Erkennung
beam_size = 5
word_timestamps = true
vad_filter = true
model_dir = "./data/models"
[search]
default_limit = 50
default_min_score = 70
context_words = 50
window_before = 2 # Suchfenster = Anfrage - 2 Wörter
window_after = 4 # Suchfenster = Anfrage + 4 Wörter
candidate_limit = 4000
min_token_overlap = 0.34
exhaustive_fallback = true
max_hits_per_file = 5
[processing]
workers = 1
resume = true
compute_hash = "auto" # auto, always, never
hash_max_size_mb = 4096
[database]
path = "./data/sjaudiosearch.db"
[logging]
level = "INFO"
path = "./logs/sjaudiosearch.log"
```
Unbekannte Schlüssel werden beim Start gemeldet, nicht stillschweigend ignoriert.
`workers` ist bewusst auf 1 festgelegt: Die GPU soll nur von einem
Transkriptionsprozess genutzt werden.
---
## Wie die Suche funktioniert
1. **Normalisierung** der Anfrage (Kleinschreibung, Satzzeichen entfernen,
Leerraum vereinheitlichen). Der gespeicherte Originaltext bleibt unverändert.
2. **Kandidatensuche** über SQLite FTS5 (ODER-Verknüpfung, Präfixe für längere
Wörter) und den FTS5-Trigramm-Index (Teilzeichenketten).
3. **Sliding Window** über die Wort-Timeline jeder Kandidatendatei. Die
Fenstergröße liegt bei Anfrage −2 bis Anfrage +4 Wörtern, die Timeline läuft
über Segmentgrenzen hinweg.
4. **Bewertung** mit RapidFuzz (`ratio`, `token_set_ratio`, `WRatio`,
`partial_ratio`). Teilfenster werden über das Längenverhältnis gedämpft,
damit ein einzelnes Wort einer mehrwörtigen Anfrage nicht als 100-%-Treffer
gilt.
5. **Fallback**: Reichen die FTS-Kandidaten nicht aus, werden alle übrigen
Dateien vollständig durchsucht. Dadurch wird z. B. `austeilen` gefunden,
obwohl Whisper `Aussteilen` geschrieben hat und FTS keinen Treffer liefert.
6. **Entduplizierung und Sortierung** nach Ähnlichkeit, danach Begrenzung auf
`--limit`.
### Kontext und Zeitstempel
Der Kontext wird aus der durchgehenden Wort-Timeline geschnitten, nicht aus
einzelnen Segmenten. Dadurch beginnt und endet er exakt an der Fundstelle, auch
mitten in einem Segment. Liegen Wort-Zeitstempel vor, wird die Genauigkeit als
`Wort` ausgewiesen; andernfalls werden Zeiten innerhalb des Segments verteilt
und als `Segment` gekennzeichnet. Die Zeit bezieht sich immer auf die
Originaldatei.
---
## Datenbank
SQLite mit WAL, Foreign Keys und Migrationen (`PRAGMA user_version`).
| Tabelle | Inhalt |
| --- | --- |
| `audio_files` | Pfad, Dateiname, Dauer, Größe, Änderungszeit, Hash, Status, Duplikat-Verweis |
| `transcripts` | ein Transkript pro Datei, Sprache, Modell, Volltext |
| `segments` | Text mit Start-/Endzeit und Confidence |
| `words` | optionale Wort-Zeitstempel |
| `search_index` | FTS5-Volltextindex (unicode61, ohne Diakritika) |
| `search_trigram` | FTS5-Trigramm-Index für Teilzeichenketten |
| `meta` | interne Metadaten |
Transkripte werden pro Datei in einer Transaktion gespeichert: Entweder ist
eine Datei vollständig verarbeitet oder sie bleibt `pending`/`error`. Ein
Absturz hinterlässt keinen halben Suchindex.
---
## Tests
```bash
pip install -e ".[test]"
pytest
```
Die Tests verwenden winzige, künstlich erzeugte WAV-Dateien und eine
Fake-Transkriptions-Engine. Es wird **kein Whisper-Modell heruntergeladen**.
Getestet werden unter anderem:
- Scan mehrerer Dateien, Duplikat- und Änderungserkennung, defekte Dateien
- Datenbankschema, Migrationen, Foreign-Key-Kaskaden, Transkripte, Wörter
- Statusverwaltung, Retry, Wiederaufnahme, `--force`, `--limit`
- Fuzzy-Suche mit fehlenden/zusätzlichen/falsch erkannten Wörtern
- Suche über Segmentgrenzen hinweg
- Fallback-Suche ohne FTS-Treffer
- 50 Wörter Kontext davor/danach und Zeitstempel-Genauigkeit
- Reindex ohne Veränderung der Transkripte
- CPU-Fallback und Ablehnung von FP16 auf Pascal
Ergebnis dieser Umgebung:
```
49 passed
```
---
## Verifizierter GPU-Test
Auf der GTX 1070 Ti wurde der komplette Ablauf mit echten deutschen
Sprachaufnahmen (Public-Domain-Dateien von Wikimedia Commons) ausgeführt:
```
Modell large-v3
Gerät cuda (GPU)
Compute Type int8_float32
GPU NVIDIA GeForce GTX 1070 Ti (CC 6.1, 8192 MB)
Warteschlange 2
Erfolgreich 2
Audiodauer 24 s
Laufzeit 2 s
Durchschnitt 13.10x Echtzeit
```
Beispiel für die Fallback-Suche (Whisper schrieb `Aussteilen` statt
`austeilen`):
```
$ sjaudiosearch search "Austeilen"
[1] hoerspiel_02.wav
Similarity: 94.7%
Timestamp: 00:00:06 (bis 00:00:08, Wort-Genauigkeit)
Quelle: fallback
```
Das sind kurze Testclips, kein Benchmark über komplette Hörspiele. Die
Transkription lief vollständig auf der GPU; die Geschwindigkeit hängt von
Dateilänge, Modell und Festplattenzugriff ab.
---
## Bekannte Einschränkungen
- **Wiederholtes identisches Audio:** Whisper (large-v3) hat in einem Testclip
drei identische Sätze hintereinander nur einmal transkribiert. Das ist ein
Modellverhalten, kein Fehler der Datenbank oder der Suche. Unterschiedliche
Dialoge sind davon nicht betroffen.
- **Wiedergabe** benötigt ein funktionierendes Audio-Ausgabegerät. Der Befehl
wurde hier mit einem Dummy-Audiotreiber geprüft; auf einem normalen Desktop
startet `ffplay` hörbar.
- **WMA** ist nur zuverlässig, wenn PyAV/FFmpeg den jeweiligen Codec kennt.
- Ohne Wort-Zeitstempel (`word_timestamps = false`) sind Zeitangaben
segmentgenau; das wird im Ergebnis entsprechend gekennzeichnet.
- Die Fallback-Suche durchsucht bei wenigen Treffern alle übrigen Dateien. Das
ist für Korrektheit wichtig, kostet bei sehr großen Sammlungen aber Zeit.
Mit `exhaustive_fallback = false` lässt sich das abschalten.
- Es läuft bewusst nur ein Transkriptionsprozess gleichzeitig (eine GPU).
- Python 3.14 wird wegen fehlender CTranslate2-Wheels nicht unterstützt.
- `remove` löscht ausschließlich Indexdaten, niemals die Audiodatei.
- Ein vollständiger Benchmark über mehrere Stunden Hörspielmaterial wurde in
dieser Umgebung nicht durchgeführt.
---
## Fehlerbehebung
| Problem | Lösung |
| --- | --- |
| `Library libcublas.so.12 is not found` | `pip install -e ".[cuda]"` (nvidia-cublas-cu12, nvidia-cudnn-cu12) |
| `CUDA ist nicht nutzbar` | Treiber prüfen (`nvidia-smi`), danach `sjaudiosearch diagnose`; notfalls `--device cpu` |
| `float16` nicht unterstützt | Pascal: `compute_type = "int8_float32"` oder `"float32"` verwenden |
| `TypeError ... metadata_errors` | PyAV-Version prüfen: `pip install av==16.1.0` |
| Kein FTS5 | Python mit FTS5-Unterstützung installieren (Standard bei python.org/Arch) |
| Kein Player gefunden | `ffmpeg` installieren (enthält `ffplay`) oder `mpv`/`vlc` |
| Modell-Download schlägt fehl | Internetverbindung prüfen; Modell manuell nach `./data/models` legen |
| GPU-Speicher voll | kleineres Modell (`--model small`), `--limit`, oder CPU verwenden |
| Suche findet nichts | `--min-score` senken, `--context-words` erhöhen, `sjaudiosearch reindex` |
| Datei dauerhaft `error` | Ursache in `logs/sjaudiosearch.log`; danach `sjaudiosearch retry` |
Logs: `./logs/sjaudiosearch.log` (rotierend, 5 MB × 3).
Datenbank: `./data/sjaudiosearch.db`.
---
## Projektstruktur
```
sjaudiosearch/
├── sjaudiosearch/
│ ├── cli.py # Typer-CLI
│ ├── config.py # TOML-Konfiguration
│ ├── core/ # Scanner, Metadaten, Audio, Modelle
│ ├── transcription/ # faster-whisper-Engine und Warteschlange
│ ├── search/ # Fuzzy, Sliding Window, Kontext, Ranking
│ ├── database/ # Verbindung, Schema, Migrationen, Repository
│ ├── system/ # GPU-Diagnose und Systembericht
│ └── utils/ # Hashing, Formatierung, Logging
├── tests/ # pytest-Suite (49 Tests)
├── config.toml
├── pyproject.toml
├── PKGBUILD # Paket fuer Arch Linux / AUR
├── data/ # Datenbank und Modelle (nicht versioniert)
├── logs/ # Logdateien (nicht versioniert)
└── README.md
```
---
## Lizenz
MIT. Die Testaufnahmen stammen aus Wikimedia Commons (Public Domain bzw.
freie Lizenzen) und sind nicht Teil des Projekts.