The definitive native YouTube player and dashboard for Hermes Desktop: dock it, float it, open /youtube, browse signed-in shelves, play real YouTube watch pages, and control playback without leaving your workspace.
26 seconds of the player doing the thing:
This is not a toy embed and it is not a browser tab with a YouTube page thrown into it.
It is a native Hermes Desktop media player and account-aware YouTube dashboard. Playback stays on YouTube's real watch-page player, while Hermes owns the controls, dock/floating panes, /youtube route, dashboard shelves, status chip, safe persistence, and close/reopen lifecycle.
If you want YouTube inside Hermes without losing your workspace, exposing browser chrome, or rebuilding playback from broken scraped streams, this is the one.
YouTube inside an Electron desktop plugin is easy until you try to make it good.
- Normal embeds fail or throw player configuration errors.
- Scraped direct streams can play audio with black video.
- YouTube's page chrome fights your UI.
- Search results, Shorts, playlists, signed-in feeds, History, captions, and quality controls all come from different YouTube surfaces.
- Hermes panes have their own lifecycle: docked, floating, closed, reopened, moved, remounted.
- A media player must survive all of that without hijacking chat typing, duplicating panes, losing state, or randomly autoplaying on app reopen.
This plugin does the boring hard work: real YouTube playback, native Hermes controls, safe persistence, signed-in account support, /youtube dashboard shelves, fast pin/unpin resume, and single-active-pane behavior.
- Docked + floating player panes with one active player instance — no duplicate dock/floating copies.
- Fast pin/unpin switching beside the timeline, with current video state carried across placement changes.
/youtuberoute + sidebar entry for the native dashboard surface.- Command palette opener and status-bar chip with open/closed and docked/floating state.
- Safe close/reopen lifecycle from docked tab, floating header, and status chip.
- Real YouTube watch-page player in a persistent webview partition — not a broken stream scrape.
- Hermes-owned controls: Show, Prev, Next, -10s, +10s, Play/Pause.
- Dominant scrub timeline with live time/duration.
- Volume popover, quality selector, captions, and loop modes.
- Plugin-only Big Screen mode using the real watch page.
- OS media controls via Media Session.
- No chat-stealing shortcuts: Hermes typing stays safe.
- Locked shelf cluster: Recommended, History, Subscriptions, Watch Later, Shorts, Playlists.
- Recommended from YouTube Home, not a stale search term.
- Background shelf loading so rows fill without driving the main player view.
- Cards open directly in the player across videos, Shorts, and playlists.
- Compact media-control top bar with contained thumbnail, Show-first controls, timeline, and stats.
- Stats panel with channel, duration, views, source, row counts, and scrollable description.
- Highlighted/clickable description links.
- Signed-in History, Subscriptions, Watch Later, and Your Playlists.
- History follows the selected YouTube account/channel through signed-in YouTube browse data.
- Shorts source is isolated so Shorts do not pollute History.
- Playlists are filtered to real playlist IDs so History videos do not leak into Playlist rows.
- Account/login mode is intentionally temporary; normal playback returns to the locked media-player surface.
- Persists safe preferences: size, volume, loop, quality, captions, placement.
- Persists YouTube session through the shared webview partition.
- Pin/unpin and pane remounts resume the current video quickly.
- Does not persist current video as a long-term app-reopen autoplay trap.
- Mini / Small / Medium / Large size modes.
- Pin button left of the timeline, volume right of the timeline.
- Thumbnail uses contained/full-image scaling in the dashboard top bar.
- Docked and floating close controls use Hermes chrome where possible.
- Raw account/feed panes are covered while loading so the plugin stays a media player, not a random browser window.
Real YouTube playback inside a Hermes-native player shell: timeline, transport controls, account entry point, quality, captions, loop, dock/floating placement, and status-aware chrome.
Shorts search and playback stay inside the same controlled media pane. The plugin chains Shorts deliberately and guards against YouTube drifting into unrelated long-form autoplay.
Playlist results open into a playable queue, autoplay the first item, and roll through the list without dumping you into a full YouTube browser page.
- Clone or download this repo.
- Run the installer for your platform from the repo folder.
powershell -ExecutionPolicy Bypass -File .\install-youtube-float-v3.141.ps1Writes to %LOCALAPPDATA%\hermes\desktop-plugins and %USERPROFILE%\.hermes\desktop-plugins, plus profile plugin folders when present.
chmod +x ./install-youtube-float-v3.141.sh
./install-youtube-float-v3.141.shWrites to ~/.hermes/desktop-plugins, $HERMES_HOME/desktop-plugins when set, macOS ~/Library/Application Support/hermes/desktop-plugins, and profile plugin folders when present.
- Fully quit and reopen Hermes Desktop.
- Confirm the pane title shows YouTube v3.141 ★.
- Uses a persistent YouTube webview session so signed-in shelves work.
- Login happens inside YouTube; the plugin does not directly handle YouTube passwords.
- Stores small local preferences and safe UI state only.
- Does not intentionally store/copy cookies, auth tokens, passwords, or raw session data.
- Debug diagnostics are off by default and redact sensitive-looking keys before copying.
- See
SECURITY.mdfor the full security/privacy model. - See
TROUBLESHOOTING.mdfor install, shelf, update, and reporting fixes.
- True taskbar-covering fullscreen needs Hermes Desktop host support; current Big Screen is plugin-owned and keeps the Windows taskbar visible.
- YouTube signed-in feeds can hydrate slowly; some shelves may take a few seconds before rows appear.
- YouTube can change private feed surfaces; History currently works through signed-in browse data, but future YouTube markup/API changes may need maintenance.
Coming soon:
- Host-owned true fullscreen once Hermes Desktop exposes a safe native fullscreen API.
- Fresh dashboard screenshots showing the final
/youtubeshelves and media-control top bar. - Ask about what's playing: Hermes-aware title/channel/timestamp context for questions about the current video.
- Feed resilience tools: clearer diagnostics if YouTube changes signed-in shelf data again.
- Optional shortcut mode behind an explicit toggle, if keyboard controls return without interfering with Hermes chat.
Stable builds are published from versioned tags and GitHub Releases. The in-plugin Check updates action validates the latest stable release and opens the release page when manual install is required. Download youtube-float-desktop-plugin-<version>.zip, run the installer for your platform, then fully quit and reopen Hermes Desktop.
Release hygiene lives in RELEASE_CHECKLIST.md. CI must be green before a stable release is published.
Bug reports use a diagnostics-first GitHub issue template so failures arrive with version, surface, repro steps, and optional redacted Debug output. See TROUBLESHOOTING.md first for common fixes.
plugin.js— the runtime plugin, loaded directly by Hermes Desktop.install-youtube-float.ps1— current installer.docs/versions/andCHANGELOG.md— release history.- Runtime imports stay limited to
@hermes/plugin-sdk,react, andreact/jsx-runtime.
Checks used before release:
node --check plugin.js
node --test tests/*.test.mjs
node scripts/check-release.mjs
python3 scripts/build-release-zip.py --check
python3 scripts/changelog-release-notes.py > /tmp/youtube-float-release-notes.md
python3 scripts/publish-release.py --dry-runA small runtime import harness is also used during development to catch module-scope plugin load failures that syntax checks miss.
Apache License 2.0. See LICENSE.