# Pro Editor

Vollzugriff auf Overlay-HTML/CSS/JS. Fuer Streamer, die genau wissen was sie wollen.

# Pro Editor Grundlagen

# Pro Editor Grundlagen

Der Pro Editor liegt unter `/overlay/editor.php` und ist server-side PHP plus ein Canvas-basierter JS-Editor. Im Gegensatz zum Builder arbeitest du hier pixelgenau auf einer 1920×1080-Fläche.

## Aufbau

Drei-Spalten-Layout:

| Bereich | Inhalt |
|---|---|
| Links | Element-Palette: Text, Box, Image, Camera, Chat-Box, Alert, alle Counter-Typen, Goal, Poll, Hype-Train, Event-List, Leaderboard, Timer |
| Mitte | Canvas 1920×1080 |
| Rechts | Eigenschaften-Panel des aktuell gewählten Elements |

Dazu Top-Bar mit `« Speichern »`, `« Szene »`-Selector, `« Vorschau »`, `« Browser-Source-URL »`, `« Versionen »`.

## Element platzieren

Linkes Panel: Element ziehen, auf Canvas droppen. Position via Drag oder im rechten Panel direkt als `x`, `y`, `width`, `height` in Pixel eintragen.

Getting startet, kommt schnell der Reflex zum Drag - aber pixelgenaue Werte sind oft schneller, vor allem für Wiederholungen ("alle Text-Elemente auf x=120").

## Z-Order

Unten in der Mitte: Layer-Liste. Element selektieren, Pfeile `« Nach oben »` / `« Nach unten »`. Oben in der Liste = vorne im Stack.

Tastenkürzel:
- `]` - eine Schicht nach vorne
- `[` - eine Schicht nach hinten

## Szenen

Oben: Szenen-Selector. `+ Neue Szene` legt eine zusätzliche Szene im selben Overlay an. Szenen teilen sich Browser-Source-URL und Token. Das aktive Szenen-Wechseln steuerst du in OBS - du wählst, welche Szene gerade rendert, über die URL-Parameter:

```
/overlay/view.php?token=<token>&scene=gameplay
```

Oder ohne `scene`-Parameter rendert die als "Default" markierte Szene.

## Versionen

`« Versionen »` zeigt die Historie. Jedes `« Speichern »` legt einen Eintrag an mit Timestamp + User. `« Wiederherstellen »` lädt eine alte Version in den Editor - bestätigen + speichern, dann ist die alte Version wieder aktiv.

Versionen helfen vor allem bei:
- "Was hat der Co-Streamer gestern geändert?"
- "Ich hab gerade alles kaputt gemacht - zurück auf vorhin."

## Token rotieren

`« Sicherheit »` → `« Token erneuern »`. Achtung: alle existierenden Browser-Quellen bekommen sofort HTTP 401. Du musst die neue URL nach OBS kopieren.

Useful, wenn:
- Co-Streamer ist nicht mehr im Team.
- Du vermutest, dass der Token irgendwo geleakt ist (im Stream eingeblendet, in einem Discord-Screenshot).

## Tastenkürzel

| Kürzel | Aktion |
|---|---|
| Strg+Z | Undo |
| Strg+Y / Strg+Shift+Z | Redo |
| Strg+C / Strg+V | Copy / Paste Element |
| Strg+D | Element duplizieren |
| Entf | Element löschen |
| `[` / `]` | Z-Order |
| Pfeiltasten | Element 1 px verschieben |
| Shift+Pfeil | 10 px verschieben |
| Strg+S | Speichern |

Undo / Redo greift auf den letzten 50 Aktionen, browser-lokal (kein Server-Roundtrip). Beim Reload ist die Undo-Historie weg, die Versionen-Liste nicht.

# Vom Builder zum Pro Editor

# Vom Builder zum Pro Editor

Wenn du im Builder gestartet bist und an dessen Grenzen stößt, lohnt der Wechsel. Diese Seite erklärt den Migrations-Workflow ohne Datenverlust.

## Wann lohnt der Wechsel

Typische Symptome, die für den Pro Editor sprechen:

- Du legst für jede Szene ein neues Overlay an und musst in OBS X Browser-Quellen pflegen.
- Du brauchst genau eine Pixel-Position, die der Slider nicht trifft ("Cam soll exakt 280 px von links sein").
- Du willst ein Widget, das es nur im Pro Editor gibt: Poll, Leaderboard, Custom-Counter, Goal mit Custom-Steps.
- Du arbeitest im Team und willst Änderungen rückgängig machen können (Versionen-Historie).

## Import-Workflow

1. Im Dashboard `/dashboard/overlays` öffnen.
2. Bei dem Builder-Overlay auf `« Aktionen »` → `« In Pro Editor importieren »`.
3. Es entsteht ein **neues** Overlay (das Builder-Original bleibt unangetastet, falls du zurück willst).
4. Name des neuen Overlays anpassen (z. B. Suffix `_pro`).

Der Import übernimmt:

- Alle Widgets als Pro-Editor-Elemente.
- Quadranten-Positionen werden in absolute Pixel umgerechnet.
- Schrift, Farben, Animation-Settings.
- Token wird **neu generiert** (anders als bei einem internen Builder-Save).

