YouTube / YouTube Music: BookmarkSnippet-Connector für Playback-Events #9

New issue

Closed

opened 2026-07-12 00:52:11 +02:00 by frank · 1 comment

frank commented

2026-07-12 00:52:11 +02:00

Owner

Kontext

Streamertool hat einen zentralen Event-Bus (AppEvent mit source, type, payload), über den Connectors wie Twitch, OBS und Streamer.Bot Events bereitstellen. Overlays und Extensions können diese über WS /ws/events bzw. SSE /sse/events abonnieren.

Für YouTube und YouTube Music gibt es aktuell keine Anbindung. Viele Streamer nutzen YT Music als Hintergrundmusik oder spielen YouTube-Videos während des Streams ab — ein Now-Playing-Overlay oder Automatisierungen (z. B. via Streamer.Bot) wären hier sinnvoll.

Da YouTube keine offizielle, streamer-taugliche Playback-API für Browser-Tabs bereitstellt, soll die Überwachung über ein BookmarkSnippet (Bookmarklet / Userscript-Snippet im Browser) erfolgen, das auf youtube.com und music.youtube.com läuft und Playback-Daten an Streamertool meldet.

Ziel

BookmarkSnippet bereitstellen, das Nutzer im Browser (Chrome, Firefox, Edge, …) als Lesezeichen oder via Snippet-Manager installieren
Snippet überwacht den aktiven Tab auf YouTube und YouTube Music
Streamertool empfängt die Daten (z. B. via lokalem HTTP-Endpoint des Overlay-Servers) und publiziert sie auf dem Event-Bus
Connector-Status und Konfiguration in der Admin-UI (analog zu anderen Connectors)

Event-Typen

`type`	Beschreibung
`youtube.play`	Wiedergabe gestartet oder fortgesetzt
`youtube.pause`	Wiedergabe pausiert
`youtube.position`	Aktuelle Position (periodisch oder bei signifikanten Sprüngen)

source: youtube (ggf. mit payload.platform: youtube | youtube-music)

Payload (gemeinsam für alle Event-Typen)

{
  "title": "Song- oder Videotitel",
  "author": "Künstler / Kanal",
  "album": "Albumname (YT Music) oder null/leer (YouTube Video)",
  "position": 42.5,
  "duration": 210.0,
  "coverArt": "https://…",
  "platform": "youtube-music",
  "url": "https://music.youtube.com/watch?v=…"
}

position und duration in Sekunden (float)
coverArt: URL zum Thumbnail / Albumcover
album: nur bei YouTube Music befüllt, bei reinem YouTube optional leer

BookmarkSnippet (Lieferumfang)

