@kodezen/player 1.0.2 → 1.0.3

package/README.md

@@ -70,7 +70,8 @@ import '@kodezen/player/styles.css';
 `createPlayer(container, options)` → instance.
 
 **Options:** `source {type,url,id,poster,mime}`, `resumeAt`, `lockSeek`,
-`autoplay`, `muted`, `speeds[]`, `controls{}`, `className`.
+`autoplay`, `muted`, `speeds[]`, `controls{}`, `className`,
+`tracks[] {src,label,srclang,default}`.
 
 **Instance:** `play()`, `pause()`, `toggle()`, `seek(s)`, `getState()`,
 `on(event, cb)`, `off(event, cb)`, `destroy()`.
@@ -80,6 +81,25 @@ import '@kodezen/player/styles.css';
 (`percent` = furthest / duration, so it reflects watched coverage, not the
 scrub position).
 
+## Subtitles / captions
+
+Pass WebVTT files as `tracks`. The player fetches and renders them itself in
+an overlay, so the same `.vtt` works for `html5`, `youtube` and `vimeo`
+(YouTube/Vimeo iframes can't load an external caption file). A CC button
+toggles a single track, or opens a menu when there are several. A track with
+`default: true` is shown as soon as it loads; otherwise captions start off.
+
+```js
+createPlayer(el, {
+  source: { type: 'youtube', id: 'dQw4w9WgXcQ' },
+  tracks: [{ src: '/uploads/lesson-1.vtt', label: 'English', srclang: 'en', default: true }],
+});
+```
+
+The file must be same-origin or served with CORS. Cue settings
+(position/alignment) and styling blocks are ignored — cues render as plain
+centred text. `parseVtt(text)` is exported if you need the cues yourself.
+
 ## Host integration notes
 
 - **Resume** = pass `resumeAt`; player seeks on `ready` unless within 2s of end.

package/dist/index.cjs

@@ -447,13 +447,124 @@ function createProvider(source) {
   }
 }
 
