Skip to main content
Version: Stable 3.x

LibreTime API usage

info

We're in the process of rewriting LibreTime's API. This page contains the instructions for the current version, written in PHP.

The LibreTime API enables many types of information about the broadcast schedule and configuration to be retrieved from the LibreTime server. Other than the live-info and week-info data fetched by website widgets (see the chapter Exporting the schedule), all API requests must be authenticated using the secret API key stored in the file /etc/libretime/api_client.cfg on the LibreTime server. This key is autogenerated during LibreTime installation and should be unique for each server.

If you intend to use the LibreTime API across a public network, for security reasons it's highly recommended that all API requests are sent over encrypted https: and that the web server is configured to accept requests to the api/ directory from specific host names or IP addresses only.

The format of API requests is:

https://libretime.example.org/api/api-action/format/json/api_key/XXXXXX

where api-action is the type of request and XXXXXX is the secret API key. Available actions include:

  • on-air-light - return true if the station is on air
  • status - get the status of LibreTime components and resource usage
  • version - returns the version of LibreTime installed
  • get-files-without-silan-value - list files for which silence detection hasn't yet been performed
  • get-stream-setting - gets the settings of LibreTime output streams
  • get-stream-parameters - gets the parameters of LibreTime output streams

For example, using the action get-stream-setting returns the following output for the first configured stream:

{"keyname":"s1_type","value":"ogg","type":"string"},

{"keyname":"s1_host","value":"streaming.example.com","type":"string"},

{"keyname":"s1_port","value":"8000","type":"integer"},

{"keyname":"s1_mount","value":"main","type":"string"},

{"keyname":"s1_url","value":"http:\/\/airtime.sourcefabric.org","type":"string"},

{"keyname":"s1_description","value":"Airtime Radio! Stream #1","type":"string"},

{"keyname":"s1_genre","value":"Screamo","type":"string"},

which is enough information to construct a player widget dynamically. (s1_url is the station's homepage, not the stream URL). The same information is provided with an s2_ prefix for the second stream, and s3_ prefix for the third stream.

Some API requests require the directory ID number to be specified as dir_id including:

  • list-all-files - list files in the specified directory
  • get-files-without-replay-gain - list files in the specified directory for which ReplayGain hasn't been calculated yet

For example, using a request such as:

http://libretime.example.org/api/list-all-files/format/json/api_key/XXXXXX/dir_id/1/

returns the full path to each media file in the LibreTime storage directory:

{
  "files": [
    "imported/1/Mark Ronson feat. Saigon/Here Comes the Fuzz/7-Diduntdidunt-unknown.flac",
    "imported/1/Jimi Tenor & Tony Allen/Inspiration Information/3-Selfish Gene-128kbps.mp3"
  ]
}