@scarlett-player/embed 1.7.0 → 1.8.1

package/README.md

@@ -11,6 +11,7 @@ Standalone, CDN-ready embed package for Scarlett Player. Drop in a single `<scri
 - **Multi-tenant Ready** - Brand customization via data attributes
 - **Unified API** - Single API for video, audio, and compact audio players
 - **iframe Support** - Helper page for URL-based iframe embeds
+- **Sharing** - Opt-in share button on video: OS share sheet, copy link, embed code
 
 ## Installation
 
@@ -35,6 +36,34 @@ npm install @scarlett-player/embed
 pnpm add @scarlett-player/embed
 ```
 
+## Supported sources
+
+Every build registers two providers and picks the first one that accepts the
+source URL, by file extension:
+
+| Source | Provider | Extensions |
+|--------|----------|------------|
+| HLS | hls.js, or the browser's own HLS in Safari | `.m3u8` |
+| Progressive video | native `<video>` element | `.mp4`, `.m4v`, `.webm`, `.mov`, `.mkv`, `.ogv` |
+| Progressive audio | native media element | `.mp3`, `.m4a`, `.aac`, `.wav`, `.ogg`, `.opus`, `.flac`, `.weba` |
+
+HLS always wins for `.m3u8`. The native provider also asks the browser whether
+it can play the format before claiming a source, so an `.mkv` in a browser
+without Matroska support is declined rather than played into a black frame.
+
+Before 1.7.1 no embed build registered the native provider at all, and any
+non-HLS source failed with `PROVIDER_NOT_FOUND`. If you are on an older build,
+upgrade rather than working around it.
+
+### Audio build: hls.js/light
+
+`embed.audio.js` / `embed.audio.umd.cjs` build on `hls.js/light`, which drops
+in-stream subtitle parsing, ID3 tag parsing and EME/DRM in exchange for a much
+smaller bundle. The audio build ships no captions plugin and audio embeds are
+not DRM sources, so **ID3 timed metadata is the one capability an audio embed
+gives up**. If you need ID3 (in-stream "now playing" updates on a live audio
+stream, typically), use the Full build.
+
 ## Usage
 
 ### 1. Declarative (Data Attributes)
@@ -54,7 +83,7 @@ The simplest way to embed a player. Just add the script and use data attributes:
     data-src="https://example.com/stream.m3u8"
   ></div>
 
-  <!-- Audio player -->
+  <!-- Audio player (HLS) -->
   <div
     data-scarlett-player
     data-src="https://example.com/podcast.m3u8"
@@ -63,6 +92,16 @@ The simplest way to embed a player. Just add the script and use data attributes:
     data-artist="My Podcast"
   ></div>
 
+  <!-- Audio player (progressive MP3 file) -->
+  <div
+    data-scarlett-player
+    data-src="https://example.com/episode-42.mp3"
+    data-type="audio"
+    data-title="Episode 42: Deep Dive"
+    data-artist="My Podcast"
+    data-artwork="https://example.com/podcast-cover.jpg"
+  ></div>
+
   <!-- Compact audio player -->
   <div
     data-scarlett-player
