@karnstack/kino 0.2.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 <p align="center">
   A themeable React video player with a pluggable-provider architecture —
   translucent glass chrome, keyboard-first controls, and a small typed surface.
-  Mux is the first provider.
+  Mux, raw files, and YouTube are built in.
 </p>
 
 <p align="center">
@@ -24,7 +24,7 @@
 
 > **[Try it live → kino.karnstack.com](https://kino.karnstack.com)** — drop in any public Mux playback ID, pick an accent, and play with the real glass UI.
 
-kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. The Mux provider is built on the `@mux/mux-video` custom element.
+kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. Three providers ship today: **Mux** (adaptive HLS via `@mux/mux-video`), **Native** (a plain `<video>` over any raw file URL), and **YouTube** (the IFrame Player API wrapped in the same chrome). Each lives behind its own entry point, so you only pull in the engine you use.
 
 ## Install
 
@@ -106,6 +106,32 @@ Pass sidecar subtitles/captions via `tracks`, and kino renders the cues in its o
 
 `NativePlayer` also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `crossOrigin` (set the last when the media or a caption track is cross-origin). Quality switching hides itself since a raw file carries no rendition ladder.
 
+## Playing a YouTube video
+
+For a YouTube source, use the YouTube provider. It drives the YouTube IFrame Player API under the same glass chrome, with kino owning the controls and keyboard map (the native YouTube UI is hidden).
+
+```tsx
+import { YouTubePlayer } from "@karnstack/kino/youtube"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <YouTubePlayer
+        videoId="dQw4w9WgXcQ"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+`videoId` accepts a bare id or any `watch`, `youtu.be`, `embed`, or `shorts` URL — kino resolves it (the `parseYouTubeId` helper is exported if you want it directly). It also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `metadata`.
+
+Speed, fullscreen, and captions work. The captions menu lists the video's own subtitle tracks; YouTube renders the cues itself inside the embed, so they appear in YouTube's style rather than kino's caption overlay.
+
+kino plays YouTube through the official IFrame Player API and, per YouTube's terms, **doesn't obscure the player**: before playback and while paused, YouTube shows its own thumbnail, play button, title, and logo, and kino's controls sit alongside them. A few things the API simply doesn't expose, so kino hides those controls: **manual quality** (YouTube dropped it — playback is always automatic), **picture-in-picture**, and **scrub-preview thumbnails** (storyboards aren't available to embeds).
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -175,7 +201,7 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: YouTube and Vimeo
+- More providers: Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome

package/dist/{captions-BBk_DvTt.js → captions-CGVAzrJq.js}

@@ -1,38 +1,3 @@
-//#region src/core/fake-provider.ts
-const DEFAULT_CAPS = {
-	canSetQuality: true,
-	hasStoryboard: false,
-	canPiP: true,
-	canFullscreen: true,
-	canSetRate: true,
-	hasTextTracks: false
-};
-function defaultState() {
-	return {
-		paused: true,
-		currentTime: 0,
-		duration: 0,
-		buffered: [],
-		rate: 1,
-		volume: 1,
-		muted: false,
-		readyState: 0,
-		seeking: false,
-		ended: false,
-		error: null,
-		qualities: [],
-		activeQualityId: "auto",
-		videoHeight: 0,
-		textTracks: [],
-		activeTextTrackId: null,
-		activeCueText: "",
-		fullscreen: false,
-		pip: false,
-		storyboard: null,
-		capabilities: { ...DEFAULT_CAPS }
-	};
-}
-//#endregion
 //#region src/util/platform.ts
 function detectIOS(ua, maxTouchPoints = 0) {
 	if (/iPhone|iPad|iPod/.test(ua)) return true;
@@ -72,4 +37,4 @@ function activeCueText(tracks, now) {
 	return "";
 }
 //#endregion
-export { detectIOS as n, defaultState as r, activeCueText as t };
+export { detectIOS as n, activeCueText as t };

package/dist/fake-provider-Do3fX4-T.js

@@ -0,0 +1,36 @@
+//#region src/core/fake-provider.ts
+const DEFAULT_CAPS = {
+	canSetQuality: true,
+	hasStoryboard: false,
+	canPiP: true,
+	canFullscreen: true,
+	canSetRate: true,
+	hasTextTracks: false
+};
+function defaultState() {
+	return {
+		paused: true,
+		currentTime: 0,
+		duration: 0,
+		buffered: [],
+		rate: 1,
+		volume: 1,
+		muted: false,
+		readyState: 0,
+		seeking: false,
+		ended: false,
+		error: null,
+		qualities: [],
+		activeQualityId: "auto",
+		videoHeight: 0,
+		textTracks: [],
+		activeTextTrackId: null,
+		activeCueText: "",
+		fullscreen: false,
+		pip: false,
+		storyboard: null,
+		capabilities: { ...DEFAULT_CAPS }
+	};
+}
+//#endregion
+export { defaultState as t };

package/dist/mux.js

@@ -1,5 +1,6 @@
 import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
-import { n as detectIOS, r as defaultState, t as activeCueText } from "./captions-BBk_DvTt.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { n as detectIOS, t as activeCueText } from "./captions-CGVAzrJq.js";
 import { useEffect, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import "@mux/mux-video";

package/dist/native.js

@@ -1,5 +1,6 @@
 import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
-import { n as detectIOS, r as defaultState, t as activeCueText } from "./captions-BBk_DvTt.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { n as detectIOS, t as activeCueText } from "./captions-CGVAzrJq.js";
 import { useEffect, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/native/provider.ts

package/dist/styles.css

@@ -28,11 +28,21 @@
   box-sizing: border-box;
 }
 .kino mux-video,
-.kino video {
+.kino video,
+/* The YouTube provider mounts an <iframe> here; size it like the video. */
+.kino .kino-video-host iframe {
   position: absolute;
   inset: 0;
   width: 100%;
   height: 100%;
+  border: 0;
+}
+/* Let kino's gesture layer own every pointer interaction. Without this the
+   YouTube iframe surfaces its own hover chrome — title, "More videos", a second
+   progress bar — on top of kino's controls. Killing pointer events on the
+   iframe stops YouTube from ever seeing a hover, so only kino's UI shows. */
+.kino .kino-video-host iframe {
+  pointer-events: none;
 }
 .kino .kino-placeholder {
   position: absolute;

package/dist/youtube.d.ts

@@ -0,0 +1,54 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/youtube/provider.d.ts
+type YouTubeProviderOptions = {
+  videoId: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  defaultRate?: number;
+};
+declare function parseYouTubeId(input: string): string;
+declare function createYouTubeProvider(opts: YouTubeProviderOptions): Provider;
+//#endregion
+//#region src/youtube/youtube-player.d.ts
+type YouTubePlayerProps = YouTubeProviderOptions & {
+  accentColor?: string;
+  theme?: Record<string, string>;
+  className?: string; /** Blur-up still painted behind the video until the first frame loads. */
+  placeholder?: string;
+  children?: ReactNode;
+};
+/**
+ * kino's glass chrome over a YouTube video, backed by the YouTube IFrame Player
+ * API. Pass a video id or any watch / youtu.be / embed / shorts URL.
+ *
+ * Only `videoId` and `metadata.videoTitle` are reactive (they flow through
+ * `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read once
+ * when the provider is created — changing them later is a no-op. Remount (e.g.
+ * via `key`) if you need them to change.
+ *
+ * The IFrame API can't expose quality or picture-in-picture, so those controls
+ * hide themselves automatically. Captions work through the API and are rendered
+ * by YouTube inside the embed.
+ *
+ * Per YouTube's API terms, kino doesn't obscure the player: YouTube shows its
+ * own thumbnail, play button, title, and logo before playback and while paused.
+ * kino's controls sit alongside them.
+ */
+declare function YouTubePlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: YouTubePlayerProps): import("react").JSX.Element;
+//#endregion
+export { YouTubePlayer, type YouTubePlayerProps, type YouTubeProviderOptions, createYouTubeProvider, parseYouTubeId };

