# 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 rekursiv scannen, neue/geänderte Dateien vormerken | | `sjaudiosearch transcribe` | Transkriptionswarteschlange abarbeiten | | `sjaudiosearch search ""` | Fuzzy-Suche über alle Transkripte | | `sjaudiosearch status` | Anzahl Dateien, Status, Spieldauer, Datenbankgröße, Modell | | `sjaudiosearch list` | Bekannte Dateien auflisten (`--status`, `--search`, `--limit`) | | `sjaudiosearch info ` | Details zu Datei und Transkript | | `sjaudiosearch play --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 ` | 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.