@dudgy/podcast-widget 0.1.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.
- package/README.md +347 -0
- package/dist/index.cjs +1088 -0
- package/dist/index.d.cts +342 -0
- package/dist/index.d.ts +342 -0
- package/dist/index.js +1088 -0
- package/dist/podcast-index.cjs +65 -0
- package/dist/podcast-index.d.cts +57 -0
- package/dist/podcast-index.d.ts +57 -0
- package/dist/podcast-index.js +65 -0
- package/dist/podcast-player.css +773 -0
- package/package.json +54 -0
package/README.md
ADDED
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
# podcast-widget
|
|
2
|
+
|
|
3
|
+
Framework-agnostic podcast player widget with configurable player modes, CSS custom property theming, and an optional PodcastIndex API client.
|
|
4
|
+
|
|
5
|
+
Zero runtime dependencies. Ships ESM + CJS with full TypeScript declarations.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install podcast-widget
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { AudioEngine, PlayerController, FetchEpisodeProvider, MiniPlayer, FullPlayer } from 'podcast-widget';
|
|
17
|
+
import 'podcast-widget/styles';
|
|
18
|
+
|
|
19
|
+
// 1. Create the core objects
|
|
20
|
+
const engine = new AudioEngine();
|
|
21
|
+
const provider = new FetchEpisodeProvider('/api/podcast-episodes', {
|
|
22
|
+
storagePrefix: 'podcast',
|
|
23
|
+
maxStoredPositions: 100,
|
|
24
|
+
positionSaveInterval: 5000,
|
|
25
|
+
skipSeconds: 30,
|
|
26
|
+
episodeCacheTTL: 3600000,
|
|
27
|
+
});
|
|
28
|
+
const controller = new PlayerController(engine, provider);
|
|
29
|
+
|
|
30
|
+
// 2. Create one or more player UIs
|
|
31
|
+
const mini = new MiniPlayer({
|
|
32
|
+
container: document.getElementById('mini-player')!,
|
|
33
|
+
controller,
|
|
34
|
+
controls: { playPause: true, progress: true, expand: true },
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
const full = new FullPlayer({
|
|
38
|
+
container: document.getElementById('full-player')!,
|
|
39
|
+
controller,
|
|
40
|
+
controls: { playPause: true, skipForward: true, skipBackward: true, volume: true, speed: true, progress: true, playlist: true },
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
// 3. Wire them together
|
|
44
|
+
mini.on('expand', () => full.show());
|
|
45
|
+
full.on('close', () => full.hide());
|
|
46
|
+
|
|
47
|
+
// 4. Load episodes
|
|
48
|
+
controller.loadEpisodes();
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Architecture
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
podcast-widget/
|
|
55
|
+
├── src/
|
|
56
|
+
│ ├── core/
|
|
57
|
+
│ │ ├── types.ts # Episode, PlayerConfig, events, EpisodeProvider interface
|
|
58
|
+
│ │ ├── event-emitter.ts # Lightweight typed event emitter
|
|
59
|
+
│ │ ├── audio-engine.ts # HTMLAudioElement wrapper with seek, destroy, error handling
|
|
60
|
+
│ │ ├── playback-storage.ts # localStorage for resume positions (namespaced keys)
|
|
61
|
+
│ │ ├── player-state.ts # localStorage for player state + speed preference
|
|
62
|
+
│ │ └── episode-provider.ts # FetchEpisodeProvider with caching + retry
|
|
63
|
+
│ ├── ui/
|
|
64
|
+
│ │ ├── utils.ts # formatTime, escapeHtml, getEpisodeImage
|
|
65
|
+
│ │ ├── html-templates.ts # SVG icons, playlist rendering, speed options
|
|
66
|
+
│ │ ├── player-controller.ts # Orchestrator: engine + storage + provider → events
|
|
67
|
+
│ │ ├── mini-player.ts # Mini mode with configurable controls + inline playlist
|
|
68
|
+
│ │ └── full-player.ts # Full modal with hero, playlist, keyboard shortcuts
|
|
69
|
+
│ ├── podcast-index/
|
|
70
|
+
│ │ ├── auth.ts # HMAC-SHA1 auth headers (server-only, uses Node crypto)
|
|
71
|
+
│ │ ├── client.ts # Typed PodcastIndexClient
|
|
72
|
+
│ │ └── index.ts # Barrel export
|
|
73
|
+
│ ├── styles/
|
|
74
|
+
│ │ └── podcast-player.css # Plain CSS with custom property theming (pw- prefix)
|
|
75
|
+
│ └── index.ts # Main barrel export
|
|
76
|
+
├── package.json # Dual ESM/CJS, subpath exports
|
|
77
|
+
├── tsconfig.json # Client-side TS config
|
|
78
|
+
├── tsconfig.server.json # Server-side (podcast-index) config
|
|
79
|
+
└── tsup.config.ts # Build config
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Player Modes
|
|
83
|
+
|
|
84
|
+
The package provides two player modes that can be used independently or together. Each mode accepts a `controls` config to toggle which controls are visible.
|
|
85
|
+
|
|
86
|
+
### Controls Config
|
|
87
|
+
|
|
88
|
+
All controls default to `false` (opt-in):
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
interface ControlsConfig {
|
|
92
|
+
playPause?: boolean;
|
|
93
|
+
skipForward?: boolean;
|
|
94
|
+
skipBackward?: boolean;
|
|
95
|
+
volume?: boolean;
|
|
96
|
+
speed?: boolean;
|
|
97
|
+
progress?: boolean;
|
|
98
|
+
playlist?: boolean; // Inline dropdown playlist (mini) or full playlist (full)
|
|
99
|
+
expand?: boolean; // Button to emit 'expand' event
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### MiniPlayer
|
|
104
|
+
|
|
105
|
+
Compact horizontal bar. Defaults: `playPause: true, progress: true`.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
const mini = new MiniPlayer({
|
|
109
|
+
container: document.getElementById('mini-player')!,
|
|
110
|
+
controller,
|
|
111
|
+
controls: {
|
|
112
|
+
playPause: true,
|
|
113
|
+
progress: true,
|
|
114
|
+
volume: true,
|
|
115
|
+
playlist: true, // Adds inline dropdown playlist
|
|
116
|
+
expand: true, // Adds expand button
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
mini.on('expand', () => { /* open full player, etc. */ });
|
|
121
|
+
mini.destroy(); // Cleanup when done
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### FullPlayer
|
|
125
|
+
|
|
126
|
+
Modal overlay with hero section (blurred artwork background), controls, and scrollable playlist. Defaults: all controls enabled.
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
const full = new FullPlayer({
|
|
130
|
+
container: document.getElementById('full-player')!,
|
|
131
|
+
backdrop: document.getElementById('backdrop'), // Optional separate backdrop element
|
|
132
|
+
controller,
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
full.show(); // Open modal
|
|
136
|
+
full.hide(); // Close modal
|
|
137
|
+
full.on('close', () => { /* cleanup, etc. */ });
|
|
138
|
+
full.destroy();
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Keyboard shortcuts** (when full player is visible):
|
|
142
|
+
- `Space` / `k` — play/pause
|
|
143
|
+
- `ArrowLeft` — skip backward
|
|
144
|
+
- `ArrowRight` — skip forward
|
|
145
|
+
- `Escape` — close
|
|
146
|
+
|
|
147
|
+
## Core API
|
|
148
|
+
|
|
149
|
+
### AudioEngine
|
|
150
|
+
|
|
151
|
+
Wraps `HTMLAudioElement` with typed events and proper cleanup.
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
const engine = new AudioEngine(30); // skip seconds (default: 30)
|
|
155
|
+
|
|
156
|
+
engine.load(url, startPosition?);
|
|
157
|
+
await engine.play();
|
|
158
|
+
engine.pause();
|
|
159
|
+
engine.stop();
|
|
160
|
+
engine.skipForward();
|
|
161
|
+
engine.skipBackward();
|
|
162
|
+
engine.seek(120); // Seek to 120 seconds
|
|
163
|
+
engine.seekToPercentage(50); // Seek to 50%
|
|
164
|
+
|
|
165
|
+
engine.volume = 0.8;
|
|
166
|
+
engine.playbackRate = 1.5;
|
|
167
|
+
|
|
168
|
+
engine.on('play', () => {});
|
|
169
|
+
engine.on('pause', ({ currentTime }) => {});
|
|
170
|
+
engine.on('time-update', ({ currentTime, duration, percentage }) => {});
|
|
171
|
+
engine.on('ended', () => {});
|
|
172
|
+
engine.on('error', ({ error, context }) => {});
|
|
173
|
+
|
|
174
|
+
engine.destroy(); // Removes all listeners, releases audio element
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### PlayerController
|
|
178
|
+
|
|
179
|
+
Orchestrates AudioEngine, PlaybackStorage, and EpisodeProvider. Manages episode state, resume positions, and player preferences.
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
const controller = new PlayerController(engine, provider, {
|
|
183
|
+
storagePrefix: 'podcast', // localStorage key prefix (default: "podcast")
|
|
184
|
+
maxStoredPositions: 100, // Max saved resume positions (default: 100)
|
|
185
|
+
positionSaveInterval: 5000, // Save interval in ms (default: 5000)
|
|
186
|
+
skipSeconds: 30, // Skip amount (default: 30)
|
|
187
|
+
episodeCacheTTL: 3600000, // Cache TTL in ms (default: 1 hour)
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
await controller.loadEpisodes();
|
|
191
|
+
controller.loadEpisode(0); // Load without playing
|
|
192
|
+
controller.playEpisode(2); // Load and play
|
|
193
|
+
controller.setSpeed(1.5);
|
|
194
|
+
controller.setVolume(0.8);
|
|
195
|
+
|
|
196
|
+
controller.on('episode-change', ({ episode, index }) => {});
|
|
197
|
+
controller.on('episodes-loaded', ({ episodes }) => {});
|
|
198
|
+
controller.on('episode-display', ({ imageUrl, title, show }) => {});
|
|
199
|
+
|
|
200
|
+
controller.destroy();
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### EpisodeProvider
|
|
204
|
+
|
|
205
|
+
Interface for loading episodes. The package ships `FetchEpisodeProvider` which fetches from a URL with caching and retry.
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
// Use the built-in fetch provider
|
|
209
|
+
const provider = new FetchEpisodeProvider('/api/episodes', resolvedConfig);
|
|
210
|
+
|
|
211
|
+
// Or implement your own
|
|
212
|
+
const customProvider: EpisodeProvider = {
|
|
213
|
+
async getEpisodes() {
|
|
214
|
+
return [
|
|
215
|
+
{ id: '1', feedId: 123, feedName: 'My Show', title: 'Ep 1', audioUrl: '...', pubDate: '...' },
|
|
216
|
+
];
|
|
217
|
+
},
|
|
218
|
+
};
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
The `FetchEpisodeProvider` expects the endpoint to return `{ episodes: Episode[] }`.
|
|
222
|
+
|
|
223
|
+
### Episode Interface
|
|
224
|
+
|
|
225
|
+
```typescript
|
|
226
|
+
interface Episode {
|
|
227
|
+
id: string;
|
|
228
|
+
feedId: number;
|
|
229
|
+
feedName: string;
|
|
230
|
+
title: string;
|
|
231
|
+
audioUrl: string;
|
|
232
|
+
pubDate: string;
|
|
233
|
+
pubDateTime?: string;
|
|
234
|
+
pubTimestamp?: number;
|
|
235
|
+
duration?: number;
|
|
236
|
+
image?: string;
|
|
237
|
+
feedImage?: string;
|
|
238
|
+
artwork?: string;
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## CSS Theming
|
|
243
|
+
|
|
244
|
+
Import the styles:
|
|
245
|
+
|
|
246
|
+
```typescript
|
|
247
|
+
import 'podcast-widget/styles';
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Or link directly:
|
|
251
|
+
|
|
252
|
+
```html
|
|
253
|
+
<link rel="stylesheet" href="node_modules/podcast-widget/dist/podcast-player.css">
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Define these CSS custom properties on a parent element to theme the player:
|
|
257
|
+
|
|
258
|
+
```css
|
|
259
|
+
.my-player-wrapper {
|
|
260
|
+
--player-surface: #002b36; /* Player background */
|
|
261
|
+
--player-surface-variant: #073642; /* Secondary background */
|
|
262
|
+
--player-on-surface: #839496; /* Primary text */
|
|
263
|
+
--player-on-surface-variant: #657b83; /* Secondary text */
|
|
264
|
+
--player-on-surface-rgb: 131, 148, 150; /* RGB triplet for rgba() overlays */
|
|
265
|
+
--player-outline: #586e75; /* Borders */
|
|
266
|
+
--player-outline-variant: #073642; /* Subtle borders */
|
|
267
|
+
--md-primary: #268bd2; /* Accent (play button, active episode) */
|
|
268
|
+
--md-on-primary: #fdf6e3; /* Text on accent */
|
|
269
|
+
--md-secondary: #2aa198; /* Secondary accent (saved position) */
|
|
270
|
+
--md-on-secondary: #fdf6e3; /* Text on secondary accent */
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
All CSS classes use the `pw-` prefix to avoid collisions.
|
|
275
|
+
|
|
276
|
+
## PodcastIndex Client (Server-Only)
|
|
277
|
+
|
|
278
|
+
Separate subpath export for server-side use. Uses Node's `crypto` module for HMAC-SHA1 auth — not included in the browser bundle.
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
import { PodcastIndexClient } from 'podcast-widget/podcast-index';
|
|
282
|
+
|
|
283
|
+
const client = new PodcastIndexClient(API_KEY, API_SECRET);
|
|
284
|
+
|
|
285
|
+
const episodes = await client.getEpisodes(feedId, 10);
|
|
286
|
+
const latest = await client.getLatestEpisode(feedId);
|
|
287
|
+
const feed = await client.getFeedInfo(feedId);
|
|
288
|
+
const results = await client.search('javascript');
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
You can also use the auth headers directly:
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
import { createPodcastIndexHeaders } from 'podcast-widget/podcast-index';
|
|
295
|
+
|
|
296
|
+
const headers = createPodcastIndexHeaders(apiKey, apiSecret);
|
|
297
|
+
// { 'X-Auth-Key': '...', 'X-Auth-Date': '...', Authorization: '...', 'User-Agent': '...' }
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## Local Development
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
npm run build # Build
|
|
304
|
+
npm run dev # Build + watch
|
|
305
|
+
npm run typecheck # Type check
|
|
306
|
+
npm test # Run tests
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Testing in a Consumer Before Publishing
|
|
310
|
+
|
|
311
|
+
```bash
|
|
312
|
+
cd /path/to/podcast-widget
|
|
313
|
+
npm run build
|
|
314
|
+
npm link
|
|
315
|
+
|
|
316
|
+
cd /path/to/my-site
|
|
317
|
+
npm link podcast-widget
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
Now `import ... from 'podcast-widget'` resolves to your local build. Run `npm run build` in podcast-widget after changes and the consumer picks them up immediately.
|
|
321
|
+
|
|
322
|
+
When done:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
cd /path/to/my-site
|
|
326
|
+
npm unlink podcast-widget
|
|
327
|
+
npm install
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
## Publishing
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
npm login # First time only
|
|
334
|
+
npm publish
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Version bumping:
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
npm version patch # 0.1.0 → 0.1.1 (bug fixes)
|
|
341
|
+
npm version minor # 0.1.1 → 0.2.0 (new features)
|
|
342
|
+
npm version major # 0.2.0 → 1.0.0 (breaking changes)
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
## License
|
|
346
|
+
|
|
347
|
+
MIT
|