Minifiziertes JS-Snippet + Anleitung zur Installation (Lesezeichen / Tampermonkey)
Konfigurierbare Streamertool-URL (Default: lokaler Server, z. B. http://127.0.0.1:19850)
Erkennung von Tab-Wechsel, Song-/Video-Wechsel, Play/Pause, Seek
Throttling für youtube.position (z. B. alle 1–2 s während Playback, kein Spam im Pause-Zustand)

Backend / Connector

HTTP-Endpoint zum Empfang der Snippet-Daten (z. B. POST /api/youtube/snippet)
Validierung, Normalisierung und Event-Bus-Publish
Connector youtube in Admin-UI: Status (letztes Update, verbundenes Tab), Endpoint-URL zum Kopieren, Snippet-Installationshinweis

Akzeptanz

BookmarkSnippet funktioniert auf music.youtube.com und www.youtube.com
Events youtube.play, youtube.pause, youtube.position erscheinen in WS/SSE mit vollständigem Payload (title, author, album, position, duration, coverArt)
Song-/Video-Wechsel löst youtube.play mit aktualisierten Metadaten aus
Admin-UI zeigt Connector-Status und Installationsanleitung
Dokumentation in README (Setup-Schritte für Streamer)

Offene Punkte / Hinweise

Kein offizielles YouTube-API-OAuth nötig; Snippet liest DOM/Media-API des geöffneten Tabs
DOM-Struktur von YouTube kann sich ändern — Snippet-Versionierung und Wartung einplanen
CORS: Endpoint muss Snippet-Requests vom Browser aus erlauben (localhost)
Optional später: youtube.track_changed als separates Event (kann initial in youtube.play mit neuem title abgebildet werden)

## Kontext Streamertool hat einen zentralen Event-Bus (`AppEvent` mit `source`, `type`, `payload`), über den Connectors wie Twitch, OBS und Streamer.Bot Events bereitstellen. Overlays und Extensions können diese über `WS /ws/events` bzw. `SSE /sse/events` abonnieren. Für **YouTube** und **YouTube Music** gibt es aktuell keine Anbindung. Viele Streamer nutzen YT Music als Hintergrundmusik oder spielen YouTube-Videos während des Streams ab — ein Now-Playing-Overlay oder Automatisierungen (z. B. via Streamer.Bot) wären hier sinnvoll. Da YouTube keine offizielle, streamer-taugliche Playback-API für Browser-Tabs bereitstellt, soll die Überwachung über ein **BookmarkSnippet** (Bookmarklet / Userscript-Snippet im Browser) erfolgen, das auf `youtube.com` und `music.youtube.com` läuft und Playback-Daten an Streamertool meldet. ## Ziel - BookmarkSnippet bereitstellen, das Nutzer im Browser (Chrome, Firefox, Edge, …) als Lesezeichen oder via Snippet-Manager installieren - Snippet überwacht den aktiven Tab auf **YouTube** und **YouTube Music** - Streamertool empfängt die Daten (z. B. via lokalem HTTP-Endpoint des Overlay-Servers) und publiziert sie auf dem Event-Bus - Connector-Status und Konfiguration in der Admin-UI (analog zu anderen Connectors) ### Event-Typen | `type` | Beschreibung | |--------|--------------| | `youtube.play` | Wiedergabe gestartet oder fortgesetzt | | `youtube.pause` | Wiedergabe pausiert | | `youtube.position` | Aktuelle Position (periodisch oder bei signifikanten Sprüngen) | `source`: `youtube` (ggf. mit `payload.platform`: `youtube` | `youtube-music`) ### Payload (gemeinsam für alle Event-Typen) ```json { "title": "Song- oder Videotitel", "author": "Künstler / Kanal", "album": "Albumname (YT Music) oder null/leer (YouTube Video)", "position": 42.5, "duration": 210.0, "coverArt": "https://…", "platform": "youtube-music", "url": "https://music.youtube.com/watch?v=…" } ``` - `position` und `duration` in **Sekunden** (float) - `coverArt`: URL zum Thumbnail / Albumcover - `album`: nur bei YouTube Music befüllt, bei reinem YouTube optional leer ### BookmarkSnippet (Lieferumfang) - [ ] Minifiziertes JS-Snippet + Anleitung zur Installation (Lesezeichen / Tampermonkey) - [ ] Konfigurierbare Streamertool-URL (Default: lokaler Server, z. B. `http://127.0.0.1:19850`) - [ ] Erkennung von Tab-Wechsel, Song-/Video-Wechsel, Play/Pause, Seek - [ ] Throttling für `youtube.position` (z. B. alle 1–2 s während Playback, kein Spam im Pause-Zustand) ### Backend / Connector - [ ] HTTP-Endpoint zum Empfang der Snippet-Daten (z. B. `POST /api/youtube/snippet`) - [ ] Validierung, Normalisierung und Event-Bus-Publish - [ ] Connector `youtube` in Admin-UI: Status (letztes Update, verbundenes Tab), Endpoint-URL zum Kopieren, Snippet-Installationshinweis ## Akzeptanz - [ ] BookmarkSnippet funktioniert auf `music.youtube.com` und `www.youtube.com` - [ ] Events `youtube.play`, `youtube.pause`, `youtube.position` erscheinen in WS/SSE mit vollständigem Payload (`title`, `author`, `album`, `position`, `duration`, `coverArt`) - [ ] Song-/Video-Wechsel löst `youtube.play` mit aktualisierten Metadaten aus - [ ] Admin-UI zeigt Connector-Status und Installationsanleitung - [ ] Dokumentation in README (Setup-Schritte für Streamer) ## Offene Punkte / Hinweise - Kein offizielles YouTube-API-OAuth nötig; Snippet liest DOM/Media-API des geöffneten Tabs - DOM-Struktur von YouTube kann sich ändern — Snippet-Versionierung und Wartung einplanen - CORS: Endpoint muss Snippet-Requests vom Browser aus erlauben (localhost) - Optional später: `youtube.track_changed` als separates Event (kann initial in `youtube.play` mit neuem `title` abgebildet werden)

frank referenced this issue from a commit

2026-07-12 01:53:30 +02:00

feat: add YouTube playback connector (#9)

frank commented

2026-07-12 01:53:43 +02:00

Author

Owner

Implementiert in ba257de und auf main gepusht.

Enthalten:

Bookmarklet und Tampermonkey-Userscript für YouTube/YouTube Music
POST /api/youtube/snippet mit Validierung, Normalisierung, CORS und Event-Bus-Publish
Events youtube.play, youtube.pause und youtube.position
Connector-Status, letzter Tab/Track und Installationshinweise in der Admin-UI
Setup-Dokumentation in README und docs/youtube.md

Verifiziert mit make test (TypeScript + 47 Rust-Tests), npm run build sowie JS-Syntaxchecks.

Implementiert in ba257de und auf main gepusht. Enthalten: - Bookmarklet und Tampermonkey-Userscript für YouTube/YouTube Music - POST /api/youtube/snippet mit Validierung, Normalisierung, CORS und Event-Bus-Publish - Events youtube.play, youtube.pause und youtube.position - Connector-Status, letzter Tab/Track und Installationshinweise in der Admin-UI - Setup-Dokumentation in README und docs/youtube.md Verifiziert mit make test (TypeScript + 47 Rust-Tests), npm run build sowie JS-Syntaxchecks.

frank closed this issue

2026-07-12 01:53:43 +02:00

frank referenced this issue

2026-07-15 18:55:31 +02:00

Song-Request-System: Viewer wünschen Musik via YouTube/Spotify #37

frank referenced this issue

2026-07-15 19:21:52 +02:00

Stream Music Player: Lizenzfreie Hintergrundmusik mit Auto-Duck und VOD-Track #51