Skip to main content

applepodbar

A keyboard-driven terminal podcast player for Apple Podcasts, built with Python and Textual.

Status

Early. Home charts, genre/editorial browse, search, show detail, and free-episode playback are wired to the AMP catalog. Playwright login is available as an optional extra. If Apple's web token cannot be found, search and playback fall back to iTunes Search and publisher RSS. Signed-in Library, Up Next, and cross-device playback-position sync, and follow/save actions are now wired. Paid FairPlay content remains out of scope; see docs/SPEC.md.

applepodbar home screen showing top podcasts

applepodbar playing an ANTIC episode, with the show's episode list, cover art, and queue

Features

  • Browse and search the Apple Podcasts catalog; play free episodes through mpv
  • Signed-in Library, Up Next, follows/saves, and cross-device position sync
  • Zero-auth iTunes Search + RSS fallback with local follows and resume positions
  • Paid FairPlay episodes are listed but not playable

Requirements

  • Python 3.12+
  • uv
  • mpv on PATH (needed for playback; browsing works without it)
  • An Apple account, only for the signed-in features

Install

uv tool install applepodbar
applepodbar

# With sign-in support (Library, Up Next, position sync):
uv tool install 'applepodbar[login]' --with-executables-from playwright
playwright install chromium
applepodbar login

Installation for development

git clone git@github.com:feoh/applepodbar.git
cd applepodbar
uv sync
uv run applepodbar

Signing in

Catalog browsing, search, and playback of free episodes need no sign-in at all.

Library, Up Next, and position sync need a per-user token. applepodbar captures it once by opening a real browser window for you to sign in to Apple yourself — it never sees or stores your Apple ID password. This needs the optional login extra:

uv sync --extra login
uv run playwright install chromium
uv run applepodbar login

Configuration

Configuration lives in the platform-standard user config directory:

<config_dir>/applepodbar/
  config.toml          storefront and playback preferences
  tokens.json          cached developer JWT, written user-only (mode 600)
  local_library.json   local follows and RSS resume positions (mode 600)
OS keyring             media-user-token and browser session cookies

Set [general] catalog_backend = "rss" in config.toml to avoid the private API altogether. In RSS mode, press a on a show to follow it locally; l lists locally followed shows. Resume positions stay on this device.

Linux keyring support requires an unlocked Secret Service backend. No account password is handled by applepodbar.

Development

uv run pytest -q
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/applepodbar tests
uv run pyright
uvx prek run --all-files
uv build

Releasing

Publishing a GitHub release runs .github/workflows/publish.yml, which re-runs the checks, builds, and uploads to PyPI through trusted publishing (no API token). The release tag must be v plus the pyproject.toml version:

uv version --bump patch        # or minor / major
git commit -am "Release v$(uv version --short)"
git push
gh release create "v$(uv version --short)" --generate-notes

License

MIT — see LICENSE.

Metadata

Release files for applepodbar 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for applepodbar 0.1.0
File Size Uploaded Provenance Actions
applepodbar-0.1.0.tar.gz 31.9 kB With provenance Details for applepodbar-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for applepodbar 0.1.0
File Interpreter ABI Platform Actions
applepodbar-0.1.0-py3-none-any.whl Python 3 none any Details for applepodbar-0.1.0-py3-none-any.whl

Total release size: 69.5 kB

Release files / applepodbar-0.1.0.tar.gz

Download URL applepodbar-0.1.0.tar.gz
Size 31.9 kB
Tags Source
SHA-256 checksum
How to use checksums
961c947fb702ae323274ff179afff77ed3d5dc31991a6c94de39372a806c3fa5
BLAKE2b-256 checksum
How to use checksums
83fd7b488620ded7cb227809b90f320a55b2e2fcbb36518cb9cf79a2ec8bd81c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / applepodbar-0.1.0-py3-none-any.whl

Download URL applepodbar-0.1.0-py3-none-any.whl
Size 37.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
afe4e57d1ec168525c77f6f6a6a8184b0cfd1235ae9c685e59034aacd0dc4e12
BLAKE2b-256 checksum
How to use checksums
cb9494a995b213b331926ca068d67f0acd7b8a3b087658ff9329deeaad44514c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Security for applepodbar 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for applepodbar-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page