@karnstack/kino 0.1.3 → 0.2.0

package/README.md

@@ -67,6 +67,45 @@ Before the poster and first frame load, the video box is empty. Pass a small `pl
 
 The poster itself stays the signed Mux thumbnail (kino derives it from `playbackId` + the `thumbnail` token), so `placeholder` is purely the instant low-res layer underneath.
 
+## Playing a raw URL
+
+For a plain media URL (mp4, webm, ogg, …) — no Mux account or HLS engine — use the native provider. It puts the same glass chrome over a native `<video>` element, so this entry pulls in none of the Mux engine.
+
+```tsx
+import { NativePlayer } from "@karnstack/kino/native"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <NativePlayer
+        src="https://example.com/clip.mp4"
+        poster="https://example.com/clip.jpg"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+Pass sidecar subtitles/captions via `tracks`, and kino renders the cues in its own styled overlay:
+
+```tsx
+<NativePlayer
+  src="https://example.com/clip.mp4"
+  tracks={[
+    {
+      src: "https://example.com/en.vtt",
+      srclang: "en",
+      label: "English",
+      default: true,
+    },
+  ]}
+/>
+```
+
+`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.
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -136,7 +175,7 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: YouTube, file, and Vimeo
+- More providers: YouTube and Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome

package/dist/captions-BBk_DvTt.js

@@ -0,0 +1,75 @@
+//#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;
+	return /Macintosh/.test(ua) && maxTouchPoints > 1;
+}
+//#endregion
+//#region src/util/captions.ts
+function joinCues(cues) {
+	if (!cues || cues.length === 0) return "";
+	const parts = [];
+	for (let i = 0; i < cues.length; i++) {
+		const c = cues[i];
+		if (c && typeof c.text === "string") parts.push(c.text);
+	}
+	return parts.join("\n").replace(/<[^>]+>/g, "").replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{2,}/g, "\n").trim();
+}
+function activeCueText(tracks, now) {
+	if (!tracks) return "";
+	for (let i = 0; i < tracks.length; i++) {
+		const t = tracks[i];
+		if (!t) continue;
+		if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+		if (t.mode === "disabled") continue;
+		const active = joinCues(t.activeCues);
+		if (active) return active;
+		const all = t.cues;
+		if (all && all.length) {
+			const hits = [];
+			for (let j = 0; j < all.length; j++) {
+				const c = all[j];
+				if (c && c.startTime <= now && now < c.endTime) hits.push(c);
+			}
+			const text = joinCues(hits);
+			if (text) return text;
+		}
+	}
+	return "";
+}
+//#endregion
+export { detectIOS as n, defaultState as r, activeCueText as t };

package/dist/mux.js

@@ -1,88 +1,18 @@
 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 { useEffect, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import "@mux/mux-video";
-//#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/mux/urls.ts
 const IMAGE_HOST = "https://image.mux.com";
 function buildImageUrl(playbackId, kind, token, ext = kind === "storyboard" ? "vtt" : "webp") {
 	const base = `${IMAGE_HOST}/${playbackId}/${kind}.${ext}`;
 	return token ? `${base}?token=${token}` : base;
 }
-function detectIOS(ua) {
-	return /iPhone|iPad|iPod/.test(ua);
-}
-//#endregion
-//#region src/util/captions.ts
-function joinCues(cues) {
-	if (!cues || cues.length === 0) return "";
-	const parts = [];
-	for (let i = 0; i < cues.length; i++) {
-		const c = cues[i];
-		if (c && typeof c.text === "string") parts.push(c.text);
-	}
-	return parts.join("\n").replace(/<[^>]+>/g, "").replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{2,}/g, "\n").trim();
-}
-function activeCueText(tracks, now) {
-	if (!tracks) return "";
-	for (let i = 0; i < tracks.length; i++) {
-		const t = tracks[i];
-		if (!t) continue;
-		if (t.kind !== "subtitles" && t.kind !== "captions") continue;
-		if (t.mode === "disabled") continue;
-		const active = joinCues(t.activeCues);
-		if (active) return active;
-		const all = t.cues;
-		if (all && all.length) {
-			const hits = [];
-			for (let j = 0; j < all.length; j++) {
-				const c = all[j];
-				if (c && c.startTime <= now && now < c.endTime) hits.push(c);
-			}
-			const text = joinCues(hits);
-			if (text) return text;
-		}
-	}
-	return "";
-}
 //#endregion
 //#region src/mux/provider.ts
 function createMuxProvider(opts) {
-	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent);
+	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent, navigator.maxTouchPoints);
 	let el = null;
 	let renditions = null;
 	let renditionsBound = false;

package/dist/native.d.ts

@@ -0,0 +1,56 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/native/provider.d.ts
+type NativeTextTrack = {
+  src: string;
+  srclang: string;
+  label: string;
+  kind?: "subtitles" | "captions";
+  default?: boolean;
+};
+type NativeProviderOptions = {
+  src: string;
+  poster?: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  defaultRate?: number;
+  muted?: boolean;
+  loop?: boolean;
+  crossOrigin?: "anonymous" | "use-credentials";
+  tracks?: NativeTextTrack[];
+};
+declare function createNativeProvider(opts: NativeProviderOptions): Provider;
+//#endregion
+//#region src/native/native-player.d.ts
+type NativePlayerProps = NativeProviderOptions & {
+  accentColor?: string;
+  theme?: Record<string, string>;
+  className?: string; /** Blur-up still painted behind the video until the poster/first frame loads. */
+  placeholder?: string;
+  children?: ReactNode;
+};
+/**
+ * kino's glass chrome over a plain HTML <video> element, playing a raw media
+ * URL (mp4, webm, ogg, …) directly. Use this when you have a file URL rather
+ * than a Mux playback id.
+ *
+ * Only `src`, `poster`, and `metadata.videoTitle` are reactive (they flow
+ * through `swapSource`). `tracks`, `crossOrigin`, `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.
+ */
+declare function NativePlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: NativePlayerProps): import("react").JSX.Element;
+//#endregion
+export { NativePlayer, type NativePlayerProps, type NativeProviderOptions, type NativeTextTrack, createNativeProvider };

