diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 65 |
1 files changed, 64 insertions, 1 deletions
@@ -30,15 +30,64 @@ post-processing, after the bytes are already on disk. | Command | What it does | | --- | --- | -| `podkit fetch <url>` | Download and extract audio | +| `podkit fetch <url>` | Download and extract audio via yt-dlp | +| `podkit get <url>` | Download a direct audio URL, or every enclosure in an RSS feed — no yt-dlp, no ffmpeg | | `podkit tag` | Write ID3 tags derived from filenames | | `podkit feed` | Generate `feed.xml` | | `podkit serve` | Host the directory and feed over HTTP | +| `podkit push` | Upload a local library to a remote `podkit serve --ingest` | | `podkit all <url>` | fetch → tag → feed | Each stage runs independently on purpose: the download is the slow part and shouldn't be repeated while you're adjusting titles or the base URL. +## Downloading somewhere other than where you host + +The download and the hosting do not have to happen on the same machine, and +usually shouldn't. A server on a datacentre IP is treated very differently from +a home connection by the larger video sites — YouTube in particular will refuse +a datacentre request outright with *"Sign in to confirm you're not a bot"* while +the identical command works fine from a laptop. + +So run the download where you actually are, and push the result to the host: + +```bash +# on your own machine +podkit get "<rss or audio url>" --dir ./audio +podkit tag --dir ./audio --title "…" --artist "…" +podkit push --dir ./audio --server https://your-host/podkit --token "$TOKEN" +``` + +```bash +# on the server, once +podkit serve --dir /srv/podkit/audio --addr 127.0.0.1:8099 \ + --ingest --token "$TOKEN" \ + --title "…" --artist "…" \ + --base-url "https://your-host/podkit/audio/" +``` + +`push` asks the server what it already has and uploads only the difference, so +re-running after adding three episodes to a 200-episode series sends three +files. `--ingest` regenerates the feed after each upload. + +This also means the server never needs credentials for, or a working route to, +wherever the audio came from. + +**`--ingest` is off by default.** A host that accepts writes is a different +security proposition from one that only reads, and it refuses to start without +a token. + +### Behind a reverse proxy + +`serve` expects to be mounted with the path prefix stripped, which is what +doot's `NewServiceProxy` already does. Give `--base-url` the public path and +point `push --server` at the same place: + +``` +--base-url https://doot.terst.org/podkit/audio/ +--server https://doot.terst.org/podkit +``` + ## Notes on the things that usually go wrong These are the parts a hand-rolled version of this pipeline tends to get wrong, @@ -74,6 +123,15 @@ preserves artwork yt-dlp embedded rather than replacing the tag wholesale. **ID3 only on MP3.** ID3v2 is an MP3 convention; writing it into `.opus` or `.m4a` produces something no player reads, so other formats are left alone. +**The token has to be in the enclosure URLs.** A podcast client fetches the +feed, then fetches each episode as a plain GET carrying nothing from the first +request. If the server wants a token and the enclosure URLs don't have one, the +feed loads, lists every episode, and not one of them will ever download. +`--token` on `feed` puts it in the URLs; `serve --ingest` does it for you. + +**Identifying itself.** Go's default user-agent is rejected outright by several +podcast CDNs — libsyn returns 403 for it. `get` sends a real one. + ## "Private" `--token` means unlisted-and-unguessable, not authenticated. Podcast clients @@ -90,6 +148,11 @@ For anything beyond a home network, put it behind a reverse proxy with TLS. may download a given item is between you and whoever published it — check the source's terms. +There is deliberately no cookie-jar or sign-in option. Feeding a site your +logged-in session to get past a check that exists to stop automated downloading +is a different act from downloading, and this tool doesn't do it. `get` covers +the sources that don't ask: RSS feeds, archive.org, direct links. + ## Tests ``` |