Media in Action verwenden

Assets aus der Mediathek werden aktuell an zwei fest verdrahteten Stellen wiederverwendet: der Automation-Action „Mediathek: Sound abspielen" und dem Bild-Widget im Pro Editor (Overlay Builder). Für Audio/Video im Pro Editor sowie für StoryQuest und Alerts gibt es (Stand jetzt) keinen eingebauten Asset-Picker — dort kopierst du die Asset-URL aus der Mediathek und fügst sie manuell in ein URL-Feld ein. Dieses Kapitel zeigt beide Wege plus die API-Variante.

Automation-Action „Mediathek: Sound abspielen"

In /dashboard/automations öffnest du eine Automation, klickst Action hinzufügen und wählst 🔊 Mediathek: Sound abspielen (interner Typ play_media_sound). Verwechsle das nicht mit Soundboard: Sound abspielen (spielt einen Soundboard-Eintrag) oder Lokalen Sound abspielen (Connect) (spielt eine Datei lokal auf deinem PC über Connect) — „Mediathek: Sound abspielen" spielt einen direkt in chatlix_media (Kind sound) hochgeladenen Sound, ohne Umweg über Soundboard oder OBS.

Das Config-Panel hat genau zwei Felder:

Mediathek-Sound: Dropdown/Picker mit deinen Sound-Assets. Hast du noch keine hochgeladen, zeigt das Panel einen Hinweis „🔇 Noch keine Sounds in der Mediathek" mit direktem Link → Zur Mediathek.
Lautstärke: 0–100, Standard 80.

Es gibt in diesem Action-Typ kein separates Feld für Ziel-Overlay oder Cooldown — falls du das aus älteren Notizen kennst, das war nie so oder ist inzwischen anders. Validierung serverseitig (ActionExecutor::validateConfig):

Ohne gewählten Sound (media_id fehlt/0/negativ) → Fehler media_id_required.
volume muss numerisch und zwischen 0 und 100 liegen, sonst volume_not_numeric bzw. volume_out_of_range.

Beim Feuern der Automation (z.B. Reward eingelöst, Follow-Event) wird der Sound serverseitig über die Media-Engine an deine aktiven Overlays geroutet.

Sound direkt aus der Mediathek testen

Du musst für einen Testlauf keine Automation bauen: In der Mediathek selbst gibt es pro Sound-Asset einen Test-Button (Sound/Overlay Test Center). Der schickt den Sound als Test-Event an deine eigenen, aktuell verbundenen Overlays. Die Antwort liefert unter anderem overlays_total/overlays_live, damit du siehst, ob überhaupt ein Overlay-Fenster gerade offen ist — läuft kein Overlay, kannst du den Sound zwar „abschicken", hörst ihn aber logischerweise nirgends. Praktisch, um vor dem Stream schnell zu prüfen, ob ein neu hochgeladener Sound überhaupt sauber abspielt, ohne extra eine Automation anzulegen. Der Test ist rate-limitiert (gegen versehentlichen Button-Spam), das merkst du nur, wenn du sehr schnell hintereinander viele Tests auslöst.

Pro Editor (Overlay Builder) — Bild-Widget

Im Overlay Builder (/dashboard/overlays/<id>) hat ein Image-Element im Eigenschaften-Panel einen Button 🖼 Aus Media-Library wählen. Klick öffnet ein Sheet mit deinen Bild-Assets (Kind image, inkl. GIFs); Auswahl setzt die Bildquelle direkt, ohne dass du eine URL von Hand eintippen musst.

