@scarlett-player/embed 0.1.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +155 -40
  3. package/dist/embed.audio.js +4554 -0
  4. package/dist/embed.audio.js.map +1 -0
  5. package/dist/embed.audio.umd.cjs +2 -0
  6. package/dist/embed.audio.umd.cjs.map +1 -0
  7. package/dist/embed.js +6218 -4210
  8. package/dist/embed.js.map +1 -1
  9. package/dist/embed.umd.cjs +1 -1
  10. package/dist/embed.umd.cjs.map +1 -1
  11. package/dist/embed.video.js +4736 -0
  12. package/dist/embed.video.js.map +1 -0
  13. package/dist/embed.video.umd.cjs +2 -0
  14. package/dist/embed.video.umd.cjs.map +1 -0
  15. package/dist/{hls-BI8mYU47.js → hls.js} +1 -1
  16. package/dist/hls.js.map +1 -0
  17. package/package.json +31 -16
  18. package/dist/hls-BI8mYU47.js.map +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Hackney Enterprises Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -9,6 +9,7 @@ Standalone, CDN-ready embed package for Scarlett Player. Drop in a single `<scri
9
9
  - **Data Attributes** - Configure players via HTML attributes
10
10
  - **Global API** - Programmatic control via `window.ScarlettPlayer`
11
11
  - **Multi-tenant Ready** - Brand customization via data attributes
12
+ - **Unified API** - Single API for video, audio, and compact audio players
12
13
  - **iframe Support** - Helper page for URL-based iframe embeds
13
14
 
14
15
  ## Installation
@@ -16,11 +17,14 @@ Standalone, CDN-ready embed package for Scarlett Player. Drop in a single `<scri
16
17
  ### CDN Usage (Recommended for Embeds)
17
18
 
18
19
  ```html
19
- <!-- UMD Bundle (works everywhere) -->
20
- <script src="https://cdn.example.com/scarlett-player/embed.umd.cjs"></script>
20
+ <!-- Full build (video + audio + all plugins) -->
21
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.umd.cjs"></script>
21
22
 
22
- <!-- ES Module (for modern browsers) -->
23
- <script type="module" src="https://cdn.example.com/scarlett-player/embed.js"></script>
23
+ <!-- Video-only build (lightweight) -->
24
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.video.umd.cjs"></script>
25
+
26
+ <!-- Audio-only build (audio + playlist + media-session) -->
27
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.audio.umd.cjs"></script>
24
28
  ```
25
29
 
26
30
  ### NPM Installation
@@ -41,16 +45,34 @@ The simplest way to embed a player. Just add the script and use data attributes:
41
45
  <!DOCTYPE html>
42
46
  <html>
43
47
  <head>
44
- <script src="https://cdn.example.com/scarlett-player/embed.umd.cjs"></script>
48
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.umd.cjs"></script>
45
49
  </head>
46
50
  <body>
47
- <!-- Basic player -->
51
+ <!-- Video player (default) -->
48
52
  <div
49
53
  data-scarlett-player
50
54
  data-src="https://example.com/stream.m3u8"
51
55
  ></div>
52
56
 
53
- <!-- Customized player -->
57
+ <!-- Audio player -->
58
+ <div
59
+ data-scarlett-player
60
+ data-src="https://example.com/podcast.m3u8"
61
+ data-type="audio"
62
+ data-title="Episode 1: Introduction"
63
+ data-artist="My Podcast"
64
+ ></div>
65
+
66
+ <!-- Compact audio player -->
67
+ <div
68
+ data-scarlett-player
69
+ data-src="https://example.com/music.m3u8"
70
+ data-type="audio-mini"
71
+ data-title="Song Title"
72
+ data-artist="Artist Name"
73
+ ></div>
74
+
75
+ <!-- Customized video player -->
54
76
  <div
55
77
  data-scarlett-player
56
78
  data-src="https://example.com/stream.m3u8"
@@ -68,10 +90,11 @@ The simplest way to embed a player. Just add the script and use data attributes:
68
90
 
69
91
  | Attribute | Type | Default | Description |
70
92
  |-----------|------|---------|-------------|
71
- | `data-src` | string | **required** | Video source URL (HLS .m3u8) |
93
+ | `data-src` | string | **required** | Media source URL (HLS .m3u8) |
94
+ | `data-type` | string | `video` | Player type: `video`, `audio`, or `audio-mini` |
72
95
  | `data-autoplay` | boolean | `false` | Auto-play on load |
73
96
  | `data-muted` | boolean | `false` | Start muted |
74
- | `data-poster` | string | - | Poster image URL |
97
+ | `data-poster` | string | - | Poster/artwork image URL |
75
98
  | `data-controls` | boolean | `true` | Show/hide UI controls |
76
99
  | `data-brand-color` | string | - | Accent color (e.g., `#e50914`) |
77
100
  | `data-primary-color` | string | - | Primary UI color |
