In this guide we discuss how local files are exposed in the Spotify Web API Playlist endpoints.

What Are Local Files?

Spotify allows you to play your own collection of music files from within the Spotify client. These tracks appear alongside the music available on Spotify and can be included in users’ playlists, even if that particular track is not available on Spotify itself. For more information on local files, please read our support article.

The Web API can retrieve the contents of playlists, including information on any local files that have been added, via the playlist endpoints.

Identifying Local Files

Requesting the contents of a playlist returns a set of track objects along with extra information about that track’s instance in the playlist. For example:

{
  "added_at": "2015-01-25T07:51:45Z",
  "added_by": {
    "external_urls": {
    "spotify": "http://open.spotify.com/user/exampleuser"
  },
  "href": "https://api.spotify.com/v1/users/exampleuser",
  "id": "exampleuser",
  "type": "user",
  "uri": "spotify:user:exampleuser"
},
"is_local": true,
"track": {
  [Spotify Track Object]
}

The key part here is the new property "is_local" which should be used to determine whether the track is a local file.

The Track Object for a Local File

The structure of a Spotify track object for a local file is identical to that of a regular Spotify track, with some notable differences in available data:

  • A number of fields will always be empty, zero, false or null
  • Some fields are populated from available local file information
  • The track URI has a special formatting
  "track": {
   "album": {
     "album_type": null,
     "available_markets": [],
     "external_urls": {},
     "href": null,
     "id": null,
     "images": [],
     "name": "Donkey Kong Country: Tropical Freeze",
     "type": "album",
     "uri": null
   },
   "artists": [
     {
       "external_urls": {},
       "href": null,
       "id": null,
       "name": "David Wise",
       "type": "artist",
       "uri": null
     }
   ],
   "available_markets": [],
   "disc_number": 0,
   "duration_ms": 127000,
   "explicit": false,
   "external_ids": {},
   "external_urls": {},
   "href": null,
   "id": null,
   "name": "Snomads Island",
   "popularity": 0,
   "preview_url": null,
   "track_number": 0,
   "type": "track",
   "uri": "spotify:local:David+Wise:Donkey+Kong+Country%3A+Tropical+Freeze:Snomads+Island:127"
 }
}

The local file information is read by the client software when the file was added to the playlist. Although as much information as possible is taken from the local file, some may be missing so this information is not guaranteed to exist for all local files.

Understanding the Local File URI

The local file URI is constructed from information extracted from the local file when it was added to the playlist as follows:

spotify:local:{artist}:{album_title}:{track_title}:{duration_in_seconds}

All available information is also used to populate the object album name, artist name, track name and track duration properties, so parsing this directly should not be necessary.

How Should I Render Local Files to the User?

Whether you display these files to your app’s users is entirely dependent on the functionality that you require in your app. Initially, you could “grey out” the tracks or hide them altogether. If you have access to the filesystem, you could use the information to match the track to the file and replicate the Spotify clients’ behaviour. Or perhaps use the title and artist information to perform a search in the Spotify catalogue.

Limitations

It is not currently possible to add local files to playlists using the Web API, but they can be reordered or removed. The latter should be done by specifying the index and snapshot_id, and NOT the URI of the track.