@scarlett-player/embed 0.2.0 → 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 (30) hide show
  1. package/README.md +135 -114
  2. package/dist/embed.audio.js +4251 -4051
  3. package/dist/embed.audio.js.map +1 -1
  4. package/dist/embed.audio.umd.cjs +1 -1
  5. package/dist/embed.audio.umd.cjs.map +1 -1
  6. package/dist/embed.js +6198 -4185
  7. package/dist/embed.js.map +1 -1
  8. package/dist/embed.umd.cjs +1 -1
  9. package/dist/embed.umd.cjs.map +1 -1
  10. package/dist/{embed.light.js → embed.video.js} +4060 -3935
  11. package/dist/embed.video.js.map +1 -0
  12. package/dist/embed.video.umd.cjs +2 -0
  13. package/dist/embed.video.umd.cjs.map +1 -0
  14. package/dist/{hls-BI8mYU47.js → hls.js} +1 -1
  15. package/dist/hls.js.map +1 -0
  16. package/package.json +14 -26
  17. package/dist/embed.audio.light.js +0 -4338
  18. package/dist/embed.audio.light.js.map +0 -1
  19. package/dist/embed.audio.light.umd.cjs +0 -2
  20. package/dist/embed.audio.light.umd.cjs.map +0 -1
  21. package/dist/embed.full.js +0 -5835
  22. package/dist/embed.full.js.map +0 -1
  23. package/dist/embed.full.umd.cjs +0 -2
  24. package/dist/embed.full.umd.cjs.map +0 -1
  25. package/dist/embed.light.js.map +0 -1
  26. package/dist/embed.light.umd.cjs +0 -2
  27. package/dist/embed.light.umd.cjs.map +0 -1
  28. package/dist/hls-BI8mYU47.js.map +0 -1
  29. package/dist/hls.light-YJMge-Mx.js +0 -21849
  30. package/dist/hls.light-YJMge-Mx.js.map +0 -1
package/README.md CHANGED
@@ -9,31 +9,22 @@ 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
15
16
 
16
17
  ### CDN Usage (Recommended for Embeds)
17
18
 
18
- **Video Player:**
19
19
  ```html
20
- <!-- Standard video player -->
20
+ <!-- Full build (video + audio + all plugins) -->
21
21
  <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.umd.cjs"></script>
22
22
 
23
- <!-- Light build (~30% smaller, no subtitles/DRM/ID3) -->
24
- <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.light.umd.cjs"></script>
23
+ <!-- Video-only build (lightweight) -->
24
+ <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.video.umd.cjs"></script>
25
25
 
26
- <!-- Full build (includes analytics, playlist, media-session) -->
27
- <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.full.umd.cjs"></script>
28
- ```
29
-
30
- **Audio Player:**
31
- ```html
32
- <!-- Audio player (compact UI, lock screen controls, playlists) -->
26
+ <!-- Audio-only build (audio + playlist + media-session) -->
33
27
  <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.audio.umd.cjs"></script>
34
-
35
- <!-- Light audio (~30% smaller) -->
36
- <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.audio.light.umd.cjs"></script>
37
28
  ```
38
29
 
39
30
  ### NPM Installation
@@ -57,13 +48,31 @@ The simplest way to embed a player. Just add the script and use data attributes:
57
48
  <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.umd.cjs"></script>
58
49
  </head>
59
50
  <body>
60
- <!-- Basic player -->
51
+ <!-- Video player (default) -->
61
52
  <div
62
53
  data-scarlett-player
63
54
  data-src="https://example.com/stream.m3u8"
64
55
  ></div>
65
56
 
66
- <!-- 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 -->
67
76
  <div
68
77
  data-scarlett-player
69
78
  data-src="https://example.com/stream.m3u8"
@@ -81,10 +90,11 @@ The simplest way to embed a player. Just add the script and use data attributes:
81
90
 
82
91
  | Attribute | Type | Default | Description |
83
92
  |-----------|------|---------|-------------|
84
- | `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` |
85
95
  | `data-autoplay` | boolean | `false` | Auto-play on load |
86
96
  | `data-muted` | boolean | `false` | Start muted |
87
- | `data-poster` | string | - | Poster image URL |
97
+ | `data-poster` | string | - | Poster/artwork image URL |
88
98
  | `data-controls` | boolean | `true` | Show/hide UI controls |
89
99
  | `data-brand-color` | string | - | Accent color (e.g., `#e50914`) |
90
100
  | `data-primary-color` | string | - | Primary UI color |
