butter/contentpack-sample-podcast
6
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

update with build script to configure base path and generate files dynamically

Browse source
This commit is contained in:
n8fr8 2026-04-15 09:09:53 -04:00
parent 6f63c1a734
commit 6915aac092
10 changed files with 250 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

51
README.md
View file

@ -1,20 +1,61 @@
# ButterBox Content Pack Sample Podcast
A small, self-contained sample podcast webpage and RSS feed from [Guardian Project](https://guardianproject.info). This repository is intended as an example "content pack" — a minimal, portable bundle of everything needed to host and distribute a podcast: episode audio, show notes, a landing page, and a standards-compliant feed.
A small, self-contained sample podcast webpage and RSS feed from [Guardian Project](https://guardianproject.info). This repository is intended as an example "content pack": a minimal, portable bundle of everything needed to host and distribute a podcast, including episode audio, show notes, a landing page, and a standards-compliant feed.
## What's inside
- **`index.html`** : A simple, styled landing page that lists each episode with inline audio playback.
- **`podcast.xml`** : An RSS 2.0 feed with iTunes podcast extensions, suitable for submission to podcast directories and use in podcast players.
- **`*.mp3`** : The three episode audio files.
- **`*.md`** : Per-episode show notes in Markdown.
- **`posts/*.md`** : Per-episode show notes in Markdown (YAML frontmatter holds the episode metadata).
- **`posts/*.mp3`** : The episode audio files, colocated with their show notes.
- **`build.sh`** : Regenerates `index.html` and `podcast.xml` from the contents of `posts/`.
## Using it
Because everything is relative-linked, you can serve this site from a folder on a USB drive plugged into a ButterBox device.
Because everything in `index.html` is relative-linked, you can serve this site from a folder on a USB drive plugged into a ButterBox device.
To subscribe in a podcast client, point it at the hosted URL of `podcast.xml`.
## Building `index.html` and `podcast.xml`
Both output files are generated from the markdown posts in `posts/` by `build.sh`. Run the script any time you add, remove, or edit a post:
```sh
./build.sh <baseURL>
```
The single required argument is the **absolute URL prefix where the mp3 files will be served**. It is only used for the `<enclosure url="...">` entries in `podcast.xml`, because RSS enclosures must be absolute URLs so podcast clients can download them without knowing where the feed lives. Everything else in the generated files (the RSS `<link>`, the `<audio>` players in `index.html`, and the link to the feed itself) stays relative, so you can still move the whole bundle around and serve it from any path.
### Example
If the files will be served from a USB drive called `usb-butter` plugged into a ButterBox, inside a folder named `engardepodcast`, run:
```sh
./build.sh http://butterbox.local/serve_file/media/usb-butter/engardepodcast/
```
Note that `butterbox.local` in the URL must match the configured hostname of your ButterBox. `butterbox.local` is the default, but if you have changed yours to, for example, `someotherbox.local`, use that hostname instead.
The script will produce `podcast.xml` with enclosures like:
```
http://butterbox.local/serve_file/media/usb-butter/engardepodcast/posts/ProofModeCaravan-English-Feb2024.mp3
```
and an `index.html` whose audio elements still use the relative `posts/<file>.mp3` path.
### How it works
For each `posts/*.md` file (sorted newest-first by filename date prefix), the script:
1. Parses the YAML frontmatter (`title`, `date`, `description`, `file`, `voices`, `keywords`, `duration`/`length`, `explicit`).
2. Looks up the referenced mp3 in `posts/` and reads its real byte size with `stat` for the RSS `length` attribute.
3. Picks whichever of the `duration`/`length` frontmatter fields actually looks like `HH:MM[:SS]` for `<itunes:duration>` (the two fields are used inconsistently across the sample posts).
4. Normalizes the `date` field into an RFC 822 `<pubDate>`.
5. Emits one `<item>` block into `podcast.xml` and one `<article class="episode">` block into `index.html`.
Adding a new episode is just a matter of dropping a new `YYYY-MM-DD-slug.md` file and its `.mp3` into `posts/` and re-running `build.sh`.
## License
All content in this repository — audio, show notes, webpage, and feed — is released under [Creative Commons Zero (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/). You may copy, modify, distribute, and use the material for any purpose, including commercial, without asking permission.
All content in this repository (audio, show notes, webpage, and feed) is released under [Creative Commons Zero (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/). You may copy, modify, distribute, and use the material for any purpose, including commercial, without asking permission.