deezspot-spotizerr-dev/docs/callback_examples.md

Callback JSON Examples

This document provides examples for all possible callback JSON objects as generated by deezspot. These examples are based on the dataclasses defined in deezspot/models/callback/.

These callbacks are service-agnostic, which means they will have the same exact format regardless of the service used. Basically: one interface to rule them both.

However, don't be so confident this will perfectly unify both service's APIs, since there are still key differences in the metadata itself, for example: in spotify, certain band shows up as Maná but in deezer it shows up as Mana. There's really nothing to be done in those cases other than deal with it, since the inconsistency is not a matter of how the services store their data but literally what data they store.

Naming Convention

The data models in deezspot/models/callback/ follow a specific naming convention to clarify the context of nested objects. The pattern is generally childContext1Context2...Object. This reads as "A child object representation when nested inside a Context1 object, which itself is in a Context2 context, and so on."

For example:

• playlistTrackObject: This represents a playlist object within a track reporting context. It's a simplified version of a full playlistObject and is used as the parent for a track being processed as part of a playlist operation (more on what a "parent" is later).
• artistAlbumTrackPlaylistObject: This represents an artist object, nested within an album object, which is inside a track object that is part of a playlist. This shows the full hierarchy of contexts.

trackCallbackObject Examples

A trackCallbackObject is sent to provide updates on the status of a single track's processing.

Status: initializing

Indicates that the track processing is starting.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [
        {
          "height": 640,
          "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
          "width": 640
        }
      ],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": [
        {
          "type": "artistAlbumTrack",
          "name": "Queen",
          "ids": {
            "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
            "deezer": "412"
          }
        }
      ]
    },
    "artists": [
      {
        "type": "artistTrack",
        "name": "Queen",
        "ids": {
          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
          "deezer": "412"
        }
      }
    ],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "initializing",
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

Track with Parent Context

When a track is processed as part of a larger operation (like downloading an album or playlist), the parent field in the trackCallbackObject will be populated. This provides context about the containing entity. current_track and total_tracks will also be populated accordingly.

Parent: albumTrackObject

This example shows a track being processed as part of an album download. The parent is an albumTrackObject, which provides a summary of the album. The current_track and total_tracks fields reflect the progress within that album.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": [
      "Rock"
    ],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": [
        "Rock"
      ],
      "images": [
        {
          "height": 640,
          "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
          "width": 640
        }
      ],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": [
        {
          "type": "artistAlbumTrack",
          "name": "Queen",
          "ids": {
            "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
            "deezer": "412"
          }
        }
      ]
    },
    "artists": [
      {
        "type": "artistTrack",
        "name": "Queen",
        "ids": {
          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
          "deezer": "412"
        }
      }
    ],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "initializing",
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 2,
  "total_tracks": 12,
  "parent": {
    "type": "albumTrack",
    "album_type": "album",
    "title": "A Night at the Opera",
    "release_date": {
      "year": 1975,
      "month": 11,
      "day": 21
    },
    "total_tracks": 12,
    "genres": [
      "Rock"
    ],
    "images": [
      {
        "height": 640,
        "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
        "width": 640
      }
    ],
    "ids": {
      "spotify": "6l8GvAOfAccdwJAIF13j3m",
      "deezer": "11223344"
    },
    "artists": [
      {
        "type": "artistAlbumTrack",
        "name": "Queen",
        "ids": {
          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
          "deezer": "412"
        }
      }
    ]
  }
}

Parent: playlistTrackObject

This example shows a track being processed as part of a playlist download. The parent is a playlistTrackObject, which provides a summary of the playlist.

