sfx-library

Soundeffekt-Bibliothek

834 Dateien / 63 Kategorien / ~1 GB. Ein einziger Einstiegspunkt: das Skript sfx befindet sich im selben Verzeichnis wie diese SKILL.md-Datei. Das Skript ermittelt seinen eigenen Pfad automatisch, daher kann es von überall mit dem vollständigen Pfad aufgerufen werden – die folgenden Beispiele verwenden der Einfachheit halber sfx.

Schritt 0 – Prüfen, ob Daten bereits vorhanden sind

Das Repository enthält nur Code und Katalog; die Audiodateien liegen in data/ (nicht eingecheckt).

sfx status

Meldet „Keine Daten vorhanden“? Dann die Daten herunterladen – einmalig, ~1 GB, den Benutzer vor dem Download informieren:

sfx setup

setup folgt einer festen Prioritätsreihenfolge – diese nicht umkehren:

1. Zuerst Google Drive – eine .zip-Datei herunterladen (~880 MB, etwa 1 Minute), SHA256 prüfen und entpacken.
2. Im Katalog hinterlegte URLs als Fallback – nur verwenden, wenn Drive fehlschlägt (404, Datei nicht öffentlich geteilt, Download-Limit erreicht, SHA256-Fehler). In diesem Fall lädt setup automatisch jede Datei einzeln über die URL in catalog/source/*.json herunter (sequentiell, ~18 Minuten) und prüft SHA256 gegen catalog/meta.json.

Erfordert nur python3 (≥ 3.8), keine weiteren Installationen. Wird der Vorgang unterbrochen, einfach sfx setup erneut ausführen – er setzt fort, ohne neu zu beginnen. Der Fallback-Schritt ist langsam: im Hintergrund ausführen und den Benutzer über die Wartezeit informieren.

sfx setup --source nur dann direkt aufrufen (d. h. ohne Drive-Versuch), wenn der Benutzer es ausdrücklich verlangt.

Meldet setup „Beide Quellen fehlgeschlagen“, dann sfx doctor ausführen und den Benutzer informieren – keine anderen Audioguellen eigenständig suchen.

SFX suchen – der einzige Befehl, den man sich merken muss

sfx find "<Suchbegriff>"

Eingabe auf Deutsch (mit oder ohne Umlaute) sowie auf Englisch führt zu denselben Ergebnissen – Umlaute werden vor dem Vergleich normalisiert, und jede Kategorie verfügt über zweisprachige Schlüsselwörter.

sfx find "Übergang"              # nach Absicht
sfx find "Benachrichtigung" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5

Die Ausgabe enthält jeweils die Dauer (Sekunden) – die wichtigste Information beim Einpassen von SFX in die Timeline.

Flag	Verwendung
--max-dur N / --min-dur N	Dauer auf ein Zeitfenster in der Timeline beschränken
--group <Gruppe>	eine ganze Absicht durchsuchen (siehe Gruppentabelle unten)
--category <Slug>	wenn die genaue Kategorie bereits bekannt ist
--ext wav	nur WAV- (oder MP3-)Dateien anzeigen
--paths	nur Pfade ausgeben, eine Datei pro Zeile – direkt zur Weiterverarbeitung in anderen Befehlen
--json	maschinenlesbare Ausgabe mit duration, sha256, score
--abs	absolute Pfade – verwenden, wenn sfx aus einem anderen Verzeichnis aufgerufen wird
-n N / --all	Anzahl der Ergebnisse (Standard: 20)

Mehrere Suchbegriffe werden standardmäßig mit AND verknüpft; wenn keine Datei alle Begriffe erfüllt, wird automatisch auf OR umgeschaltet und eine entsprechende Meldung auf stderr ausgegeben.

Bei Unsicherheit: sfx list zeigt alle Kategorien mit „Verwendung“ und Schlüsselwörtern an.

10 Gruppen nach Absicht

Zuerst eine Gruppe auswählen, dann filtern – schneller, als Kategorienamen zu erraten.

Gruppe	Verwendung	Typische Kategorien
transition	Zwei Szenen verbinden	fast-whoosh swoosh-swish whip zoom reverse
impact	Punkt setzen, Zahlen präsentieren	hit boom impacts slam bass
ui	Texteinblendungen, Button-Klicks, Tastatur	pop click typing ui-mini tick shine
alert	Benachrichtigungen, Erinnerungen	notification ding bell alarm
tension	Spannung vor dem Höhepunkt aufbauen	riser builder braam tension trailer
ambience	Hintergrundatmosphäre für eine Szene	ambience environment
foley	Reale Objektgeräusche	paper doors footsteps liquid draw camera-shutter
comedy	Humorvoll	comedy-cartoon memes
scifi	Technologie, Fantasie	technology glitch laser magic data
horror	Gruselig	horror jumpscare

Vorhören vor der Auswahl

Der Slug-Name reicht nicht, um die Klangfarbe einer Datei zu erahnen. whoosh-fast-05 und whoosh-fast-06 können sich klanglich völlig unterscheiden.

afplay "$(sfx find whoosh --paths --abs -n 1)"     # macOS; Linux: ffplay -nodisp -autoexit

Ist Abspielen nicht möglich (headless), dann 2–3 Auswahlmöglichkeiten mit Dauer anzeigen und den Benutzer wählen lassen – nicht eigenständig entscheiden und behaupten, es passe.

SFX in Video einfügen

sfx mix video.mp4 -o mit-ton.mp4 \
    2.4:fast-whoosh/whoosh-fast-05.wav \
    5.0:ding/[email protected]

Jeder Cue ist <Sekunden>:<Pfad>[@Lautstärke]. Der Pfad bezieht sich auf data/sfx/, alternativ kann nur der Dateiname angegeben werden, wenn keine Dopplungen auftreten. Standardlautstärke: 0.6. Benötigt ffmpeg.

• Vorhandene Audiospuren im Video bleiben erhalten und werden gemischt, nicht überschrieben – die Ausführung von sfx mix nach dem Hinzufügen von Voiceover ist unbedenklich.
• Verwendet amix=normalize=0 + alimiter: zusätzliche Cues verringern die Originallautstärke nicht und verhindern Verzerrungen bei überlappenden Quellen.
• --dry-run gibt den ffmpeg-Befehl aus, falls er in ein anderes Skript eingebunden werden soll.

Videos, die aus HTML erstellt wurden (Playwright/Puppeteer/Remotion-Bildschirmaufnahmen): <audio>-Tags oder new Audio().play() sind nur im Browser hörbar – sie erscheinen nicht in der aufgenommenen MP4-Datei. Fügen Sie SFX daher im ffmpeg-Schritt mit sfx mix hinzu und verwenden Sie die Zeitmarken aus der Timeline-Animation.

Drei Faktoren entscheiden, ob ein Video professionell klingt:

1. SFX muss kürzer sein als das Zeitfenster in der Timeline – von Anfang an mit --max-dur filtern, anstatt später zu schneiden.
2. SFX genau auf den Frame der Bewegung setzen, nicht an den Szenenanfang – der Whoosh muss genau dann einsetzen, wenn das Objekt sich zu bewegen beginnt.
3. SFX nicht über Sprache legen. Bei Voiceover die Lautstärke auf @0.3 reduzieren oder die Kategorie ui-mini verwenden.

Drei häufige Fehler

1. data/ nicht einchecken – ~1 GB, bereits in .gitignore, mit sfx setup neu herunterladen.
2. Dateien in data/sfx/ nicht bearbeiten. Dies sind die Originale; schneiden oder Normalisieren in ein separates Verzeichnis ausgeben.
3. Nicht direkt sfx download für den Erstdatendownload verwenden. Es lädt 834 Einzeldateien, ist langsam und der Fallback-Pfad. Immer sfx setup verwenden, damit zuerst Google Drive versucht wird.

Bei Verdacht auf Probleme: sfx doctor (Werkzeug + Datenquelle prüfen), sfx verify --hash (SHA256 jeder Datei erneut berechnen).

Wartung der Bibliothek (Kategorie hinzufügen, neu packen, Drive-Link ändern): siehe README.md.