diff --git a/README.md b/README.md index 18d6885..b85554b 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,14 @@ [![GitHub stars](https://img.shields.io/github/stars/adurrr/wavecast?style=flat&color=6366f1)](https://github.com/adurrr/wavecast/stargazers)

- Wavecast demo showing persistent audio player across page navigation + Wavecast demo: persistent audio player across page navigation, with documentation section and language switcher

-A persistent podcast/radio audio player for Hugo - drop `` into any page with a single shortcode. Supports **local files**, **AzuraCast** radio streams, and **iVoox** episodes. Works as a **Hugo module** _and_ as a **Hugo theme**. +A persistent podcast/radio audio player for Hugo: drop `` into any page with a single shortcode. Supports **local files**, **AzuraCast** radio streams, and **iVoox** episodes. Works as a **Hugo module** and as a **Hugo theme**. + +**[Live demo](https://adurrr.github.io/wavecast/)** | **[Documentation](https://adurrr.github.io/wavecast/docs/)** + +--- ## How It Works @@ -18,108 +22,32 @@ Wavecast provides two custom Web Components that work together: | Component | Where | What it does | |-----------|-------|-------------| | `` | Inline (in your content) | Play/pause, skip, seek, volume, chapters, poster | -| `` | Sticky footer | Persistent player bar at the bottom of every page | +| `` | Sticky footer | Persistent player bar that follows you across every page | -Both components are **bidirectionally synced** - pausing the footer pauses all inline players, and vice versa. Only one audio source plays at a time. Position, volume, mute, and speed are saved to `sessionStorage` and restored across page navigations. +Both components are bidirectionally synced: pausing the footer pauses all inline players, and vice versa. Only one audio source plays at a time. Position, volume, mute, and speed survive page navigation. ## Features -- **Web Component** (``) with Shadow DOM - framework-agnostic, works anywhere -- **Inline player**: play/pause, skip ±15s, seekable progress bar, volume slider, mute, playback rate (0.5×–2×) -- **Sticky footer player**: radio-t style bottom bar with cover art, track name, skip, play/pause, wide progress bar, volume, mute, speed, close -- **Bidirectional sync**: pausing any player pauses all audio; all play buttons stay in sync +- **Web Component** with Shadow DOM: framework-agnostic, works anywhere +- **Inline player**: play/pause, skip +-15s, seekable progress bar, volume slider, mute, playback rate (0.5x-2x) +- **Sticky footer player**: cover art, track name, skip, play/pause, progress bar, volume, mute, speed, close +- **Bidirectional sync** between inline and footer players - **Single-stream**: playing a new source stops the previous one automatically -- **Chapters**: timestamp-labelled navigation chips (`00:00:00-Intro, ...`) -- **Poster & description**: cover image with responsive sizing, Markdown-rendered show notes -- **Source adapters**: local files, AzuraCast radio stations, iVoox episodes (with auto-detection) -- **Navigation persistence**: survives Turbolinks, Turbo, htmx, and vanilla page loads via `sessionStorage` -- **Theming**: 12 CSS custom properties for light/dark themes, responsive on mobile (<480px) +- **Chapters**: timestamp-labelled navigation chips +- **Poster and description**: cover image with responsive sizing, Markdown-rendered show notes +- **Source adapters**: local files, AzuraCast, iVoox (with auto-detection) +- **Navigation persistence**: survives Turbolinks, Turbo, htmx, and vanilla page loads +- **CSS custom properties** for light/dark themes, responsive on mobile - **`::part()` selectors**: style individual Shadow DOM elements from outside - **Keyboard shortcuts**: Space (play/pause), Left/Right (skip), M (mute) -- **Media Session API**: integrates with OS media controls (lock screen, notification centre) +- **Media Session API**: integrates with OS media controls +- **Podcast RSS feed**: iTunes-compatible feed generation from Hugo content - **Accessible**: ARIA labels, `:focus-visible` rings, semantic controls -- **Well tested**: Go integration tests, JS unit tests (Vitest), Playwright E2E, RSS output tests -- **Podcast RSS feed**: iTunes-compatible podcast RSS generation from Hugo content with automatic detection - ---- - -## Installation - -Wavecast can be used in two ways. Choose the one that fits your project. - -### Prerequisites - -- Hugo v0.146.0+ -- Go 1.23+ - -### Option A: Install as a Hugo theme (recommended for most sites) - -Clone or copy the repo into the `themes/` directory of your Hugo site: - -```bash -git clone git@github.com:adurrr/wavecast.git themes/wavecast -``` - -Then add to your site's `hugo.toml`, `hugo.yaml`, or `hugo.json`: - -```toml -theme = "wavecast" -``` - -That's it. Hugo automatically discovers the shortcode (`layouts/_shortcodes/podcast-player.html`), JS (`assets/js/podcast-player.js`), and CSS (`assets/css/podcast-player.css`) from the theme directory. - -> **Tip:** Pin a specific version with a Git tag: -> ```bash -> cd themes/wavecast && git checkout v0.1.0 -> ``` - -### Option B: Install as a Hugo module (for multi-module sites) - -If you're already using Hugo modules or need to compose Wavecast with other modules: - -```bash -hugo mod init github.com/yourusername/your-site -hugo mod get github.com/adurrr/wavecast -``` - -Then in your site's `hugo.toml`: - -```toml -[module] - [[module.imports]] - path = "github.com/adurrr/wavecast" -``` - -Hugo will resolve the module and make the shortcode, JS, and CSS available. - -### Which option should I choose? - -| You want... | Use | -|-------------|-----| -| Simple setup, one theme | **Theme** (`theme = "wavecast"`) | -| To use Wavecast alongside other modules | **Module** (`[module.imports]`) | -| To override Wavecast's templates in your own project theme | **Theme** (Hugo's theme cascade handles overrides) | -| Pinned, reproducible builds | Either - both support version pinning | -| No git submodule or clone in your repo | **Module** (`hugo mod get`) | - -### Local development / demo - -Clone the repo and use the included example site: - -```bash -git clone git@github.com:adurrr/wavecast.git -cd wavecast/exampleSite -hugo server --port 1313 -``` - -Open your browser to the URL shown in the server output (e.g. `http://localhost:1313/wavecast/`). The first demo player uses a local `.wav` file so it works immediately with no external dependencies. --- ## Quick Start -### With a remote audio URL - ```markdown {{< podcast-player src="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3" @@ -127,359 +55,70 @@ Open your browser to the URL shown in the server output (e.g. `http://localhost: poster="https://picsum.photos/seed/podcast/400/400" description="Show notes with **Markdown**." chapters="00:00:00-Intro,00:05:30-News,00:15:00-Interview" - persistent="true" ->}} -``` - -### With a local asset - -Place your audio file in your Hugo project's `assets/` directory, then reference it by path: - -```markdown -{{< podcast-player - src="episodes/my-episode.mp3" - title="Episode 42: Hello World" >}} ``` -The shortcode resolves local files via `resources.GetMatch` - it checks page-scoped resources first, then the global `assets/` directory. Remote URLs are passed through as-is to the `