Pipeline File Format

Pipelines can be defined in YAML or JSON format. This page documents the structure and available options.

Basic Structure

name: My Pipeline
tasks:
  - type: taskType
    # task-specific options
  - type: anotherTask
    # task-specific options

Fields

Field	Type	Required	Description
name	string	Yes	Name of the pipeline
tasks	array	Yes	List of tasks to execute in order

Task Types

Source Tasks

getPlaylistTracks

Fetch tracks from a Spotify playlist.

- type: getPlaylistTracks
  playlistId: "37i9dQZF1DXcBWIGoYBM5M"

Option	Type	Required	Description
playlistId	string	Yes	Spotify playlist ID or URI

getSavedTracks

Fetch the user’s liked/saved tracks.

- type: getSavedTracks

No options required.

getAlbumTracks

Fetch tracks from an album.

- type: getAlbumTracks
  albumId: "4aawyAB9vmqN3uQ7FjRGTy"

Option	Type	Required	Description
albumId	string	Yes	Spotify album ID or URI

getArtistTopTracks

Fetch an artist’s top tracks.

- type: getArtistTopTracks
  artistId: "0OdUWJ0sBjDrqHygGUXeCF"

Option	Type	Required	Description
artistId	string	Yes	Spotify artist ID or URI

Transform Tasks

filterTracks

Filter tracks by criteria.

- type: filterTracks
  field: releaseDate
  operator: after
  value: "2024-01-01"

Option	Type	Required	Description
field	string	Yes	Field to filter on
operator	string	Yes	Comparison operator
value	string	Yes	Value to compare against

Fields: name, artist, album, releaseDate, popularity, duration, explicit

Operators: equals, contains, startsWith, endsWith, after, before, greaterThan, lessThan

sortTracks

Sort tracks by a field.

- type: sortTracks
  field: popularity
  order: descending

Option	Type	Required	Description
field	string	Yes	Field to sort by
order	string	No	ascending (default) or descending

shuffleTracks

Randomize track order.

- type: shuffleTracks

No options required.

reverseTracks

Reverse the track order.

- type: reverseTracks

No options required.

deduplicateTracks

Remove duplicate tracks.

- type: deduplicateTracks
  strategy: byTrackId

Option	Type	Required	Description
strategy	string	No	byTrackId (default) or byNameAndArtist

limitTracks

Keep only the first N tracks.

- type: limitTracks
  limit: 50

Option	Type	Required	Description
limit	number	Yes	Maximum number of tracks to keep

skipTracks

Skip the first N tracks.

- type: skipTracks
  count: 10

Option	Type	Required	Description
count	number	Yes	Number of tracks to skip

mergeTracks

Combine tracks from multiple sources. Place this after multiple source tasks.

- type: mergeTracks

No options required.

Output Tasks

saveToPlaylist

Save tracks to a Spotify playlist.

- type: saveToPlaylist
  playlistId: "your-playlist-id"
  mode: replace

Or create a new playlist:

- type: saveToPlaylist
  name: "My New Playlist"
  mode: replace

Option	Type	Required	Description
playlistId	string	No*	Existing playlist ID
name	string	No*	Name for new playlist
mode	string	No	replace (default) or append

*Either playlistId or name is required.

Complete Example

name: Weekly Top 50
tasks:
  # Get tracks from multiple sources
  - type: getPlaylistTracks
    playlistId: "37i9dQZEVXcQ9COmYvdajy"
  - type: getSavedTracks

  # Combine and process
  - type: mergeTracks
  - type: deduplicateTracks
    strategy: byNameAndArtist
  - type: filterTracks
    field: releaseDate
    operator: after
    value: "2024-01-01"
  - type: sortTracks
    field: popularity
    order: descending
  - type: limitTracks
    limit: 50

  # Save result
  - type: saveToPlaylist
    name: "My Weekly Top 50"
    mode: replace

JSON Format

The same pipeline in JSON:

{
  "name": "Weekly Top 50",
  "tasks": [
    { "type": "getPlaylistTracks", "playlistId": "37i9dQZEVXcQ9COmYvdajy" },
    { "type": "getSavedTracks" },
    { "type": "mergeTracks" },
    { "type": "deduplicateTracks", "strategy": "byNameAndArtist" },
    { "type": "filterTracks", "field": "releaseDate", "operator": "after", "value": "2024-01-01" },
    { "type": "sortTracks", "field": "popularity", "order": "descending" },
    { "type": "limitTracks", "limit": 50 },
    { "type": "saveToPlaylist", "name": "My Weekly Top 50", "mode": "replace" }
  ]
}