contentpack-sample-podcast/README.md

# 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, 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.
- **`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 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.