@karnstack/kino 0.3.0 → 0.4.0

package/README.md

@@ -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. 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.
+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. Four providers ship today: **Mux** (adaptive HLS via `@mux/mux-video`), **Native** (a plain `<video>` over any raw file URL), **YouTube** (the IFrame Player API wrapped in the same chrome), and **Vimeo** (the Vimeo Player SDK under the same chrome). Each lives behind its own entry point, so you only pull in the engine you use.
 
 ## Install
 
@@ -132,6 +132,27 @@ Speed, fullscreen, and captions work. The captions menu lists the video's own su
 
 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).
 
+## Playing a Vimeo video
+
+For a Vimeo source, use the Vimeo provider. It drives the Vimeo Player SDK under the same glass chrome, with kino owning the controls and keyboard map.
+
+```tsx
+import { VimeoPlayer } from "@karnstack/kino/vimeo"
+import "@karnstack/kino/styles.css"
+
+export default function Watch() {
+  return <VimeoPlayer videoId="291235566" accentColor="#00adef" />
+}
+```
+
+For an unlisted video, pass the hash (or a share URL that contains it):
+
+```tsx
+<VimeoPlayer videoId="123456789" hash="abcdef0123" />
+```
+
+Chromeless playback (kino owning the controls) requires a paid Vimeo plan.
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -201,7 +222,6 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome

package/dist/vimeo.d.ts

