RadioBrowser (RadioBrowser v0.1.0)
View SourceClient 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
@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
Returns a specification to start this module under a supervisor.
See Supervisor
.
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.
@spec discover_servers() :: [String.t()]
Returns a list of URI structs for radio-browser API servers.
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
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.
Plays a radio station and records a click event.
This function does two things:
- Returns the station information immediately
- 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.
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
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
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
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
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