Skip to main content

Radio Browser smart home integration, free and open source

Radio Browser integration for Gladys Assistant

Web radios of the world from the free Radio Browser directory: favorites, logos and streams.

View on GitHubAll integrations

Web radios of the whole world in Gladys, from Radio Browser, a free directory of about 50,000 stations run by volunteers. This integration is not affiliated with radio-browser.info.

What it does​

  • Search the directory by name, country, language or genre, from the Configuration tab of the integration.
  • Keep your favorite stations: each favorite becomes a device in Gladys, with its stream state, bitrate, codec and stream address.
  • Show them on the dashboard with their logo, in the Favorite radios widget.
  • Use them in scenes: the Get the stream of a radio and Pick a random radio scene actions hand the stream address to the player of your choice (for example the DLNA integration).

Gladys cannot yet let an integration start the player of another integration: playing a radio therefore takes two actions in a scene (see Scene examples).

Before you start​

  • Gladys 5.1.0 or later.
  • Internet access from the machine running Gladys. No account, no key.
  • To listen to a radio: an integration whose player can play a URL in a scene, such as the DLNA integration ("Play a URL on a DLNA renderer" action).

Configuration​

Open the Configuration tab of the integration.

  • Language of names and messages: the language of the feature names of the stations you add from now on (Gladys keeps them once a device is added), and of the error messages of the scene actions. French by default.
  • Refresh interval (minutes): how often the favorites are read again from Radio Browser, 60 minutes by default (15 to 360).

Finding and adding stations​

The favorites are managed with the actions at the bottom of the Configuration tab (click Run under each one):

  1. Search a station: fill in one field or more, for example the name FIP, or the genre jazz and the country FR. The country is a name in English (France, Germany) or a two-letter code; the language is written in English (french, german). The 10 most played working stations are listed, each with a number. Stations already in your favorites carry a ★.
  2. Add to favorites: type the number of a result of the last search (or the identifier, UUID, of a station, or its radio-browser.info address). You may give it another name. Up to 50 favorites.
  3. Open the Discover tab: the station is there. Click Add to Gladys.
  4. List the favorites shows them, numbered, and whether they were added to Gladys.
  5. Remove a favorite takes its number in that list, its name or its UUID. Its device stays in Gladys: delete it from the Devices tab if you no longer want it.

The favorites are stored in the integration's data folder, with their last known details: the dashboard and the scenes keep working when the directory is down.

The station devices​

Each favorite added to Gladys is a device named after the station, with four read-only features:

FeatureWhat it says
Stream onlineOn when the last check of the stream by Radio Browser succeeded, Off when it failed or the station left the directory
BitrateIn kbit/s, as announced by the station (not sent when unknown)
CodecMP3, AAC, OGG...
Stream addressThe address to give to a player

The country, language, genres, website and logo address are kept as device parameters. The device is refreshed by the integration itself, at the interval of the configuration.

The "Favorite radios" widget​

Add the Favorite radios widget to a dashboard. It shows your favorites with their logo, country, codec and bitrate, and a green Online or red Offline badge. Tap a station to see its language, its genres, and links to its website and, when the stream is secure (https), to the stream itself: your browser plays it in a new tab.

Settings:

  • Stations shown: pick some of the stations added to Gladys, in the order you want; empty shows every favorite (12 at most).
  • Display: a Logo grid, or a List (8 at most).

The widget has no "play" button: Gladys does not let an integration start the player of another integration yet.

Scene triggers and actions​

The integration declares no scene trigger: a station going offline is the state of its Stream online feature, which the "Device state changed" trigger of Gladys already covers.

Get the stream of a radio​

Pick a favorite station. The action gives the following actions of the scene:

  • Stream address: to give to the "Play a URL" action of a player;
  • Station name, Codec, Bitrate (kbit/s);
  • Stream online: the last check of the stream by Radio Browser succeeded;
  • HLS stream (.m3u8): many network players cannot play those.

It also counts a listen in Radio Browser, as the directory asks. When the directory does not answer, the last known stream address is given anyway.

Pick a random radio​

A random working station of a Genre, a Country and/or a Language (same rules as the search). It gives the same values as above.

