17 KiB
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,mpvodervlc - 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.13installiert und kann direkt verwendet werden.
Installation
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:
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_float32ist der bevorzugte Modus.- FP16 und BF16 werden nie automatisch verwendet.
- Falls
int8_float32nicht gemeldet wird, wirdfloat32versucht, danachint8. - 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:
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:
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
-
Konfiguration prüfen (optional anpassen):
cat config.toml -
Systemdiagnose ausführen:
sjaudiosearch diagnose -
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
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
# 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
sjaudiosearch search "Der Schlüssel liegt im alten Haus"
Optionen:
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):
[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
- Normalisierung der Anfrage (Kleinschreibung, Satzzeichen entfernen, Leerraum vereinheitlichen). Der gespeicherte Originaltext bleibt unverändert.
- Kandidatensuche über SQLite FTS5 (ODER-Verknüpfung, Präfixe für längere Wörter) und den FTS5-Trigramm-Index (Teilzeichenketten).
- 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.
- 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. - Fallback: Reichen die FTS-Kandidaten nicht aus, werden alle übrigen
Dateien vollständig durchsucht. Dadurch wird z. B.
austeilengefunden, obwohl WhisperAussteilengeschrieben hat und FTS keinen Treffer liefert. - 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
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
ffplayhö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 = falselä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.
removelö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.