{
  "track": {
    "type": "track",
    "title": "Stairway to Heaven",
    "disc_number": 1,
    "track_number": 4,
    "duration_ms": 482830,
    "explicit": false,
    "genres": [
      "Rock"
    ],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "Led Zeppelin IV",
      "release_date": {
        "year": 1971,
        "month": 11,
        "day": 8
      },
      "total_tracks": 8,
      "genres": [
        "Rock",
        "Hard Rock"
      ],
      "images": [],
      "ids": {
        "spotify": "1J8mRIzSgWvztCMj2Y3GJc"
      },
      "artists": [
        {
          "type": "artistAlbumTrack",
          "name": "Led Zeppelin",
          "ids": {
            "spotify": "36QJpDe2go2KgaRleHCDls"
          }
        }
      ]
    },
    "artists": [
      {
        "type": "artistTrack",
        "name": "Led Zeppelin",
        "ids": {
          "spotify": "36QJpDe2go2KgaRleHCDls"
        }
      }
    ],
    "ids": {
      "spotify": "5CQ30WqJwcep0pYcV4AMNc",
      "isrc": "US-AT2-00-00435"
    }
  },
  "status_info": {
    "status": "initializing",
    "ids": {
      "spotify": "5CQ30WqJwcep0pYcV4AMNc"
    },
    "convert_to": "mp3",
    "bitrate": "320"
  },
  "current_track": 5,
  "total_tracks": 50,
  "parent": {
    "type": "playlistTrack",
    "title": "Classic Rock Anthems",
    "description": "The greatest rock songs of all time.",
    "owner": {
      "name": "Spotify",
      "type": "user",
      "ids": {
        "spotify": "spotify"
      }
    },
    "ids": {
      "spotify": "37i9dQZF1DX1rVvRgjX59F"
    }
  }
}

Status: skipped

Indicates that the track was skipped.

{
  "track": {
    "type": "track",
    "title": "Interlude",
    "disc_number": 1,
    "track_number": 8,
    "duration_ms": 60000,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": []
    },
    "artists": [],
    "ids": {
      "spotify": "5v6tU25G4kZ1gL9v3b1z7p",
      "deezer": "9876544",
      "isrc": "GBUM71021260"
    }
  },
  "status_info": {
    "status": "skipped",
    "reason": "Track is shorter than minimum duration.",
    "ids": {
      "spotify": "5v6tU25G4kZ1gL9v3b1z7p"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

Status: retrying

Indicates a temporary failure, and a retry is scheduled.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": []
    },
    "artists": [],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "retrying",
    "retry_count": 1,
    "seconds_left": 30,
    "error": "Network connection lost.",
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

Status: real-time

Provides real-time progress of the download/conversion.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": []
    },
    "artists": [],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "real-time",
    "time_elapsed": 15,
    "progress": 50,
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

Status: error

Indicates a fatal error occurred during processing.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": []
    },
    "artists": [],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "error",
    "error": "Track not available in specified quality.",
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

Status: done

Indicates that the track has been processed successfully.

{
  "track": {
    "type": "track",
    "title": "Bohemian Rhapsody",
    "disc_number": 1,
    "track_number": 7,
    "duration_ms": 354320,
    "explicit": false,
    "genres": ["Rock"],
    "album": {
      "type": "albumTrack",
      "album_type": "album",
      "title": "A Night at the Opera",
      "release_date": {
        "year": 1975,
        "month": 11,
        "day": 21
      },
      "total_tracks": 12,
      "genres": ["Rock"],
      "images": [],
      "ids": {
        "spotify": "6l8GvAOfAccdwJAIF13j3m",
        "deezer": "11223344"
      },
      "artists": []
    },
    "artists": [],
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8",
      "deezer": "9876543",
      "isrc": "GBUM71021259"
    }
  },
  "status_info": {
    "status": "done",
    "summary": null,
    "ids": {
      "spotify": "4u7EnebtmKWzANvK9IClu8"
    },
    "convert_to": "flac",
    "bitrate": "1411"
  },
  "current_track": 1,
  "total_tracks": 1,
  "parent": null
}

albumCallbackObject Examples

An albumCallbackObject provides status updates for a whole album.

Status: initializing