@@ -99,6 +109,15 @@ The simplest way to embed a player. Just add the script and use data attributes:
99
109
  | `data-start-time` | number | `0` | Start position (seconds) |
100
110
  | `data-class` | string | - | Custom CSS class(es) |
101
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
+
102
121
  ### 2. Programmatic API
103
122
 
104
123
  For dynamic player creation:
@@ -109,8 +128,8 @@ For dynamic player creation:
109
128
  <div id="my-player"></div>
110
129
 
111
130
  <script>
112
- // Create player programmatically
113
- const player = ScarlettPlayer.create({
131
+ // Create video player
132
+ const videoPlayer = await ScarlettPlayer.create({
114
133
  container: '#my-player',
115
134
  src: 'https://example.com/stream.m3u8',
116
135
  autoplay: true,
@@ -119,14 +138,39 @@ For dynamic player creation:
119
138
  aspectRatio: '16:9',
120
139
  });
121
140
 
122
- // Access player methods
123
- player.play();
124
- player.pause();
125
- 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
+ });
126
170
  </script>
127
171
  ```
128
172
 
129
- #### Global API Methods
173
+ #### Global API
130
174
 
131
175
  ```typescript
132
176
  // Initialize all players on page
@@ -137,6 +181,9 @@ ScarlettPlayer.create(options);
137
181
 
138
182
  // Check version
139
183
  console.log(ScarlettPlayer.version);
184
+
185
+ // Check available player types in this build
186
+ console.log(ScarlettPlayer.availableTypes); // ['video', 'audio', 'audio-mini']
140
187
  ```
141
188
 
142
189
  ### 3. iframe Embed
@@ -154,6 +201,15 @@ For secure, sandboxed embeds:
154
201
  allow="autoplay; fullscreen; picture-in-picture"
155
202
  ></iframe>
156
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
+
157
213
  <!-- With customization -->
158
214
  <iframe
159
215
  src="https://assets.thestreamplatform.com/scarlett-player/latest/iframe.html?src=https://example.com/stream.m3u8&autoplay=true&muted=true&brand-color=%23e50914"
@@ -169,67 +225,36 @@ For secure, sandboxed embeds:
169
225
 
170
226
  All data attributes work as URL parameters (use kebab-case):
171
227
  - `src` (required)
228
+ - `type` - `video`, `audio`, or `audio-mini`
172
229
  - `autoplay`, `muted`, `loop`
173
230
  - `poster`
174
231
  - `brand-color`, `primary-color`, `background-color`
175
232
 
176
- ### 4. Audio Player
233
+ ## Player Types
177
234
 
178
- For audio streaming (podcasts, music, live audio):
179
-
180
- ```html
181
- <script src="https://assets.thestreamplatform.com/scarlett-player/latest/embed.audio.umd.cjs"></script>
235
+ ### Video Player (default)
182
236
 
183
- <!-- Basic audio player -->
184
- <div
185
- data-scarlett-audio
186
- data-src="https://example.com/podcast.m3u8"
187
- data-title="Episode 1: Introduction"
188
- data-artist="My Podcast"
189
- ></div>
237
+ Standard video player with full controls, fullscreen, picture-in-picture support.
190
238
 
191
- <!-- Compact audio player -->
192
- <div
193
- data-scarlett-audio
194
- data-src="https://example.com/music.m3u8"
195
- data-compact
196
- data-title="Song Title"
197
- data-artist="Artist Name"
198
- data-artwork="https://example.com/album-art.jpg"
199
- ></div>
239
+ ```html
240
+ <div data-scarlett-player data-src="video.m3u8"></div>
200
241
  ```
201
242
 
202
- #### Audio Programmatic API
243
+ ### Audio Player
203
244
 
204
- ```javascript
205
- // Audio uses ScarlettAudio global
206
- const player = await ScarlettAudio.create({
207
- container: '#audio-player',
208
- src: 'https://example.com/stream.m3u8',
209
- title: 'Track Title',
210
- artist: 'Artist Name',
211
- artwork: 'https://example.com/artwork.jpg',
212
- compact: true,
213
- // Playlist support
214
- playlist: [
215
- { src: 'track1.m3u8', title: 'Track 1', artist: 'Artist' },
216
- { src: 'track2.m3u8', title: 'Track 2', artist: 'Artist' },
217
- ],
218
- });
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>
219
249
  ```
220
250
 
221
- #### Audio Data Attributes
251
+ ### Compact Audio Player
222
252
 
