@banou/media-player 0.8.20 → 0.8.21

package/dist/remote/index.d.ts

@@ -83,6 +83,24 @@ export type MediaPlayerHandle = {
      * lifetime or `Promise.race` for the wait alone.
      */
     readonly ready: Promise<void>;
+    /**
+     * Start playing, muting first if that is what the far document requires, and say which happened.
+     *
+     * `play()` runs under the FAR document's autoplay policy, and no message carries a user gesture
+     * across a frame boundary: however deliberately somebody clicked over here, an unmuted element in
+     * a document nobody has touched refuses to start. Muted playback is always permitted, so this
+     * tries honestly first and falls back rather than leaving the player stopped.
+     *
+     * `muted` in the result is what the player ended up as, so an app that gets `true` can offer the
+     * viewer a way to turn sound on. That click is itself the gesture the document was missing, and
+     * clearing `muted` afterwards needs no permission from anyone.
+     *
+     * If muted playback is refused too, the FIRST error is what rejects, since a policy refusal says
+     * more than whatever the retry hit, and the player is left unmuted as it was found.
+     */
+    autoplay: () => Promise<{
+        muted: boolean;
+    }>;
     /** stop mirroring and release the channel; the far player keeps playing */
     destroy: () => void;
 };

package/dist/remote/index.js