{
  "album": {
    "type": "album",
    "album_type": "album",
    "title": "A Night at the Opera",
    "release_date": {
      "year": 1975,
      "month": 11,
      "day": 21
    },
    "total_tracks": 12,
    "genres": ["Rock"],
    "images": [
      {
        "height": 640,
        "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
        "width": 640
      }
    ],
    "copyrights": [
      {
        "text": "© 1975 Queen Productions Ltd",
        "type": "C"
      }
    ],
    "ids": {
      "spotify": "6l8GvAOfAccdwJAIF13j3m",
      "deezer": "11223344",
      "upc": "00050087328753"
    },
    "tracks": [
      {
        "type": "trackAlbum",
        "title": "Bohemian Rhapsody",
        "disc_number": 1,
        "track_number": 7,
        "duration_ms": 354320,
        "explicit": false,
        "genres": ["Rock"],
        "ids": {
          "spotify": "4u7EnebtmKWzANvK9IClu8",
          "deezer": "9876543",
          "isrc": "GBUM71021259"
        },
        "artists": [
          {
            "type": "artistTrackAlbum",
            "name": "Queen",
            "ids": {
              "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
              "deezer": "412"
            }
          }
        ]
      }
    ],
    "artists": [
      {
        "type": "artistAlbum",
        "name": "Queen",
        "genres": ["Rock"],
        "ids": {
          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
          "deezer": "412"
        }
      }
    ]
  },
  "status_info": {
    "status": "initializing",
    "ids": {
      "spotify": "6l8GvAOfAccdwJAIF13j3m"
    },
    "convert_to": "flac",
    "bitrate": null
  }
}

Status: done

The done status for an album includes a summary of all track operations.

{
  "album": {
    "type": "album",
    "album_type": "album",
    "title": "A Night at the Opera",
    "release_date": {
      "year": 1975,
      "month": 11,
      "day": 21
    },
    "total_tracks": 12,
    "genres": ["Rock"],
    "images": [],
    "copyrights": [],
    "ids": {
      "spotify": "6l8GvAOfAccdwJAIF13j3m",
      "deezer": "11223344",
      "upc": "00050087328753"
    },
    "tracks": [],
    "artists": []
  },
  "status_info": {
    "status": "done",
    "summary": {
      "successful_tracks": [
        {
          "type": "track",
          "title": "Bohemian Rhapsody",
          "disc_number": 1,
          "track_number": 7,
          "duration_ms": 354320,
          "explicit": false,
          "genres": ["Rock"],
          "album": {
            "type": "albumTrack",
            "album_type": "album",
            "title": "A Night at the Opera",
            "release_date": {"year": 1975, "month": 11, "day": 21},
            "total_tracks": 12,
            "genres": ["Rock"],
            "images": [],
            "ids": {"spotify": "6l8GvAOfAccdwJAIF13j3m"},
            "artists": []
          },
          "artists": [{"type": "artistTrack", "name": "Queen", "ids": {"spotify": "1dfeR4HaWDbWqFHLkxsg1d"}}],
          "ids": {"spotify": "4u7EnebtmKWzANvK9IClu8", "isrc": "GBUM71021259"}
        }
      ],
      "skipped_tracks": [],
      "failed_tracks": [],
      "total_successful": 1,
      "total_skipped": 0,
      "total_failed": 0
    },
    "ids": {
      "spotify": "6l8GvAOfAccdwJAIF13j3m"
    }
  }
}

playlistCallbackObject Examples

A playlistCallbackObject provides status updates for a playlist.

Status: initializing