package/dist/youtube.js

@@ -0,0 +1,293 @@
+import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/youtube/provider.ts
+const PLAYING = 1;
+const ENDED = 0;
+const BUFFERING = 3;
+const CAPTION_MODULES = ["captions", "cc"];
+const IFRAME_API_SRC = "https://www.youtube.com/iframe_api";
+function parseYouTubeId(input) {
+	const trimmed = input.trim();
+	if (/^[\w-]{11}$/.test(trimmed)) return trimmed;
+	const m = trimmed.match(/(?:youtu\.be\/|\/embed\/|\/shorts\/|[?&]v=)([\w-]{11})/);
+	return m ? m[1] : trimmed;
+}
+let apiPromise = null;
+function loadYouTubeAPI() {
+	const w = window;
+	if (w.YT?.Player) return Promise.resolve(w.YT);
+	if (apiPromise) return apiPromise;
+	apiPromise = new Promise((resolve) => {
+		const prev = w.onYouTubeIframeAPIReady;
+		w.onYouTubeIframeAPIReady = () => {
+			prev?.();
+			if (w.YT) resolve(w.YT);
+		};
+		if (!document.querySelector(`script[src="${IFRAME_API_SRC}"]`)) {
+			const script = document.createElement("script");
+			script.src = IFRAME_API_SRC;
+			script.async = true;
+			document.head.appendChild(script);
+		}
+	});
+	return apiPromise;
+}
+function readyYT() {
+	if (typeof window === "undefined") return null;
+	const yt = window.YT;
+	return yt && typeof yt.Player === "function" ? yt : null;
+}
+function createYouTubeProvider(opts) {
+	const initialId = parseYouTubeId(opts.videoId);
+	let player = null;
+	let destroyed = false;
+	let ready = false;
+	let ticker;
+	let desiredRate = opts.defaultRate ?? 1;
+	let captionModule = CAPTION_MODULES[0];
+	let captionsSig = "";
+	let state = {
+		...defaultState(),
+		rate: desiredRate,
+		muted: opts.muted ?? false,
+		capabilities: {
+			canSetQuality: false,
+			hasStoryboard: false,
+			canPiP: false,
+			canFullscreen: true,
+			canSetRate: true,
+			hasTextTracks: false
+		}
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	const patch = (p) => {
+		state = {
+			...state,
+			...p
+		};
+		emit();
+	};
+	const onFullscreenChange = () => patch({ fullscreen: document.fullscreenElement != null });
+	const syncFromPlayer = () => {
+		if (!player || !ready) return;
+		if (player.getPlaybackRate() !== desiredRate) player.setPlaybackRate(desiredRate);
+		const ps = player.getPlayerState();
+		const duration = player.getDuration() || 0;
+		const loaded = player.getVideoLoadedFraction() || 0;
+		patch({
+			paused: ps !== PLAYING && ps !== BUFFERING,
+			ended: ps === ENDED,
+			currentTime: player.getCurrentTime() || 0,
+			duration,
+			buffered: duration > 0 ? [[0, loaded * duration]] : [],
+			rate: desiredRate,
+			volume: (player.getVolume() || 0) / 100,
+			muted: player.isMuted(),
+			readyState: 4
+		});
+		syncCaptions();
+	};
+	const syncCaptions = () => {
+		if (!player) return;
+		let list = [];
+		for (const mod of CAPTION_MODULES) try {
+			const got = player.getOption(mod, "tracklist");
+			if (Array.isArray(got)) {
+				list = got;
+				captionModule = mod;
+				if (got.length) break;
+			}
+		} catch {}
+		const tracks = list.map((t) => ({
+			id: t.languageCode,
+			kind: "captions",
+			label: t.displayName || t.languageCode,
+			lang: t.languageCode,
+			mode: state.activeTextTrackId === t.languageCode ? "showing" : "disabled"
+		}));
+		const sig = tracks.map((t) => `${t.id}:${t.mode}`).join("|");
+		if (sig === captionsSig) return;
+		captionsSig = sig;
+		patch({
+			textTracks: tracks,
+			capabilities: {
+				...state.capabilities,
+				hasTextTracks: tracks.length > 0
+			}
+		});
+	};
+	const setSessionMetadata = (title) => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		if (typeof MediaMetadata === "undefined") return;
+		try {
+			navigator.mediaSession.metadata = new MediaMetadata({ title });
+		} catch {}
+	};
+	const startTicker = () => {
+		if (ticker == null) ticker = setInterval(syncFromPlayer, 250);
+	};
+	const actions = {
+		play: () => player?.playVideo(),
+		pause: () => player?.pauseVideo(),
+		seek: (t) => player?.seekTo(t, true),
+		setRate: (r) => {
+			desiredRate = r;
+			player?.setPlaybackRate(r);
+			patch({ rate: r });
+		},
+		setVolume: (v) => player?.setVolume(Math.min(100, Math.max(0, v * 100))),
+		setMuted: (m) => {
+			if (m) player?.mute();
+			else player?.unMute();
+			patch({ muted: m });
+		},
+		setQuality: () => {},
+		setTextTrack: (id) => {
+			patch({ activeTextTrackId: id });
+			try {
+				player?.setOption(captionModule, "track", id == null ? {} : { languageCode: id });
+			} catch {}
+			syncCaptions();
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+		},
+		enterPiP: () => {},
+		exitPiP: () => {}
+	};
+	const createPlayer = (yt, host) => {
+		player = new yt.Player(host, {
+			videoId: initialId,
+			playerVars: {
+				controls: 0,
+				playsinline: 1,
+				rel: 0,
+				modestbranding: 1,
+				disablekb: 1,
+				autoplay: opts.autoPlay ? 1 : 0,
+				mute: opts.muted ? 1 : 0,
+				loop: opts.loop ? 1 : 0,
+				...opts.loop ? { playlist: initialId } : {}
+			},
+			events: {
+				onReady: (e) => {
+					player = e.target;
+					ready = true;
+					player.setPlaybackRate(desiredRate);
+					if (opts.muted) player.mute();
+					for (const mod of CAPTION_MODULES) try {
+						player.loadModule(mod);
+					} catch {}
+					setSessionMetadata(opts.metadata?.videoTitle ?? "Video");
+					syncFromPlayer();
+					startTicker();
+				},
+				onStateChange: syncFromPlayer,
+				onError: (e) => patch({ error: {
+					code: e.data ?? 0,
+					message: "YouTube playback error"
+				} })
+			}
+		});
+	};
+	return {
+		mount(container) {
+			const host = document.createElement("div");
+			container.appendChild(host);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			const yt = readyYT();
+			if (yt) createPlayer(yt, host);
+			else loadYouTubeAPI().then((loaded) => {
+				if (destroyed) return;
+				if (host.isConnected) createPlayer(loaded, host);
+			});
+		},
+		swapSource(next) {
+			if (!player || !ready || next.src == null) return;
+			player.loadVideoById(parseYouTubeId(next.src));
+			if (next.metadata?.videoTitle != null) setSessionMetadata(next.metadata.videoTitle);
+			player.setPlaybackRate(desiredRate);
+			patch({
+				currentTime: 0,
+				duration: 0,
+				ended: false,
+				seeking: false,
+				error: null
+			});
+		},
+		getState: () => state,
+		subscribe: (l) => {
+			listeners.add(l);
+			return () => listeners.delete(l);
+		},
+		actions,
+		destroy() {
+			destroyed = true;
+			ready = false;
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			if (ticker != null) clearInterval(ticker);
+			ticker = void 0;
+			try {
+				player?.destroy();
+			} catch {}
+			player = null;
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/youtube/youtube-player.tsx
+/**
+* kino's glass chrome over a YouTube video, backed by the YouTube IFrame Player
+* API. Pass a video id or any watch / youtu.be / embed / shorts URL.
+*
+* Only `videoId` and `metadata.videoTitle` are reactive (they flow through
+* `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read once
+* when the provider is created — changing them later is a no-op. Remount (e.g.
+* via `key`) if you need them to change.
+*
+* The IFrame API can't expose quality or picture-in-picture, so those controls
+* hide themselves automatically. Captions work through the API and are rendered
+* by YouTube inside the embed.
+*
+* Per YouTube's API terms, kino doesn't obscure the player: YouTube shows its
+* own thumbnail, play button, title, and logo before playback and while paused.
+* kino's controls sit alongside them.
+*/
+function YouTubePlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(null);
+	if (providerRef.current === null) providerRef.current = createYouTubeProvider(opts);
+	const provider = providerRef.current;
+	const mountedRef = useRef(false);
+	useEffect(() => {
+		if (!mountedRef.current) {
+			mountedRef.current = true;
+			return;
+		}
+		provider.swapSource?.({
+			src: opts.videoId,
+			metadata: opts.metadata
+		});
+	}, [opts.videoId, opts.metadata?.videoTitle]);
+	return /* @__PURE__ */ jsxs(Player, {
+		provider,
+		accentColor,
+		theme,
+		className,
+		placeholder,
+		children: [
+			/* @__PURE__ */ jsx(IdleOverlay, {}),
+			/* @__PURE__ */ jsx(Captions, {}),
+			/* @__PURE__ */ jsx(ControlBar, {}),
+			children
+		]
+	});
+}
+//#endregion
+export { YouTubePlayer, createYouTubeProvider, parseYouTubeId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karnstack/kino",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Themeable React video player with pluggable providers.",
   "license": "MIT",
   "author": "Karn",
@@ -17,6 +17,7 @@
     "player",
     "react",
     "mux",
+    "youtube",
     "hls",
     "video-player"
   ],
@@ -44,6 +45,10 @@
       "types": "./dist/native.d.ts",
       "import": "./dist/native.js"
     },
+    "./youtube": {
+      "types": "./dist/youtube.d.ts",
+      "import": "./dist/youtube.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "peerDependencies": {