ytplayer/README.md

YT Player

A lightweight, ad-free YouTube player with on-device playlists. No login, no tracking, no ads — it extracts direct video/audio streams with yt-dlp and plays them in a native window.

Built on zero-native (Zig + the system WebView) instead of Electron, so the binary is tiny — no bundled Chromium or Node runtime.

Features

• 🔍 Search YouTube without an account
• 🚫 No ads — plays the raw stream, never the YouTube player
• 📺 High quality via a dual-stream engine: a muted video track synced with a separate audio track (1080p+) with no ffmpeg muxing required; progressive formats are used as a fallback
• 🎵 Audio-only mode — great for music, saves bandwidth
• 📂 On-device playlists — create, rename, delete, add/remove videos. Stored locally as JSON; nothing leaves your machine
• 🕘 Watch history
• ⏯ Full controls: seek, volume, playback speed, quality switching, fullscreen, next/prev, and keyboard shortcuts (space, ←/→, f, m)

Architecture

frontend/            Static web UI (no framework, no build step)
  index.html
  styles.css
  app.js             Player engine + UI; calls window.zero.invoke(...)
src/
  main.zig           App definition + bridge handler registration
  bridge.zig         Native handlers: spawn yt-dlp, slim its JSON, local store
scripts/
  setup-ytdlp.js     Downloads the standalone yt-dlp binary into ./bin
bin/                 yt-dlp lands here (gitignored)
app.zon              App manifest (window, engine, permissions, frontend dir)

The web UI talks to the Zig side over the zero-native bridge:

window.zero.invoke(...)	Native handler	Returns
yt.search { query }	ytSearch	{ ok, results:[…] }
yt.streams { videoId }	ytStreams	{ ok, data:{ meta, audioUrl, qualities[] } }
store.load {}	storeLoad	playlists / history / settings
store.save { data }	storeSave	{ ok }

Because the bridge is size-limited, the Zig handlers parse yt-dlp's large JSON and return only the compact fields the UI needs.

Prerequisites

• Zig (0.14.x recommended) — https://ziglang.org/download/
• zero-native CLI: npm install -g zero-native
• Node.js (only to run the yt-dlp downloader script)
• No system yt-dlp needed — the setup script bundles it. (On Linux/macOS the bundled build is self-contained; Python is not required.)

Setup & run

# 1. Download the yt-dlp binary into ./bin
npm run setup            # or: node scripts/setup-ytdlp.js

# 2. Generate the zero-native build files for your installed version
#    (build.zig, build.zig.zon, src/runner.zig). Run this in a scratch dir and
#    copy the generated build.zig / build.zig.zon next to this project, OR run
#    init here and keep your files:
zero-native init ytplayer --frontend none

# 3. Merge: keep THIS repo's frontend/, src/main.zig, src/bridge.zig and app.zon.
#    (src/main.zig shows exactly how the handlers are registered — fold that into
#    the generated App if the scaffold differs.)

# 4. Build & launch the native window
zig build run

To refresh yt-dlp later (YouTube changes often): npm run update-ytdlp.

Notes & caveats

• zero-native is pre-1.0. The bridge handler signature used here follows its documented contract (fn(context, invocation, output) anyerror![]const u8). If your installed version exposes the Invocation type or BridgeDispatcher fields slightly differently, only the wiring in src/main.zig and the payloadField helper need adjusting — the handler logic is self-contained.
• Stream URLs from yt-dlp are IP-locked and expire after a few hours; the app re-fetches them each time you play a video, so this is transparent.
• This is for personal use. Respect YouTube's Terms of Service and the rights of content creators.

License

MIT