Add basic docs
This commit is contained in:
Ollie Taylor
@@ -6,10 +6,185 @@ A collection of tools for building podcast websites and tools with Svelte or Sve
|
||||
| :-------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------: |
|
||||
| [](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
|
||||
|
||||
Coming Soon...
|
||||
> **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
|
||||
|
||||
Coming Soon...
|
||||
> **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.
|
||||
|
||||
Reference in New Issue
Block a user