Ollie Taylor
191 lines
6.1 KiB
Markdown
191 lines
6.1 KiB
Markdown
# Svelte Podcast
|
||
|
||
A collection of tools for building podcast websites and tools with Svelte or SvelteKit.
|
||
|
||
| Version | License | Status |
|
||
| :-------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------: |
|
||
| [](https://www.npmjs.com/package/svelte-podcast) | [](https://www.npmjs.com/package/svelte-podcast) |  |
|
||
|
||
## What's inside?
|
||
|
||
- 🔊 Load and play audio files via URL or local files
|
||
- 🔃 Navigate via client-side routing while audio continues to play
|
||
- 🎛️ Simpler control over audio playback:
|
||
- Seek to a specific time
|
||
- skip forward ﹢ backward
|
||
- play ﹢ pause
|
||
- mute ﹢ unmute
|
||
- 🛟 Save and load a users progress for each episode in localStorage
|
||
- 💾 Save and load a users preferences (like playback speed) in localStorage
|
||
- ﹢ volume
|
||
- ﹢ playback speed
|
||
- 🖼️ Inject episode metadata into the audio store for ea
|
||
|
||
**Roadmap**
|
||
In no particular order, here are some of the things I'm confident will be added to this library:
|
||
|
||
- ☐ Podcast player component utilities
|
||
- ☐ Pre-built player component
|
||
- ☐ RSS Feed parsing
|
||
- ☐ Looping segments of an episode
|
||
- [And more ideas being discussed](https://github.com/OllieJT/svelte-podcast/labels/feature)
|
||
|
||
## Docs
|
||
|
||
> **Warning**
|
||
> This project is in early development. The docs are not yet complete and the API is likely to change before 1.0.0.
|
||
|
||
#### Install
|
||
|
||
```bash
|
||
# with npm
|
||
npm install svelte-podcast
|
||
|
||
# with yarn
|
||
yarn add svelte-podcast
|
||
|
||
# with pnpm
|
||
pnpm add svelte-podcast
|
||
```
|
||
|
||
You must add one instance of the `<AudioLoader />` to your app. This should be places as high as possible, ideally in your root `+layout,svelte` file.
|
||
|
||
```html
|
||
<script>
|
||
import { AudioLoader } from 'svelte-podcast';
|
||
</script>
|
||
|
||
<AudioLoader />
|
||
|
||
<slot />
|
||
```
|
||
|
||
#### Basic usage
|
||
|
||
You will likely be interacting with svelte-podcast via one of the stores it exports.
|
||
|
||
```html
|
||
<script>
|
||
import {
|
||
// a custom store for subscribing to the state of the audio player and controlling audio element
|
||
audio,
|
||
|
||
// a custom store for subscribing to the users preferences and setting a users preference
|
||
user_preferences,
|
||
|
||
// a utility for saving and loading the progress of an episode
|
||
episode_progress,
|
||
|
||
// a utility for saving and loading both the progress and preferences
|
||
save_podcast_state,
|
||
} from 'svelte-podcast';
|
||
</script>
|
||
```
|
||
|
||
#### `audio` store
|
||
|
||
##### `subscribe`
|
||
|
||
```html
|
||
<script>
|
||
import { audio } from 'svelte-podcast';
|
||
|
||
// shorthand
|
||
$audio;
|
||
|
||
// longhand
|
||
audio.subscribe((value) => {
|
||
// value is the current state of the audio store
|
||
});
|
||
</script>
|
||
```
|
||
|
||
##### methods
|
||
|
||
###### play / pause
|
||
|
||
`audio.play()` to play the currently loaded audio, or `audio.play("toggle")` to toggle play/pause.
|
||
|
||
`audio.pause()` to pause the currently loaded audio, or `audio.pause("toggle")` to toggle play/pause.
|
||
|
||
###### mute / unmute
|
||
|
||
`audio.mute()` to mute the audio for the `<audio />` element, or `audio.mute("toggle")` to toggle mute/unmute.
|
||
`audio.unmute()` to unmute the audio for the `<audio />` element, or `audio.unmute("toggle")` to toggle mute/unmute.
|
||
|
||
###### load / unload
|
||
|
||
`audio.load(data: AudioLoadData, opts: AudioLoadOptions)` to load a new episode into the `<audio />` element.
|
||
|
||
- AudioLoadData is an object with the following properties:
|
||
- src: `string` - the URL or local path to the audio file
|
||
- title: `string` - the title of the episode
|
||
- artwork: `string` - the URL or local path to the artwork for the episode
|
||
- AudioLoadOptions is an object with the following properties:
|
||
- autoplay: `boolean` - whether or not to autoplay the audio when it is loaded. Typically this should be set to `true`
|
||
- start_at: `number | undefined` - the time in seconds to start the audio at. Useful for resuming playback from a previous session. This will be overridden by the users episode progress if it exists.
|
||
|
||
`audio.unload()` - unloads the currently loaded audio file from the `<audio />` element.
|
||
|
||
###### seek / skip
|
||
|
||
`audio.seek(seconds, from)` - seek to a specific moment in the audio file.
|
||
|
||
- seconds: `number` - the time in seconds to seek to
|
||
- from: `'from-start' | 'from-end'` - whether to seek relative to the start or end of the audio file. Defaults to `'from-start'`
|
||
|
||
`audio.skip(seconds, type)` - similar to seek, but always relative to the current time.
|
||
|
||
- seconds: `number` - the time in seconds to skip
|
||
- type: `'forward' | 'backward'` - whether to skip forward or backward. Defaults to `'forward'`
|
||
|
||
Example payload:
|
||
|
||
```json
|
||
{
|
||
"current_time": 35.624346,
|
||
"duration": 3378.756,
|
||
"ended": false,
|
||
"loading": false,
|
||
"paused": true,
|
||
"start_at": 27.37508,
|
||
"autoplay": true,
|
||
"muted": false,
|
||
"src": "/example-syntax.mp3",
|
||
"metadata": {
|
||
"title": "Supper Club × Rich Harris, Author of Svelte",
|
||
"artwork": "https://ssl-static.libsyn.com/p/assets/b/3/c/d/b3cdf28da11ad39fe5bbc093207a2619/Syntax_-_499.jpg"
|
||
},
|
||
"playback_rate": 2,
|
||
"volume": 1,
|
||
"timestamp": "00:35"
|
||
}
|
||
```
|
||
|
||
#### `user_preferences` store
|
||
|
||
##### `subscribe`
|
||
|
||
```html
|
||
<script>
|
||
import { user_preferences } from 'svelte-podcast';
|
||
|
||
// shorthand
|
||
$user_preferences;
|
||
|
||
// longhand
|
||
user_preferences.subscribe((value) => {
|
||
// value is the current state of the user_preferences store
|
||
});
|
||
</script>
|
||
```
|
||
|
||
#### `episode_progress` utilities
|
||
|
||
#### `save_podcast_state` utilities
|
||
|
||
## Contributing
|
||
|
||
> **Warning**
|
||
> This project is very early in development. Contributions are welcome but I do not plan to provide detailed docs for contributions until the project is more stable.
|