In the scene editor, the values of an action appear in the variable picker of the next actions, as {{0.0.stream_url}} for the first action of the first block.

Scene examples​

Wake up with FIP (with the DLNA integration):

  1. Trigger: Time, 7:00, Monday to Friday.
  2. Action: Get the stream of a radio, station FIP.
  3. Next block, action: Play a URL on a DLNA renderer, renderer of the bedroom, URL {{0.0.stream_url}}, title {{0.0.name}}, volume 20.

A random jazz radio on Sunday morning:

  1. Trigger: Time, 10:00, Sunday.
  2. Action: Pick a random radio, genre jazz.
  3. Next block, action: Play a URL on a DLNA renderer, URL {{0.0.stream_url}}, title {{0.0.name}}.

Be told when your favorite station is down:

  1. Trigger: Device state changed, feature Stream online of the station, equal to 0.
  2. Action: Send a message: "FIP is offline in Radio Browser".

Troubleshooting​

  • "Radio Browser cannot be reached" in the Configuration tab: check that the Gladys machine has Internet access. The directory runs on servers maintained by volunteers: the integration tries the next server, and again at the next refresh. The favorites keep their last known details meanwhile.
  • A station is offline but plays: the state is the directory's last check of the stream, which runs about once a day. It follows at the next refresh after a new check.
  • No logo: only PNG, JPEG and WebP logos of 300 KB at most can be shown in a Gladys widget; many stations publish an icon (.ico) or an SVG file.
  • The player does not play the stream: try another version of the station (an MP3 one rather than AAC, or http rather than https), and avoid HLS streams (.m3u8).
  • The station is not in the Discover tab: run List the favorites, then reopen the Discover tab.
  • Detailed logs: set the LOG_LEVEL variable to debug. The logs never contain the stream addresses.

How the integration uses Radio Browser​

Radio Browser is free and run by volunteers. The integration follows its guidelines:

  • one request for all your favorites at each refresh (every 60 minutes by default, 15 minutes at the fastest); a search only when you run it;
  • a server picked at random among the ones the directory announces (DNS), then the next one when it fails;
  • an explicit User-Agent: gladys-radio-browser/<version>;
  • the stream address resolved by the directory (url_resolved);
  • a listen counted each time a scene action starts a station, which keeps the popularity of the stations meaningful (the directory counts one per day and per address).

Radio Browser publishes no quota. The logos are downloaded directly from the stations' websites, which then see the Internet address of your home.

Limits​

  • No direct play: Gladys 5.2 has no way for an integration to command a device of another integration, nor a scene action that plays an address on the speakers of the core (Sonos, AirPlay, Google Cast: their "play a notification" only plays a spoken text, and stops after a few seconds or minutes). The stream address goes through a scene to the player of an integration that accepts one, like DLNA.
  • 50 favorites at most; the widget shows 12 of them (8 as a list).
  • The stream state is the one checked by the directory, not a live check.
  • Feature names stay in the language they were added in.
  • Removing a favorite does not delete its device.
  • Developed without a live connection to the directory, on recorded answers of its API: feedback welcome on the GitHub repository.

Configuration settings​

These are the settings Radio Browser asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Getting startedsectionNoRadio Browser is a free directory of about 50,000 web radios, run by volunteers: no account, no key. Find a station with the "Search a station" action below, then add it with "Add to favorites" and its number. Each favorite then appears in the Discover tab: click "Add to Gladys". This integration is not affiliated with radio-browser.info.
Playing a radiosectionNoGladys does not let an integration start the player of another integration yet. In a scene, add the "Get the stream of a radio" action, then the "Play a URL" action of your player (the DLNA integration, for example) with the stream address as URL. The documentation shows a full example.
Language of names and messagesselectNoNames of the features of the stations added from now on (Gladys keeps them once a device is added), and error messages of the scene actions.
Refresh interval (minutes)numberNoHow often the favorites are read again from Radio Browser (stream check, bitrate, logo), in one request for all of them. 15 to 360 minutes: the directory checks each stream about once a day.

How to install Radio Browser in Gladys​

  1. In Gladys, open Integrations: Radio Browser appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-radio-browser:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-radio-browser.

Radio Browser requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Radio Browser is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on