package/dist/native.js

@@ -0,0 +1,358 @@
+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 { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/native/provider.ts
+function createNativeProvider(opts) {
+	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent, navigator.maxTouchPoints);
+	const tracks = opts.tracks ?? [];
+	let el = null;
+	let state = {
+		...defaultState(),
+		rate: opts.defaultRate ?? 1,
+		muted: opts.muted ?? false,
+		activeTextTrackId: null,
+		capabilities: {
+			canSetQuality: false,
+			hasStoryboard: false,
+			canPiP: typeof document !== "undefined" && "pictureInPictureEnabled" in document,
+			canFullscreen: true,
+			canSetRate: true,
+			hasTextTracks: tracks.length > 0
+		}
+	};
+	let desiredRate = opts.defaultRate ?? 1;
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	const patch = (p) => {
+		state = {
+			...state,
+			...p
+		};
+		emit();
+	};
+	const reload = () => {
+		try {
+			el?.load();
+		} catch {}
+	};
+	const onFullscreenChange = () => patch({ fullscreen: document.fullscreenElement != null });
+	const onWebkitBeginFullscreen = () => patch({ fullscreen: true });
+	const onWebkitEndFullscreen = () => patch({ fullscreen: false });
+	const onEnterPip = () => patch({ pip: true });
+	const onLeavePip = () => patch({ pip: false });
+	let activeTrack = null;
+	const readCueText = () => ios ? "" : activeCueText(el?.textTracks, el?.currentTime ?? 0);
+	const modeForActiveTrack = () => ios ? "showing" : "hidden";
+	const onCueChange = () => patch({ activeCueText: readCueText() });
+	const bindActiveTrack = (track) => {
+		if (activeTrack) activeTrack.removeEventListener("cuechange", onCueChange);
+		activeTrack = track;
+		if (activeTrack) activeTrack.addEventListener("cuechange", onCueChange);
+		patch({ activeCueText: readCueText() });
+	};
+	const applyTextTrackModes = () => {
+		const tt = el?.textTracks;
+		if (!tt) return;
+		const id = state.activeTextTrackId;
+		let next = null;
+		for (let i = 0; i < tt.length; i++) {
+			const t = tt[i];
+			if (!t) continue;
+			if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+			if (id != null && (t.id || String(i)) === id) {
+				const mode = modeForActiveTrack();
+				if (t.mode !== mode) t.mode = mode;
+				next = t;
+			} else if (t.mode !== "disabled") t.mode = "disabled";
+		}
+		if (next !== activeTrack) bindActiveTrack(next);
+	};
+	const readTextTracks = () => {
+		const tt = el?.textTracks;
+		if (!tt) return [];
+		const out = [];
+		for (let i = 0; i < tt.length; i++) {
+			const t = tt[i];
+			if (!t) continue;
+			if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+			out.push({
+				id: t.id || String(i),
+				kind: t.kind,
+				label: t.label,
+				lang: t.language,
+				mode: t.mode
+			});
+		}
+		return out;
+	};
+	const syncFromEl = () => {
+		if (!el) return;
+		if (el.playbackRate !== desiredRate) el.playbackRate = desiredRate;
+		applyTextTrackModes();
+		const ranges = [];
+		for (let i = 0; i < el.buffered.length; i++) ranges.push([el.buffered.start(i), el.buffered.end(i)]);
+		patch({
+			paused: el.paused,
+			currentTime: el.currentTime,
+			duration: el.duration || 0,
+			buffered: ranges,
+			rate: desiredRate,
+			volume: el.volume,
+			muted: el.muted,
+			readyState: el.readyState,
+			seeking: el.seeking,
+			ended: el.ended,
+			error: el.error ? {
+				code: el.error.code,
+				message: el.error.message
+			} : null,
+			videoHeight: el.videoHeight || 0,
+			textTracks: readTextTracks(),
+			activeCueText: readCueText()
+		});
+		if (typeof navigator !== "undefined" && "mediaSession" in navigator) navigator.mediaSession.playbackState = el.paused ? "paused" : "playing";
+	};
+	const MEDIA_SESSION_ACTIONS = [
+		"play",
+		"pause",
+		"seekbackward",
+		"seekforward",
+		"seekto"
+	];
+	const setupMediaSession = () => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		const ms = navigator.mediaSession;
+		const set = (a, h) => {
+			try {
+				ms.setActionHandler(a, h);
+			} catch {}
+		};
+		set("play", () => actions.play());
+		set("pause", () => actions.pause());
+		set("seekbackward", (d) => actions.seek(Math.max(0, state.currentTime - (d.seekOffset || 10))));
+		set("seekforward", (d) => actions.seek(state.currentTime + (d.seekOffset || 10)));
+		set("seekto", (d) => {
+			if (typeof d.seekTime === "number") actions.seek(d.seekTime);
+		});
+		setSessionMetadata(opts.metadata?.videoTitle ?? "Video");
+	};
+	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 teardownMediaSession = () => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		for (const a of MEDIA_SESSION_ACTIONS) try {
+			navigator.mediaSession.setActionHandler(a, null);
+		} catch {}
+	};
+	const MEDIA_EVENTS = [
+		"play",
+		"pause",
+		"timeupdate",
+		"durationchange",
+		"progress",
+		"volumechange",
+		"ratechange",
+		"seeking",
+		"seeked",
+		"ended",
+		"loadedmetadata",
+		"canplay",
+		"waiting",
+		"error"
+	];
+	const actions = {
+		play: () => {
+			el?.play?.();
+		},
+		pause: () => el?.pause(),
+		seek: (t) => {
+			if (el) el.currentTime = t;
+		},
+		setRate: (r) => {
+			desiredRate = r;
+			if (el) el.playbackRate = r;
+			patch({ rate: r });
+		},
+		setVolume: (v) => {
+			if (el) el.volume = Math.min(1, Math.max(0, v));
+		},
+		setMuted: (m) => {
+			if (el) el.muted = m;
+		},
+		setQuality: () => {},
+		setTextTrack: (id) => {
+			if (!el?.textTracks) return;
+			patch({ activeTextTrackId: id });
+			applyTextTrackModes();
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+			else el?.webkitEnterFullscreen?.();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+			else el?.webkitExitFullscreen?.();
+		},
+		enterPiP: () => {
+			el?.requestPictureInPicture?.();
+		},
+		exitPiP: () => {
+			document.exitPictureInPicture?.();
+		}
+	};
+	const appendTracks = () => {
+		if (!el) return;
+		let activeId = null;
+		tracks.forEach((t, i) => {
+			const node = document.createElement("track");
+			node.kind = t.kind ?? "subtitles";
+			node.src = t.src;
+			node.srclang = t.srclang;
+			node.label = t.label;
+			node.id = `kino-track-${i}`;
+			el.appendChild(node);
+			if (t.default && activeId == null) activeId = node.id;
+		});
+		if (activeId != null) state = {
+			...state,
+			activeTextTrackId: activeId
+		};
+	};
+	return {
+		mount(container) {
+			el = document.createElement("video");
+			el.src = opts.src;
+			el.setAttribute("playsinline", "");
+			el.playsInline = true;
+			el.preload = "metadata";
+			if (opts.poster) el.poster = opts.poster;
+			if (opts.crossOrigin) el.crossOrigin = opts.crossOrigin;
+			if (opts.muted) el.muted = true;
+			if (opts.loop) el.loop = true;
+			if (opts.autoPlay) el.autoplay = true;
+			el.playbackRate = desiredRate;
+			for (const ev of MEDIA_EVENTS) el.addEventListener(ev, syncFromEl);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			el.addEventListener("webkitbeginfullscreen", onWebkitBeginFullscreen);
+			el.addEventListener("webkitendfullscreen", onWebkitEndFullscreen);
+			el.addEventListener("enterpictureinpicture", onEnterPip);
+			el.addEventListener("leavepictureinpicture", onLeavePip);
+			appendTracks();
+			container.appendChild(el);
+			const tt = el.textTracks;
+			if (tt && typeof tt.addEventListener === "function") {
+				tt.addEventListener("addtrack", onTextTracksChanged);
+				tt.addEventListener("removetrack", onTextTracksChanged);
+				tt.addEventListener("change", onTextTracksChanged);
+			}
+			applyTextTrackModes();
+			setupMediaSession();
+		},
+		swapSource(next) {
+			if (!el || next.src == null) return;
+			el.src = next.src;
+			if (next.poster != null) el.poster = next.poster;
+			if (next.metadata?.videoTitle != null) setSessionMetadata(next.metadata.videoTitle);
+			reload();
+			el.playbackRate = 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() {
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			teardownMediaSession();
+			if (activeTrack) activeTrack.removeEventListener("cuechange", onCueChange);
+			activeTrack = null;
+			if (el) {
+				for (const ev of MEDIA_EVENTS) el.removeEventListener(ev, syncFromEl);
+				el.removeEventListener("webkitbeginfullscreen", onWebkitBeginFullscreen);
+				el.removeEventListener("webkitendfullscreen", onWebkitEndFullscreen);
+				el.removeEventListener("enterpictureinpicture", onEnterPip);
+				el.removeEventListener("leavepictureinpicture", onLeavePip);
+				const tt = el.textTracks;
+				if (tt && typeof tt.removeEventListener === "function") {
+					tt.removeEventListener("addtrack", onTextTracksChanged);
+					tt.removeEventListener("removetrack", onTextTracksChanged);
+					tt.removeEventListener("change", onTextTracksChanged);
+				}
+				el.removeAttribute("src");
+				reload();
+				el.remove();
+			}
+			el = null;
+			listeners.clear();
+		}
+	};
+	function onTextTracksChanged() {
+		applyTextTrackModes();
+		patch({
+			textTracks: readTextTracks(),
+			activeCueText: readCueText()
+		});
+	}
+}
+//#endregion
+//#region src/native/native-player.tsx
+/**
+* kino's glass chrome over a plain HTML <video> element, playing a raw media
+* URL (mp4, webm, ogg, …) directly. Use this when you have a file URL rather
+* than a Mux playback id.
+*
+* Only `src`, `poster`, and `metadata.videoTitle` are reactive (they flow
+* through `swapSource`). `tracks`, `crossOrigin`, `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.
+*/
+function NativePlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(null);
+	if (providerRef.current === null) providerRef.current = createNativeProvider(opts);
+	const provider = providerRef.current;
+	const mountedRef = useRef(false);
+	useEffect(() => {
+		if (!mountedRef.current) {
+			mountedRef.current = true;
+			return;
+		}
+		provider.swapSource?.({
+			src: opts.src,
+			poster: opts.poster,
+			metadata: opts.metadata
+		});
+	}, [
+		opts.src,
+		opts.poster,
+		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 { NativePlayer, createNativeProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karnstack/kino",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Themeable React video player with pluggable providers.",
   "license": "MIT",
   "author": "Karn",
@@ -40,6 +40,10 @@
       "types": "./dist/mux.d.ts",
       "import": "./dist/mux.js"
     },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "peerDependencies": {
@@ -64,6 +68,7 @@
     "prettier": "^3.3.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "shiki": "^4.3.0",
     "tailwindcss": "^4.3.1",
     "tsdown": "^0.22.3",
     "typescript": "^5.7.0",