@@ -86,18 +109,27 @@ The simplest way to embed a player. Just add the script and use data attributes:
86
109
  | `data-start-time` | number | `0` | Start position (seconds) |
87
110
  | `data-class` | string | - | Custom CSS class(es) |
88
111
 
112
+ #### Audio-specific Attributes
113
+
114
+ | Attribute | Type | Description |
115
+ |-----------|------|-------------|
116
+ | `data-title` | string | Track/episode title |
117
+ | `data-artist` | string | Artist/creator name |
118
+ | `data-album` | string | Album name |
119
+ | `data-artwork` | string | Album art / cover image URL |
120
+
89
121
  ### 2. Programmatic API
90
122
 
91
123
  For dynamic player creation:
92
124
 
93
125
  ```html
94
- <script src="https://cdn.example.com/scarlett-player/embed.umd.cjs"></script>
126
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.umd.cjs"></script>
95
127
 
96
128
  <div id="my-player"></div>
97
129
 
98
130
  <script>
99
- // Create player programmatically
100
- const player = ScarlettPlayer.create({
131
+ // Create video player
132
+ const videoPlayer = await ScarlettPlayer.create({
101
133
  container: '#my-player',
102
134
  src: 'https://example.com/stream.m3u8',
103
135
  autoplay: true,
@@ -106,14 +138,39 @@ For dynamic player creation:
106
138
  aspectRatio: '16:9',
107
139
  });
108
140
 
109
- // Access player methods
110
- player.play();
111
- player.pause();
112
- player.setVolume(0.5);
141
+ // Create audio player
142
+ const audioPlayer = await ScarlettPlayer.create({
143
+ container: '#audio-player',
144
+ src: 'https://example.com/podcast.m3u8',
145
+ type: 'audio',
146
+ title: 'Episode Title',
147
+ artist: 'Podcast Name',
148
+ artwork: 'https://example.com/artwork.jpg',
149
+ });
150
+
151
+ // Create compact audio player
152
+ const miniPlayer = await ScarlettPlayer.create({
153
+ container: '#mini-player',
154
+ src: 'https://example.com/music.m3u8',
155
+ type: 'audio-mini',
156
+ title: 'Song Title',
157
+ artist: 'Artist Name',
158
+ });
159
+
160
+ // With playlist
161
+ const playlistPlayer = await ScarlettPlayer.create({
162
+ container: '#playlist-player',
163
+ src: 'track1.m3u8',
164
+ type: 'audio',
165
+ playlist: [
166
+ { src: 'track1.m3u8', title: 'Track 1', artist: 'Artist' },
167
+ { src: 'track2.m3u8', title: 'Track 2', artist: 'Artist' },
168
+ ],
169
+ });
113
170
  </script>
114
171
  ```
115
172
 
116
- #### Global API Methods
173
+ #### Global API
117
174
 
118
175
  ```typescript
119
176
  // Initialize all players on page
@@ -124,6 +181,9 @@ ScarlettPlayer.create(options);
124
181
 
125
182
  // Check version
126
183
  console.log(ScarlettPlayer.version);
184
+
185
+ // Check available player types in this build
186
+ console.log(ScarlettPlayer.availableTypes); // ['video', 'audio', 'audio-mini']
127
187
  ```
128
188
 
129
189
  ### 3. iframe Embed
@@ -133,7 +193,7 @@ For secure, sandboxed embeds:
133
193
  ```html
134
194
  <!-- Basic iframe embed -->
135
195
  <iframe
136
- src="https://cdn.example.com/scarlett-player/iframe.html?src=https://example.com/stream.m3u8"
196
+ src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/stream.m3u8"
137
197
  width="640"
138
198
  height="360"
139
199
  frameborder="0"
@@ -141,9 +201,18 @@ For secure, sandboxed embeds:
141
201
  allow="autoplay; fullscreen; picture-in-picture"
142
202
  ></iframe>
143
203
 
204
+ <!-- Audio player iframe -->
205
+ <iframe
206
+ src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/audio.m3u8&type=audio"
207
+ width="100%"
208
+ height="120"
209
+ frameborder="0"
210
+ allow="autoplay"
211
+ ></iframe>
212
+
144
213
  <!-- With customization -->
145
214
  <iframe
146
- src="https://cdn.example.com/scarlett-player/iframe.html?src=https://example.com/stream.m3u8&autoplay=true&muted=true&brand-color=%23e50914"
215
+ src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/stream.m3u8&autoplay=true&muted=true&brand-color=%23e50914"
147
216
  width="100%"
148
217
  height="100%"
149
218
  frameborder="0"
@@ -156,11 +225,36 @@ For secure, sandboxed embeds:
156
225
 
157
226
  All data attributes work as URL parameters (use kebab-case):
158
227
  - `src` (required)
228
+ - `type` - `video`, `audio`, or `audio-mini`
159
229
  - `autoplay`, `muted`, `loop`
160
230
  - `poster`
161
231
  - `brand-color`, `primary-color`, `background-color`
162
- - `hide-delay`, `playback-rate`, `start-time`
163
- - `controls` (set to `false` to hide)
232
+
233
+ ## Player Types
234
+
235
+ ### Video Player (default)
236
+
237
+ Standard video player with full controls, fullscreen, picture-in-picture support.
238
+
239
+ ```html
240
+ <div data-scarlett-player data-src="video.m3u8"></div>
241
+ ```
242
+
243
+ ### Audio Player
244
+
245
+ Full-sized audio player with waveform, track info, and media session integration.
246
+
247
+ ```html
248
+ <div data-scarlett-player data-src="audio.m3u8" data-type="audio"></div>
249
+ ```
250
+
251
+ ### Compact Audio Player
252
+
253
+ Minimal audio player for space-constrained layouts (64px height).
254
+
255
+ ```html
256
+ <div data-scarlett-player data-src="audio.m3u8" data-type="audio-mini"></div>
257
+ ```
164
258
 
165
259
  ## Multi-Tenant Branding
166
260
 
@@ -184,18 +278,23 @@ Perfect for The Stream Platform's white-label needs:
184
278
  ></div>
185
279
  ```