@@ -90,13 +129,15 @@ The simplest way to embed a player. Just add the script and use data attributes:
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `data-src` | string | **required** | Media source URL (HLS .m3u8) |
+| `data-src` | string | **required** | Media source URL. HLS (`.m3u8`) or a progressive file, see [Supported sources](#supported-sources) |
 | `data-type` | string | `video` | Player type: `video`, `audio`, or `audio-mini` |
 | `data-autoplay` | boolean | `false` | Auto-play on load |
 | `data-muted` | boolean | `false` | Start muted |
 | `data-poster` | string | - | Poster/artwork image URL |
 | `data-controls` | boolean | `true` | Show/hide UI controls |
-| `data-brand-color` | string | - | Accent color (e.g., `#e50914`) |
+| `data-big-play-button` | boolean | `true` | Centred play button over the poster (video only). Set `false` when your page draws its own play affordance |
+| `data-gestures` | boolean | `true` | Touch gestures on the picture (video only): double-tap the sides to seek, tap to toggle the controls. Touch only, by input type, so a mouse never triggers them. Set `false` if your page owns those gestures |
+| `data-brand-color` | string | - | Accent color (e.g., `#e50914`). `data-color` is accepted as an alias |
 | `data-primary-color` | string | - | Primary UI color |
 | `data-background-color` | string | - | Control bar background |
 | `data-hide-delay` | number | `3000` | Auto-hide delay (ms) |
@@ -107,8 +148,9 @@ The simplest way to embed a player. Just add the script and use data attributes:
 | `data-loop` | boolean | `false` | Loop playback |
 | `data-playback-rate` | number | `1.0` | Playback speed |
 | `data-start-time` | number | `0` | Start position (seconds) |
-| `data-share-url` | string | - | Canonical page URL for the share plugin. Set this on iframe embeds, or sharing links to the player page instead of yours |
 | `data-class` | string | - | Custom CSS class(es) |
+| `data-share-url` | string | - | Page URL to share. Setting it adds a share button to the video control bar; leaving it out changes nothing. Never the media `src`, see [Sharing](#sharing) |
+| `data-embed-base-url` | string | - | URL of your `iframe.html` deployment. Only read alongside `data-share-url`, and only to enable the `embed` target in the share sheet |
 
 #### Audio-specific Attributes
 
@@ -118,6 +160,17 @@ The simplest way to embed a player. Just add the script and use data attributes:
 | `data-artist` | string | Artist/creator name |
 | `data-album` | string | Album name |
 | `data-artwork` | string | Album art / cover image URL |
+| `data-playlist` | JSON | Array of `{ src, title?, artist?, poster?, artwork?, duration? }` (Full and Audio builds) |
+
+#### Analytics Attributes (Full build)
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `data-analytics-beacon-url` | string | Beacon endpoint. Setting it enables the analytics plugin |
+| `data-analytics-video-id` | string | Video identifier sent with every beacon |
+| `data-analytics-api-key` | string | Optional API key |
+
+The auto-initializer also accepts `data-sp` in place of `data-scarlett-player`.
 
 ### 2. Programmatic API
 
@@ -137,6 +190,9 @@ For dynamic player creation:
     muted: true,
     brandColor: '#e50914',
     aspectRatio: '16:9',
+    // Video only, and optional: omit it to keep the centred play button.
+    // false hides it, for a page that draws its own play affordance.
+    bigPlayButton: false,
   });
 
   // Create audio player
@@ -149,6 +205,16 @@ For dynamic player creation:
     artwork: 'https://example.com/artwork.jpg',
   });
 
