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

17 KiB
Raw Permalink Blame History

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

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_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:

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

  1. Konfiguration prüfen (optional anpassen):

    cat config.toml
    
  2. Systemdiagnose ausführen:

    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

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

  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

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.