Playlist parsers

Liquidsoap supports various playlist formats. Those formats can be used for playlist sources and manually using request.create.

Supported formats

Most supported playlist formats are strict, which means that the decoder can be sure that it has found a correct playlist for that format. Some other formats, such as m3u, however, may cause false positive detections.

All formats are identified by their mime-type or content-type. Supported formats are the following:

• Text formats:

  • audio/x-scpls: PLS format, strict
  • application/x-cue: CUE format, strict. This format's usage is described below.
  • audio/x-mpegurl, audio/mpegurl, application/x-mpegURL: M3U, non strict

• XML formats:

  • video/x-ms-asf, audio/x-ms-asx: ASX, strict
  • application/smil, application/smil+xml: SMIL, strict
  • application/xspf+xml: XSPF, strict
  • application/rss+xml: Podcast, strict

Playlist format is driven by the Content-Type and Content-Disposition HTTP headers (see m3u example below). You should make sure that your HTTP endpoint returns appropriate values for those.

As a last resort, you should be able to use the settings.http.mime.extnames setting to add or adjust support for your endpoint's mime-type if liquidsoap supports its corresponding playlist format. See for instance issue #3451.

Usage

Playlist files are parsed automatically when used in a playlist operator. This operator has specific options to specify how to pick up a track from the playlist, e.g. pick a random track, the first one, etc.

Additionally, you can also manually parse and process a playlist using request.create and request.resolve and some programming magic. You can check the source code of playlist.files in our standard library for a detailed example.

Remote M3U playlist example

Here is an example of an m3u playlist being read from nodejs/express.

Liquidsoap script:

#!/usr/local/bin/liquidsoap

p = playlist(reload=10, "http://localhost:8080/radio/playlists/0/playlist.m3u")

Node.js/Express app:

import express from "express";

const app = express();

app.get("/radio/playlists/:id/playlist.m3u", async (req, res) => {
  const playlist = ["/media/foo.mp3", "/media/bar.mp3"];

  // Liquidsoap will use the file extension from the `Content-Disposition` header to guess
  // the playlist format
  res.set(
    "Content-Disposition",
    `attachment; filename="playlist-${req.params.id}.m3u"`,
  );

  // Otherwise, it will try to guess the file extension from the playlist mime-type.
  res.set("Content-Type", "audio/x-mpegurl");
  res
    .send(playlist.join("\r\n") + "\r\n")
    .status(200)
    .end();
});

const server = app.listen(8080);

Special case: CUE format

The CUE format originates from CD burning programs. A CUE file describes the set of tracks of a whole CD and is accompanied by a single file containing audio data for the whole CD.

By default, the CUE playlist parser will add metadata from cue-in and cue-out points for each track described in the playlist, which are automatically handled with source-based operators such as playlist.

The metadata added for cue-in and cue-out positions can be customized using the following configuration keys:

settings.playlist.cue_in_metadata := "liq_cue_in"
settings.playlist.cue_out_metadata := "liq_cue_out"