JDM170/deezspot-spotizerr-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

enhance documentation

Browse Source
This commit is contained in:
Xoconoch
2025-06-11 11:43:10 -06:00
parent ac120683e2
commit ccbaf5ff8c
1 changed files with 214 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
docs/callback_examples.md
View File

@@ -2,6 +2,15 @@
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.
* `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.
@@ -83,6 +92,211 @@ Indicates that the track processing is starting.
}
```
### 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.