Initial commit

This commit is contained in:
2026-11-16 16:29:32 +01:00
commit 97e5c9ef4d
37 changed files with 5932 additions and 0 deletions
+515
View File
@@ -0,0 +1,515 @@
# 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.