{
  "playlist": {
    "type": "playlist",
    "title": "Classic Rock Anthems",
    "description": "The greatest rock songs of all time.",
    "owner": {
      "name": "Spotify",
      "type": "user",
      "ids": {
        "spotify": "spotify"
      }
    },
    "tracks": [
      {
        "type": "trackPlaylist",
        "title": "Stairway to Heaven",
        "position": 1,
        "duration_ms": 482830,
        "artists": [
          {
            "type": "artistTrackPlaylist",
            "name": "Led Zeppelin",
            "ids": {
              "spotify": "36QJpDe2go2KgaRleHCDls"
            }
          }
        ],
        "album": {
          "type": "albumTrackPlaylist",
          "album_type": "album",
          "title": "Led Zeppelin IV",
          "release_date": {"year": 1971, "month": 11, "day": 8},
          "total_tracks": 8,
          "images": [],
          "ids": {
            "spotify": "1J8mRIzSgWvztCMj2Y3GJc"
          },
          "artists": []
        },
        "ids": {
          "spotify": "5CQ30WqJwcep0pYcV4AMNc",
          "isrc": "US-AT2-00-00435"
        },
        "disc_number": 1,
        "track_number": 4,
        "explicit": false
      }
    ],
    "images": [],
    "ids": {
      "spotify": "37i9dQZF1DX1rVvRgjX59F"
    }
  },
  "status_info": {
    "status": "initializing",
    "ids": {
      "spotify": "37i9dQZF1DX1rVvRgjX59F"
    },
    "convert_to": "mp3",
    "bitrate": "320"
  }
}

Status: done

The done status for a playlist includes a summary of all track operations.

{
  "playlist": {
    "type": "playlist",
    "title": "Classic Rock Anthems",
    "description": "The greatest rock songs of all time.",
    "owner": {
      "name": "Spotify",
      "type": "user",
      "ids": {
        "spotify": "spotify"
      }
    },
    "tracks": [],
    "images": [],
    "ids": {
      "spotify": "37i9dQZF1DX1rVvRgjX59F"
    }
  },
  "status_info": {
    "status": "done",
    "summary": {
      "successful_tracks": [
        {
          "type": "track",
          "title": "Stairway to Heaven",
          "disc_number": 1,
          "track_number": 4,
          "duration_ms": 482830,
          "explicit": false,
          "genres": [],
          "album": {
            "type": "albumTrack",
            "album_type": "album",
            "title": "Led Zeppelin IV",
            "release_date": {"year": 1971, "month": 11, "day": 8},
            "total_tracks": 8,
            "genres": [],
            "images": [],
            "ids": {"spotify": "1J8mRIzSgWvztCMj2Y3GJc"},
            "artists": []
          },
          "artists": [
            {"type": "artistTrack", "name": "Led Zeppelin", "ids": {"spotify": "36QJpDe2go2KgaRleHCDls"}}
          ],
          "ids": {"spotify": "5CQ30WqJwcep0pYcV4AMNc", "isrc": "US-AT2-00-00435"}
        }
      ],
      "skipped_tracks": [],
      "failed_tracks": [
        {
          "track": {
            "type": "track",
            "title": "Another Brick in the Wall, Pt. 2",
            "disc_number": 1,
            "track_number": 5,
            "duration_ms": 239000,
            "explicit": false,
            "genres": [],
            "album": {
                "type": "albumTrack",
                "album_type": "album",
                "title": "The Wall",
                "release_date": {"year": 1979},
                "total_tracks": 26,
                "genres": [],
                "images": [],
                "ids": {"spotify": "5Dbax7G8SWrP9xyzkOvy2F"},
                "artists": []
            },
            "artists": [
              {"type": "artistTrack", "name": "Pink Floyd", "ids": {"spotify": "0k17h0D3J5Vfs3UeZzLahq"}}
            ],
            "ids": {"spotify": "4gMgiXfqyzZLMhsksGmbQV", "isrc": "TCABM1559814"}
          },
          "reason": "Could not find a match on Deezer."
        }
      ],
      "total_successful": 1,
      "total_skipped": 0,
      "total_failed": 1
    },
    "ids": {
      "spotify": "37i9dQZF1DX1rVvRgjX59F"
    }
  }
}