Skip to content

radio.md

Latest commit

 

History

History
267 lines (199 loc) · 11.4 KB

radio.md

File metadata and controls

267 lines (199 loc) · 11.4 KB
Raw

Radio

cliamp ships with the Radio Browser directory: about 58,000 internet radio stations across 241 countries. Press R in the player to open it.

A list that long is only useful if you can cut it down. Browse it by location, filter the directory's genres and tags, or search for a station by name.

cliamp radio

cliamp opens on the cliamp radio view: the channels cliamp runs on radio.cliamp.stream, and nothing else. The Radio Browser directory stays in the Radio provider.

── cliamp radio ───────────────────
  Omarchy · 33 tracks
  Chiptunes · 108 tracks
  Amiga · 68 tracks
  Lofi · live
  Synthwave · live
  • A channel that shows a track count opens as a playlist of its songs. Each song is a file, so you can seek, skip with > and <, and let the next song start without a gap.
  • A channel marked live has no song library. It plays the live stream.
  • Channels with songs come first, so the cursor starts on a playlist.
  • Ctrl+R reloads the channel list and its track counts.
  • Each channel shows who else is listening: ● 3 listening now, or ○ quiet right now when nobody is. Your own listening adds one to the channel you play. The counts come from the same statistics the website renders, refresh every few minutes, and stay hidden when offline.
  • R opens the Radio provider. To come back, Tab to Source (SRC) and choose "cliamp radio" with Left and Right.

cliamp loads the channel list from https://radio.cliamp.stream/stations. The view is the default provider, cliamp. With auto_play = true, cliamp starts the live channel streams instead, so the music starts without a keypress. The daemon also starts with the live streams.

Quick start

Do this To get
R, then Enter on "Browse all countries" The country list, your own regions first
/ in the country list Filter it: type japan, europe, oslo
Enter on "Browse genres & tags" The complete tag list, most-used first
/ in the tag list Filter it: type jazz, rock, news, 80s
f on a country Pin it, so it gets its own row in the radio pane
Enter on a country row That country's stations as a playlist
Enter on "Use my location" Offers to work out your country, once, and only if you say yes

The radio pane

── Countries ──────────────────────
  Browse all countries
  Norway (near you)
  ★ Germany
  ★ Japan
── Genres & Tags ──────────────────
  Browse genres & tags
── Stations ───────────────────────
  cliamp radio
── Favorites ──────────────────────
  ★ Radio Paradise [320k] · United States
── Catalog ────────────────────────
  MANGORADIO [128k] · Germany
  Dance Wave! [128k] · Hungary

"Norway (near you)" appears only once you have said yes to using your location. Starred rows are places you pinned. Selecting any of them loads that country's or region's stations as a playlist, so > and < scan between stations of one place.

Browsing by country

"Browse all countries" opens the country list. Each row shows the country, its station count, and its region:

☆ Innlandet (16) — Norway
☆ Oslo (11) — Norway
☆ United States Of America (7975) — Americas
★ Germany (6235) — Europe
☆ Japan (215) — Asia

Regions of your own country come first, grouped under its name. Only about 44% of stations record a region at all, so cliamp fetches them for your home country only, where they are worth the request.

/ filters the list on both the name and the region, so asia narrows to Asian countries and oslo finds one Norwegian region.

Pick a country and choose how to order its stations:

Order Sorts by
Most Voted Directory votes, all-time
Most Listened Total clicks
Trending Recent click growth
By Name Station name, A to Z
Random Nothing; a different set each time

The result replaces your playlist with up to 200 stations from that place.

Browsing by genre or tag

"Browse genres & tags" opens Radio Browser's complete community-maintained tag index, ordered by the number of stations carrying each tag:

pop (5723)
rock (2983)
classical (1525)
jazz (1134)
electronic (928)

Press / and type to filter the list. Select a tag, choose the same vote, listener, trend, name, or random order offered by the country browser, and cliamp replaces the playlist with up to 200 matching stations. Tag matching is exact: selecting rock does not imply classic rock, although a station that carries both tags appears in both results.

The tags are supplied by the directory's contributors, not a controlled genre taxonomy. They include genres, formats, eras, languages, and descriptors such as news, talk, or public radio. Some are inconsistent or unusually specific; cliamp exposes the index as submitted, removes empty and case-only duplicates, and shows station counts so useful filters are easy to recognize.

Station favorites

Press f on a directory station in the Catalog, search results, or the playback playlist to toggle its Radio favorite. This includes stations loaded from countries, regions, genres, and tags. The action follows the highlighted station, not necessarily the one playing, and still works after switching providers.

