Skip to main content

termradio

Radio, music and podcasts in your terminal. No browser, no API keys, no extra executables: audio goes through the VLC you already have installed (python-vlc loads libvlc.dll from it).

Install

pip install termradio
termradio
termradio --country IN   # podcast charts for India (remembered)

Needs Python 3.9+ and VLC 3.x installed (the app plays audio through it).

What's in it

Tab Sources What you get
1 Radio Radio Browser, SomaFM, a curated list ~50,000 live stations. Browse by genre, country or language, or see trending, most played and top voted. 49 hand-checked stations (Radio Paradise, KEXP, FIP, NTS, BBC World Service, WFMU, Swiss Jazz, Nightride…) and all ~46 SomaFM channels
2 Music Audius, Internet Archive, ccMixter Full-length on-demand tracks. Audius has trending tracks by genre (36 genres) and playlists. Internet Archive has live concerts, Grateful Dead, netlabels, 78 RPM records, jazz and classical. ccMixter has Creative Commons tracks. Search covers all three
3 Podcasts Apple Podcasts directory + RSS, Internet Archive Top charts in 20 categories, search for any podcast, full episode lists. Also LibriVox audiobooks and Old Time Radio. Episodes remember where you stopped
4 Favourites – Anything you star with f or the ☆ Fav button: stations, tracks, albums, playlists, podcasts, episodes, and whole categories from the sidebar (e.g. Radio › Jazz)
5 History – The last 300 things you played

Keys

Key Action
enter play, or open a folder / album / podcast
backspace / esc go back to the previous list (after opening something, a search or a category); while loading, cancels
/ search (in the current tab)
space pause / resume
s stop
n / p next / previous in the list
+ / - volume, m mute
[ / ] seek -15s / +30s (tracks and episodes)
, / . seek -5s / +5s
mouse click or drag the progress bar at the bottom to jump anywhere
f add / remove favourite
c copy a shareable ID for the selected item
t sleep timer: 15 → 30 → 60 → 90 min → off
1–5 switch tab
q quit

Favourites and sharing. f / ☆ Fav and c / ⧉ Copy ID act on the highlighted row, or on the highlighted sidebar category when the sidebar has focus. The copied ID looks like termradio:audius-album:eNpN…; paste it into any tab's search box to bring that exact item up (play it, open it or favourite it). It carries everything needed, so it works on a colleague's machine too.

Radio search can filter: tag:jazz, country:IN, lang:hindi, and they combine, e.g. country:IN tag:bollywood or mirchi country:IN.

Files

  • app.py: the terminal UI (Textual)
  • sources.py: every data source. All are free and need no key
  • player.py: playback through libvlc
  • If audio won't start, termradio says why and exits: VLC missing, 32-bit VLC with 64-bit Python (or the reverse), or VLC 4 (only VLC 3.x is supported). Installed somewhere unusual? Set TERMRADIO_VLC_DIR to the folder that contains libvlc.dll.
  • State (favourites, history, volume, podcast positions): ~/.termradio/state.json

Notes

  • SomaFM rejects requests that send no User-Agent (you get a 403, as with plain curl). termradio always sends one.
  • ccMixter refuses hotlinks without a Referer header. The player sends the stream's own site as the Referer.
  • Podcast URLs often chain 4–6 tracking redirects, which VLC won't follow, so they're resolved in Python first.
  • Radio streams that drop reconnect automatically, up to 3 times in a row.

Metadata

Release files for termradio 0.1.1

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

Source distribution (sdist)

Source distribution for termradio 0.1.1
File Size Uploaded Provenance Actions
termradio-0.1.1.tar.gz 25.0 kB Without provenance Details for termradio-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 52.0 kB

Release files / termradio-0.1.1.tar.gz

Download URL termradio-0.1.1.tar.gz
Size 25.0 kB
Tags Source
SHA-256 checksum
How to use checksums
cc9674e78e6050e849a66c5acab61e8c36a4e40fb60e03cd4e97196e59c02e1e
BLAKE2b-256 checksum
How to use checksums
aa259aaaf39d1fbfc7f365378d0b55324d8b897907db7dc94399ea654687d1ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / termradio-0.1.1-py3-none-any.whl

Download URL termradio-0.1.1-py3-none-any.whl
Size 27.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fd3fb962a53ecf41cbd17b5067e07fcdee98e73c6ff9432a6136ff031b461a1
BLAKE2b-256 checksum
How to use checksums
b4b48c2248648b2de81801baa246d317688fcbcefafbbeeb65028f10d3ce75c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for termradio 0.1.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.1 This release

2 release files No 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