@@ -90,29 +90,29 @@ var t = [
 	length: e.length,
 	start: (t) => e[t]?.[0] ?? 0,
 	end: (t) => e[t]?.[1] ?? 0
-}), f = 1e4, p = 8, m = 32, h = (e, t = {}) => {
-	C(t.origin);
+}), f = 1e4, p = 1500, m = () => new DOMException("the far player did not start playing", "NotAllowedError"), h = 8, g = 32, _ = (e, t = {}) => {
+	T(t.origin);
 	let n = typeof window < "u" && window.parent !== window;
-	return !t.transport && !n ? () => {} : v(t).serve(e, t);
-}, g = /* @__PURE__ */ new WeakMap(), _ = /* @__PURE__ */ new Map(), v = (i) => {
-	let a = i.channel ?? "banou-media-player", s = i.transport, l = `${a}|${i.origin ?? "*"}`, d = s ? g.get(s) ?? (g.set(s, /* @__PURE__ */ new Map()), g.get(s)) : _, f = d.get(l);
+	return !t.transport && !n ? () => {} : b(t).serve(e, t);
+}, v = /* @__PURE__ */ new WeakMap(), y = /* @__PURE__ */ new Map(), b = (i) => {
+	let a = i.channel ?? "banou-media-player", s = i.transport, l = `${a}|${i.origin ?? "*"}`, d = s ? v.get(s) ?? (v.set(s, /* @__PURE__ */ new Map()), v.get(s)) : y, f = d.get(l);
 	if (f) return f;
-	let h = /* @__PURE__ */ new Map(), v = /* @__PURE__ */ new Map(), y = (e) => v.get(e) ?? v.set(e, /* @__PURE__ */ new Set()).get(e), b = (e, t) => {
-		v.get(e)?.delete(t);
+	let p = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Map(), _ = (e) => m.get(e) ?? m.set(e, /* @__PURE__ */ new Set()).get(e), b = (e, t) => {
+		m.get(e)?.delete(t);
 		try {
 			t.onmessage = null, t.close();
 		} catch {}
 	}, x = (e, t, n) => {
-		for (let r of n ? [n] : [...y(e)]) try {
+		for (let r of n ? [n] : [..._(e)]) try {
 			r.postMessage(t);
 		} catch {
 			b(e, r);
 		}
 	}, S = (e) => {
-		let t = h.get(e);
+		let t = p.get(e);
 		return t ? c(t) : void 0;
 	}, C = (e, t) => {
-		if (!v.get(e)?.size) return;
+		if (!m.get(e)?.size) return;
 		let n = S(e);
 		n && x(e, {
 			event: t,
@@ -122,9 +122,9 @@ var t = [
 		subscribe: (e, t) => {
 			if (typeof e != "string") throw TypeError("a player id must be a string");
 			if (typeof MessagePort < "u" && !(t instanceof MessagePort)) throw TypeError("subscribe takes a MessagePort");
-			if (!v.has(e) && v.size >= m) throw RangeError("too many players on this channel");
-			let n = y(e);
-			if (n.size >= p) throw RangeError("too many embedders for this player");
+			if (!m.has(e) && m.size >= g) throw RangeError("too many players on this channel");
+			let n = _(e);
+			if (n.size >= h) throw RangeError("too many embedders for this player");
 			n.add(t), t.onmessage = () => b(e, t), t.start?.();
 			let r = S(e);
 			r && x(e, {
@@ -133,24 +133,28 @@ var t = [
 			}, t);
 		},
 		set: (e, t, r) => {
-			let i = h.get(e);
+			let i = p.get(e);
 			if (!(!i || !n.includes(t))) try {
 				i[t] = r;
 			} catch {}
 		},
 		call: async (e, t) => {
-			let n = h.get(e);
-			!n || !r.includes(t) || (t === "play" ? await n.play() : t === "pause" ? n.pause() : n.load?.());
+			let n = p.get(e);
+			if (!(!n || !r.includes(t))) try {
+				t === "play" ? await n.play() : t === "pause" ? n.pause() : n.load?.();
+			} finally {
+				C(e, "timeupdate");
+			}
 		}
 	}, T = new AbortController();
 	T.signal.addEventListener("abort", () => {
 		d.delete(l);
-		for (let [e, t] of v) for (let n of [...t]) b(e, n);
-		v.clear(), h.clear();
+		for (let [e, t] of m) for (let n of [...t]) b(e, n);
+		m.clear(), p.clear();
 	}, { once: !0 }), e(w, {
 		transport: i.transport ?? {
 			emit: window.parent,
-			receive: O(() => window.parent, i.origin)
+			receive: A(() => window.parent, i.origin)
 		},
 		origin: i.origin,
 		key: a,
@@ -158,18 +162,18 @@ var t = [
 	});
 	let E = { serve: (e, n) => {
 		let r = n.id ?? "default", i = t.map((t) => [t, () => {
-			h.get(r) === e && C(r, t);
+			p.get(r) === e && C(r, t);
 		}]);
 		for (let [t, n] of i) e.addEventListener(t, n);
-		let a = h.has(r);
-		h.set(r, e), a && x(r, {
+		let a = p.has(r);
+		p.set(r, e), a && x(r, {
 			event: "emptied",
 			snapshot: { ...u }
 		});
 		for (let t of o(c(e))) C(r, t);
 		let s = () => {
 			for (let [t, n] of i) e.removeEventListener(t, n);
-			h.get(r) === e && (h.delete(r), x(r, {
+			p.get(r) === e && (p.delete(r), x(r, {
 				event: "emptied",
 				snapshot: { ...u }
 			}));
@@ -179,10 +183,10 @@ var t = [
 		return n.signal && (n.signal.aborted ? l() : n.signal.addEventListener("abort", l, { once: !0 })), s;
 	} };
 	return d.set(l, E), E;
-}, y = /* @__PURE__ */ new WeakMap(), b = (t, n) => {
-	let r = n.channel ?? "banou-media-player", i = `${r}|${n.origin ?? "*"}`, a = y.get(t) ?? (y.set(t, /* @__PURE__ */ new Map()), y.get(t)), o = a.get(i);
+}, x = /* @__PURE__ */ new WeakMap(), S = (t, n) => {
+	let r = n.channel ?? "banou-media-player", i = `${r}|${n.origin ?? "*"}`, a = x.get(t) ?? (x.set(t, /* @__PURE__ */ new Map()), x.get(t)), o = a.get(i);
 	if (o) return o;
-	let s = E(t, n.origin), c = /* @__PURE__ */ new Set(), l = new AbortController(), u, d = (e) => {
+	let s = O(t, n.origin), c = /* @__PURE__ */ new Set(), l = new AbortController(), u, d = (e) => {
 		try {
 			e.port?.postMessage("close");
 		} catch {}
@@ -195,7 +199,7 @@ var t = [
 		let { port1: t, port2: n } = new MessageChannel();
 		e.port = t, t.onmessage = ({ data: t }) => {
 			l.signal.aborted || e.update(t);
-		}, await S(() => u.subscribe(e.id, n)).catch((t) => {
+		}, await w(() => u.subscribe(e.id, n)).catch((t) => {
 			throw d(e), t;
 		});
 	}, p = () => {
@@ -232,24 +236,24 @@ var t = [
 		}
 	};
 	return a.set(i, m), m;
-}, x = (e, t = {}) => {
-	C(t.origin);
-	let r = new AbortController(), i = t.signal ? AbortSignal.any([t.signal, r.signal]) : r.signal, a = t.id ?? "default", s = { ...u }, c = new EventTarget(), l = (e) => c.dispatchEvent(new Event(e)), f, p, m = new Promise((e, t) => {
-		f = e, p = t;
+}, C = (e, t = {}) => {
+	T(t.origin);
+	let r = new AbortController(), i = t.signal ? AbortSignal.any([t.signal, r.signal]) : r.signal, a = t.id ?? "default", s = { ...u }, c = new EventTarget(), l = (e) => c.dispatchEvent(new Event(e)), f, h, g = new Promise((e, t) => {
+		f = e, h = t;
 	});
-	m.catch(() => {});
-	let h = () => new DOMException("the remote player was closed", "AbortError"), g = /* @__PURE__ */ new Set(), _ = () => {
-		for (let e of [...g]) e(h());
-		g.clear();
-	}, v = /* @__PURE__ */ new Map(), y = !1, x = b(e, t).attach({
+	g.catch(() => {});
+	let _ = () => new DOMException("the remote player was closed", "AbortError"), v = /* @__PURE__ */ new Set(), y = () => {
+		for (let e of [...v]) e(_());
+		v.clear();
+	}, b = /* @__PURE__ */ new Map(), x = !1, C = S(e, t).attach({
 		id: a,
 		reset: () => {
-			y = !1, _();
+			x = !1, y();
 		},
 		update: ({ event: e, snapshot: t }) => {
-			let n = !y;
-			y = !0, Object.assign(s, t);
-			for (let [e, t] of v) s[e] = t;
+			let n = !x;
+			x = !0, Object.assign(s, t);
+			for (let [e, t] of b) s[e] = t;
 			if (!n) {
 				l(e);
 				return;
@@ -257,11 +261,11 @@ var t = [
 			for (let e of o(s)) l(e);
 			f();
 		}
-	}), S = () => {
-		x(), _(), p(h());
+	}), w = () => {
+		C(), y(), h(_());
 	};
-	i.aborted ? queueMicrotask(S) : i.addEventListener("abort", S, { once: !0 });
-	let w = (e, t) => Object.defineProperty(c, e, {
+	i.aborted ? queueMicrotask(w) : i.addEventListener("abort", w, { once: !0 });
+	let E = (e, t) => Object.defineProperty(c, e, {
 		get: () => t ? t(s[e]) : s[e],
 		enumerable: !0
 	});
@@ -276,40 +280,70 @@ var t = [
 		"error",
 		"videoWidth",
 		"videoHeight"
-	]) w(e);
-	w("buffered", d), w("seekable", d);
-	let T = (e) => m.then(() => i.aborted ? void 0 : e()).catch(() => {}), E = b(e, t);
+	]) E(e);
+	E("buffered", d), E("seekable", d);
+	let D = (e) => g.then(() => i.aborted ? void 0 : e()).catch(() => {}), O = S(e, t);
 	for (let e of n) Object.defineProperty(c, e, {
 		get: () => s[e],
 		set: (t) => {
-			s[e] = t, v.set(e, t), T(async () => {
-				await E.set(a, e, t), v.get(e) === t && v.delete(e);
+			s[e] = t, b.set(e, t), D(async () => {
+				await O.set(a, e, t), b.get(e) === t && b.delete(e);
 			});
 		},
 		enumerable: !0
 	});
-	let D = (e) => m.then(() => {
-		if (i.aborted) throw h();
-		let t = E.call(a, e);
+	let k = (e) => g.then(() => {
+		if (i.aborted) throw _();
+		let t = O.call(a, e);
 		return new Promise((e, n) => {
-			g.add(n), t.then(() => {
-				g.delete(n), e();
+			v.add(n), t.then(() => {
+				v.delete(n), e();
 			}, (e) => {
-				g.delete(n), n(i.aborted ? h() : e);
+				v.delete(n), n(i.aborted ? _() : e);
 			});
 		});
 	});
-	return c.play = () => (s.paused = !1, D("play").catch((e) => {
+	c.play = () => (s.paused = !1, k("play").catch((e) => {
 		throw s.paused = !0, e;
-	})), c.pause = () => {
-		s.paused = !0, D("pause").catch(() => {});
+	}));
+	let A = () => new Promise((e) => {
+		let t = (t) => {
+			clearTimeout(r), c.removeEventListener("playing", n), c.removeEventListener("play", n), e(t);
+		}, n = () => t(!0);
+		c.addEventListener("playing", n), c.addEventListener("play", n);
+		let r = setTimeout(() => t(!s.paused), p);
+	}), j = async () => {
+		let e = !s.paused, t;
+		try {
+			await c.play();
+		} catch (e) {
+			t = e;
+		}
+		return e ? {
+			started: !0,
+			refusal: t
+		} : {
+			started: await A(),
+			refusal: t
+		};
+	};
+	return c.autoplay = async () => {
+		let e = await j();
+		if (e.started) return { muted: c.muted };
+		if (c.muted || i.aborted) throw e.refusal ?? m();
+		c.muted = !0;
+		let t = await j();
+		if (t.started) return { muted: !0 };
+		throw c.muted = !1, e.refusal ?? t.refusal ?? m();
+	}, c.pause = () => {
+		s.paused = !0, k("pause").catch(() => {});
 	}, c.load = () => {
-		D("load").catch(() => {});
+		k("load").catch(() => {});
 	}, Object.defineProperty(c, "ready", {
-		value: m,
+		value: g,
 		enumerable: !1
 	}), c.destroy = () => r.abort(), c;
-}, S = async (e) => {
+}, w = async (e) => {
 	let t;
 	try {
 		return await Promise.race([e(), new Promise((e, n) => {
@@ -318,7 +352,7 @@ var t = [
 	} finally {
 		t && clearTimeout(t);
 	}
-}, C = (e) => {
+}, T = (e) => {
 	if (e === void 0 || e === "*") return;
 	if (e === "null") throw TypeError("an opaque origin (\"null\") cannot be spoken to; leave `origin` unset and the sender check stands alone");
 	let t;
@@ -328,47 +362,47 @@ var t = [
 		throw TypeError(`\`origin\` must be an origin like https://example.com, not ${e}`);
 	}
 	if (t.origin !== e) throw TypeError(`\`origin\` must be an origin like ${t.origin}, not ${e}`);
-}, w = (e) => {
+}, E = (e) => {
 	try {
 		return !!e && typeof e == "object" && e.window === e;
 	} catch {
 		return !1;
 	}
-}, T = (e) => {
-	if (w(e)) return !1;
+}, D = (e) => {
+	if (E(e)) return !1;
 	try {
 		return !!e && typeof e == "object" && "contentWindow" in e;
 	} catch {
 		return !1;
 	}
-}, E = (e, t) => {
-	if (w(e)) {
-		let n = D(t);
+}, O = (e, t) => {
+	if (E(e)) {
+		let n = k(t);
 		return {
 			emit: (t, r) => {
 				e.postMessage(t, n.target(), r ?? []);
 			},
-			receive: O(() => e, t, n)
+			receive: A(() => e, t, n)
 		};
 	}
-	if (T(e)) {
+	if (D(e)) {
 		if (!e.contentWindow) throw TypeError("mediaPlayer: the iframe has no window yet; append it to a document first");
-		let n = () => e.contentWindow, r = D(t);
+		let n = () => e.contentWindow, r = k(t);
 		return {
 			emit: (e, t) => {
 				n()?.postMessage(e, r.target(), t ?? []);
 			},
-			receive: O(n, t, r)
+			receive: A(n, t, r)
 		};
 	}
 	return e;
-}, D = (e) => {
+}, k = (e) => {
 	let t = e && e !== "*" ? e : void 0;
 	return {
 		target: () => t && t !== "null" ? t : "*",
 		admits: (e) => t ? e === t : (e && (t = e), !0)
 	};
-}, O = (e, t, n = D(t)) => (t) => {
+}, A = (e, t, n = k(t)) => (t) => {
 	let r = (r) => {
 		r.source === e() && n.admits(r.origin) && t(r.data, {
 			source: r.source,
@@ -379,4 +413,4 @@ var t = [
 	return window.addEventListener("message", r), () => window.removeEventListener("message", r);
 };
 //#endregion
-export { a as DEFAULT_PLAYER_ID, i as PLAYER_CHANNEL, t as PLAYER_EVENTS, h as exposePlayer, x as mediaPlayer };
+export { a as DEFAULT_PLAYER_ID, i as PLAYER_CHANNEL, t as PLAYER_EVENTS, _ as exposePlayer, C as mediaPlayer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/remote/index.ts

@@ -24,6 +24,17 @@ export { DEFAULT_PLAYER_ID, PLAYER_CHANNEL, PLAYER_EVENTS } from './protocol'
 /** How long a peer has to answer its handshake before the mirror stops waiting on it and moves on. */
 const HANDSHAKE_MS = 10_000
 /** How many embedders one player will report to, per id. A page needs one; the cap is there so a peer cannot grow the set without bound. */
+/**
+ * How long `autoplay` waits for the far player to actually start before calling it refused.
+ *
+ * It is a bound on a refusal that announces nothing, not on buffering: a player that starts answers
+ * with its own `playing` and settles the wait immediately, however long the source took.
+ */
+const PLAY_CONFIRM_MS = 1_500
+
+const notStartedError = () =>
+  new DOMException('the far player did not start playing', 'NotAllowedError')
+
 const MAX_SUBSCRIBERS = 8
 /** How many distinct player ids one channel will hold. The id comes from the peer, so it is bounded too. */
 const MAX_PLAYERS = 32
@@ -184,9 +195,21 @@ const channelFor = (options: ExposePlayerOptions): Channel => {
     call: async (id, name) => {
       const media = medias.get(id)
       if (!media || !CALLABLE.includes(name)) return
-      if (name === 'play') await media.play()
-      else if (name === 'pause') media.pause()
-      else media.load?.()
+      try {
+        if (name === 'play') await media.play()
+        else if (name === 'pause') media.pause()
+        else media.load?.()
+      } finally {
+        // What the call ACTUALLY did, whether it threw or not.
+        //
+        // An embedder writes its mirror optimistically when it calls, exactly as an element does, and
+        // then waits for events to correct it. A play that is refused fires no event at all, so
+        // without this the mirror is left believing it is playing, stops asking, and the far video
+        // sits paused for ever while seeks keep landing on it. Worse, a player whose `play()`
+        // RESOLVES without starting (a wrapper that swallows the refusal) is invisible to a promise
+        // and visible here. Measured against stub's watch party, 2026-09-07.
+        announce(id, 'timeupdate')
+      }
     },
   }
 
@@ -265,6 +288,22 @@ export type MediaPlayerHandle =
      * lifetime or `Promise.race` for the wait alone.
      */
     readonly ready: Promise<void>
+    /**
+     * Start playing, muting first if that is what the far document requires, and say which happened.
+     *
+     * `play()` runs under the FAR document's autoplay policy, and no message carries a user gesture
+     * across a frame boundary: however deliberately somebody clicked over here, an unmuted element in
+     * a document nobody has touched refuses to start. Muted playback is always permitted, so this
+     * tries honestly first and falls back rather than leaving the player stopped.
+     *
+     * `muted` in the result is what the player ended up as, so an app that gets `true` can offer the
+     * viewer a way to turn sound on. That click is itself the gesture the document was missing, and
+     * clearing `muted` afterwards needs no permission from anyone.
+     *
+     * If muted playback is refused too, the FIRST error is what rejects, since a policy refusal says
+     * more than whatever the retry hit, and the player is left unmuted as it was found.
+     */
+    autoplay: () => Promise<{ muted: boolean }>
     /** stop mirroring and release the channel; the far player keeps playing */
     destroy: () => void
   }
@@ -523,6 +562,47 @@ export const mediaPlayer = (
   // like an element's, `play` settles with the far side's own answer, so an autoplay refusal over
   // there rejects over here, and the mirror goes back to paused when it does
   player.play = () => { state.paused = false; return call('play').catch(error => { state.paused = true; throw error }) }
+  // Whether the far player is actually running, shortly after being asked to. Its own `playing`
+  // settles this the moment it arrives; the timeout is for the refusal that announces nothing, and
+  // reads the state the call itself reported on its way out.
+  const startedPlaying = () => new Promise<boolean>(resolve => {
+    // Deliberately NOT short-circuiting on `state.paused` here: `play()` has just written it
+    // optimistically, so it reads as playing whatever the far side does. Only an event from over
+    // there, or the state left behind once the call has answered, can settle this.
+    const finish = (started: boolean) => {
+      clearTimeout(timer)
+      player.removeEventListener('playing', ok)
+      player.removeEventListener('play', ok)
+      resolve(started)
+    }
+    const ok = () => finish(true)
+    player.addEventListener('playing', ok)
+    player.addEventListener('play', ok)
+    const timer = setTimeout(() => finish(!state.paused), PLAY_CONFIRM_MS)
+  })
+
+  const askToPlay = async () => {
+    // read before `play()` writes its optimism over it
+    const alreadyPlaying = !state.paused
+    let refusal: unknown
+    try { await player.play() } catch (error) { refusal = error }
+    if (alreadyPlaying) return { started: true, refusal }
+    // the far side's own word, not the promise's: a wrapper that resolves a refused play is common
+    // enough that trusting the promise is what left followers paused for ever
+    return { started: await startedPlaying(), refusal }
+  }
+
+  player.autoplay = async () => {
+    const first = await askToPlay()
+    if (first.started) return { muted: player.muted }
+    // already muted and still refused, or torn down mid-try: nothing left to trade away
+    if (player.muted || signal.aborted) throw first.refusal ?? notStartedError()
+    player.muted = true
+    const second = await askToPlay()
+    if (second.started) return { muted: true }
+    player.muted = false
+    throw first.refusal ?? second.refusal ?? notStartedError()
+  }
   player.pause = () => { state.paused = true; call('pause').catch(() => {}) }
   player.load = () => { call('load').catch(() => {}) }
   Object.defineProperty(player, 'ready', { value: ready, enumerable: false })