avbridge 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbridge",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Play and convert arbitrary video files in the browser. Native, remux, hybrid, fallback, and transcode — one API.",
   "license": "MIT",
   "author": "Keishi Hattori",

package/src/element/avbridge-player.ts

@@ -23,7 +23,7 @@ import {
   ICON_FULLSCREEN, ICON_FULLSCREEN_EXIT,
   ICON_REPLAY_10, ICON_FORWARD_10,
 } from "./player-icons.js";
-import type { AvbridgeVideoElementEventMap } from "../types.js";
+import type { AvbridgeVideoElementEventMap, SettingsSectionConfig } from "../types.js";
 
 // ── Helpers ──────────────────────────────────────────────────────────────
 
@@ -87,6 +87,8 @@ export class AvbridgePlayerElement extends HTMLElement {
   private _volumeInput!: HTMLInputElement;
   private _settingsBtn!: HTMLButtonElement;
   private _settingsMenu!: HTMLDivElement;
+  private _settingsScrim!: HTMLDivElement;
+  private _customSections: import("../types.js").SettingsSectionConfig[] = [];
   private _fullscreenBtn!: HTMLButtonElement;
   // Strategy badge removed — visible in Stats for Nerds instead.
   // Spinner is rendered but driven entirely by CSS :host([data-state]) selectors.
@@ -133,6 +135,7 @@ export class AvbridgePlayerElement extends HTMLElement {
     this._volumeInput = shadow.querySelector(".avp-volume-input") as HTMLInputElement;
     this._settingsBtn = shadow.querySelector(".avp-settings-btn") as HTMLButtonElement;
     this._settingsMenu = shadow.querySelector(".avp-settings") as HTMLDivElement;
+    this._settingsScrim = shadow.querySelector(".avp-settings-scrim") as HTMLDivElement;
     this._fullscreenBtn = shadow.querySelector(".avp-fullscreen") as HTMLButtonElement;
     // Badge removed from controls bar — strategy visible in Stats for Nerds.
     // Spinner is rendered in shadow DOM, driven by CSS :host([data-state]).
@@ -199,7 +202,8 @@ export class AvbridgePlayerElement extends HTMLElement {
       <button class="avp-btn avp-settings-btn" part="settings-button" aria-label="Settings">${ICON_SETTINGS}</button>
       <button class="avp-btn avp-fullscreen" part="fullscreen-button" aria-label="Fullscreen">${ICON_FULLSCREEN}</button>
     </div>
-    <div class="avp-settings" part="settings-menu"></div>
+    <div class="avp-settings-scrim"></div>
+    <div class="avp-settings" part="settings-menu"><div class="avp-settings-handle"></div></div>
   </div>
 </div>`;
   }
@@ -285,6 +289,7 @@ export class AvbridgePlayerElement extends HTMLElement {
 
     // Settings
     on(this._settingsBtn, "click", (e) => { e.stopPropagation(); this._toggleSettings(); });
+    on(this._settingsScrim, "click", () => this._closeSettings());
 
     // Fullscreen
     on(this._fullscreenBtn, "click", (e) => { e.stopPropagation(); this._toggleFullscreen(); });
@@ -298,14 +303,9 @@ export class AvbridgePlayerElement extends HTMLElement {
     on(container, "click", (e) => this._onContainerClick(e as MouseEvent));
     on(container, "dblclick", (e) => this._onContainerDblClick(e as MouseEvent));
 
-    // Dismiss settings menu on click outside (inside or outside the player)
-    on(container, "click", (e) => {
-      if (this._settingsOpen &&
-          !(e.target as HTMLElement).closest?.(".avp-settings-btn, .avp-settings")) {
-        this._closeSettings();
-      }
-    });
-    // Also dismiss if user clicks outside the player element entirely
+    // Dismiss settings sheet when clicking outside it. The scrim handles
+    // most of this (its own click handler calls _closeSettings), but we
+    // also catch clicks outside the player element entirely.
     on(document, "click", (e) => {
       if (this._settingsOpen && !this.contains(e.target as Node)) {
         this._closeSettings();
@@ -535,100 +535,151 @@ export class AvbridgePlayerElement extends HTMLElement {
   private _toggleSettings(): void {
     this._settingsOpen = !this._settingsOpen;
     this._settingsMenu.classList.toggle("open", this._settingsOpen);
-    if (this._settingsOpen) this._showControls();
+    this._settingsScrim.classList.toggle("open", this._settingsOpen);
+    if (this._settingsOpen) {
+      this._fitSettingsToPlayer();
+      this._showControls();
+    }
+  }
+
+  private _fitSettingsToPlayer(): void {
+    const container = this.shadowRoot?.querySelector(".avp") as HTMLElement | null;
+    if (!container) return;
+    const rect = container.getBoundingClientRect();
+    // Bottom sheet can use up to 70% of the player height, leaving room
+    // to see the video behind the scrim. Floor at 120px so it's always
+    // usable.
+    const maxH = Math.max(120, Math.floor(rect.height * 0.7));
+    this._settingsMenu.style.maxHeight = `${maxH}px`;
   }
 
   private _closeSettings(): void {
     this._settingsOpen = false;
     this._settingsMenu.classList.remove("open");
+    this._settingsScrim.classList.remove("open");
   }
 
   private _buildSettingsMenu(): void {
     const sections: string[] = [];
 
-    // Fit mode — opt-in via the `show-fit` attribute. Off by default so
-    // chromeless consumers don't get a surprise entry they have to theme
-    // around.
-    if (this.hasAttribute("show-fit")) {
-      const currentFit = (this._video.fit ?? "contain") as FitMode;
-      let fitItems = "";
-      for (const mode of FIT_MODES) {
-        const active = mode === currentFit;
-        const label = mode[0].toUpperCase() + mode.slice(1);
-        fitItems += `<div class="avp-settings-item${active ? " active" : ""}" data-fit="${mode}">${label}</div>`;
-      }
-      sections.push(`<div class="avp-settings-section"><div class="avp-settings-label">Fit</div>${fitItems}</div>`);
-    }
-
-    // Playback speed
+    // Helper: a row with an invisible native <select> layered on top of
+    // a styled label+value. Tapping opens the OS picker (escapes the
+    // shadow DOM — intentional for small players). The visible label
+    // updates on change.
+    const selectRow = (label: string, currentValue: string, options: string, selectAttrs: string): string =>
+      `<div class="avp-settings-section">` +
+        `<div class="avp-settings-header">` +
+          `<span class="avp-settings-header-label">${label}</span>` +
+          `<span class="avp-settings-header-value">${currentValue}</span>` +
+          `<select class="avp-settings-select" ${selectAttrs}>${options}</select>` +
+        `</div>` +
+      `</div>`;
+
+    // Speed
     const currentRate = this._video.playbackRate ?? 1;
-    let speedItems = "";
+    const speedValue = Math.abs(currentRate - 1) < 0.01 ? "Normal" : `${currentRate}x`;
+    let speedOpts = "";
     for (const spd of PLAYBACK_SPEEDS) {
-      const active = Math.abs(spd - currentRate) < 0.01;
+      const sel = Math.abs(spd - currentRate) < 0.01 ? " selected" : "";
       const label = spd === 1 ? "Normal" : `${spd}x`;
-      speedItems += `<div class="avp-settings-item${active ? " active" : ""}" data-speed="${spd}">${label}</div>`;
+      speedOpts += `<option value="${spd}"${sel}>${label}</option>`;
+    }
+    sections.push(selectRow("Speed", speedValue, speedOpts, `data-action="speed"`));
+
+    // Audio tracks
+    const audios = this._video.audioTracks ?? [];
+    if (audios.length > 1) {
+      let audioOpts = "";
+      for (const t of audios) {
+        audioOpts += `<option value="${t.id}">${t.language ?? `Track ${t.id}`}</option>`;
+      }
+      sections.push(selectRow("Audio", audios[0]?.language ?? "Track 1", audioOpts, `data-action="audio"`));
     }
-    sections.push(`<div class="avp-settings-section"><div class="avp-settings-label">Speed</div>${speedItems}</div>`);
 
     // Subtitle tracks
     const subs = this._video.subtitleTracks ?? [];
     if (subs.length > 0) {
-      let subItems = `<div class="avp-settings-item" data-subtitle="-1">Off</div>`;
+      let subOpts = `<option value="-1" selected>Off</option>`;
       for (const t of subs) {
-        subItems += `<div class="avp-settings-item" data-subtitle="${t.id}">${t.language ?? `Track ${t.id}`}</div>`;
+        subOpts += `<option value="${t.id}">${t.language ?? `Track ${t.id}`}</option>`;
       }
-      sections.push(`<div class="avp-settings-section"><div class="avp-settings-label">Subtitles</div>${subItems}</div>`);
+      sections.push(selectRow("Subtitles", "Off", subOpts, `data-action="subtitle"`));
     }
 
-    // Audio tracks
-    const audios = this._video.audioTracks ?? [];
-    if (audios.length > 1) {
-      let audioItems = "";
-      for (const t of audios) {
-        audioItems += `<div class="avp-settings-item" data-audio="${t.id}">${t.language ?? `Track ${t.id}`}</div>`;
+    // Fit mode — opt-in via the `show-fit` attribute
+    if (this.hasAttribute("show-fit")) {
+      const currentFit = (this._video.fit ?? "contain") as FitMode;
+      const fitValue = currentFit[0].toUpperCase() + currentFit.slice(1);
+      let fitOpts = "";
+      for (const mode of FIT_MODES) {
+        const sel = mode === currentFit ? " selected" : "";
+        const label = mode[0].toUpperCase() + mode.slice(1);
+        fitOpts += `<option value="${mode}"${sel}>${label}</option>`;
       }
-      sections.push(`<div class="avp-settings-section"><div class="avp-settings-label">Audio</div>${audioItems}</div>`);
+      sections.push(selectRow("Fit", fitValue, fitOpts, `data-action="fit"`));
     }
 
-    // Stats for nerds
-    sections.push(`<div class="avp-settings-section"><div class="avp-settings-item" data-stats>Stats for nerds</div></div>`);
-
-    this._settingsMenu.innerHTML = sections.join("");
-
-    // Bind click handlers
-    for (const item of this._settingsMenu.querySelectorAll("[data-fit]")) {
-      item.addEventListener("click", (e) => {
-        e.stopPropagation();
-        const mode = (item as HTMLElement).dataset.fit as FitMode;
-        this.setAttribute("fit", mode);
-        this._buildSettingsMenu();
-      });
+    // Consumer-added sections
+    for (const cfg of this._customSections) {
+      const activeItem = cfg.items.find((i) => i.active);
+      let customOpts = "";
+      for (const item of cfg.items) {
+        const sel = item.active ? " selected" : "";
+        customOpts += `<option value="${item.id}"${sel}>${item.label}</option>`;
+      }
+      sections.push(selectRow(cfg.label, activeItem?.label ?? "", customOpts, `data-action="custom" data-custom-id="${cfg.id}"`));
     }
-    for (const item of this._settingsMenu.querySelectorAll("[data-speed]")) {
-      item.addEventListener("click", (e) => {
+
+    // Stats for nerds — toggle row (no select)
+    sections.push(
+      `<div class="avp-settings-section">` +
+        `<div class="avp-settings-header avp-settings-toggle" data-stats>` +
+          `<span class="avp-settings-header-label">Stats for Nerds</span>` +
+        `</div>` +
+      `</div>`,
+    );
+
+    // Rebuild sheet content (preserve the handle).
+    const handle = this._settingsMenu.querySelector(".avp-settings-handle");
+    this._settingsMenu.innerHTML = "";
+    if (handle) this._settingsMenu.appendChild(handle);
+    else this._settingsMenu.insertAdjacentHTML("afterbegin", `<div class="avp-settings-handle"></div>`);
+    this._settingsMenu.insertAdjacentHTML("beforeend", sections.join(""));
+
+    // ── <select> change handlers ──
+    for (const sel of this._settingsMenu.querySelectorAll<HTMLSelectElement>(".avp-settings-select")) {
+      sel.addEventListener("change", (e) => {
         e.stopPropagation();
-        this._video.playbackRate = Number((item as HTMLElement).dataset.speed);
+        const action = sel.dataset.action;
+        const val = sel.value;
+        switch (action) {
+          case "speed":
+            this._video.playbackRate = Number(val);
+            break;
+          case "audio":
+            void this._video.setAudioTrack(Number(val));
+            break;
+          case "subtitle":
+            void this._video.setSubtitleTrack(Number(val) >= 0 ? Number(val) : null);
+            break;
+          case "fit":
+            this.setAttribute("fit", val);
+            break;
+          case "custom": {
+            const cfgId = sel.dataset.customId!;
+            const cfg = this._customSections.find((s) => s.id === cfgId);
+            cfg?.onSelect(val);
+            break;
+          }
+        }
         this._buildSettingsMenu();
       });
     }
-    for (const item of this._settingsMenu.querySelectorAll("[data-subtitle]")) {
-      item.addEventListener("click", (e) => {
-        e.stopPropagation();
-        const id = Number((item as HTMLElement).dataset.subtitle);
-        void this._video.setSubtitleTrack(id >= 0 ? id : null);
-        this._closeSettings();
-      });
-    }
-    for (const item of this._settingsMenu.querySelectorAll("[data-audio]")) {
-      item.addEventListener("click", (e) => {
-        e.stopPropagation();
-        void this._video.setAudioTrack(Number((item as HTMLElement).dataset.audio));
-        this._closeSettings();
-      });
-    }
-    const statsItem = this._settingsMenu.querySelector("[data-stats]");
-    if (statsItem) {
-      statsItem.addEventListener("click", (e) => {
+
+    // Stats toggle (no select — just a clickable row)
+    const statsRow = this._settingsMenu.querySelector("[data-stats]");
+    if (statsRow) {
+      statsRow.addEventListener("click", (e) => {
         e.stopPropagation();
         this._toggleStats();
         this._closeSettings();
@@ -750,10 +801,17 @@ export class AvbridgePlayerElement extends HTMLElement {
   }
 
   private _onContainerClick(e: MouseEvent): void {
-    // Ignore clicks on controls
+    // Ignore clicks on controls and slotted content
     if ((e.target as HTMLElement).closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
     if (this._isSlottedContentEvent(e)) return;
 
+    // If the bottom sheet is open, any click outside it dismisses
+    // instead of toggling play/pause.
+    if (this._settingsOpen) {
+      this._closeSettings();
+      return;
+    }
+
     // Touch taps are handled by _onPointerUp (show/hide controls + double-tap).
     // The browser fires a synthetic click after touchend — skip it.
     if (this._lastPointerTypeWasTouch) {
@@ -799,6 +857,12 @@ export class AvbridgePlayerElement extends HTMLElement {
     if ((e.target as HTMLElement).closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
     if (this._isSlottedContentEvent(e)) return;
 
+    // If the bottom sheet is open, dismiss it on any touch outside.
+    if (this._settingsOpen) {
+      this._closeSettings();
+      return;
+    }
+
     // Double-tap detection
     const now = Date.now();
     if (now - this._lastTapTime < 300) {
@@ -991,6 +1055,17 @@ export class AvbridgePlayerElement extends HTMLElement {
     return this._video.destroy();
   }
   async setAudioTrack(id: number): Promise<void> { return this._video.setAudioTrack(id); }
+
+  addSettingsSection(config: SettingsSectionConfig): void {
+    this._customSections = this._customSections.filter((s) => s.id !== config.id);
+    this._customSections.push(config);
+    this._buildSettingsMenu();
+  }
+
+  removeSettingsSection(id: string): void {
+    this._customSections = this._customSections.filter((s) => s.id !== id);
+    this._buildSettingsMenu();
+  }
   async setSubtitleTrack(id: number | null): Promise<void> { return this._video.setSubtitleTrack(id); }
   getDiagnostics(): unknown { return this._video.getDiagnostics(); }
   canPlayType(mime: string): string { return this._video.canPlayType(mime); }

package/src/element/player-styles.ts

@@ -34,7 +34,6 @@ export const PLAYER_STYLES = /* css */ `
   position: relative;
   width: 100%;
   height: 100%;
-  cursor: pointer;
   -webkit-tap-highlight-color: transparent;
   user-select: none;
 }
@@ -484,62 +483,113 @@ export const PLAYER_STYLES = /* css */ `
 
 .avp-spacer { flex: 1; }
 
-/* ── Settings menu ────────────────────────────────────────────────────── */
+/* ── Settings bottom sheet ────────────────────────────────────────────── */
+
+/* Scrim — semi-transparent overlay behind the sheet, above the video.
+   Tapping it dismisses the sheet. */
+.avp-settings-scrim {
+  position: absolute;
+  inset: 0;
+  z-index: 9;
+  background: rgba(0, 0, 0, 0.4);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.2s;
+}
 
+.avp-settings-scrim.open {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* Sheet container — slides up from the bottom. Height is content-driven
+   up to a JS-measured max (set on open via style.maxHeight). */
 .avp-settings {
   position: absolute;
-  bottom: 52px;
-  right: 12px;
-  background: rgba(28, 28, 28, 0.95);
-  border-radius: 8px;
-  min-width: 220px;
-  /* Fit within the player: leave room for the controls bar (52px bottom)
-     and a small top margin (8px). On tall players this caps at 300px;
-     on short players it shrinks to whatever fits. */
-  max-height: min(300px, calc(100% - 52px - 8px));
-  overflow-y: auto;
-  display: none;
+  bottom: 0;
+  left: 0;
+  right: 0;
   z-index: 10;
-  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.4);
+  background: rgba(28, 28, 28, 0.97);
+  border-radius: 12px 12px 0 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  transform: translateY(100%);
+  transition: transform 0.2s ease-out;
+  max-height: 70%;
+  padding-bottom: 52px;
+  box-shadow: 0 -4px 20px rgba(0, 0, 0, 0.5);
 }
 
-.avp-settings.open { display: block; }
+.avp-settings.open {
+  transform: translateY(0);
+}
 
-.avp-settings-section {
-  padding: 8px 0;
-  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+/* Drag handle indicator at top of sheet. */
+.avp-settings-handle {
+  width: 36px;
+  height: 4px;
+  border-radius: 2px;
+  background: rgba(255, 255, 255, 0.3);
+  margin: 8px auto 4px;
 }
 
-.avp-settings-section:last-child { border-bottom: none; }
+/* ── Accordion sections ──────────────────────────────────────────────── */
 
-.avp-settings-label {
-  padding: 4px 16px;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-  opacity: 0.5;
+.avp-settings-section {
+  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
 }
 
-.avp-settings-item {
+.avp-settings-section:last-child { border-bottom: none; }
+
+/* Section header — clickable row showing label + current value. */
+.avp-settings-header {
+  position: relative;
   display: flex;
   align-items: center;
-  padding: 8px 16px;
-  font-size: 13px;
+  justify-content: space-between;
+  padding: 12px 16px;
   cursor: pointer;
+  font-size: 14px;
   transition: background 0.1s;
 }
 
-.avp-settings-item:hover { background: rgba(255, 255, 255, 0.1); }
+.avp-settings-header:hover { background: rgba(255, 255, 255, 0.06); }
 
-.avp-settings-item.active {
-  color: #3ea6ff;
+.avp-settings-header-label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 500;
 }
 
-.avp-settings-item.active::before {
-  content: "\\2713";
-  margin-right: 8px;
-  font-weight: bold;
+.avp-settings-header-value {
+  margin-left: auto;
+  opacity: 0.6;
+  font-size: 13px;
+  text-align: right;
+}
+
+/* Invisible native <select> layered over the value portion of the row.
+   Covers from the value text to the right edge so tapping the value
+   opens the OS picker. The label side remains inert. */
+.avp-settings-select {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 50%;
+  opacity: 0;
+  cursor: pointer;
+  font-size: 16px;
+  direction: rtl;
+}
+
+/* Toggle-style rows (Stats for Nerds) — no select, just clickable. */
+.avp-settings-toggle {
+  cursor: pointer;
 }
+.avp-settings-toggle:hover { background: rgba(255, 255, 255, 0.06); }
 
 /* ── Stats for nerds ──────────────────────────────────────────────────── */
 

package/src/index.ts

@@ -36,6 +36,7 @@ export type {
   HardwareAccelerationHint,
   FetchFn,
   TransportConfig,
+  SettingsSectionConfig,
 } from "./types.js";
 
 export { classify } from "./classify/index.js";

package/src/strategies/fallback/audio-output.ts

@@ -80,6 +80,10 @@ export class AudioOutput implements ClockSource {
   private _volume = 1;
   /** User-set muted flag. When true, gain is forced to 0. */
   private _muted = false;
+  /** Playback rate. Scales the media clock and each AudioBufferSourceNode's
+   *  playbackRate so audio pitches up/down accordingly (same as native
+   *  <video>.playbackRate). Default 1. */
+  private _rate = 1;
 
   constructor() {
     this.ctx = new AudioContext();
@@ -107,6 +111,24 @@ export class AudioOutput implements ClockSource {
     return this._muted;
   }
 
+  /** Set playback rate. Scales the media clock and pitches audio output
+   *  (same as native <video>.playbackRate — speed without pitch correction).
+   *  Rebases the anchor so the clock transition is seamless. */
+  setPlaybackRate(rate: number): void {
+    if (rate === this._rate) return;
+    // Rebase anchor at the current media time before changing rate,
+    // so the clock doesn't jump.
+    const t = this.now();
+    this.mediaTimeOfAnchor = t;
+    this.ctxTimeAtAnchor = this.ctx.currentTime;
+    this.wallAnchorMs = performance.now();
+    this._rate = rate;
+  }
+
+  getPlaybackRate(): number {
+    return this._rate;
+  }
+
   private applyGain(): void {
     const target = this._muted ? 0 : this._volume;
     try { this.gain.gain.value = target; } catch { /* ignore */ }
@@ -127,12 +149,12 @@ export class AudioOutput implements ClockSource {
   now(): number {
     if (this.noAudio) {
       if (this.state === "playing") {
-        return this.mediaTimeOfAnchor + (performance.now() - this.wallAnchorMs) / 1000;
+        return this.mediaTimeOfAnchor + (performance.now() - this.wallAnchorMs) / 1000 * this._rate;
       }
       return this.mediaTimeOfAnchor;
     }
     if (this.state === "playing") {
-      return this.mediaTimeOfAnchor + (this.ctx.currentTime - this.ctxTimeAtAnchor);
+      return this.mediaTimeOfAnchor + (this.ctx.currentTime - this.ctxTimeAtAnchor) * this._rate;
     }
     return this.mediaTimeOfAnchor;
   }
@@ -200,9 +222,12 @@ export class AudioOutput implements ClockSource {
     const node = this.ctx.createBufferSource();
     node.buffer = buffer;
     node.connect(this.gain);
+    // Pitch the audio to match the playback rate (same as native <video>).
+    if (this._rate !== 1) node.playbackRate.value = this._rate;
 
-    // Convert media time → ctx time using the anchor.
-    let ctxStart = this.ctxTimeAtAnchor + (this.mediaTimeOfNext - this.mediaTimeOfAnchor);
+    // Convert media time → ctx time using the anchor + rate. At rate=2,
+    // each second of media time occupies 0.5s of ctx time.
+    let ctxStart = this.ctxTimeAtAnchor + (this.mediaTimeOfNext - this.mediaTimeOfAnchor) / this._rate;
 
     // When the decoder is slower than realtime, `ctxStart` falls into
     // the past (ctx.currentTime has already passed it). Clamping each

package/src/strategies/fallback/index.ts

@@ -128,6 +128,17 @@ export async function createFallbackSession(
       get: () => ctx.duration ?? NaN,
     });
   }
+  // Playback rate — canvas strategies don't use the real <video>, so the
+  // native playbackRate property does nothing. Patch it to drive the
+  // AudioOutput clock speed + pitch.
+  Object.defineProperty(target, "playbackRate", {
+    configurable: true,
+    get: () => audio.getPlaybackRate(),
+    set: (v: number) => {
+      audio.setPlaybackRate(v);
+      target.dispatchEvent(new Event("ratechange"));
+    },
+  });
   // Synthesize HTMLMediaElement parity surfaces that the canvas strategies
   // can't otherwise answer truthfully (the inner <video> has no src, so
   // its own readyState/seekable are zero/empty).
@@ -351,6 +362,7 @@ export async function createFallbackSession(
         delete (target as unknown as Record<string, unknown>).muted;
         delete (target as unknown as Record<string, unknown>).readyState;
         delete (target as unknown as Record<string, unknown>).seekable;
+        delete (target as unknown as Record<string, unknown>).playbackRate;
       } catch { /* ignore */ }
     },
 

package/src/strategies/hybrid/index.ts

@@ -84,6 +84,14 @@ export async function createHybridSession(
       get: () => ctx.duration ?? NaN,
     });
   }
+  Object.defineProperty(target, "playbackRate", {
+    configurable: true,
+    get: () => audio.getPlaybackRate(),
+    set: (v: number) => {
+      audio.setPlaybackRate(v);
+      target.dispatchEvent(new Event("ratechange"));
+    },
+  });
   // HTMLMediaElement parity surfaces — see fallback/index.ts for rationale.
   Object.defineProperty(target, "readyState", {
     configurable: true,
@@ -213,6 +221,7 @@ export async function createHybridSession(
         delete (target as unknown as Record<string, unknown>).muted;
         delete (target as unknown as Record<string, unknown>).readyState;
         delete (target as unknown as Record<string, unknown>).seekable;
+        delete (target as unknown as Record<string, unknown>).playbackRate;
       } catch { /* ignore */ }
     },
 

package/src/types.ts

@@ -465,3 +465,28 @@ export interface ConvertResult {
    */
   notes?: string[];
 }
+
+// ── Settings extensibility ──────────────────────────────────────────────
+
+/**
+ * Configuration for a custom settings section added to `<avbridge-player>`
+ * via {@link addSettingsSection}. Sections render in the bottom-sheet
+ * settings panel alongside built-in sections (Speed, Audio, Subtitles,
+ * Fit, Stats for Nerds). The player owns rendering — consumers describe
+ * data; avbridge renders it in a consistent visual style.
+ */
+export interface SettingsSectionConfig {
+  /** Unique id for this section. Used to update/remove later. */
+  id: string;
+  /** Display label (e.g. "Quality", "Translate"). */
+  label: string;
+  /** Items to show when the section is expanded. */
+  items: Array<{
+    id: string;
+    label: string;
+    /** Mark the currently-selected item. */
+    active?: boolean;
+  }>;
+  /** Called when the user picks an item. */
+  onSelect(itemId: string): void;
+}