DownloadController Documentation

The DownloadController provides several API endpoints that allow users to download tracks, and track/album/artist/playlist/collection artwork. The controller supports both direct downloads and transcoding to mp3 on the fly. When downloading artwork, if the linked object isn't found or artwork isn't found for it, the default artwork is sent. See Artwork Architecture for more info.

Controller Route: `/api/download`

All routes within the DownloadController are prefixed by /api/download/ and are primarily used for downloading media-related content such as tracks and artwork.

Summary of Endpoints

Endpoint	Method	Description	Authorization
`/api/download/track`	GET	Download a track file based on its ID.	Admin, User
`/api/download/track-transcode`	GET	Download a transcoded version of a track.	Admin, User
`/api/download/track-wave`	GET	Get the waveform of a track in a specified width.	Admin, User
`/api/download/track-art`	GET	Download the artwork associated with a specific track.	Admin, User
`/api/download/album-art`	GET	Download the artwork associated with a specific album.	Admin, User
`/api/download/artist-pfp`	GET	Download the profile picture of an artist.	Admin, User
`/api/download/artist-banner`	GET	Download the banner artwork of an artist.	Admin, User
`/api/download/playlist-art`	GET	Download the artwork of a specific playlist.	Admin, User
`/api/download/collection-art`	GET	Download the artwork associated with a specific collection.	Admin, User

Download Track

This endpoint allows users to download a track based on its ID. Downloading supports range requests for partial content streaming or resuming interrupted downloads.

Details:

Endpoint: /api/download/track
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the track to be downloaded.

Responses:

200 OK: Returns the track file.
404 Not Found: Track not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/track?id=66bc9aadab7ba419497e6a97" \
             -H "Authorization: Bearer <User-JWT>"

Example Request with range (using curl):

curl -X GET "https://your-melon-server.com/api/download/track?id=66bc9aadab7ba419497e6a97" \
             -H "Authorization: Bearer <User-JWT>" \
             -H "Range: bytes=1000-"

Download Track with Transcoding

This endpoint allows users to download an mp3 transcoded version of a track in a specific bitrate.

Details:

Endpoint: /api/download/track-transcode
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the track to be transcoded and downloaded.
transcodeBitrate (int, optional): The desired bitrate of the transcoded track (default is 256 kbps).

Responses:

200 OK: Returns the transcoded track.
404 Not Found: Track not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/track-transcode?id=66bc9aadab7ba419497e6a97&transcodeBitrate=320" \
             -H "Authorization: Bearer <User-JWT>"

Download Track Waveform

This endpoint allows users to generate and download a visual representation of the track's waveform with a specified width. Waveform is represented as float points of amplitude.

Details:

Endpoint: /api/download/track-wave
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the track.
width (float, required): The width (in pixels) of the waveform to be generated.

Responses:

200 OK: Returns a float array representing the track's waveform data.
400 Bad Request: Width parameter is required.
404 Not Found: Track not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/track-wave?id=66bc9aadab7ba419497e6a97&width=500" \
             -H "Authorization: Bearer <User-JWT>"

Download Track Artwork

This endpoint allows users to download the artwork embedded within a track.

Details:

Endpoint: /api/download/track-art
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the track.
index (int, optional): The index of the artwork (for tracks with multiple embedded artworks). If not specified, defaults to the track's default artwork.

Responses:

200 OK: Returns the track artwork.
404 Not Found: Track or artwork not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/track-art?id=66bc9aadab7ba419497e6a97" \
             -H "Authorization: Bearer <User-JWT>"

Download Album Artwork

This endpoint allows users to download the artwork associated with a specific album. See Artwork Architecture for more info on how album art is handled.

Details:

Endpoint: /api/download/album-art
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the album.
index (int, optional): The index of the album artwork. If not specified, defaults to the album's default artwork.

Responses:

200 OK: Returns the album artwork.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/album-art?id=album123" \
             -H "Authorization: Bearer <User-JWT>"

Download Artist Profile Picture

This endpoint allows users to download the profile picture of an artist.

Details:

Endpoint: /api/download/artist-pfp
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the artist.
index (int, optional): The index of the profile picture. If not specified, defaults to the artist's default profile picture.

Responses:

200 OK: Returns the artist's profile picture.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/artist-pfp?id=artist123" \
             -H "Authorization: Bearer <User-JWT>"

This endpoint allows users to download the banner artwork of an artist.

Details:

Endpoint: /api/download/artist-banner
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the artist.
index (int, optional): The index of the banner artwork. If not specified, defaults to the artist's default banner.

Responses:

200 OK: Returns the artist's banner artwork.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/artist-banner?id=artist123" \
             -H "Authorization: Bearer <User-JWT>"

Download Playlist Artwork

This endpoint allows users to download the artwork associated with a specific playlist.

Details:

Endpoint: /api/download/playlist-art
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the playlist.

Responses:

200 OK: Returns the playlist artwork.
404 Not Found: Playlist or artwork not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/playlist-art?id=playlist123" \
             -H "Authorization: Bearer <User-JWT>"

Download Collection Artwork

This endpoint allows users to download the artwork associated with a specific collection.

Details:

Endpoint: /api/download/collection-art
Method: GET
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the collection.

Responses:

200 OK: Returns the collection artwork.
404 Not Found: Collection or artwork not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/download/collection-art?id=collection123" \
             -H "Authorization: Bearer <User-JWT>"

DownloadController Documentation

Controller Route: /api/download

Summary of Endpoints

Download Track

Download Track with Transcoding

Download Track Waveform

Download Track Artwork

Download Album Artwork

Download Artist Profile Picture

Download Artist Banner

Download Playlist Artwork

Download Collection Artwork

Controller Route: `/api/download`