Echte-SFX

real-sfx: Echte Klänge für ein Bewegtbild-Video

Das Ziel: Der Film klingt, als hätte ihn eine Person mit einer guten Bibliothek geschnitten. Also:

• Klang wird niemals synthetisiert. Quellen: die Bibliotheken des Nutzers (config.json) und uisfx (ein fertiges CC0-Paket mit Interface-Klängen, selbst synthetisiert: die eine Ausnahme, nur für Interface-Momente; "keine Synthese" schaltet es aus: --ui library. Passt kein Klang: der Moment bleibt still und wird in den Bericht aufgenommen. Dies überschreibt "keine Spur: synthetisieren" aus motion-standards.
• Du kannst nicht hören. Klang wird als Zahlen, Wörter und Bilder gelesen (references/listening.md). Stelle eine Auswahl nicht als gehört dar: sage, was durch Augenschein und Messung geprüft wurde und was der Nutzer anhören sollte.
• Behalte die Musik und Sprachspur bei, wenn sie den Film tragen. Das Ergebnis ist immer eine neue MP4 und eine separate WAV-Spur.
• Nicht verdoppeln. Die im Render-Audio eingebettete Synthese wird durch die echten Klänge ersetzt, nicht darunter gelegt (Schritt 1). Die Kritik misst dies als Zahl (die doubling-Achse).
• Ändere weder das Projekt noch den Skill-Ordner. Lege alle Arbeitsdateien in deinem eigenen Ordner ab (work/, result/).

Im Video Director

(Hinzugefügt in der Kopie des Video Directors; nicht im Original von Clipwing. UPSTREAM.md listet jede Änderung.) Diese Kopie befindet sich innerhalb des Video Director-Skills und wird von dessen Sound-Stufe ausgeführt: ../references/sound-stage.md, "Tontechnik". Diese Schritte legen fest, welche Momente einen Klang erhalten, geben diesem Skill nur diese (build/audio/sfx/events.json), fixieren die Aufnahmen, die der Nutzer ausgewählt hat (sound_handoff.py pins), führen ihn mit --ui library, --no-loudnorm und ohne Textur-Schicht oder Bett aus und nehmen nur die Effektspur und die aufgelösten Cues zurück (sound_handoff.py collect). Folge ihnen und lies diese Datei nur für Optionen, die sie nicht abdecken. Setze REAL_SFX_CONFIG, REAL_SFX_INDEX, REAL_SFX_TASTE, REAL_SFX_RATINGS, REAL_SFX_STEADY und REAL_SFX_STYLES auf Pfade unter ~/.config/real-sfx/ (das Plugin installiert jede Version in einem neuen Ordner, sodass alles, was hier geschrieben wird, beim nächsten Update zurückgelassen wird) und verwende nicht --remember, das in diesen Ordner schreibt (das tut auch learn_style.py: kopiere einen gelernten Stil in ~/.config/real-sfx/styles/).

Schneller Pfad

Zuerst python scripts/setup.py check (ffmpeg, Haupt-/Zusatzbibliotheken, Index, uisfx) und python scripts/look.py FILM.mp4 --out work/look (Frames mit Zeit + dem originalen Klang darunter). Dann, je nachdem, was du hast:

# 1. Das Projekt hat eine Ereignisliste (docs/cues.json, scripts/cues.json) ODER ein Skript, das seinen Klang synthetisiert (audio.cjs)
python scripts/from_cues.py PROJECT_FOLDER|docs/cues.json --video RENDER.mp4 --out work/cues.json
# 2. Bildschirmaufnahme ohne Liste: ui_events.py ... (references/screencast.md), dann from_cues.py work/ui/events.json
# 3. Nur Bild:                    find_moments.py FILM.mp4 --out work/moments; suggest_cues.py work/moments/moments.json --out work/cues.json
# 3b. SANFTE FARBIGE ANIMATION ohne Liste (UI-Vorschau, Illustration, Motion Graphics): Automatisierung erkennt 5-6 Bewegungen von 40.
#     Schritt 2, "Stille Animation ohne Liste": find_moments.py FILM --out work/moments --fine; look.py FILM --at T --span 2.4
#     --step 0.1 --out work/at.png; EIGENE Ereignisliste aus den Frames (references/typed-cues.md) -> from_cues.py - --ui library
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --plan     # was wohin kommt; dann ohne --plan
python scripts/critique.py result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav
python scripts/levels.py   result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav --json work/edits.json
# ein Film, dessen Klang NUR SFX ist (keine eigene Musik oder Sprachspur): kleine Klänge in den Lücken, dann mix.py erneut (Schritt 4, "Kleinklang-Schicht")
python scripts/texture.py work/cues.json --moments work/moments/moments.json
# derselbe Film: ein Bett (eine lange, dunkle, echte Aufnahme unter dem gesamten Film; Schritt 4, "Bett"), dann mix.py erneut
python scripts/bed.py work/cues.json [--list]
# Zahlen gegen neun fertige SFX-Spulen (Schritt 6, "Gegen die Referenz"): keine Bewertungen, beeinflusst das Urteil nicht
python scripts/critique.py RESOLVED.json WAV --style clean-sfx-refs
# menschliche Ohren, billig gemacht (Schritt 6): eine Seite mit den Fragen der Kritik und einem Ein-Klick-Urteil; das Maskierungsmodell
python scripts/listen_page.py build work/listen --moments result/film_sfx.mp4 --critique RESOLVED.json WAV
python scripts/listen_page.py serve work/listen [--lan]        # dann: listen_page.py results work/listen --log
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --masking        # welche Klänge der Rest verdeckt (benötigt die venv)

Ein Projektordner findet seine eigene Ereignisliste (docs/, scripts/, assets/); das Synthesizer-Skript wird nur gelesen, wenn es keine Liste gibt. Wähle alle from_cues.py-Flags aus, bevor du das Blatt bearbeitest: ein erneuter Aufruf löscht manuelle Bearbeitungen (dann sheet.py apply). Sprachspur im Film: mix.py ... --voice-safe (Tiefe normal; --voice-depth light bei vielen leisen Texturen, deep nur für seltene Klänge in Pausen: es entfernt die Oberfläche vollständig aus dem Mix). Musik trägt den Film: --duck. Lautstärke: eine neu aufgebaute Basis entspricht standardmäßig dem Original; eigene: --target-lufs NUMBER. Kein Index, oder die Bibliotheken wurden verschoben: python scripts/build_index.py, dann python scripts/listen.py tag-index. Kein uisfx: setup.py init --uisfx. Ein anderer Rechner: setup.py scan FOLDER, setup.py add-library NAME PATH [--tier main|extra] --index. Führe Skripte aus dem Skill-Ordner aus; setze Pfade mit Leerzeichen oder Nicht-Latin-Zeichen in Anführungszeichen; eigenes Python mit Nicht-Latin-Pfaden unter Windows: PYTHONUTF8=1. In PowerShell unterbrechen Anführungszeichen JSON-Argumente: lege sie in eine Datei.

Woher die Klänge kommen

Was benötigt wird	Woher
Die Basis: Woosher, Hits, Riser, Pops, Glocken, Tasten, Papier, Foley, Atmosphäre	die Hauptbibliothek (tier: main, Pfad in config.json). Ein sortiertes Paket mit catalog.json / catalog.csv gibt jedem Klang seinen Typ und seine Quellaufnahme, was besser ist als Raten anhand von Dateinamen
Was der Hauptbibliothek fehlt: tiefe Tropfen, Münzen, kurze Glitches	Fallback-Bibliotheken (tier: extra, markiert mit ~ in Ergebnissen): nur wenn die Hauptbibliothek weniger als drei passende Klänge hat
Designte Pakete mit eigenen Rollen	Rollen granular, atmosphere, power, music_transition, voice werden niemals automatisch angefordert: nimm sie explizit (--role, "pick": {"role": ...})
Ein Interface-Moment: Klick, Tick, Fenster, Benachrichtigung	uisfx (--ui auto) wenn die Liste selbst Interface-Arten benennt (Klick, Glockenspiel...): from_cues sagt warum und wo (routes: key -> library:click, pop -> uisfx:select)
Tippen	immer die echte Tastatur der Bibliothek, auch mit --ui auto; eine Folge von 8+ click-Ereignissen im Abstand von 35–170 ms wird von from_cues selbst als Tippen erkannt (--no-typing-detect)
Physischer Kontakt: Ball, Schritt, Perle, Objekt	immer die Bibliothek: ein Ball auf dem Boden ist ein dumpfer Schlag, nicht select (Rezept unten)

Noch keine Bibliothek: setup.py init --uisfx allein gibt 78 CC0 UI-Cues. Kostenlose echte Aufnahmequellen, die einen Blick wert sind (lese jeweils die Lizenz): Freesound (CC0-Filter), Sonniss GDC-Bundles, Mixkit, Pixabay-Soundeffekte.

"Aus meiner Bibliothek", "keine Synthese" oder "Klänge klingen synthetisch": --ui library. Ein Akzent auf dem Logo oder ein "Cha-Ching" in einem Projekt mit uisfx-Interface-Klängen: --from-library pop,bell (Artnamen aus der Liste); für einen einzelnen Klang: sheet.py set --at T --label bell id=65. Unter tonaler Musik:

• die Tonhöhenschritte von uisfx-Wiederholungen und von den tonalen Klängen der Bibliothek (Glockenspiel, Pop, Glas, Münze) schalten sich von selbst ab, wenn das Projekt eine Partitur hat (--ui-pitch off|cycle);
• die Tonhöhe eines echten Klangs wird an die Noten der Musik angepasst: mix.py nimmt das music_ref des Blatts (das Bett ohne Effekte, den Musik-STEM) oder --music-ref FILE und verschiebt einen tonalen Klang um ganze Halbtöne bis zu 2 plus die Cents, die ihn auf eine Note setzen (insgesamt 2,5), falls dies ihn auf eine Note setzt; Rauschen wird in Ruhe gelassen (--no-tonal-fit; scripts/tonal.py SOUND --music FILE --at T zeigt die Noten);
• die Intervalle der eigenen Frequenzen des Autors (tick(t, 1800 * 2 ** (4 * i / 12))) werden zu den Tonhöhenschritten des Ersatzes (melody:).

Arbeitsablauf

1. Was bereits im Klang ist

look.py zeigt das Spektrogramm des nativen Klangs (Sprachspur ist Band von Phrasen, Musik ein Teppich mit einem Beat, Stille ist schwarz); listen.py voice FILM.mp4 gibt den Anteil von Sprache und Musik. Drei Fälle:

• Die Musik oder Sprachspur des Autors: sie bleiben, SFX gehen darüber (--duck / --voice-safe). Ausnahme (Antwort einer Person auf einem echten Film, 2026-10-19): der Film wurde "zum Sounddesign" gesendet, sein nativer Klang ist nur Musik (listen.py voice: Sprachspur 0 %), und die Person möchte ihn ohne die Musik, wie ihre eigenen sauberen SFX-Spulen. Erstelle eine Version ohne Musik (from_cues.py ... --ui library --drop-original, dann bed.py --id ... --level -46 mit einer Lieblingsatmosphäre), und eine Version mit Musik, falls nützlich, und sage, welche welche ist. In einer blinden Wahl von drei (Original / Effekte über Musik / nur Effekte) wählte die Person die letzte ohne eine einzige Beschwerde. from_cues druckt BAKED: bei einem solchen Film, obwohl es keine eingebettete Synthese gibt (Sprachspur 0 %, Musik 84 %, die Angriffe stimmen nicht mit den Ereignissen überein: 7 % gegenüber 9 % zufällig): dies ist ein Fehlalarm.
• In die Spur eingebettete Synthese (das Projekt wurde für eine synthetisierte Partitur geschrieben): echte Klänge darüber sind eine Verdoppelung. from_cues.py prüft dies selbst (BAKED:, unbake:) und entfernt die Synthese aus der Basis, ohne Musik und Sprachspur zu berühren; wie genau, und was zu tun ist, wenn das Skript fehlschlägt oder die Synthese im Musik-STEM sitzt (--extra-synth): references/project-audio.md (lies es, sobald die Ausgabe BAKED, WARN stems, unbake: not possible enthält, oder das Projekt seinen Klang mit einem Skript synthetisiert). Nach dem Build druckt critique.py die doubling-Achse: die Korrelation der Schicht mit dem Original und mit dem neuen Film (sollte etwa 0 sein).
• Der Klang von Clips, die innerhalb eines Fensters einer Bildschirmaufnahme abgespielt werden: nativ, bleibt; Ereignisse innerhalb dieser Fenster werden verworfen.

2. Finde die Momente (von der besten zur schlechtesten Quelle)

• Die Ereignisliste oder das Synthesizer-Skript des Projekts → from_cues.py (unten). Im Detail: references/typed-cues.md.
• Eine Bildschirmaufnahme → references/screencast.md (ui_events.py Regionen, Zuordnung von Tastenanschlägen zu Zeichen, Clip-Klang).
• HyperFrames mit data-start und ohne Liste: from_hyperframes.py PROJECT --out work/moments.json. "1 Momente" mit 18 Elementen bedeutet, dass die Bewegung nicht data-start folgt: suche nach einem Synthesizer-Skript.
• Nur Video: find_moments.py FILM --out work/moments [--roi x,y,w,h] [--from A --to B] [--fine]; Arten cut, burst, onset, settle (settle feuert auch bei einem leeren Frame oder einer Schleife im Ruhezustand: schau auf den Frame); look.py --moments ... zeichnet die Frames der Momente. Skelett: suggest_cues.py (references/recipes.md); ein Entwurf ist ein Anfang, keine Antwort. --fine für sanfte farbige Animation (Verläufe, Glühen, pastellfarbene Formen, die eher die Farbe ändern als die Helligkeit): es liest auch Chroma-Änderungen, Momente erhalten src=chroma|luma; bei drei solchen Filmen findet es 33–69 % der Ereignisse, die ein Agent aus den Frames notiert hat (innerhalb von 80 ms), gegenüber 13–25 % nur aus der Helligkeit; 3–4 Mal mehr Kandidaten (15–25 pro 10 s). Dies sind Kandidaten: die Frames entscheiden.
• Unter Musik: beats.py FILM --out work/beats.json --plot work/beats.png; mit usable: true, mix.py --snap-beats (±50 ms). Das Raster wird gegen den Kick geprüft (das tiefe Band < 125 Hz separat): es druckt, wie viele Beats innerhalb von 40 ms auf einem Kick landeten. Ein Raster neben dem Kick (der Tracker saß auf den Hi-Hats, "0.22 s abweichend") wird darauf verschoben; ein Raster, das auf nichts landet, erhält usable: false, und --snap-beats ignoriert es. --plot zeichnet das Band, die Kicks (grüne Markierungen) und das Raster (rote Linien): die Markierungen sitzen auf den Linien, oder vertraue dem Raster nicht. Wenn die Musik dir gehört und an das Bild angepasst werden kann: beats.py FILM --suggest-offset work/moments.json sagt, wie weit die Musik verschoben werden muss, damit Schnitte und Hits auf Beats landen (nur Ratschlag; die Musik wird nicht berührt).

from_cues.py: python scripts/from_cues.py LIST|PROJECT_FOLDER|SCRIPT.cjs|- --video RENDER.mp4 --out work/cues.json (- liest die Liste von stdin; ein BOM von PowerShell wird verstanden). Was es von selbst tut und sagt:

• ist es der richtige Render: die Liste verpasst das Bild (VERDICHT); eine Entwurfszeitliste gegen einen auf die Sprachspur getakteten Render: eine Zeitkarte von den Ankern des Projekts (timing.json mit a)