186
280
 
187
- ## Build Output
281
+ ## CDN Builds
188
282
 
189
- After building, you'll get:
283
+ All builds are available at `https://assets.thestreamplatform.com/scarlett-player/latest/`
190
284
 
191
- ```
192
- dist/
193
- ├── embed.js # ES module
194
- ├── embed.umd.cjs # UMD bundle (for script tags)
195
- ├── embed.d.ts # TypeScript definitions
196
- ├── embed.js.map # Source map
197
- └── embed.umd.cjs.map # Source map for UMD
198
- ```
285
+ | Build | Files | Features |
286
+ |-------|-------|----------|
287
+ | **Full** | `embed.js` / `embed.umd.cjs` | Video + Audio + Analytics + Playlist + Media Session |
288
+ | **Video** | `embed.video.js` / `embed.video.umd.cjs` | Video player only (lightweight) |
289
+ | **Audio** | `embed.audio.js` / `embed.audio.umd.cjs` | Audio + Playlist + Media Session |
290
+
291
+ **Which build should I use?**
292
+
293
+ - Use **Full** (`embed.umd.cjs`) if you need both video and audio, or want analytics
294
+ - Use **Video** (`embed.video.umd.cjs`) for video-only sites to reduce bundle size
295
+ - Use **Audio** (`embed.audio.umd.cjs`) for audio-only sites (podcasts, music streaming)
296
+
297
+ **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.
199
298
 
200
299
  ## Development
201
300
 
@@ -209,6 +308,9 @@ pnpm build
209
308
  # Run in dev mode
210
309
  pnpm dev
211
310
 
311
+ # Run tests
312
+ pnpm test
313
+
212
314
  # Type checking
213
315
  pnpm typecheck
214
316
 
@@ -221,16 +323,15 @@ pnpm clean
221
323
  Full TypeScript support when using as a module:
222
324
 
223
325
  ```typescript
224
- import { create, type EmbedPlayerOptions } from '@scarlett-player/embed';
326
+ import type { EmbedPlayerOptions, PlayerType } from '@scarlett-player/embed';
225
327
 
226
328
  const options: EmbedPlayerOptions = {
227
329
  container: '#player',
228
330
  src: 'https://example.com/stream.m3u8',
331
+ type: 'video' as PlayerType,
229
332
  autoplay: true,
230
333
  brandColor: '#e50914',
231
334
  };
232
-
233
- const player = create(options);
234
335
  ```
235
336
 
236
337
  ## Browser Support
@@ -254,7 +355,7 @@ When `data-keyboard` is enabled (default):
254
355
 
255
356
  ## Examples
256
357
 
257
- ### Responsive Player
358
+ ### Responsive Video Player
258
359
 
259
360
  ```html
260
361
  <div
@@ -289,15 +390,29 @@ When `data-keyboard` is enabled (default):
289
390
  ></div>
290
391
  ```
291
392
 
292
- ### Controls Hidden (Audio-only)
393
+ ### Podcast Player
293
394
 
294
395
  ```html
295
396
  <div
296
397
  data-scarlett-player
297
- data-src="https://example.com/audio.m3u8"
298
- data-controls="false"
299
- data-autoplay
300
- data-height="50px"
398
+ data-src="https://example.com/podcast.m3u8"
399
+ data-type="audio"
400
+ data-title="Episode 42: Deep Dive"
401
+ data-artist="Tech Podcast"
402
+ data-artwork="https://example.com/podcast-cover.jpg"
403
+ ></div>
404
+ ```
405
+
406
+ ### Music Player (Compact)
407
+
408
+ ```html
409
+ <div
410
+ data-scarlett-player
411
+ data-src="https://example.com/track.m3u8"
412
+ data-type="audio-mini"
413
+ data-title="Great Song"
414
+ data-artist="Awesome Artist"
415
+ data-brand-color="#1DB954"
301
416
  ></div>
302
417
  ```
303
418