223
- | Attribute | Type | Description |
224
- |-----------|------|-------------|
225
- | `data-src` | string | Audio source URL (HLS .m3u8) |
226
- | `data-title` | string | Track/episode title |
227
- | `data-artist` | string | Artist/creator name |
228
- | `data-album` | string | Album name |
229
- | `data-artwork` | string | Album art / cover image URL |
230
- | `data-compact` | boolean | Use compact layout |
231
- | `data-brand-color` | string | Accent color |
232
- | `data-playlist` | JSON | Playlist as JSON array |
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
+ ```
233
258
 
234
259
  ## Multi-Tenant Branding
235
260
 
@@ -253,43 +278,23 @@ Perfect for The Stream Platform's white-label needs:
253
278
  ></div>
254
279
  ```
255
280
 
256
- ## Build Output
281
+ ## CDN Builds
257
282
 
258
- After building, you'll get:
259
-
260
- ```
261
- dist/
262
- ├── embed.js # ES module - standard video
263
- ├── embed.umd.cjs # UMD - standard video (~177KB gzip)
264
- ├── embed.light.js # ES module - light video
265
- ├── embed.light.umd.cjs # UMD - light video (~124KB gzip)
266
- ├── embed.full.js # ES module - all plugins
267
- ├── embed.full.umd.cjs # UMD - all plugins (~183KB gzip)
268
- ├── embed.audio.js # ES module - audio player
269
- ├── embed.audio.umd.cjs # UMD - audio player (~175KB gzip)
270
- ├── embed.audio.light.js # ES module - light audio
271
- ├── embed.audio.light.umd.cjs # UMD - light audio (~122KB gzip)
272
- ├── hls-*.js # HLS.js chunk (ESM only)
273
- ├── hls.light-*.js # HLS.js light chunk (ESM only)
274
- └── *.map # Source maps
275
- ```
283
+ All builds are available at `https://assets.thestreamplatform.com/scarlett-player/latest/`
276
284
 
277
- ### Bundle Variants
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 |
278
290
 
279
- **Video Players:**
280
- | Variant | Size (gzip) | Features |
281
- |---------|-------------|----------|
282
- | `embed.umd.cjs` | ~177KB | Standard: core + HLS + UI |
283
- | `embed.light.umd.cjs` | ~124KB | Light: HLS light (no subtitles/DRM/ID3) |
284
- | `embed.full.umd.cjs` | ~183KB | Full: + analytics, playlist, media-session |
291
+ **Which build should I use?**
285
292
 
286
- **Audio Players:**
287
- | Variant | Size (gzip) | Features |
288
- |---------|-------------|----------|
289
- | `embed.audio.umd.cjs` | ~175KB | Audio: core + HLS + audio-ui + media-session + playlist |
290
- | `embed.audio.light.umd.cjs` | ~122KB | Light Audio: with HLS light |
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)
291
296
 
292
- Use light variants for most streaming use cases to reduce load time by ~30%.
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.
293
298
 
294
299
  ## Development
295
300
 
@@ -303,6 +308,9 @@ pnpm build
303
308
  # Run in dev mode
304
309
  pnpm dev
305
310
 
311
+ # Run tests
312
+ pnpm test
313
+
306
314
  # Type checking
307
315
  pnpm typecheck
308
316
 
@@ -315,16 +323,15 @@ pnpm clean
315
323
  Full TypeScript support when using as a module:
316
324
 
317
325
  ```typescript
318
- import { create, type EmbedPlayerOptions } from '@scarlett-player/embed';
326
+ import type { EmbedPlayerOptions, PlayerType } from '@scarlett-player/embed';
319
327
 
320
328
  const options: EmbedPlayerOptions = {
321
329
  container: '#player',
322
330
  src: 'https://example.com/stream.m3u8',
331
+ type: 'video' as PlayerType,
323
332
  autoplay: true,
324
333
  brandColor: '#e50914',
325
334
  };
326
-
327
- const player = create(options);
328
335
  ```
329
336
 
330
337
  ## Browser Support
@@ -348,7 +355,7 @@ When `data-keyboard` is enabled (default):
348
355
 
349
356
  ## Examples
350
357
 
351
- ### Responsive Player
358
+ ### Responsive Video Player
352
359
 
353
360
  ```html
354
361
  <div
@@ -383,15 +390,29 @@ When `data-keyboard` is enabled (default):
383
390
  ></div>
384
391
  ```
385
392
 
386
- ### Controls Hidden (Audio-only)
393
+ ### Podcast Player
387
394
 
388
395
  ```html
389
396
  <div
390
397
  data-scarlett-player
391
- data-src="https://example.com/audio.m3u8"
392
- data-controls="false"
393
- data-autoplay
394
- 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"
395
416
  ></div>
396
417
  ```
397
418