@lincyaw/addon-lecture 1.0.0-rc.1 → 1.0.0-rc.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/addon-lecture",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.11",
   "description": "Presmium plugin: lecture tracks: recording, playback, scripted lectures with speech, and video export (presmium-lecture)",
   "license": "Apache-2.0",
   "repository": {
@@ -41,9 +41,9 @@
     "playwright-chromium": "^1.40.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "@lincyaw/host": "^1.0.0-rc.1",
-    "@lincyaw/kernel": "^1.0.0-rc.1",
-    "@lincyaw/compiler": "^1.0.0-rc.1"
+    "@lincyaw/compiler": "^1.0.0-rc.11",
+    "@lincyaw/host": "^1.0.0-rc.11",
+    "@lincyaw/kernel": "^1.0.0-rc.11"
   },
   "peerDependenciesMeta": {
     "playwright-chromium": {
@@ -57,11 +57,11 @@
     "@types/react": "18.3.28",
     "react-dom": "18.3.1",
     "@types/react-dom": "18.3.7",
-    "@lincyaw/cli": "1.0.0-rc.1",
-    "@lincyaw/compiler": "1.0.0-rc.1",
-    "@lincyaw/kernel": "1.0.0-rc.1",
-    "@lincyaw/viewer": "1.0.0-rc.1",
-    "@lincyaw/host": "1.0.0-rc.1"
+    "@lincyaw/cli": "1.0.0-rc.11",
+    "@lincyaw/compiler": "1.0.0-rc.11",
+    "@lincyaw/viewer": "1.0.0-rc.11",
+    "@lincyaw/kernel": "1.0.0-rc.11",
+    "@lincyaw/host": "1.0.0-rc.11"
   },
   "presmium": {
     "preview": {

package/src/client/PlayerPanel.css

@@ -118,3 +118,36 @@ html.pm-lecture-exporting .pm-slide-fit__canvas {
     display: none;
   }
 }
+
+/* A lecture the browser would not autoplay waits here, centred on the slide, for the reader's click. */
+.pm-lecture-start {
+  position: fixed;
+  inset: 0;
+  z-index: var(--pm-z-lecture-player);
+  display: grid;
+  place-items: center;
+  pointer-events: none;
+}
+
+.pm-lecture-start__button {
+  display: grid;
+  place-items: center;
+  width: var(--pm-size-start);
+  height: var(--pm-size-start);
+  border: 0;
+  border-radius: var(--pm-radius-pill);
+  background: color-mix(in srgb, var(--pm-color-ink) 78%, transparent);
+  color: var(--pm-color-bg);
+  box-shadow: var(--pm-shadow-float);
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.pm-lecture-start__button:hover {
+  background: var(--pm-color-ink);
+}
+
+.pm-lecture-start__button .pm-ui-icon {
+  width: var(--pm-size-start-icon);
+  height: var(--pm-size-start-icon);
+}

package/src/client/PlayerPanel.tsx

@@ -1,4 +1,4 @@
-import { PmCaption, PmDrawer, PmIconButton, PmMenu, PmTabs, PRODUCTION_PLAYBACK, TIMED_CAPTIONS, useMessages, useServer, useService, useStore } from '@lincyaw/host'
+import { PmCaption, PmDrawer, PmIcon, PmIconButton, PmMenu, PmTabs, PRODUCTION_PLAYBACK, TIMED_CAPTIONS, useMessages, useServer, useService, useStore } from '@lincyaw/host'
 import type { MenuItem } from '@lincyaw/host'
 import { isPreviewEmbedded } from '@lincyaw/kernel'
 import { useEffect, useMemo, useState } from 'react'
@@ -47,7 +47,8 @@ export default function PlayerPanel(_props: { view?: string }) {
   const timedCaptions = useService(TIMED_CAPTIONS)
   const production = useService(PRODUCTION_PLAYBACK)
   const controlled = useStore(production instanceof ProductionPlaybackController ? production.engaged : undefined, false)
-  useEffect(() => player && status === 'ready' ? timedCaptions?.claim() : undefined, [player, status, timedCaptions])
+  // The lecture times the captions from the moment it is asked for: while it loads, the slides show none of their own.
+  useEffect(() => id && !failure && status !== 'missing' ? timedCaptions?.claim() : undefined, [id, failure, status, timedCaptions])
   useEffect(() => {
     if (!player || status !== 'ready' || failure || controlled || exporting) return
     keyboardPlayer.set(player)
@@ -57,6 +58,8 @@ export default function PlayerPanel(_props: { view?: string }) {
     }
     return () => { if (keyboardPlayer.getSnapshot() === player) keyboardPlayer.set(undefined) }
   }, [player, status, failure, controlled])
+  // The browser would not start the sound without the reader: a large Play waits for their click.
+  const blocked = useStore(player?.clock.blocked, false)
   const time = useStore(player?.time, 0),
     clockPlaying = useStore(player?.clock.playing, false),
     rate = useStore(player?.clock.rate, 1)
@@ -172,6 +175,7 @@ export default function PlayerPanel(_props: { view?: string }) {
     else if (option === 'close') play(undefined)
   }
   return <>
+    {blocked && <div className="pm-lecture-start"><button type="button" className="pm-lecture-start__button" aria-label={t.player.play} onClick={() => void player.play()}><PmIcon name="play" /></button></div>}
     {(captions || current?.unsaid) && (current || manual) && caption && <PmCaption overlay label={t.player.captions} lines={[caption]} lang={lang}
       data-stale={current && stale.has(current.id) ? 'true' : undefined} hint={current && stale.has(current.id) ? t.player.stale : undefined} />}
     {panel && <PmDrawer open label={panel === 'transcript' ? t.player.transcript : t.player.chapters} onClose={() => setPanel(undefined)}>

package/src/client/clock.ts

@@ -6,6 +6,8 @@ export interface TrackClock {
   readonly playing: Readonly<Store<boolean>>
   readonly rate: Readonly<Store<number>>
   readonly error: Readonly<Store<Error | undefined>>
+  /** The browser refused to start the sound before the reader acted on this page (autoplay): playback waits for them. */
+  readonly blocked: Readonly<Store<boolean>>
   play(): void
   pause(): void
   seek(t: number): void
@@ -18,6 +20,7 @@ export class SilentClock implements TrackClock {
   readonly playing = createStore(false)
   readonly rate = createStore(1)
   readonly error = createStore<Error | undefined>(undefined)
+  readonly blocked = createStore(false)
   protected at = 0
   protected since = performance.now()
   protected readonly duration: number
@@ -33,6 +36,7 @@ export class SilentClock implements TrackClock {
 
   play(): void {
     if (this.playing.getSnapshot()) return
+    this.blocked.set(false)
     if (this.at >= this.duration) this.at = 0
     this.since = performance.now()
     this.playing.set(true)
@@ -150,6 +154,12 @@ export class MediaClock extends SilentClock {
         if (!this.playing.getSnapshot() || at < m.start || at >= m.start + m.duration) m.el.pause()
       }).catch((error: unknown) => {
         if (error instanceof DOMException && error.name === 'AbortError') return
+        // Autoplay without the reader's gesture: not a failure, playback waits for their click.
+        if (error instanceof DOMException && error.name === 'NotAllowedError') {
+          this.pause()
+          this.blocked.set(true)
+          return
+        }
         this.fail(error instanceof Error ? error : new Error(String(error)))
       })
     }

package/src/client/playback.ts

@@ -18,14 +18,25 @@ async function createClock(track: LectureTrack, source: LectureSource, signal?:
   const length = trackDuration(track)
   const segments = audioSegments(track)
   if (!segments.length) return new SilentClock(length)
+  // Clips cut from one file (a score split per step) share one download.
+  const files = new Map<string, Promise<string>>()
+  const fileOf = (segment: typeof segments[number]) => {
+    const key = segment.sha256 ?? segment.assetId ?? segment.src
+    let url = files.get(key)
+    if (!url) {
+      url = track.binding && source.productionMedia && segment.clipId ? source.productionMedia(track.binding, segment.clipId, signal) : source.media(track.id, segment.src)
+      files.set(key, url)
+    }
+    return url
+  }
   const loaded = await Promise.allSettled(segments.map(async (segment): Promise<ClockMedia> => {
     if (track.binding && source.productionMedia && !segment.clipId) throw new Error('production-clip-unavailable')
-    const url = track.binding && source.productionMedia && segment.clipId ? await source.productionMedia(track.binding, segment.clipId, signal) : await source.media(track.id, segment.src)
+    const url = await fileOf(segment)
     return { url, start: segment.start, duration: segment.duration, sourceStartMs: segment.sourceStartMs, volume: segment.volume, muted: segment.muted }
   }))
   const media = loaded.flatMap(result => result.status === 'fulfilled' ? [result.value] : [])
   const failed = loaded.find(result => result.status === 'rejected')
-  if (failed || signal?.aborted) { for (const { url } of media) if (url.startsWith('blob:')) URL.revokeObjectURL(url); if (failed) throw failed.reason; signal?.throwIfAborted() }
+  if (failed || signal?.aborted) { for (const url of new Set(media.map(item => item.url))) if (url.startsWith('blob:')) URL.revokeObjectURL(url); if (failed) throw failed.reason; signal?.throwIfAborted() }
   return new MediaClock(length, media)
 }
 function installExportHook(player: LecturePlayer, clock: StepClock | undefined): void {

package/src/domain/track.ts

@@ -289,6 +289,9 @@ export function trackDuration(track: LectureTrack): number {
 export interface AudioSegment {
   clipId?: string
   src: string
+  /** The file a clip is cut from, when known: clips of one file share one download. */
+  sha256?: string
+  assetId?: string
   start: number
   duration: number
   sourceStartMs?: number
@@ -298,5 +301,5 @@ export interface AudioSegment {
 
 export function audioSegments(track: LectureTrack): AudioSegment[] {
   const said = track.utterances.filter(u => u.clip).map(u => ({ src: `${CLIPS_DIR}/${u.clip}`, start: u.t, duration: u.d, ...u.clipId ? { clipId: u.clipId } : {} }))
-  return [...said, ...(track.audio ?? []).map(a => ({ src: a.src, start: a.start * 1000, duration: a.duration * 1000, ...a.clipId ? { clipId: a.clipId } : {}, ...a.sourceStartMs !== undefined ? { sourceStartMs: a.sourceStartMs } : {}, ...a.volume !== undefined ? { volume: a.volume } : {}, ...a.muted !== undefined ? { muted: a.muted } : {} }))]
+  return [...said, ...(track.audio ?? []).map(a => ({ src: a.src, start: a.start * 1000, duration: a.duration * 1000, ...a.clipId ? { clipId: a.clipId } : {}, ...a.sha256 ? { sha256: a.sha256 } : {}, ...a.assetId ? { assetId: a.assetId } : {}, ...a.sourceStartMs !== undefined ? { sourceStartMs: a.sourceStartMs } : {}, ...a.volume !== undefined ? { volume: a.volume } : {}, ...a.muted !== undefined ? { muted: a.muted } : {} }))]
 }

package/src/node/routes/production.ts

@@ -1,14 +1,18 @@
+import { createHash } from 'node:crypto'
 import { errorMessage, jsonResponse } from '@lincyaw/kernel'
 import type { ProductionMediaQuery, ProductionPlanQuery, Route } from '@lincyaw/kernel'
 import { productionAsset, productionMedia, productionSnapshot } from '../production.ts'
 import { ProductionAssetRefusal } from '../production-assets.ts'
 import { canonicalSource, VoiceSourceRefusal } from '../voice-source.ts'
-import { serveFile } from './serve-file.ts'
+import { MEDIA_CACHE, notModified, serveFile } from './serve-file.ts'
 import { RouteRefusal } from './served-deck.ts'
 import type { ServedDeck } from './served-deck.ts'
 
 function audioBytes(bytes: Uint8Array<ArrayBuffer>, mediaType: string, request: Request): Response {
-  const size = bytes.byteLength, headers = { 'Content-Type': mediaType, 'Cache-Control': 'no-store', 'Accept-Ranges': 'bytes' }
+  const etag = `"${createHash('sha256').update(bytes).digest('base64url').slice(0, 22)}"`
+  const size = bytes.byteLength, headers = { 'Content-Type': mediaType, 'Cache-Control': MEDIA_CACHE, 'Accept-Ranges': 'bytes', ETag: etag }
+  const unchanged = notModified(request, etag, headers)
+  if (unchanged) return unchanged
   const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '')
   if (!range || !range[1] && !range[2]) return new Response(request.method === 'HEAD' ? null : bytes, { headers: { ...headers, 'Content-Length': String(size) } })
   const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]))

package/src/node/routes/serve-file.ts

@@ -14,16 +14,29 @@ const TYPES: Record<string, string> = {
   '.mp3': 'audio/mpeg',
 }
 
+/**
+ * Media may change while the author works, so the browser keeps it but asks again each time (`no-cache`): an unchanged
+ * file answers 304 by its tag, and a reader who plays the same piece again, or several clips of one file, loads it once.
+ */
+export const MEDIA_CACHE = 'private, no-cache'
+
+export function notModified(request: Request, etag: string, headers: Record<string, string>): Response | undefined {
+  return request.headers.get('if-none-match')?.split(',').some(tag => tag.trim() === etag) ? new Response(null, { status: 304, headers: { ...headers, ETag: etag } }) : undefined
+}
+
 export function serveFile(deckDir: string, file: string | undefined, request: Request): Response {
   const fd = file === undefined ? undefined : openInDeck(deckDir, file)
   if (fd === undefined) return problemResponse(404, 'no such file')
-  const { size } = fstatSync(fd)
-  const headers = { 'Content-Type': TYPES[extname(file!)] ?? 'application/octet-stream', 'Accept-Ranges': 'bytes', 'Cache-Control': 'no-store' }
+  const { size, mtimeMs } = fstatSync(fd)
+  const etag = `"${size.toString(36)}-${Math.round(mtimeMs).toString(36)}"`
+  const headers = { 'Content-Type': TYPES[extname(file!)] ?? 'application/octet-stream', 'Accept-Ranges': 'bytes', 'Cache-Control': MEDIA_CACHE, ETag: etag }
   const body = (start: number, end: number) => Readable.toWeb(createReadStream('', { fd, start, end })) as ReadableStream<Uint8Array>
   const empty = (response: Response) => {
     closeSync(fd)
     return response
   }
+  const unchanged = notModified(request, etag, headers)
+  if (unchanged) return empty(unchanged)
   const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '')
   if (!range || (!range[1] && !range[2])) {
     if (size === 0 || request.method === 'HEAD') return empty(new Response(null, { headers: { ...headers, 'Content-Length': String(size) } }))