diff --git a/deezspot/models/callback/album.py b/deezspot/models/callback/album.py index b78a25f..5ae4d31 100644 --- a/deezspot/models/callback/album.py +++ b/deezspot/models/callback/album.py @@ -33,7 +33,6 @@ class trackAlbumObject: genres: List[str] = field(default_factory=list) ids: IDs = field(default_factory=IDs) artists: List[artistTrackAlbumObject] = field(default_factory=list) - explicit: bool = False @dataclass diff --git a/docs/callback_examples.md b/docs/callback_examples.md new file mode 100644 index 0000000..e3d5ca3 --- /dev/null +++ b/docs/callback_examples.md @@ -0,0 +1,673 @@ +# 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/`. + +## `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. + +```json +{ + "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 +} +``` + +### Status: `skipped` + +Indicates that the track was skipped. + +```json +{ + "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. + +```json +{ + "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. + +```json +{ + "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. + +```json +{ + "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. + +```json +{ + "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` + +```json +{ + "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. + +```json +{ + "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` + +```json +{ + "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. + +```json +{ + "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" + } + } +} \ No newline at end of file