Für Audio- und Video-Elemente im Pro Editor gibt es aktuell keinen Media-Library-Picker-Button — die Felder sind reine URL-Eingaben (Platzhaltertext z.B. https://…/alarm.mp3 (aus Mediathek)). Der Workflow dafür:

Gehe in die Mediathek (/dashboard/media), such dein Sound-/Video-Asset.
Klick den „URL kopieren"-Button am Asset (kopiert die signierte Proxy-URL in die Zwischenablage).
Wechsle zurück in den Pro Editor, füge die URL in das Audio-/Video-URL-Feld des Elements ein.

Weil Assets standardmäßig privat/signiert ausgeliefert werden, funktioniert eine so kopierte URL nur, solange sie gültig bleibt — falls ein eingefügter Sound/Video im Overlay plötzlich nicht mehr lädt, kopier die URL frisch neu aus der Mediathek und ersetze sie im Widget.

StoryQuest und Alerts

Für StoryQuest-Nodes und die Alert-Konfiguration (/dashboard/alerts) gibt es aktuell keinen direkten Media-Library-Asset-Picker in der Oberfläche. Wenn du dort eigene Bilder/Sounds einsetzen willst, prüf im jeweiligen Editor, ob ein freies URL-Feld existiert, und nutze denselben „URL kopieren"-Workflow wie oben. Verlass dich nicht auf ältere Beschreibungen, die einen fertigen Asset-Picker für diese Bereiche behaupten — das ist aktuell nicht der Fall.

KI-generierte Assets landen automatisch in der Mediathek

Erzeugst du Sounds im Audio Studio (TTS/SFX) oder Sprites im Sprite Studio, tauchen die Ergebnisse automatisch in der Mediathek auf — mit eigenen Kind-Werten (tts, sfx, tts-preview, sfx-preview) und als „Chatlix-generiert" markiert. Über den Quelle-Filter (Chatlix-generiert / Extern) trennst du das schnell von eigenen Uploads. Das gilt aktuell nur für TTS-/SFX-Dateien aus dem Audio Studio — KI-Bilder lassen sich derzeit nicht zuverlässig über den Origin-Filter erkennen.

API-Zugriff

Für eigene Integrationen (z.B. ein externes Tool, das einen Sound triggern soll):

GET /v1/media — Liste deiner Assets (Session-Auth).
GET /v1/media-engine/<id> — Metadaten zu einem Asset.
POST /v1/media-engine/<id>/play — spielt das Asset in deinen aktiven Overlays ab.
GET /v1/media-engine/usage — aktuelles Speicher-/Datei-Kontingent (used_bytes/max_bytes, used_files/max_files).
GET /v1/media-engine/preload-manifest — Manifest für Overlays, um Assets vorzuladen.
GET /v1/media/proxy/<token> — liefert die eigentlichen Bytes (Range-Requests unterstützt, für Audio/Video-Streaming im Browser/OBS).

Es gibt keinen Endpunkt POST /v1/media-engine/probe — Metadaten-Extraktion läuft automatisch im Hintergrund nach dem Upload (Job-Queue), nicht als manuell triggerbarer API-Call. Zum erneuten Anstoßen bei einer fehlgeschlagenen Probe nutzt du POST /v1/media-engine/<id>/reprocess.

Praxis-Tipps

Loudness-Konsistenz: Normalisier deine Sound-Assets vor dem Upload (Richtwert -16 LUFS für Effekte, -14 LUFS für Musik), sonst schwankt die gefühlte Lautstärke zwischen Assets stark — die einzige Lautstärke-Regelung, die du in Chatlix selbst hast, ist der 0–100-Volume-Regler der Automation-Action.
Bildgrößen: Lad für kleine Overlay-Elemente keine 4K-Bilder hoch — kostet unnötig Speicher-Kontingent, ohne sichtbaren Qualitätsgewinn im kleinen Widget.
Label statt kryptischer Dateiname: Alert Follow Standard findest du in der Automation-Auswahl schneller wieder als Recording_2026_05_03_141.mp3.
URL frisch halten: Wenn du Assets per kopierter URL in Overlay Builder/StoryQuest/Alerts einbindest und das Bild/der Sound irgendwann nicht mehr lädt, kopier die URL neu aus der Mediathek statt lange nach dem Fehler zu suchen — signierte URLs sind der wahrscheinlichste Kandidat.