Flows & Playlists

Aurral supports both dynamic, weekly refreshing music discovery (Flows) and static, imported sets of music (Playlists). Here is how they differ and how to use them.

Flows

Dynamic, recommended playlists that refresh automatically every week based on your listening context.

  • Generated automatically
  • Replaced entirely on refresh
  • Can generate replacement tracks if initial downloads fail

Playlists

Static tracklists imported from JSON files (like converted Spotify playlists).

  • Imported manually
  • Kept separate from flow refreshes
  • Will retry exact tracks forever, never replacing them

Playlist Imports

Aurral accepts imported playlists via JSON files. You can convert your existing Spotify playlists into this format using our CSV to JSON converter.

Required Fields

Each track in your JSON must include the artist name and track name. We accept a variety of aliases to make importing easier:

Download Retries

When a playlist track fails to download, Aurral behaves differently than it does for Flows:

  • Retryable failures get an immediate retry with a backoff delay.
  • If a playlist is incomplete and has no active jobs, failed tracks are requeued every ~15 minutes.
  • Imported playlists will always retry the exact tracks you imported; they will never generate replacement tracks like Flows do.

JSON Formats

The importer is flexible and accepts several JSON shapes. If you are writing your own scripts or modifying files by hand, you can use any of these formats.

1. Single Playlist Object

{
  "name": "My Playlist",
  "tracks": [
    { "artistName": "Massive Attack", "trackName": "Teardrop" },
    { "artistName": "Portishead", "trackName": "Roads" }
  ]
}

2. Raw Array of Tracks

A top-level array of track objects is treated as one single playlist. (This is what our CSV converter generates). 

[
  { "artistName": "Burial", "trackName": "Archangel" },
  { "artistName": "Air", "trackName": "La Femme d'Argent" }
]

3. Multi-Playlist Bundle

You can import multiple playlists at once by providing an array of playlist objects. 

{
  "playlists": [
    {
      "name": "Warm",
      "tracks": [
        { "artistName": "Bonobo", "trackName": "Kiara" }
      ]
    },
    {
      "name": "Dark",
      "tracks": [
        { "artistName": "Burial", "trackName": "Near Dark" }
      ]
    }
  ]
}

4. Aurral Export Format

Aurral can also re-import the exact files it exports.

{
  "type": "aurral-static-tracklist",
  "version": 1,
  "name": "Late Night Finds",
  "tracks": [
    {
      "artistName": "Burial",
      "trackName": "Archangel",
      "albumName": "Untrue"
    }
  ]
}