+  // Create audio player from a progressive MP3 file
+  const mp3Player = await ScarlettPlayer.create({
+    container: '#mp3-player',
+    src: 'https://example.com/episode-42.mp3',
+    type: 'audio',
+    title: 'Episode 42: Deep Dive',
+    artist: 'Tech Podcast',
+    artwork: 'https://example.com/podcast-cover.jpg',
+  });
+
   // Create compact audio player
   const miniPlayer = await ScarlettPlayer.create({
     container: '#mini-player',
@@ -202,15 +268,6 @@ For secure, sandboxed embeds:
   allow="autoplay; fullscreen; picture-in-picture"
 ></iframe>
 
-<!-- Audio player iframe -->
-<iframe
-  src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/audio.m3u8&type=audio"
-  width="100%"
-  height="120"
-  frameborder="0"
-  allow="autoplay"
-></iframe>
-
 <!-- With customization -->
 <iframe
   src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/stream.m3u8&autoplay=true&muted=true&brand-color=%23e50914"
@@ -224,29 +281,50 @@ For secure, sandboxed embeds:
 
 #### iframe URL Parameters
 
-All data attributes work as URL parameters (use kebab-case):
+`iframe.html` loads the Full build and reads these URL parameters (kebab-case
+or camelCase):
 - `src` (required)
-- `type` - `video`, `audio`, or `audio-mini`
-- `autoplay`, `muted`, `loop`
+- `autoplay`, `muted`, `loop` - `true` or `1` to enable
+- `controls` - `false` or `0` to hide the control bar
 - `poster`
 - `brand-color`, `primary-color`, `background-color`
+- `big-play-button` - omit to keep the centred play button, `false` or `0` to hide it
+- `hide-delay`, `playback-rate`, `start-time`
+- `share-url` - the page the viewer should be sent to. Setting it adds the share button; omitting it leaves the control bar unchanged. See [Sharing](#sharing)
+- `embed-base-url` - optional canonical embed URL. Enables the **Embed** snippet target in the share sheet without leaking signed playback parameters
+
+`share-url` is the one parameter the player cannot work out for itself. Inside
+the iframe, `window.location.href` is the player page rather than your page, and
+cross-origin rules stop anything reading the parent, so a share would otherwise
+offer a link to the bare embed. Pass `embed-base-url` if you wish to offer an
+`<iframe>` snippet option in the share sheet; omitting it excludes the embed
+target to avoid leaking query parameters (such as signed media URLs) from
+the running iframe.
+
+The iframe page always creates a video player: it does not read a `type`
+parameter in this version. For an audio or compact audio embed use the data
+attributes or the programmatic API on your own page.
 
 ## Player Types
 
 ### Video Player (default)
 
 Standard video player with full controls, fullscreen, picture-in-picture support.
+Takes an HLS manifest or a progressive video file.
 
 ```html
 <div data-scarlett-player data-src="video.m3u8"></div>
+<div data-scarlett-player data-src="bout-13.mp4"></div>
 ```
 
 ### Audio Player
 
-Full-sized audio player with waveform, track info, and media session integration.
+Full-sized audio player with album artwork, track info, and media session integration.
+Takes an HLS manifest or a progressive audio file.
 
 ```html
 <div data-scarlett-player data-src="audio.m3u8" data-type="audio"></div>
+<div data-scarlett-player data-src="episode-42.mp3" data-type="audio"></div>
 ```
 
 ### Compact Audio Player
@@ -257,6 +335,52 @@ Minimal audio player for space-constrained layouts (64px height).
 <div data-scarlett-player data-src="audio.m3u8" data-type="audio-mini"></div>
 ```
 
+## Sharing
+
+Off unless you ask for it. Give the embed the page URL and a share button
+appears in the video control bar; leave it out and the control bar is exactly
+what it has always been.
+
+```html
+<div
+  data-scarlett-player
+  data-src="https://example.com/stream.m3u8"
+  data-share-url="https://example.com/watch/abc"
+></div>
+```
+
+```html
+<iframe
+  src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https%3A%2F%2Fexample.com%2Fstream.m3u8&share-url=https%3A%2F%2Fexample.com%2Fwatch%2Fabc"
+  width="640" height="360" frameborder="0" allowfullscreen
+  allow="autoplay; fullscreen; picture-in-picture"
+></iframe>
+```
+
+The button opens the OS share sheet on a phone and an in-player sheet
+everywhere else, offering copy link and, where a base URL is known, an embed
+code. Everything it shares carries the current playback position.
+
+**What gets shared is `data-share-url`, never `data-src`.** There is no
+fallback, because playback URLs are frequently signed: sharing one would leak a
+credential and hand the recipient a link that expires. That is also why the
+embed cannot supply a default and the button stays off until you pass one.
+
+A few limits worth knowing:
+
+- **Video only.** The button is a registered control in the video control bar,
+  and the audio UIs render a fixed template with no control registry, so
+  `data-type="audio"` and `audio-mini` ignore `data-share-url`. The Audio build
+  ships no share plugin at all.
+- **Needs the controls.** `data-controls="false"` removes the only way in, so
+  sharing is skipped along with the rest of the UI.
+- **The embed code is opt-in separately.** The sheet's **Embed** option needs to
+  know where your `iframe.html` lives: pass `data-embed-base-url` (or `embed-base-url`
+  in `iframe.html`). Without it the option is left out rather than shown broken.
+
+Full configuration (custom targets, icon, analytics hooks) lives in
+[`@scarlett-player/share`](https://github.com/Hackney-Enterprises-Inc/scarlett-player/tree/main/packages/plugins/share).
+
 ## Multi-Tenant Branding
 
 Perfect for The Stream Platform's white-label needs:
@@ -285,15 +409,15 @@ All builds are available at `https://assets.thestreamplatform.com/scarlett-playe
 
 | Build | Files | Features |
 |-------|-------|----------|
-| **Full** | `embed.js` / `embed.umd.cjs` | Video + Audio + Analytics + Playlist + Media Session |
-| **Video** | `embed.video.js` / `embed.video.umd.cjs` | Video player only (lightweight) |
-| **Audio** | `embed.audio.js` / `embed.audio.umd.cjs` | Audio + Playlist + Media Session |
+| **Full** | `embed.js` / `embed.umd.cjs` | Video + Audio + Analytics + Playlist + Media Session + Sharing |
+| **Video** | `embed.video.js` / `embed.video.umd.cjs` | Video player only (lightweight), Sharing |
+| **Audio** | `embed.audio.js` / `embed.audio.umd.cjs` | Audio + Playlist + Media Session, on `hls.js/light` (no ID3, no sharing) |
 
 **Which build should I use?**
 
 - Use **Full** (`embed.umd.cjs`) if you need both video and audio, or want analytics
 - Use **Video** (`embed.video.umd.cjs`) for video-only sites to reduce bundle size
-- Use **Audio** (`embed.audio.umd.cjs`) for audio-only sites (podcasts, music streaming)
+- Use **Audio** (`embed.audio.umd.cjs`) for audio-only sites (podcasts, music streaming). It is built on `hls.js/light`, so it cannot read ID3 timed metadata: see [Audio build: hls.js/light](#audio-build-hlsjslight)
 
 **Note:** Using a build without support for a player type will throw an error. For example, using the Video build and setting `data-type="audio"` will fail with a helpful error message.
 
@@ -337,13 +461,14 @@ const options: EmbedPlayerOptions = {
 
 ## Browser Support
 
-- Modern browsers (ES2020+)
-- Chrome/Edge 90+
-- Firefox 88+
+- Chrome / Edge 80+
+- Firefox 78+
 - Safari 14+
 - iOS Safari 14+
 - Android Chrome 90+
 
+All three bundles are built for ES2020.
+
 ## Keyboard Shortcuts
 
 When `data-keyboard` is enabled (default):
@@ -423,8 +548,9 @@ MIT
 
 ## Documentation
 
-For detailed implementation docs including Laravel integration, see:
-- [Embed Implementation Guide](../../.claude/docs/embed-implementation.md)
+- [Architecture](https://github.com/Hackney-Enterprises-Inc/scarlett-player/blob/main/docs/architecture.md)
+- [Plugin authoring](https://github.com/Hackney-Enterprises-Inc/scarlett-player/blob/main/docs/plugin-authoring.md)
+- Live demo: https://scarlettplayer.com
 
 ## Support
 

package/dist/create-embed.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Unified embed creator factory
+ *
+ * This module creates the embed API with configurable plugin availability.
+ * Each build (full, video, audio) uses this with different plugin sets.
+ */
+import { ScarlettPlayer, type Plugin } from '@scarlett-player/core';
+import type { EmbedConfig, PlayerType, ScarlettPlayerGlobal } from './types';
+/**
+ * Plugin creators that builds can provide.
+ *
+ * `hls` and `native` are the two provider plugins. They are not
+ * interchangeable and they are not alternatives: `PluginManager.selectProvider`
+ * walks the registered providers in registration order and takes the first
+ * whose `canPlay()` accepts the source, so a build that omits `native` answers
+ * `PROVIDER_NOT_FOUND` for every progressive file. That was the shipped
+ * behaviour up to 1.7.0: an `.mp3` or `.mp4` `data-src` failed in every embed
+ * build, including the audio one.
+ */
+export interface PluginCreators {
+    hls: () => Plugin;
+    /**
+     * Native media element provider (progressive MP4/WebM/MOV/MKV/OGV/M4V and
+     * MP3/WAV/OGG/FLAC/AAC/M4A/Opus/WebA). Optional so a build can still be
+     * assembled without it, but every shipped embed build passes it.
+     */
+    native?: () => Plugin;
+    videoUI?: (config: any) => Plugin;
+    audioUI?: (config: any) => Plugin;
+    analytics?: (config: any) => Plugin;
+    playlist?: (config: any) => Plugin;
+    mediaSession?: (config: any) => Plugin;
+    watermark?: (config: any) => Plugin;
+    captions?: (config: any) => Plugin;
+    /**
+     * Touch gestures: double-tap the sides to seek, tap to toggle the controls.
+     *
+     * Video builds only. The embed passes no config at all, because the plugin
+     * decides for itself whether to arm: its `enabled` default is `'auto'`,
+     * gated on `matchMedia('(any-pointer: coarse)')`, so it installs wherever a
+     * coarse pointer exists (a touchscreen laptop included) and a mouse still
+     * never triggers any of it. Forcing `enabled: true` here would instead put a
+     * gesture surface on a pure-mouse desktop with no touch to serve.
+     */
+    gestures?: (config: any) => Plugin;
+    /**
+     * Share sheet, copy link and embed codes.
+     *
+     * Video builds only, and only when the embed was given a share URL. The
+     * plugin contributes a control through `registerControl('share')` in
+     * `@scarlett-player/ui`, and the audio UIs render a fixed template with no
+     * control registry, so an audio player has nowhere to put the button.
+     */
+    share?: (config: any) => Plugin;
+}
+/**
+ * Create an embed player with the given plugins
+ */
+export declare function createEmbedPlayer(container: HTMLElement, config: Partial<EmbedConfig>, pluginCreators: PluginCreators, availableTypes: PlayerType[]): Promise<ScarlettPlayer | null>;
+/**
+ * Initialize a player from a DOM element with data attributes
+ */
+export declare function initElement(element: HTMLElement, pluginCreators: PluginCreators, availableTypes: PlayerType[]): Promise<ScarlettPlayer | null>;
+/**
+ * Initialize all players on the page
+ */
+export declare function initAll(pluginCreators: PluginCreators, availableTypes: PlayerType[]): Promise<void>;
+/**
+ * Create the global ScarlettPlayer API
+ */
+export declare function createScarlettPlayerAPI(pluginCreators: PluginCreators, availableTypes: PlayerType[], version: string): ScarlettPlayerGlobal;
+/**
+ * Setup auto-initialization on DOMContentLoaded
+ */
+export declare function setupAutoInit(pluginCreators: PluginCreators, availableTypes: PlayerType[]): void;
+//# sourceMappingURL=create-embed.d.ts.map

package/dist/create-embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-embed.d.ts","sourceRoot":"","sources":["../src/create-embed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAgB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAsB,UAAU,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGjG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACnC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACvC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;IACnC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC;CACjC;AAmCD;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,WAAW,EACtB,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAC5B,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,EAAE,GAC3B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAsKhC;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,EAAE,GAC3B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAehC;AAWD;;GAEG;AACH,wBAAsB,OAAO,CAC3B,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,EAAE,EAC5B,OAAO,EAAE,MAAM,GACd,oBAAoB,CAyBtB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,EAAE,GAC3B,IAAI,CAUN"}

package/dist/{hls2.js → embed.audio.index.js}

@@ -9,4 +9,4 @@ function registerControl(id, factory) {
 export {
   registerControl
 };
-//# sourceMappingURL=hls2.js.map
+//# sourceMappingURL=embed.audio.index.js.map