feat: add YouTube playback as an optional provider plugin #136

Goal

Add YouTube as an optional provider plugin while keeping the media core provider-neutral and being explicit about what YouTube's APIs can and cannot detect.

Integration reality

The YouTube Data API can fetch metadata for a known video ID, but it does not expose a reliable "what this user is watching right now" endpoint. OAuth/watch-history polling is not a dependable real-time playback source.

Chosen architecture (confirmed by project owner):

• Detect playback locally in an opt-in browser extension/content script on youtube.com and music.youtube.com.
• Read the active player's video ID, title, channel, thumbnail, duration, current position, play/pause and live-stream state.
• Send a minimal validated event to the local nowplaying bridge; use the Data API only as an optional metadata enrichment/fallback for a known ID.
• Keep site selectors and player event handling isolated in the YouTube plugin because YouTube DOM/player changes are expected maintenance.

Documented alternatives (not the implementation target):

• userscript/local companion (easier prototype; weaker distribution/update story)
• desktop media-session capture (less site-specific, but inconsistent metadata/browser support)
• YouTube Data API alone (not suitable for current-playback detection)

Scope

• Browser extension/content script is the chosen capture route. Start with a short spike to prove the player events, local bridge protocol, privacy boundary and selector resilience before full implementation.
• YouTube and YouTube Music support if the same mechanism is reliable.
• Provider adapter mapping into the existing media model.
• Local-only connection by default, origin allowlist and no browsing-history collection.
• No account scraping, cookie extraction, watch-history polling or playback control in the first version.

Done when

• A browser-extension spike proves active-player detection on youtube.com and music.youtube.com, the minimal local event schema, permission set and failure behavior.
• The implementation notes record why userscript, Media Session and Data API-only approaches were not chosen.
• Only active playback events are sent; page visits, searches, recommendations and history are never collected.
• Video ID, title/channel, artwork, position/duration and pause/stop map to cards and Discord Rich Presence.
• Live streams, Shorts, Music, ads, private/deleted videos, tab switches and multiple YouTube tabs have defined behavior.
• The local bridge authenticates the plugin and rejects other origins/invalid payloads.
• Site selectors/event hooks are isolated, fixture-tested and have a documented maintenance owner/fallback when YouTube changes.
• The app works unchanged when the plugin is absent or disconnected.
• Setup/privacy docs explain browser permissions and the local-only data path in plain language.
• Shipping commit is a feat, producing the next minor release under the project versioning rule.

Official references

• Data API overview: https://developers.google.com/youtube/v3/getting-started
• Video metadata endpoint: https://developers.google.com/youtube/v3/docs/videos/list
• OAuth for browser apps: https://developers.google.com/youtube/v3/guides/auth/client-side-web-apps