Initial Docs (#39)
This commit is contained in:
Ollie Taylor
GitHub
@@ -39,13 +39,13 @@ In no particular order, here are some of the things I'm confident will be added
|
||||
|
||||
```bash
|
||||
# with npm
|
||||
npm install svelte-podcast
|
||||
npm install svelte-podcast@latest
|
||||
|
||||
# with yarn
|
||||
yarn add svelte-podcast
|
||||
yarn add svelte-podcast@latest
|
||||
|
||||
# with pnpm
|
||||
pnpm add svelte-podcast
|
||||
pnpm add svelte-podcast@latest
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -62,129 +62,10 @@ You must add one instance of the `<AudioLoader />` to your app. This should be p
|
||||
|
||||
#### 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
|
||||
You can find docs and guides for getting started on [svelte-podcast-docs.vercel.app](https://svelte-podcast-docs.vercel.app/)
|
||||
|
||||
> **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.
|
||||
> This project is early in development. API changes are likely until we reach v1.0.0.
|
||||
|
||||
> **Info**
|
||||
> Contributions are welcome but I do not plan to provide guides for contributing until the project is more stable.
|
||||
|
||||
Reference in New Issue
Block a user