# 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/`.

## 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.

```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
}
```

### 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.

```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": 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.

```json
{
  "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.

```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"
    }
  }
}