@@ -0,0 +1,57 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/vimeo/provider.d.ts
+type VimeoProviderOptions = {
+  videoId: string;
+  hash?: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  defaultRate?: number;
+};
+declare function parseVimeoSource(input: string): {
+  id: string;
+  hash?: string;
+};
+declare function playerUrl(id: string, hash: string): string;
+declare function createVimeoProvider(opts: VimeoProviderOptions): Provider;
+//#endregion
+//#region src/vimeo/vimeo-player.d.ts
+type VimeoPlayerProps = VimeoProviderOptions & {
+  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 Vimeo video, backed by the Vimeo Player SDK. Pass a
+ * numeric id or any vimeo.com / player.vimeo.com URL; for unlisted videos pass
+ * the `hash` (or a share URL that already contains it).
+ *
+ * Only `videoId`, `hash`, and `metadata.videoTitle` are reactive (they flow
+ * through `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read
+ * once at creation — remount (e.g. via `key`) to change them.
+ *
+ * Chromeless playback (kino owning the controls) requires a **paid** Vimeo plan;
+ * on a free-account video Vimeo renders its own controls under kino's overlay.
+ *
+ * Per Vimeo's embed terms, kino does not obscure the player — no poster-on-pause
+ * cover over the embed; kino's controls sit alongside Vimeo's surface.
+ */
+declare function VimeoPlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: VimeoPlayerProps): import("react").JSX.Element;
+//#endregion
+export { VimeoPlayer, type VimeoPlayerProps, type VimeoProviderOptions, createVimeoProvider, parseVimeoSource, playerUrl };

package/dist/vimeo.js

@@ -0,0 +1,378 @@
+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/vimeo/provider.ts
+function parseVimeoSource(input) {
+	const trimmed = input.trim();
+	const q = trimmed.match(/[?&]h=([\w]+)/);
+	const path = trimmed.match(/(?:^|\/)(\d+)(?:\/([\w]+))?/);
+	if (!path) return { id: trimmed };
+	const id = path[1];
+	const hash = q?.[1] ?? path[2];
+	return hash ? {
+		id,
+		hash
+	} : { id };
+}
+function playerUrl(id, hash) {
+	return `https://player.vimeo.com/video/${id}?h=${hash}`;
+}
+const SDK_SRC = "https://player.vimeo.com/api/player.js";
+let apiPromise = null;
+function loadVimeoAPI() {
+	const w = window;
+	if (w.Vimeo?.Player) return Promise.resolve(w.Vimeo);
+	if (apiPromise) return apiPromise;
+	apiPromise = new Promise((resolve, reject) => {
+		const finish = () => {
+			if (w.Vimeo?.Player) resolve(w.Vimeo);
+			else reject(/* @__PURE__ */ new Error("Vimeo SDK loaded but window.Vimeo is missing"));
+		};
+		const existing = document.querySelector(`script[src="${SDK_SRC}"]`);
+		if (existing) {
+			existing.addEventListener("load", finish);
+			return;
+		}
+		const script = document.createElement("script");
+		script.src = SDK_SRC;
+		script.async = true;
+		script.addEventListener("load", finish);
+		document.head.appendChild(script);
+	});
+	return apiPromise;
+}
+function readyVimeo() {
+	if (typeof window === "undefined") return null;
+	const v = window.Vimeo;
+	return v && typeof v.Player === "function" ? v : null;
+}
+function mapQualities(raw) {
+	return {
+		qualities: raw.filter((q) => parseInt(q.id, 10) > 0).map((q) => ({
+			id: q.id,
+			height: parseInt(q.id, 10),
+			bitrate: 0,
+			selected: q.active
+		})),
+		activeId: raw.find((q) => q.active)?.id ?? "auto"
+	};
+}
+function mapTracks(raw) {
+	const seen = /* @__PURE__ */ new Map();
+	return raw.map((t) => {
+		const base = `${t.language}.${t.kind}`;
+		const n = seen.get(base) ?? 0;
+		seen.set(base, n + 1);
+		return {
+			id: n === 0 ? base : `${base}.${n}`,
+			kind: t.kind,
+			label: t.label || t.language,
+			lang: t.language,
+			mode: t.mode === "showing" ? "showing" : "disabled"
+		};
+	});
+}
+function createVimeoProvider(opts) {
+	const explicit = parseVimeoSource(opts.videoId);
+	const initial = {
+		id: explicit.id,
+		hash: opts.hash ?? explicit.hash
+	};
+	let player = null;
+	let destroyed = false;
+	let desiredRate = opts.defaultRate ?? 1;
+	let state = {
+		...defaultState(),
+		rate: desiredRate,
+		muted: opts.muted ?? false,
+		capabilities: {
+			canSetRate: true,
+			hasStoryboard: false,
+			canPiP: false,
+			canFullscreen: true,
+			canSetQuality: false,
+			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 actions = {
+		play: () => void player?.play().catch(() => {}),
+		pause: () => void player?.pause().catch(() => {}),
+		seek: (t) => {
+			patch({ seeking: true });
+			player?.setCurrentTime(t).catch(() => {});
+		},
+		setRate: (r) => {
+			desiredRate = r;
+			player?.setPlaybackRate(r).then(() => patch({ rate: r })).catch(() => {});
+		},
+		setVolume: (v) => void player?.setVolume(v).catch(() => {}),
+		setMuted: (m) => void player?.setMuted(m).catch(() => {}),
+		setQuality: (id) => void player?.setQuality(id).catch(() => {}),
+		setTextTrack: (id) => {
+			if (id == null) {
+				patch({
+					activeTextTrackId: null,
+					activeCueText: ""
+				});
+				player?.disableTextTrack().catch(() => {});
+				return;
+			}
+			const ref = state.textTracks.find((t) => t.id === id);
+			patch({ activeTextTrackId: id });
+			if (ref) player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {});
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+		},
+		enterPiP: () => {},
+		exitPiP: () => {}
+	};
+	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 onLoaded = async () => {
+		if (!player) return;
+		const p = player;
+		const [duration, rawQualities, rawTracks, muted] = await Promise.all([
+			p.getDuration().catch(() => 0),
+			p.getQualities().catch(() => []),
+			p.getTextTracks().catch(() => []),
+			p.getMuted().catch(() => false)
+		]);
+		if (destroyed) return;
+		p.setPlaybackRate(desiredRate).catch(() => {});
+		const { qualities, activeId } = mapQualities(rawQualities);
+		const tracks = mapTracks(rawTracks);
+		setSessionMetadata(opts.metadata?.videoTitle ?? "Video");
+		patch({
+			duration: duration || state.duration,
+			readyState: 4,
+			muted,
+			qualities,
+			activeQualityId: activeId,
+			textTracks: tracks,
+			capabilities: {
+				...state.capabilities,
+				canSetQuality: qualities.length > 0,
+				hasTextTracks: tracks.length > 0
+			}
+		});
+	};
+	const bindEvents = (p) => {
+		p.on("play", () => patch({
+			paused: false,
+			ended: false
+		}));
+		p.on("pause", () => patch({ paused: true }));
+		p.on("ended", () => patch({
+			paused: true,
+			ended: true
+		}));
+		p.on("bufferstart", () => {
+			if (!state.seeking) patch({ paused: false });
+		});
+		p.on("bufferend", () => {});
+		p.on("timeupdate", (d) => {
+			const e = d;
+			patch({
+				currentTime: e.seconds ?? 0,
+				duration: e.duration ?? state.duration,
+				seeking: false,
+				readyState: 4
+			});
+		});
+		p.on("progress", (d) => {
+			const e = d;
+			const duration = e.duration ?? state.duration;
+			patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] });
+		});
+		p.on("seeking", (d) => {
+			patch({
+				seeking: true,
+				currentTime: d?.seconds ?? state.currentTime
+			});
+		});
+		p.on("seeked", (d) => {
+			patch({
+				seeking: false,
+				ended: false,
+				currentTime: d?.seconds ?? state.currentTime
+			});
+		});
+		p.on("volumechange", (d) => {
+			const e = d;
+			patch({
+				volume: e.volume,
+				muted: e.muted ?? state.muted
+			});
+		});
+		p.on("playbackratechange", (d) => {
+			const e = d;
+			desiredRate = e.playbackRate;
+			patch({ rate: e.playbackRate });
+		});
+		p.on("fullscreenchange", (d) => {
+			patch({ fullscreen: !!d.fullscreen });
+		});
+		p.on("enterpictureinpicture", () => patch({ pip: true }));
+		p.on("leavepictureinpicture", () => patch({ pip: false }));
+		p.on("error", (d) => {
+			const e = d;
+			patch({ error: {
+				code: 0,
+				message: e.name ? `${e.name}: ${e.message ?? ""}`.trim() : e.message ?? "Vimeo playback error"
+			} });
+		});
+		p.on("loaded", () => void onLoaded());
+		p.on("qualitychange", (d) => patch({ activeQualityId: d.quality }));
+		p.on("cuechange", (d) => {
+			patch({ activeCueText: d.cues?.[0]?.text ?? "" });
+		});
+		p.on("texttrackchange", (d) => {
+			const e = d;
+			if (e.language == null) {
+				patch({
+					activeTextTrackId: null,
+					activeCueText: ""
+				});
+				return;
+			}
+			patch({ activeTextTrackId: state.textTracks.find((t) => t.lang === e.language && t.kind === e.kind)?.id ?? state.activeTextTrackId });
+		});
+	};
+	const createPlayer = (v, host) => {
+		const ctorOpts = {
+			controls: false,
+			autoplay: !!opts.autoPlay,
+			muted: !!opts.muted,
+			loop: !!opts.loop,
+			playsinline: true,
+			dnt: true,
+			keyboard: false
+		};
+		if (initial.hash) ctorOpts.url = playerUrl(initial.id, initial.hash);
+		else ctorOpts.id = initial.id;
+		const p = new v.Player(host, ctorOpts);
+		player = p;
+		p.ready().then(() => {
+			if (destroyed) return;
+		});
+		bindEvents(p);
+	};
+	return {
+		mount(container) {
+			const host = document.createElement("div");
+			container.appendChild(host);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			const v = readyVimeo();
+			if (v) createPlayer(v, host);
+			else loadVimeoAPI().then((loaded) => {
+				if (destroyed) return;
+				if (host.isConnected) createPlayer(loaded, host);
+			});
+		},
+		getState: () => state,
+		subscribe: (l) => {
+			listeners.add(l);
+			return () => listeners.delete(l);
+		},
+		swapSource(next) {
+			if (!player || next.src == null) return;
+			const { id, hash } = parseVimeoSource(next.src);
+			player.loadVideo(hash ? { url: playerUrl(id, hash) } : Number(id)).then(() => void player?.setPlaybackRate(desiredRate).catch(() => {})).catch(() => {});
+			if (next.metadata?.videoTitle != null) setSessionMetadata(next.metadata.videoTitle);
+			patch({
+				currentTime: 0,
+				duration: 0,
+				ended: false,
+				seeking: false,
+				error: null
+			});
+		},
+		actions,
+		destroy() {
+			destroyed = true;
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			try {
+				player?.destroy();
+			} catch {}
+			player = null;
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/vimeo/vimeo-player.tsx
+const packSrc = (videoId, hash) => {
+	const parsed = parseVimeoSource(videoId);
+	const h = hash ?? parsed.hash;
+	return h ? playerUrl(parsed.id, h) : parsed.id;
+};
+/**
+* kino's glass chrome over a Vimeo video, backed by the Vimeo Player SDK. Pass a
+* numeric id or any vimeo.com / player.vimeo.com URL; for unlisted videos pass
+* the `hash` (or a share URL that already contains it).
+*
+* Only `videoId`, `hash`, and `metadata.videoTitle` are reactive (they flow
+* through `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read
+* once at creation — remount (e.g. via `key`) to change them.
+*
+* Chromeless playback (kino owning the controls) requires a **paid** Vimeo plan;
+* on a free-account video Vimeo renders its own controls under kino's overlay.
+*
+* Per Vimeo's embed terms, kino does not obscure the player — no poster-on-pause
+* cover over the embed; kino's controls sit alongside Vimeo's surface.
+*/
+function VimeoPlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(null);
+	if (providerRef.current === null) providerRef.current = createVimeoProvider(opts);
+	const provider = providerRef.current;
+	const mountedRef = useRef(false);
+	useEffect(() => {
+		if (!mountedRef.current) {
+			mountedRef.current = true;
+			return;
+		}
+		provider.swapSource?.({
+			src: packSrc(opts.videoId, opts.hash),
+			metadata: opts.metadata
+		});
+	}, [
+		opts.videoId,
+		opts.hash,
+		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 { VimeoPlayer, createVimeoProvider, parseVimeoSource, playerUrl };

package/package.json

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