offshore-podcast 0.1.0

A local-first podcast feed generator and editor.

offshore

Local-first podcast feed generator and editor. Manage metadata locally and generate feed from assets hosted anywhere.

Conventional podcast hosts like Fireside or Transistor work fine, but they can be expensive for small shows, and handing all your data to a single service is a real dependency. Self-hosted alternatives exist, but most are still designed as full-stack replacements that bundles frontend website, audio storage, and feed generation into one thing.

A podcast feed is just a plain-text XML file. Hosting a handful of audio files and a text file is much easier, and cheaper than running a media server with a web frontend and database. And if you don’t want the website that comes with a podcast host then that part just becomes redundant.

offshore aims to be a more basic solution. It simply helps you manages your show metadata locally and generates feed you can host wherever makes sense — a static site, an object storage, a CDN. Audio files and any other asset live wherever you want to host them. offshore ensures your metadata and assets comply with podcast standards, but otherwise stays out of the way. It can be used as a local feed generator, or reliably on a server to serve the feed directly.

Installation

Python 3.11+.

pip install -e .

Data layout

Shows are stored in a dedicated directory outside the project, defaulting to $XDG_DATA_HOME or $HOME. On first run you will be prompted to confirm or change this.

~/offshore/              # default shows root
  <slug>/
    <slug>.json          # show + episodes
    <slug>.lock.json     # feed stability lock 
    podcast.xml          # generated
    rss.xsl              # generated

Each show lives in its own subdirectory. The JSON contains all show metadata and episodes. The lock file records each episode's GUID and pub_date to catch accidental edits that would reorder the feed for existing subscribers.

To inspect or change the configured root:

offshore config                          # show current setting
offshore config --shows-dir ~/mypodcasts # update it

Usage

Web UI

offshore serve

Opens at http://127.0.0.1:8765. On first run with no shows, the landing page offers three options: New, Import, or Open an existing file.

All CLI commands are also available from the UI.

CLI

New show:

offshore init <slug>

Import from an RSS feed URL or an offshore JSON file:

offshore import <url-or-path> --slug <slug> --feed-self-url <public-feed-url>

Validate:

offshore check            # run checks (structural + remote assets)
offshore check --no-remote  # skip network checks

Probe audio metadata:

offshore probe --all      # all episodes
offshore probe <guid>     # single episode

Probing downloads only the first 256 KB of each file to read the header. Results are cached in the episode JSON.

Generate feed:

offshore generate
offshore generate --force           # skip check failures
offshore generate --output-dir <path>  # write to a different directory

Output goes to <shows-root>/<slug>/podcast.xml by default. Falls back to the current directory if the shows root is not writable.

Republish an episode (changes pub_date, updates lock):

offshore republish <guid> --date <ISO8601>

Open a specific show file:

offshore serve --show /path/to/<slug>.json

Serving the feed

shows/<slug>/ is a static directory. Point nginx (or any web server) at it:

server {
    listen 80;
    server_name your.domain.com;
    root /path/to/shows/my-show;

    location /podcast.xml {
        add_header Content-Type "application/rss+xml; charset=utf-8";
    }
}

Make sure feed_self_url in the show JSON matches the public URL you serve the feed at.

To redirect feed output to a shared web root:

offshore generate --output-dir /var/www/html
offshore serve --output-dir /var/www/html

offshore serve can also be exposed directly behind a reverse proxy (--host 0.0.0.0). Each show's feed is available at /download/<slug>/podcast.xml.

Audio

MP3 (audio/mpeg) and M4A/AAC (audio/mp4, audio/aac) are accepted. Format is verified when an episode is saved. If the URL is unreachable at save time you can skip verification and probe later.

Checks

offshore check runs before every generate. Fail-level findings block generation; --force overrides. Checks cover:

• All required fields on the show and each episode
• Audio probe cache present (duration + byte count are required for a valid enclosure)
• Audio and image URLs reachable with the correct MIME type
• Episode pub_date is not in the future
• All person roster references resolve
• Episode GUID and pub_date match the lock file

Development

tests/ includes a sample feed and a group of scripts to validate the output for development.