+// src/core/Captions.ts
+var TIMING = /^\s*((?:\d+:)?\d{1,2}:\d{2}[.,]\d{1,3})\s+-->\s+((?:\d+:)?\d{1,2}:\d{2}[.,]\d{1,3})/;
+var ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0",
+  lrm: "\u200E",
+  rlm: "\u200F"
+};
+function toSeconds(stamp) {
+  const [clock = "", fraction = "0"] = stamp.replace(",", ".").split(".");
+  const seconds = clock.split(":").reduce((total, part) => total * 60 + Number(part), 0);
+  return seconds + Number(`0.${fraction}`);
+}
+function plainText(text) {
+  return text.replace(/<[^>]*>/g, "").replace(/&(amp|lt|gt|quot|apos|nbsp|lrm|rlm);/g, (_, name) => {
+    var _a;
+    return (_a = ENTITIES[name]) != null ? _a : "";
+  }).replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)));
+}
+function parseVtt(input) {
+  var _a;
+  const cues = [];
+  const blocks = input.replace(/^/, "").replace(/\r\n?/g, "\n").split(/\n{2,}/);
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const timingAt = lines.findIndex((line) => line.includes("-->"));
+    const timing = TIMING.exec((_a = lines[timingAt]) != null ? _a : "");
+    if (!(timing == null ? void 0 : timing[1]) || !timing[2]) continue;
+    const text = plainText(lines.slice(timingAt + 1).join("\n")).trim();
+    if (!text) continue;
+    cues.push({ start: toSeconds(timing[1]), end: toSeconds(timing[2]), text });
+  }
+  return cues.sort((a, b) => a.start - b.start);
+}
+var Captions = class {
+  /** `onChange` fires when the active track or track availability changes. */
+  constructor(tracks, onChange) {
+    this.onChange = onChange;
+    this.active = -1;
+    this.time = 0;
+    this.abort = new AbortController();
+    this.el = document.createElement("div");
+    this.el.className = "kzp-captions";
+    this.el.setAttribute("aria-live", "off");
+    this.text = document.createElement("span");
+    this.text.className = "kzp-captions-text";
+    this.text.hidden = true;
+    this.el.appendChild(this.text);
+    this.tracks = tracks.map((info) => ({ info, cues: null, failed: false }));
+    const preferred = tracks.findIndex((t) => t.default);
+    this.tracks.forEach((track, index) => {
+      void this.load(track).then(() => {
+        if (index === preferred && this.active === -1 && track.cues) this.select(index);
+        else this.onChange();
+      });
+    });
+  }
+  async load(track) {
+    try {
+      const res = await fetch(track.info.src, { signal: this.abort.signal, credentials: "same-origin" });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      track.cues = parseVtt(await res.text());
+    } catch (err) {
+      if (this.abort.signal.aborted) return;
+      track.failed = true;
+      console.warn(`@kodezen/player: could not load captions from ${track.info.src}`, err);
+    }
+  }
+  /** Labels for the menu, one per track (falls back to the language, then a number). */
+  labels() {
+    return this.tracks.map((t, i) => t.info.label || t.info.srclang || `Track ${i + 1}`);
+  }
+  /** Whether each track loaded (a failed track is hidden from the controls). */
+  available() {
+    return this.tracks.map((t) => !t.failed);
+  }
+  getActive() {
+    return this.active;
+  }
+  /** Show track `index`, or turn captions off with -1. */
+  select(index) {
+    var _a;
+    const track = this.tracks[index];
+    this.active = track && !track.failed ? index : -1;
+    this.el.lang = (_a = track == null ? void 0 : track.info.srclang) != null ? _a : "";
+    this.render();
+    this.onChange();
+  }
+  /** Called with the playhead position on every tick and after a seek. */
+  update(time) {
+    this.time = time;
+    this.render();
+  }
+  render() {
+    var _a, _b;
+    const cues = (_b = (_a = this.tracks[this.active]) == null ? void 0 : _a.cues) != null ? _b : [];
+    const text = cues.filter((cue) => this.time >= cue.start && this.time < cue.end).map((cue) => cue.text).join("\n");
+    if (text !== this.text.textContent) this.text.textContent = text;
+    this.text.hidden = !text;
+  }
+  destroy() {
+    this.abort.abort();
+    this.el.remove();
+  }
+};
+
 // src/core/Controls.ts
 var ICONS = {
   play: '<path d="M8 5v14l11-7z"/>',
   pause: '<path d="M6 5h4v14H6zM14 5h4v14h-4z"/>',
   volume: '<path d="M3 10v4h4l5 5V5L7 10H3zm13.5 2a4.5 4.5 0 0 0-2.5-4v8a4.5 4.5 0 0 0 2.5-4z"/>',
   muted: '<path d="M3 10v4h4l5 5V5L7 10H3zm13 2 3 3 1-1-3-3 3-3-1-1-3 3-3-3-1 1 3 3-3 3 1 1z"/>',
-  full: '<path d="M4 4h6v2H6v4H4V4zm10 0h6v6h-2V6h-4V4zM4 14h2v4h4v2H4v-6zm14 0h2v6h-6v-2h4v-4z"/>'
+  full: '<path d="M4 4h6v2H6v4H4V4zm10 0h6v6h-2V6h-4V4zM4 14h2v4h4v2H4v-6zm14 0h2v6h-6v-2h4v-4z"/>',
+  captions: '<path d="M19 4H5a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2zm-8 7H9.5v-.5h-2v3h2V13H11v1a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1v-4a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1zm7 0h-1.5v-.5h-2v3h2V13H18v1a1 1 0 0 1-1 1h-3a1 1 0 0 1-1-1v-4a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1z"/>'
 };
 function icon(paths) {
   return `<svg viewBox="0 0 24 24" aria-hidden="true">${paths}</svg>`;
@@ -473,20 +584,23 @@ var DEFAULT_CONFIG = {
   time: true,
   volume: true,
   speed: true,
+  captions: true,
   fullscreen: true
 };
 var Controls = class {
   constructor(cb, opts) {
     this.cb = cb;
+    this.ccActive = -1;
     this.scrubbing = false;
     this.seekableMax = Infinity;
+    var _a;
     this.config = { ...DEFAULT_CONFIG, ...opts.config };
     this.lockSeek = opts.lockSeek;
     this.el = document.createElement("div");
     this.el.className = "kzp-controls";
-    this.build(opts.speeds);
+    this.build(opts.speeds, (_a = opts.captionLabels) != null ? _a : []);
   }
-  build(speeds) {
+  build(speeds, captionLabels) {
     if (this.config.playPause) {
       this.playBtn = this.button("kzp-play", "Play", ICONS.play);
       this.playBtn.addEventListener("click", () => this.cb.onToggle());
@@ -563,16 +677,72 @@ var Controls = class {
       }
       this.speedBtn.addEventListener("click", () => {
         this.speedMenu.hidden = !this.speedMenu.hidden;
+        if (this.ccMenu) this.ccMenu.hidden = true;
       });
       wrap.append(this.speedBtn, this.speedMenu);
       this.el.appendChild(wrap);
     }
+    if (this.config.captions && captionLabels.length) {
+      this.buildCaptions(captionLabels);
+    }
     if (this.config.fullscreen) {
       const btn = this.button("kzp-full", "Fullscreen", ICONS.full);
       btn.addEventListener("click", () => this.cb.onFullscreen());
       this.el.appendChild(btn);
     }
   }
+  /**
+   * One track: the CC button toggles it. Several: it opens a menu (Off + each
+   * track), styled like the speed menu. Sits left of the speed control.
+   */
+  buildCaptions(labels) {
+    const wrap = document.createElement("div");
+    wrap.className = "kzp-cc";
+    this.ccBtn = this.button("kzp-cc-btn", "Subtitles/closed captions", ICONS.captions);
+    this.ccBtn.setAttribute("aria-pressed", "false");
+    wrap.appendChild(this.ccBtn);
+    if (labels.length === 1) {
+      this.ccBtn.addEventListener("click", () => this.cb.onCaptions(this.ccActive === -1 ? 0 : -1));
+    } else {
+      this.ccMenu = document.createElement("div");
+      this.ccMenu.className = "kzp-speed-menu kzp-cc-menu";
+      this.ccMenu.hidden = true;
+      const items = [{ index: -1, label: "Off" }, ...labels.map((label, index) => ({ index, label }))];
+      for (const { index, label } of items) {
+        const item = document.createElement("button");
+        item.type = "button";
+        item.textContent = label;
+        item.dataset.track = String(index);
+        item.addEventListener("click", () => {
+          this.cb.onCaptions(index);
+          this.ccMenu.hidden = true;
+        });
+        this.ccMenu.appendChild(item);
+      }
+      this.ccBtn.addEventListener("click", () => {
+        this.ccMenu.hidden = !this.ccMenu.hidden;
+        if (this.speedMenu) this.speedMenu.hidden = true;
+      });
+      wrap.appendChild(this.ccMenu);
+    }
+    this.ccWrap = wrap;
+    const speed = this.el.querySelector(".kzp-speed");
+    this.el.insertBefore(wrap, speed);
+  }
+  /** Reflect the active caption track, and hide tracks (or the whole control) that failed to load. */
+  setCaptions(active, available) {
+    var _a;
+    this.ccActive = active;
+    if (!this.ccBtn || !this.ccWrap) return;
+    this.ccWrap.hidden = !available.some(Boolean);
+    this.ccBtn.classList.toggle("kzp-cc-btn--on", active !== -1);
+    this.ccBtn.setAttribute("aria-pressed", String(active !== -1));
+    (_a = this.ccMenu) == null ? void 0 : _a.querySelectorAll("button").forEach((item) => {
+      const index = Number(item.dataset.track);
+      item.hidden = index !== -1 && !available[index];
+      item.classList.toggle("kzp-menu-item--active", index === active);
+    });
+  }
   button(cls, label, svg) {
     const b = document.createElement("button");
     b.type = "button";
@@ -622,13 +792,14 @@ var Player = class {
     this.container = container;
     this.options = options;
     this.emitter = new Emitter();
+    this.captions = null;
     this.furthest = 0;
     this.lastTick = 0;
     this.duration = 0;
     this.playing = false;
     this.ready = false;
     this.disposers = [];
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     const speeds = (_a = options.speeds) != null ? _a : DEFAULT_SPEEDS;
     this.root = document.createElement("div");
     this.root.className = "kzp" + (options.className ? ` ${options.className}` : "");
@@ -643,6 +814,10 @@ var Player = class {
     this.stage.appendChild(hitLayer);
     this.provider = createProvider(options.source);
     const caps = this.provider.capabilities;
+    if ((_b = options.tracks) == null ? void 0 : _b.length) {
+      this.captions = new Captions(options.tracks, () => this.syncCaptions());
+      this.root.appendChild(this.captions.el);
+    }
     this.controls = new Controls(
       {
         onToggle: () => this.toggle(),
@@ -660,17 +835,22 @@ var Player = class {
           this.provider.setRate(r);
           this.render();
         },
+        onCaptions: (index) => {
+          var _a2;
+          return (_a2 = this.captions) == null ? void 0 : _a2.select(index);
+        },
         onFullscreen: () => this.toggleFullscreen()
       },
       {
         config: {
           ...options.controls,
-          seek: ((_c = (_b = options.controls) == null ? void 0 : _b.seek) != null ? _c : true) && caps.seekable,
-          speed: ((_e = (_d = options.controls) == null ? void 0 : _d.speed) != null ? _e : true) && caps.rate,
-          volume: ((_g = (_f = options.controls) == null ? void 0 : _f.volume) != null ? _g : true) && caps.volume
+          seek: ((_d = (_c = options.controls) == null ? void 0 : _c.seek) != null ? _d : true) && caps.seekable,
+          speed: ((_f = (_e = options.controls) == null ? void 0 : _e.speed) != null ? _f : true) && caps.rate,
+          volume: ((_h = (_g = options.controls) == null ? void 0 : _g.volume) != null ? _h : true) && caps.volume
         },
         speeds,
-        lockSeek: !!options.lockSeek
+        lockSeek: !!options.lockSeek,
+        captionLabels: (_i = this.captions) == null ? void 0 : _i.labels()
       }
     );
     this.root.appendChild(this.controls.el);
@@ -723,6 +903,7 @@ var Player = class {
     this.render();
   }
   onTimeUpdate(current) {
+    var _a;
     const advance = current - this.lastTick;
     if (advance > 0 && advance <= NATURAL_ADVANCE_MAX && current > this.furthest) {
       this.furthest = current;
@@ -730,9 +911,14 @@ var Player = class {
       this.provider.seek(this.furthest);
     }
     this.lastTick = current;
+    (_a = this.captions) == null ? void 0 : _a.update(current);
     this.emitter.emit("timeupdate", this.snapshot());
     this.render();
   }
+  syncCaptions() {
+    if (!this.captions) return;
+    this.controls.setCaptions(this.captions.getActive(), this.captions.available());
+  }
   snapshot() {
     const current = this.provider.getCurrentTime();
     const duration = this.duration || this.provider.getDuration();
@@ -766,10 +952,12 @@ var Player = class {
     else this.provider.play();
   }
   seek(seconds) {
+    var _a;
     if (!this.provider.capabilities.seekable) return;
     const target = this.options.lockSeek && seconds > this.furthest ? this.furthest : Math.max(0, seconds);
     this.provider.seek(target);
     this.lastTick = target;
+    (_a = this.captions) == null ? void 0 : _a.update(target);
     this.render();
   }
   setLockSeek(locked) {
@@ -788,9 +976,11 @@ var Player = class {
     this.emitter.off(event, cb);
   }
   destroy() {
+    var _a;
     for (const dispose of this.disposers) dispose();
     this.disposers = [];
     this.provider.destroy();
+    (_a = this.captions) == null ? void 0 : _a.destroy();
     this.controls.destroy();
     this.emitter.clear();
     this.root.remove();
@@ -804,5 +994,6 @@ function createPlayer(container, options) {
 
 exports.Player = Player;
 exports.createPlayer = createPlayer;
+exports.parseVtt = parseVtt;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map