RadioBrowser (RadioBrowser v0.2.0)

View Source

Client for the Radio Browser API (https://api.radio-browser.info/).

This module provides a GenServer-based client to interact with the Radio Browser API, allowing you to search, play, and manage radio stations from a worldwide directory.

Features

  • Search radio stations by various criteria (name, country, language, etc.)
  • Play radio stations
  • Vote for stations
  • Track station clicks
  • Access station metadata and statistics
  • Fetch faceted data (tags, countries, languages, etc.)

Usage

Start the client as part of your supervision tree:

children = [
  RadioBrowser
]
Supervisor.start_link(children, strategy: :one_for_one)

Then use the various functions to interact with radio stations:

# Search for stations
RadioBrowser.search(name: "jazz", country: "US")

# Play a station
RadioBrowser.play("station-uuid")

Summary

Functions

Returns a specification to start this module under a supervisor.

Records a click event for a radio station.

Returns a list of URI structs for radio-browser API servers.

Retrieves faceted data from the API.

Retrieves a random API server from the pool of available servers.

Plays a radio station and records a click event.

Searches for radio stations using the provided parameters.

Searches for radio stations by country code.

Searches for radio stations by name.

Starts the RadioBrowser client.

Votes for a radio station.

Types

search_params()

@type search_params() :: %{
  optional(:name) => String.t(),
  optional(:name_exact) => boolean(),
  optional(:country) => String.t(),
  optional(:country_exact) => boolean(),
  optional(:countrycode) => String.t(),
  optional(:state) => String.t(),
  optional(:state_exact) => boolean(),
  optional(:language) => String.t(),
  optional(:language_exact) => boolean(),
  optional(:tag) => String.t(),
  optional(:tag_exact) => boolean(),
  optional(:tag_list) => String.t(),
  optional(:bitrate_min) => integer(),
  optional(:bitrate_max) => integer(),
  optional(:order) => String.t(),
  optional(:reverse) => boolean(),
  optional(:offset) => integer(),
  optional(:limit) => integer(),
  optional(:hidebroken) => boolean()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

click(station_uuid)

Records a click event for a radio station.

Click events are used to track station popularity and generate statistics. This is automatically called by play/1 but can be called manually if needed.

Parameters

  • station_uuid - The UUID of the station that was clicked

Return Values

Returns the click response from the API.

discover_servers()

@spec discover_servers() :: [String.t()]

Returns a list of URI structs for radio-browser API servers.

get_facet(facet)

Retrieves faceted data from the API.

Facets are pre-aggregated lists of values that can be used for filtering and navigation. Available facets are: ["tags", "countries", "languages", "codecs", "states"]

Parameters

  • facet - Name of the facet to retrieve (atom or string)

Return Values

  • List of facet values if the facet exists
  • {:error, reason} if the facet is invalid

get_server()

Retrieves a random API server from the pool of available servers.

This is mainly used internally but can be useful for debugging purposes.

Return Values

Returns a URI struct representing the server address.

play(station_uuid)

Plays a radio station and records a click event.

This function does two things:

  1. Returns the station information immediately
  2. Asynchronously records a click event for the station

Parameters

  • station_uuid - The UUID of the station to play

Return Values

Returns the station information if found, or an error if the station doesn't exist.

search(opts)

@spec search(keyword()) :: {:ok, list()} | {:error, term()}

Searches for radio stations using the provided parameters.

Parameters

  • opts - Keyword list of search parameters:
    • :name - (String) Station name to search for
    • :name_exact - (Boolean) Whether to match the name exactly
    • :country - (String) Country name to filter by
    • :country_exact - (Boolean) Whether to match the country exactly
    • :countrycode - (String) ISO country code to filter by
    • :state - (String) State/region to filter by
    • :state_exact - (Boolean) Whether to match the state exactly
    • :language - (String) Language to filter by
    • :language_exact - (Boolean) Whether to match the language exactly
    • :tag - (String) Tag to filter by
    • :tag_exact - (Boolean) Whether to match the tag exactly
    • :tag_list - (String) Comma-separated list of tags
    • :bitrate_min - (Integer) Minimum bitrate in kbps
    • :bitrate_max - (Integer) Maximum bitrate in kbps
    • :order - (String) Field to order by (see @valid_order_fields)
    • :reverse - (Boolean) Whether to reverse the order
    • :offset - (Integer) Number of results to skip
    • :limit - (Integer) Maximum number of results to return
    • :hidebroken - (Boolean) Whether to hide broken stations

Return Values

  • {:ok, stations} - List of stations matching the search criteria
  • {:error, reason} - If the search failed

search_by_countrycode(countrycode)

Searches for radio stations by country code.

This is a convenience wrapper around search/1 that automatically uppercases the country code.

Parameters

  • countrycode - ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")

Return Values

Same as search/1

search_by_name(name)

Searches for radio stations by name.

This is a convenience wrapper around search/1 that performs a non-exact name search.

Parameters

  • name - Name or partial name of the station to search for

Return Values

Same as search/1

start_link(opts \\ [])

Starts the RadioBrowser client.

This function starts a GenServer process that maintains the connection to the Radio Browser API and handles all API requests. The process is registered under the module name.

Options

Currently no options are supported, but they may be added in future versions.

Return Values

  • {:ok, pid} - If the process was started successfully
  • {:error, reason} - If the process could not be started

vote(station_uuid)

Votes for a radio station.

Each client can vote for a station once within 24 hours. Votes help determine station popularity and rankings.

Parameters

  • station_uuid - The UUID of the station to vote for

Return Values

  • {:ok, response} - If the vote was recorded successfully
  • {:error, reason} - If the vote could not be recorded