@scarlett-player/embed 1.8.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
 
@@ -136,7 +137,7 @@ The simplest way to embed a player. Just add the script and use data attributes:
 | `data-controls` | boolean | `true` | Show/hide UI controls |
 | `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-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) |
@@ -148,6 +149,8 @@ The simplest way to embed a player. Just add the script and use data attributes:
 | `data-playback-rate` | number | `1.0` | Playback speed |
 | `data-start-time` | number | `0` | Start position (seconds) |
 | `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
 
@@ -157,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
 
@@ -254,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"
@@ -276,13 +281,29 @@ 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
 
@@ -298,7 +319,7 @@ Takes an HLS manifest or a progressive video file.
 
 ### 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
@@ -314,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:
@@ -342,9 +409,9 @@ 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, on `hls.js/light` (no ID3) |
+| **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?**
 
@@ -394,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):
@@ -480,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

@@ -43,6 +43,15 @@ export interface PluginCreators {
      * 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

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

@@ -1 +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;CACpC;AAED;;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,CA4IhC;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"}
+{"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"}