Favorites appear under Radio → Favorites and show the ♥ marker in the playback playlist. The marker uses the same column as track favorites, so a toggle does not move the titles. They are saved locally in ~/.config/cliamp/radio_favorites.toml, deduplicated by station URL. The saved name is the station name, not the current song, and station details including the region are retained after restart. M3U/PLS wrapper stations keep their original station URL when resolved to a playback stream. Toggling a favorite keeps the provider highlight on the same surviving station, and completed catalog pages remain visible even when favorites change during loading. Favoriting does not fetch more catalog stations or interrupt an in-progress station load. Press f again to remove a favorite.

On Linux and macOS, favorite mutations use the latest file contents under a shared file lock, preserving changes made by other cliamp instances. The action follows the marker displayed in this instance: an unmarked station is favorited, and a marked station is unfavorited. If another instance already made that change, it is not reversed. Already-open players pick up other instances' changes on their next favorite mutation or restart, not through live refresh. On Windows, use only one writer per config directory.

For IPC clients, favorite IDs are stable f:<station URL> values returned by provider.playlists. Use those IDs for subsequent operations; positional f:<index> IDs are not supported. Existing favorites files remain readable.

In a saved local playlist, f toggles the track favorite instead, as it does for any other track. The footer distinguishes Favorite station from Favorite track. A station favorite does not change a remote provider account. See playlists.md for track favorites.

Pinning

f on a country or region pins it. Pinned places get their own row in the radio pane under "Countries", so the places you listen to are one keypress from anywhere. They are stored in ~/.config/cliamp/radio_countries.toml:

[[country]]
code = "DE"
name = "Germany"

[[country]]
code = "NO"
name = "Oslo, Norway"
state = "Oslo"

On Linux and macOS, a pin or unpin uses the latest file contents under a shared file lock, so it keeps the pins of other cliamp instances. As with favorites, the action follows the marker in this instance. If cliamp cannot read the file, f shows an error and does not change the file.

Using your location

Until you ask for it, cliamp does not work out where you are. A fresh install shows one row instead:

── Countries ──────────────────────
  Browse all countries
  Use my location

Selecting it asks:

Use your country to suggest nearby radio? cliamp would read it from your system timezone. Nothing is sent to a location service.

Answer with y or n. Either answer is remembered, so you are asked once and the row goes away. Saying yes writes your country to [radio] country and adds a "near you" row for it; saying no writes country = "none" and changes nothing else.

Nothing else in cliamp reads your location, and no other feature is gated on this. The country browser, pinning, and the catalog all work the same whether you say yes or no; a yes only saves you finding your own country in a list of 241.

How it is worked out

Only after you say yes, and never over the network:

  1. The system timezone: TZ, then the /etc/localtime symlink, then /etc/timezone.
  2. The locale: LC_ALL, then LC_MESSAGES, then LANG.

The timezone is checked before the locale on purpose. A desktop left on en_US.UTF-8 while sitting in Europe/Oslo is the common case, not the exception, and the timezone is the setting people keep accurate.

There is no geo-IP lookup. That would be more precise and would also mean telling a third party where you live every launch, which is not a trade this feature is worth.

Setting it yourself

Skip the question entirely with an ISO 3166-1 alpha-2 code:

[radio]
country = "NO"

Or turn it off for good:

[radio]
country = "none"

To be asked again, delete the country line.

Why not "stations near me"

The directory records coordinates for stations, and it would be reasonable to expect a radius search. cliamp does not offer one, because the data does not support it:

Field Coverage (1000 top stations)
countrycode 98.7%
state 44.4%
geo_lat / geo_long 11.9%

A 200 km radius search would silently hide about 88% of the catalog. The API also ignores distance ordering, so what came back would not even be sorted by how close it is. Country is the axis the data actually supports, so that is the one cliamp uses.

Custom stations

Stations you add yourself live in ~/.config/cliamp/radios.toml and appear under "Stations" alongside the built-in cliamp radio. See configuration.md.

Unlike directory entries, these are not filtered to http and https. That file is yours, and it carries the same trust as anything else you type.

Keys

Key Action
R Open the radio provider
/ Search station names through the directory (Enter runs it, Esc clears)
f Favorite the selected station, or pin the selected country
N Open the country browser
Ctrl+R Refresh: re-fetch the country list and the catalog

See keybindings.md for the rest.

Track info

For live radio, cliamp shows the current track from inline ICY metadata (StreamTitle). See streaming.md for the stations that publish now-playing data through an API instead.

Run your own station

Run an internet radio station with cliamp-server. Point it at a directory of audio files to start broadcasting. It supports multiple stations, live metadata, and on-the-fly transcoding.