Der Import übernimmt **nicht**:

- Builder-spezifische Auto-Stacking-Logik (im Pro Editor musst du die Z-Order selbst pflegen, die initiale Reihenfolge ist eine sinnvolle Heuristik).
- Custom-CSS gibt's im Builder nicht, daher leer.

## OBS-URL aktualisieren

Da der Token neu ist, musst du in OBS die Browser-Source-URL austauschen:

1. Pro Editor → `« Browser-Source-URL »` kopieren.
2. OBS, Quellen-Liste, Rechtsklick auf bestehende Browser-Quelle → `Eigenschaften`.
3. URL ersetzen, `OK`.
4. Quelle aktualisiert sich automatisch.

Alternative: das alte Builder-Overlay parallel laufen lassen, in OBS eine zweite Szene mit dem neuen Pro-Overlay anlegen, beide ein paar Streams nebeneinander testen, dann das alte abschalten.

## Rückweg

**Gibt es nicht.** Pro-Editor-Overlays können nicht in den Builder zurückgewandelt werden, weil sie Features nutzen (Szenen, Z-Order, Custom-CSS), die der Builder nicht abbildet.

Deshalb: das Builder-Original **nicht löschen**, bis du im Pro Editor ein paar Streams ohne Probleme hattest. Im Notfall ist es dein Rollback.

## Sauberer Schnitt

Wenn du den Pro Editor mehrere Wochen produktiv genutzt hast und nichts vermisst: Builder-Original archivieren (`/dashboard/overlays` → `« Archiv »`). Archivierte Overlays werden nicht mehr gerendert (URL wird 410), zählen nicht auf dein Overlay-Limit, lassen sich aber innerhalb von 90 Tagen wiederherstellen.

## Templates statt Re-Import

Wenn du nicht migrieren, sondern "das Builder-Layout als Startpunkt für mehrere Pro-Overlays nutzen" willst: aus dem importierten Pro-Overlay ein **Template** machen (`« Speichern als Template »`). Dann kannst du in `/v1/overlay-templates/` darauf zugreifen und neue Overlays als Klone anlegen.

# Verfuegbare APIs im Overlay

# Verfügbare APIs im Overlay

Der Pro Editor spricht mit dem Backend über ein paar REST-Routen. Wenn du "nur" Overlays baust, brauchst du nichts davon - aber wenn du ein Custom-Element scripten oder mit der Chatlix-API automatisieren willst, ist hier der Überblick.

## Overlay-Routen

Alle Routen unter `/v1/overlays/`. Authentifizierung: API-Token im Header `Authorization: Bearer <token>`, anlegbar unter `/dashboard/api-tokens`.

| Route | Methode | Zweck |
|---|---|---|
| `/v1/overlays` | GET | Alle Overlays des Accounts auflisten |
| `/v1/overlays/{id}` | GET | Einzelnes Overlay laden (Definition + Metadaten) |
| `/v1/overlays` | POST | Neues Overlay anlegen |
| `/v1/overlays/{id}` | PUT | Definition updaten |
| `/v1/overlays/{id}` | DELETE | Overlay löschen |
| `/v1/overlays/{id}/duplicate` | POST | Klon mit eigenem Token |
| `/v1/overlays/{id}/versions` | GET | Historie |
| `/v1/overlays/{id}/elements` | GET / POST / PUT | Element-CRUD direkt (für scripted edits) |
| `/v1/overlays/{id}/regen-token` | POST | Browser-Source-Token rotieren |

## Szenen

Separat unter `/v1/overlay-scenes/`:

| Route | Methode | Zweck |
|---|---|---|
| `/v1/overlay-scenes/{overlay_id}` | GET | Szenen eines Overlays |
| `/v1/overlay-scenes/{overlay_id}` | POST | Neue Szene |
| `/v1/overlay-scenes/{id}/duplicate` | POST | Szene innerhalb desselben Overlays klonen |

## Templates

`/v1/overlay-templates/` bietet die geteilte Template-Library:

| Route | Methode | Zweck |
|---|---|---|
| `/v1/overlay-templates` | GET | Alle eigenen + öffentliche Templates |
| `/v1/overlay-templates` | POST | Aus Overlay ein Template machen |
| `/v1/overlay-templates/{id}/apply` | POST | Template auf neues Overlay anwenden |

## Builder

Der Builder spricht mit einer eigenen Route `/v1/overlay-builder/` - die wird ausschließlich von der SvelteKit-Komponente konsumiert und ist nicht Teil der offiziellen API. Wenn du Builder-Layouts programmatisch erzeugen willst, der saubere Weg ist: über `/v1/overlays` ein Layout im Pro-Editor-Format anlegen.

## Camera-Sync

`/v1/cam/` ist die Camera-Sync-API. Sie hält Cam-Frames in mehreren Quellen (z. B. Webcam + Telefon-Cam + Capture-Card) in Sync.

| Route | Methode | Zweck |
|---|---|---|
| `/v1/cam/sources` | GET | Verfügbare Cam-Quellen |
| `/v1/cam/active` | POST | Aktive Quelle setzen |

