# Playlist parsers

Liquidsoap supports various playlists formats. Those formats can be used for `playlist` sources, `input.http` streams and manually using `request.create`.

## Supported formats

Most supported playlists format are strict, which means that the decoder can be sure that is has found a correct playlist for that format. Some other format, 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`: M3U, non strict
- Xml formats:
  - `video/x-ms-asf`, `audio/x-ms-asx`: ASX, strict
  - `application/smil+xml`, `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 last resort, you should be able to use the `settings.http.mime.extnames` settings 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` or `input.http` operator. Each of these two operators 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 code source for `playlist.reloadable` in our standard library for a detailed example.

### Remote M3U playlist example

Here is an example of a 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")

nodejs/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. They describe the set of tracks of a whole CD and are 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-base operators such as `playlist`.

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

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