Das Camera-Element im Pro Editor zeigt automatisch die gerade aktive Quelle. Wechsel = ein POST.

## WebSocket

Laufzeit-Updates (Alerts, Counter, Hype-Train) kommen über WebSocket. Das ist intern und nicht als öffentliche API dokumentiert - die Browser-Source verbindet sich selbst. Wenn du custom JS in einem Pro-Editor-Element schreibst, kannst du das globale `Chatlix` -Objekt im Render-Kontext nutzen:

```js
Chatlix.on('follow', (event) => {
  console.log('Neuer Follower:', event.username);
});
```

Das funktioniert nur im Render-Kontext (`/overlay/view.php`), nicht im Editor-Preview.

# Pro Editor Troubleshooting

# Pro Editor Troubleshooting

Die häufigsten Probleme im Pro Editor und ihre Lösungen.

## Editor lädt nicht / weißer Bildschirm

- Browser-Cache leeren (`Strg+Shift+R`).
- Browser-Konsole öffnen (`F12`), Fehler prüfen. Häufig: Adblocker oder Cookie-Blocker, der die Editor-Assets blockt.
- Login-Token abgelaufen → einmal ausloggen, einloggen.

## Element lässt sich nicht verschieben

- Layer-Liste prüfen: ist das Element "gelockt"? Schloss-Icon in der Layer-Liste. Klick darauf entsperrt.
- Z-Order: ein anderes Element liegt drüber und fängt den Klick. `Alt+Klick` greift durch zur darunter liegenden Schicht.
- Element ist außerhalb der Canvas-Bounds: in der rechten Eigenschaften-Spalte `x`/`y` manuell auf 0/0 setzen, dann wieder positionieren.

## Speichern schlägt fehl

- Top-Bar zeigt Fehler-Toast: meistens Validierung (z. B. negative Größe, leerer Text in Required-Feld).
- Browser-Konsole prüfen.
- Sehr großes Overlay (> 100 Elemente): API-Limit. Lösung: Layout in mehrere Szenen splitten.

## Browser-Source bleibt schwarz

1. URL prüfen: enthält `?token=` und ist vollständig?
2. Token noch gültig? Im Editor `« Browser-Source-URL »` neu kopieren, vergleichen.
3. Im Browser direkt öffnen: dieselbe URL in Chrome/Firefox eingeben. Wenn dort das Overlay erscheint, liegt's an OBS - `Refresh cache of current page`. Wenn auch im Browser schwarz: Editor-Layout prüfen.
4. Debug-Modus aktivieren (`« Debug »` im Editor), Browser-Source neu laden, Konsole im Browser-Source-Inspektor (in OBS: Rechtsklick → `Interact` → `F12`) zeigt Trace-Logs.

## Animation läuft nicht / ruckelt

- Hardware-Beschleunigung in OBS prüfen ([BrowserSource flackert]).
- Mehrere Animationen gleichzeitig (Hype-Train + Alert + Konfetti): das ist ein Renderer-Limit, nicht ein Bug. Reduzieren oder eines davon auf statisch stellen.
- Cam-Sync mit hoher Auflösung (4K-Webcam) kombiniert mit weiteren animierten Elementen kann GPU-Limit treffen. Cam-Quelle in OBS auf 1080p runtersetzen.

## Counter zeigt falsche Zahl

- Cache: im Editor `« Daten neu laden »` (Tooltip auf dem Counter-Element).
- Im Backend prüfen: `/v1/overlays/{id}/elements` → das Counter-Element hat ein `source`-Feld. Das muss zur verbundenen Plattform passen.
- Twitch-Scope: wenn du nach Re-Verbindung der Integration plötzlich 0 siehst, fehlt evtl. ein OAuth-Scope. Unter `/dashboard/integrations` → `« Re-Authorize »`.

## Versions-Rollback macht nichts

- Nach `« Wiederherstellen »` musst du explizit `« Speichern »`. Sonst bleibt der alte Stand nur im Editor sichtbar, ist aber nicht produktiv.
- Wenn beim Speichern nach Rollback ein Fehler kommt: meistens hat sich seit der alten Version das Datenmodell geändert (z. B. ein Widget-Typ entfernt). Logfile im Debug-Tab zeigt Details.

## Pro Editor öffnet sich aus dem Builder mit leerem Canvas

- Import-Job ist asynchron, kann bei großen Overlays ein paar Sekunden dauern. F5 nach ~5 s.
- Wenn auch nach mehrfachem Reload leer: im Builder zurückgehen, exportieren als JSON (`« Aktionen »` → `« Definition exportieren »`), im Pro Editor `« Datei »` → `« JSON importieren »`.

## Wenn nichts hilft

Debug-Logs ziehen:

1. Editor öffnen, `« Debug »` aktivieren.
2. Fehler reproduzieren.
3. `« Debug-Logs herunterladen »`.
4. Datei beim Support anhängen.

Die Logs enthalten Element-IDs, API-Responses und Browser-Konsole. Keine Passwörter, keine Tokens (Token wird vor Export geschwärzt).