### Install and Run Qobuz-DL with Docker

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Clone the repository, edit the .env file with your credentials, build the Docker image, and then start the container using docker-compose.

```bash
git clone https://github.com/QobuzDL/Qobuz-DL.git
cd Qobuz-DL
# Edit .env with real credentials first
docker build -t qobuz-dl .
docker-compose up -d   # exposes port 3000
```

```yaml
# docker-compose.yml (generated)
services:
  qobuz-dl:
    container_name: qobuz-dl
    image: qobuz-dl
    ports:
      - 3000:3000
    restart: unless-stopped
```

--------------------------------

### Install and Run Qobuz-DL with Node.js

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Clone the repository, navigate to the directory, install dependencies, copy and fill the .env file, and then run the development or production server.

```bash
git clone https://github.com/QobuzDL/Qobuz-DL.git
cd Qobuz-DL
npm i
cp .env.example .env   # then fill in QOBUZ_APP_ID, QOBUZ_SECRET, QOBUZ_AUTH_TOKENS
npm run dev            # development server at http://localhost:3000
npm run build && npm start  # production
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Install all the necessary Node.js packages required for Qobuz-DL to function.

```bash
npm i
```

--------------------------------

### Run Development Server

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Start the Qobuz-DL development server to test and use the application locally.

```bash
npm run dev
```

--------------------------------

### Check npm Version

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Verify if npm is installed on your system. This is a prerequisite for installing project dependencies.

```bash
npm -v
```

--------------------------------

### Run Docker Compose

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Start Qobuz-DL in detached mode using Docker Compose. Ensure the .env file is configured correctly before running.

```bash
docker-compose up -d
```

--------------------------------

### GET /api/download-music — Get Signed Track Download URL

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Generates a time-limited signed download URL for a specific track. The signature is computed server-side using `QOBUZ_SECRET` via MD5 hashing. The returned URL points directly to the audio file and must be fetched immediately.

```APIDOC
## GET /api/download-music — Get Signed Track Download URL

### Description
Generates a time-limited signed download URL for a specific track. The signature is computed server-side using `QOBUZ_SECRET` via MD5 hashing. The returned URL points directly to the audio file and must be fetched immediately.

### Method
GET

### Endpoint
/api/download-music

### Parameters
#### Query Parameters
- **track_id** (string) - Required - The ID of the track to download.
- **quality** (number) - Required - The desired audio quality code.
- **Token-Country** (string) - Header - Used for country routing.

### Quality Codes
| Code | Format |
|------|--------|
| `"27"` | FLAC Hi-Res (up to 24-bit/192kHz) |
| `"7"` | FLAC CD quality (16-bit/44.1kHz) |
| `"6"` | MP3 320 kbps |
| `"5"` | MP3 128 kbps |

### Request Example
```bash
# Download FLAC Hi-Res (quality 27)
curl "http://localhost:3000/api/download-music?track_id=64868671&quality=27"

# Download MP3 320kbps (quality 5)
curl "http://localhost:3000/api/download-music?track_id=64868671&quality=5"

# With country routing
curl -H "Token-Country: FR" "http://localhost:3000/api/download-music?track_id=64868671&quality=7"
```

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object)
  - **url** (string) - The signed download URL.

#### Response Example
```json
{
  "success": true,
  "data": {
    "url": "https://streaming.qobuz.com/file?...&request_sig=abc123&request_ts=1700000000"
  }
}
```

#### Error Response
```json
{
  "success": false,
  "error": [
    {
      "message": "Invalid enum value",
      "path": ["quality"]
    }
  ]
}
```
```

--------------------------------

### Get Full Resolution Image URL

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Converts a Qobuz thumbnail URL to its full-resolution equivalent. Use when displaying images at their highest quality.

```typescript
// getFullResImageUrl: converts Qobuz thumbnail URL to full-resolution
getFullResImageUrl(track);  // "https://...org.jpg"
```

--------------------------------

### Get Signed Track Download URL

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Generates a time-limited signed URL for downloading a specific track. The quality parameter determines the audio format and resolution.

```bash
# Download FLAC Hi-Res (quality 27)
curl "http://localhost:3000/api/download-music?track_id=64868671&quality=27"
```

```bash
# Download MP3 320kbps (quality 5)
curl "http://localhost:3000/api/download-music?track_id=64868671&quality=5"
```

```bash
# With country routing
curl -H "Token-Country: FR" "http://localhost:3000/api/download-music?track_id=64868671&quality=7"
```

--------------------------------

### GET /api/get-album — Fetch Full Album Details

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Returns complete album metadata including all track IDs, audio specs, and label information, required before initiating an album download. Supports country-specific token routing.

```APIDOC
## GET /api/get-album — Fetch Full Album Details

### Description
Returns complete album metadata including all track IDs, audio specs, and label information, required before initiating an album download.

### Method
GET

### Endpoint
/api/get-album

### Parameters
#### Query Parameters
- **album_id** (string) - Required - The ID of the album to fetch details for.

### Request Example
```bash
curl "http://localhost:3000/api/get-album?album_id=0060252730452"

curl -H "Token-Country: GB" "http://localhost:3000/api/get-album?album_id=0060252730452"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the album details. (Schema not fully detailed in source)

#### Error Response
(Error response schema not detailed in source)
```

--------------------------------

### GET /api/get-music — Search Qobuz Catalog

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Searches the Qobuz catalog for albums, tracks, and artists. Accepts plain text queries or direct Qobuz URLs. Supports pagination and country-specific token routing.

```APIDOC
## GET /api/get-music — Search Qobuz Catalog

### Description
Searches the Qobuz catalog for albums, tracks, and artists. Accepts plain text queries or direct Qobuz URLs (album, track, or artist). When a URL is passed, the response includes a `switchTo` field indicating which result category to display.

### Method
GET

### Endpoint
/api/get-music

### Parameters
#### Query Parameters
- **q** (string) - Required - Search text or Qobuz URL
- **offset** (number) - Optional - Pagination offset (0–1000), defaults to `0`

### Request Example
```bash
# Plain text search
curl "http://localhost:3000/api/get-music?q=Daft+Punk+Random+Access&offset=0"

# Pass a Qobuz album URL directly
curl "http://localhost:3000/api/get-music?q=https://open.qobuz.com/album/0060252730452"

# With country token routing
curl -H "Token-Country: US" "http://localhost:3000/api/get-music?q=Pink+Floyd&offset=10"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the search results.
  - **query** (string) - The original search query.
  - **switchTo** (string | null) - Indicates which result category to display if a URL was provided.
  - **albums** (object) - Album search results.
    - **limit** (number) - The limit for the number of albums returned.
    - **offset** (number) - The offset for the album results.
    - **total** (number) - The total number of albums found.
    - **items** (array) - An array of album objects.
  - **tracks** (object) - Track search results.
    - **limit** (number) - The limit for the number of tracks returned.
    - **offset** (number) - The offset for the track results.
    - **total** (number) - The total number of tracks found.
    - **items** (array) - An array of track objects.
  - **artists** (object) - Artist search results.
    - **limit** (number) - The limit for the number of artists returned.
    - **offset** (number) - The offset for the artist results.
    - **total** (number) - The total number of artists found.
    - **items** (array) - An array of artist objects.

#### Response Example
```json
{
  "success": true,
  "data": {
    "query": "Daft Punk Random Access",
    "switchTo": null,
    "albums": {
      "limit": 10, "offset": 0, "total": 3,
      "items": [
        {
          "id": "0060252730452",
          "title": "Random Access Memories",
          "artist": { "id": 26887, "name": "Daft Punk" },
          "released_at": 1368316800,
          "maximum_bit_depth": 24,
          "maximum_sampling_rate": 96,
          "hires": true,
          "streamable": true,
          "tracks_count": 13
        }
      ]
    },
    "tracks": { "limit": 10, "offset": 0, "total": 12, "items": [ /* QobuzTrack[] */ ] },
    "artists": { "limit": 10, "offset": 0, "total": 1, "items": [ /* QobuzArtist[] */ ] }
  }
}
```

#### Error Response
```json
{ "success": false, "error": "Query is required" }
```
```

--------------------------------

### GET /api/get-releases — Paginate Artist Releases

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Fetches a paginated list of an artist's releases filtered by release type. Used when the artist profile indicates `has_more: true` for a category.

```APIDOC
## GET /api/get-releases — Paginate Artist Releases

### Description
Fetches a paginated list of an artist's releases filtered by release type. Used when the artist profile indicates `has_more: true` for a category.

### Method
GET

### Endpoint
/api/get-releases

### Parameters
#### Query Parameters
- **artist_id** (string) - Required - Qobuz artist ID
- **release_type** (string) - Optional - Default: `"album"` - `album`, `live`, `compilation`, `epSingle`, `download`
- **limit** (number) - Optional - Default: `10` - Results per page
- **offset** (number) - Optional - Default: `0` - Pagination offset
- **track_size** (number) - Optional - Default: `1000` - Max tracks to fetch per release

### Request Example
```bash
# Fetch first 10 albums for artist 26887
curl "http://localhost:3000/api/get-releases?artist_id=26887&release_type=album&limit=10&offset=0"

# Fetch EPs/singles, page 2
curl "http://localhost:3000/api/get-releases?artist_id=26887&release_type=epSingle&limit=10&offset=10"
```

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object)
  - **items** (array)
  - **total** (number)
  - **limit** (number)
  - **offset** (number)

#### Response Example
```json
{
  "success": true,
  "data": {
    "items": [ /* QobuzAlbum[] */ ],
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}
```
```

--------------------------------

### GET /api/get-artist — Fetch Artist Profile

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Returns an artist's profile page data including biography, portrait image, top tracks, and a categorized releases object (albums, live, compilations, EPs/singles).

```APIDOC
## GET /api/get-artist — Fetch Artist Profile

### Description
Returns an artist's profile page data including biography, portrait image, top tracks, and a categorized releases object (albums, live, compilations, EPs/singles).

### Method
GET

### Endpoint
/api/get-artist

### Parameters
#### Query Parameters
- **artist_id** (string) - Required - Qobuz artist ID

### Request Example
```bash
curl "http://localhost:3000/api/get-artist?artist_id=26887"
```

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object)
  - **artist** (object)
    - **id** (string)
    - **name** (object)
      - **display** (string)
    - **artist_category** (string)
    - **biography** (object)
      - **content** (string)
      - **language** (string)
      - **source** (null)
    - **images** (object)
      - **portrait** (object)
        - **hash** (string)
        - **format** (string)
    - **top_tracks** (array)
    - **releases** (object)
      - **album** (object)
        - **has_more** (boolean)
        - **items** (array)
      - **live** (object)
        - **has_more** (boolean)
        - **items** (array)
      - **compilation** (object)
        - **has_more** (boolean)
        - **items** (array)
      - **epSingle** (object)
        - **has_more** (boolean)
        - **items** (array)

#### Response Example
```json
{
  "success": true,
  "data": {
    "artist": {
      "id": "26887",
      "name": { "display": "Daft Punk" },
      "artist_category": "MainArtist",
      "biography": { "content": "...", "language": "en", "source": null },
      "images": { "portrait": { "hash": "abc123", "format": "jpg" } },
      "top_tracks": [ /* QobuzTrack[] */ ],
      "releases": {
        "album":       { "has_more": false, "items": [ /* QobuzAlbum[] */ ] },
        "live":        { "has_more": false, "items": [] },
        "compilation": { "has_more": false, "items": [] },
        "epSingle":    { "has_more": true,  "items": [ /* QobuzAlbum[] */ ] }
      }
    }
  }
}
```
```

--------------------------------

### GET /api/get-countries — List Configured Country Tokens

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Returns the ISO 3166-1 alpha-2 country codes that have been configured in `config/token-countries.ts`. Used by the UI to render the country picker.

```APIDOC
## GET /api/get-countries — List Configured Country Tokens

### Description
Returns the ISO 3166-1 alpha-2 country codes that have been configured in `config/token-countries.ts`. Used by the UI to render the country picker.

### Method
GET

### Endpoint
/api/get-countries

### Request Example
```bash
curl "http://localhost:3000/api/get-countries"
```

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (array of strings) - ISO 3166-1 alpha-2 country codes.

#### Success Example
```json
{ "success": true, "data": ["US", "GB", "FR", "DE"] }
```

#### Error Response
- **success** (boolean)
- **error** (string) - Error message.

#### Error Example
```json
{ "success": false, "error": "No countries list found" }
```
```

--------------------------------

### Apply Metadata and Re-encode Audio with FFmpeg WASM

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

The `applyMetadata` function re-encodes raw audio and embeds metadata and album art using FFmpeg WASM. Setup FFmpeg once per session using `createFFmpeg` and `loadFFmpeg`. The `codecMap` provides a reference for supported output formats.

```tsx
import { applyMetadata, codecMap, loadFFmpeg, createFFmpeg } from '@/lib/ffmpeg-functions';

// Setup FFmpeg (once per session)
const ffmpeg = createFFmpeg();                      // wraps FFmpeg.createFFmpeg()
const controller = new AbortController();
await loadFFmpeg(ffmpeg, controller.signal);        // loads WASM binary

// Download raw FLAC from signed URL
const rawResponse = await fetch(signedTrackURL);
const trackBuffer: ArrayBuffer = await rawResponse.arrayBuffer();

// Re-encode to AAC 256 kbps and embed metadata + album art
const settings = {
    outputQuality: '27',
    outputCodec: 'AAC',
    bitrate: 256,
    applyMetadata: true,
    fixMD5: false,
    albumArtSize: 1400,
    albumArtQuality: 0.9,
    trackName: '{artists} - {name}',
    zipName: '{artists} - {name}',
    particles: false,
    explicitContent: true,
};

const outputBuffer = await applyMetadata(
    trackBuffer,
    qobuzTrack,          // QobuzTrack object (provides title, artist, album, ISRC, etc.)
    ffmpeg,
    settings,
    setStatusBar,        // optional React state setter for progress display
    undefined,           // albumArt: undefined = auto-fetch, false = skip, ArrayBuffer = use provided
    fetchedAlbum.upc     // optional UPC/barcode string
);

// outputBuffer is a Uint8Array ready to save
const blob = new Blob([outputBuffer], { type: 'audio/mp4' });
saveAs(blob, `${qobuzTrack.performer.name} - ${qobuzTrack.title}.m4a`);

// codecMap shows all supported output formats:
// FLAC → .flac (flac), WAV → .wav (pcm_s16le), ALAC → .m4a (alac)
// MP3  → .mp3  (libmp3lame), AAC → .m4a (aac), OPUS → .opus (libopus)
console.log(codecMap);

```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Change your current working directory to the root of the cloned Qobuz-DL project.

```bash
cd Qobuz-DL
```

--------------------------------

### Build Docker Image

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Create a Docker image for Qobuz-DL. This image can then be used to run the application in a container.

```bash
docker build -t qobuz-dl .
```

--------------------------------

### Clone Qobuz-DL Repository

Source: https://github.com/qobuzdl/qobuz-dl/blob/main/README.md

Download the Qobuz-DL project files from the GitHub repository to your local machine.

```bash
git clone https://github.com/QobuzDL/Qobuz-DL.git
```

--------------------------------

### Environment Configuration for Qobuz-DL

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Set these environment variables in a .env file at the project root for application functionality. QOBUZ_APP_ID and QOBUZ_SECRET are for request signing, while QOBUZ_AUTH_TOKENS is a JSON array of valid subscriber tokens. Optional proxy support can also be configured.

```bash
# .env
QOBUZ_API_BASE=https://www.qobuz.com/api.json/0.2/
QOBUZ_APP_ID=123456789
QOBUZ_SECRET=abcdef1234567890abcdef1234567890
QOBUZ_AUTH_TOKENS=["token_abc123", "token_def456"]

NEXT_PUBLIC_APPLICATION_NAME=Qobuz-DL
NEXT_PUBLIC_GITHUB=https://github.com/QobuzDL/Qobuz-DL

# Optional proxy support
CORS_PROXY=
SOCKS5_PROXY=
```

--------------------------------

### Fetch Full Album Details via API

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Retrieve complete album metadata, including track IDs and audio specifications, necessary for initiating an album download. Supports country-specific token routing.

```bash
curl "http://localhost:3000/api/get-album?album_id=0060252730452"

curl -H "Token-Country: GB" "http://localhost:3000/api/get-album?album_id=0060252730452"
```

--------------------------------

### Fetch Album Details

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Retrieves detailed information about a specific Qobuz album using its ID. Requires the album ID as a query parameter.

```bash
curl "http://localhost:3000/api/get-album?album_id=0060252730452"
```

--------------------------------

### Fetch Artist Profile

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Retrieves an artist's profile, including biography, top tracks, and categorized releases. Requires the artist ID.

```bash
curl "http://localhost:3000/api/get-artist?artist_id=26887"
```

--------------------------------

### createDownloadJob

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

The main function to initiate a download for a single track or an entire album. It handles job creation, fetching signed URLs, downloading audio, applying metadata, and saving files. Album downloads are automatically zipped.

```APIDOC
## createDownloadJob — Queue a Track or Album Download

`createDownloadJob` is the high-level entry point for all downloads. It inspects whether the result is a `QobuzTrack` or `QobuzAlbum`, creates a queued job via `createJob`, orchestrates fetching signed URLs, downloading audio, applying metadata, and saving files. Album downloads are zipped with `fflate` before saving.

### Parameters
- `item` (QobuzTrack | QobuzAlbum): The track or album object to download.
- `setStatusBar` (function): A callback function to update the status bar with download progress.
- `ffmpegInstance` (FFmpegType): An initialized FFmpeg instance.
- `settings` (SettingsProps): Application settings object.
- `toast` (function): A function to display toast notifications (e.g., from shadcn/ui).
- `fetchedAlbumData` (FetchedQobuzAlbum | undefined): Optional. Pre-fetched album data, useful for album downloads to avoid a redundant API call.
- `setFetchedAlbumData` (function | undefined): Optional. A state setter function for `fetchedAlbumData`.
- `countryCode` (string, optional): The two-letter country code (e.g., 'US', 'GB') to use for the download.

### Returns
- `Promise<void>`: A Promise that resolves when the download job is created and queued.

### Usage Examples

**Single track download:**
```typescript
await createDownloadJob(
    qobuzTrack,          // QobuzTrack (has .album property)
    setStatusBar,        // React state setter for the status bar
    ffmpegInstance,      // loaded FFmpegType instance
    settings,            // SettingsProps
    toast,               // shadcn/ui toast function
    undefined,           // fetchedAlbumData (not needed for single track)
    undefined,           // setFetchedAlbumData
    'US'                 // optional country code
);
```

**Full album download (saved as .zip containing numbered tracks + cover.jpg):**
```typescript
await createDownloadJob(
    qobuzAlbum,          // QobuzAlbum (no .album property)
    setStatusBar,
    ffmpegInstance,
    settings,
    toast,
    fetchedAlbumData,    // FetchedQobuzAlbum with .tracks.items[] — pass to skip a second API call
    setFetchedAlbumData,
    'GB'
);
// Album zip structure:
// {zipName}.zip
//   ├── cover.jpg
//   ├── 01 Artist - Track One.flac
//   ├── 02 Artist - Track Two.flac
//   └── ...
```
```

--------------------------------

### Create Download Job with createDownloadJob

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

High-level function to initiate track or album downloads. It handles job creation, URL fetching, audio downloading, metadata application, and file saving. Album downloads are zipped.

```tsx
import { createDownloadJob } from '@/lib/download-job';
import { createFFmpeg } from '@/lib/ffmpeg-functions';

// Single track download
await createDownloadJob(
    qobuzTrack,          // QobuzTrack (has .album property)
    setStatusBar,        // React state setter for the status bar
    ffmpegInstance,      // loaded FFmpegType instance
    settings,            // SettingsProps
    toast,               // shadcn/ui toast function
    undefined,           // fetchedAlbumData (not needed for single track)
    undefined,           // setFetchedAlbumData
    'US'                 // optional country code
);

// Full album download (saved as .zip containing numbered tracks + cover.jpg)
await createDownloadJob(
    qobuzAlbum,          // QobuzAlbum (no .album property)
    setStatusBar,
    ffmpegInstance,
    settings,
    toast,
    fetchedAlbumData,    // FetchedQobuzAlbum with .tracks.items[] — pass to skip a second API call
    setFetchedAlbumData,
    'GB'
);
// Album zip structure:
// {zipName}.zip
//   ├── cover.jpg
//   ├── 01 Artist - Track One.flac
//   ├── 02 Artist - Track Two.flac
//   └── ...

```

--------------------------------

### List Configured Country Tokens

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Returns a list of ISO 3166-1 alpha-2 country codes that are configured for use. This is used by the UI to populate the country selection.

```bash
curl "http://localhost:3000/api/get-countries"
```

--------------------------------

### Format Track and Album Titles

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Appends version strings to titles if present. Use for displaying user-friendly track or album names.

```typescript
import {
    formatTitle, formatArtists, getAlbum, getFullResImageUrl,
    formatDuration, getType, filterExplicit, parseArtistData,
    getFullAlbumInfo
} from '@/lib/qobuz-dl';
import { formatBytes, cleanFileName, formatCustomTitle, resizeImage } from '@/lib/utils';

// formatTitle: appends version string if present
formatTitle(track);   // "Get Lucky (Radio Edit)"
formatTitle(album);   // "Random Access Memories (10th Anniversary Edition)"
```

--------------------------------

### Create Download Job

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Manually enqueues a custom asynchronous download job into a sequential FIFO queue. Jobs are processed one at a time, and can be cancelled using an AbortController. The status bar UI updates as jobs are processed.

```typescript
import { createJob } from '@/lib/status-bar/jobs';
import { Disc3Icon } from 'lucide-react';

// Manually enqueue a custom async job
await createJob(
    setStatusBar,          // React state setter for StatusBarProps
    'My Custom Download',  // Label shown in queue UI
    Disc3Icon,             // Lucide icon for the queue entry
    async () => {
        // Perform async work; update status bar as needed
        setStatusBar((prev) => ({ ...prev, description: 'Working...', progress: 50 }));
        await doWork();
        // Job completes when this promise resolves
    }
);
// If another job is already running, this is appended to the queue.
// The queue processes jobs sequentially; the status bar closes when the queue empties.
// Users can remove queued (not-yet-running) jobs via the remove() callback in queue entries.
```

--------------------------------

### Paginate Artist Releases

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Fetches a paginated list of an artist's releases, filterable by release type. Use this when an artist profile indicates more releases are available.

```bash
# Fetch first 10 albums for artist 26887
curl "http://localhost:3000/api/get-releases?artist_id=26887&release_type=album&limit=10&offset=0"
```

```bash
# Fetch EPs/singles, page 2
curl "http://localhost:3000/api/get-releases?artist_id=26887&release_type=epSingle&limit=10&offset=10"
```

--------------------------------

### Search Qobuz Catalog via API

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Use this API endpoint to search the Qobuz catalog for albums, tracks, and artists. It accepts plain text queries or direct Qobuz URLs. The 'Token-Country' header can be used for country-specific token routing.

```bash
# Plain text search
curl "http://localhost:3000/api/get-music?q=Daft+Punk+Random+Access&offset=0"

# Pass a Qobuz album URL directly
curl "http://localhost:3000/api/get-music?q=https://open.qobuz.com/album/0060252730452"

# With country token routing
curl -H "Token-Country: US" "http://localhost:3000/api/get-music?q=Pink+Floyd&offset=10"
```

```json
# Success response
{
  "success": true,
  "data": {
    "query": "Daft Punk Random Access",
    "switchTo": null,
    "albums": {
      "limit": 10, "offset": 0, "total": 3,
      "items": [
        {
          "id": "0060252730452",
          "title": "Random Access Memories",
          "artist": { "id": 26887, "name": "Daft Punk" },
          "released_at": 1368316800,
          "maximum_bit_depth": 24,
          "maximum_sampling_rate": 96,
          "hires": true,
          "streamable": true,
          "tracks_count": 13
        }
      ]
    },
    "tracks": { "limit": 10, "offset": 0, "total": 12, "items": [ /* QobuzTrack[] */ ] },
    "artists": { "limit": 10, "offset": 0, "total": 1, "items": [ /* QobuzArtist[] */ ] }
  }
}

# Error response
{ "success": false, "error": "Query is required" }
```

--------------------------------

### Format File Size in Human-Readable Format

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Converts a file size in bytes into a human-readable string (e.g., '50 MB'). Useful for displaying download sizes or storage usage.

```typescript
// formatBytes: human-readable file size
formatBytes(52428800);  // "50 MB"
```

--------------------------------

### Extract Album from Track or Album Object

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Extracts the QobuzAlbum object from either a track or an album object. Use when you need album-level details regardless of the input type.

```typescript
// getAlbum: extract QobuzAlbum from either a track or album
const album = getAlbum(trackOrAlbum);
```

--------------------------------

### Format Custom File Name

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Expands template variables (like {artists}, {name}, {year}) in a string to create custom file names. Use for flexible and consistent file naming conventions.

```typescript
// formatCustomTitle: expand template variables for file naming
formatCustomTitle('{artists} - {name} ({year})', track);
// → "Daft Punk - Get Lucky (2013)"
```

--------------------------------

### Manage Client-Side Settings with useSettings Hook

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Access and update user preferences persisted to localStorage using the `useSettings` hook. The `SettingsProvider` must wrap the application tree. Settings can be updated individually or reset to defaults.

```tsx
// Accessing and updating settings in a component
import { useSettings, defaultSettings, nameVariables } from '@/lib/settings-provider';

function MyComponent() {
    const { settings, setSettings, resetSettings } = useSettings();

    // Change output codec to OPUS at 128 kbps
    setSettings((prev) => ({ ...prev, outputCodec: 'OPUS', bitrate: 128 }));

    // Switch to FLAC Hi-Res with metadata and album art
    setSettings((prev) => ({
        ...prev,
        outputQuality: '27',    // Hi-Res FLAC from Qobuz
        outputCodec: 'FLAC',    // Keep as FLAC (no re-encode)
        applyMetadata: true,
        fixMD5: true,           // Re-encode FLAC through libFLAC to fix MD5 hash
        albumArtSize: 3600,     // Max art resolution
        albumArtQuality: 1.0,
        trackName: '{artists} - {name}',   // supports: {artists}, {name}, {year}, {duration}
        zipName: '{artists} - {name}',
    }));

    // Reset all settings to defaults
    resetSettings();

    return <div>Output: {settings.outputCodec} @ quality {settings.outputQuality}</div>;
}

// Available outputCodec values: 'FLAC' | 'WAV' | 'ALAC' | 'MP3' | 'AAC' | 'OPUS'
// Available outputQuality values: '27' (Hi-Res) | '7' (CD) | '6' (MP3 320) | '5' (MP3 128)
// nameVariables (for trackName/zipName templates): ['artists', 'name', 'year', 'duration']

```

--------------------------------

### Fetch and Cache Full Album Info

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Fetches and caches detailed album information from the Qobuz API (specifically `/api/get-album`). This is a client-side function that can update React state. It accepts optional country code for regional data.

```typescript
// getFullAlbumInfo: fetch and cache album details (client-side, calls /api/get-album)
const fetched = await getFullAlbumInfo(
    fetchedAlbumData,      // current cached FetchedQobuzAlbum | null
    setFetchedAlbumData,
    selectedAlbum,
    'US'                   // optional country
);
```

--------------------------------

### downloadArtistDiscography

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Queues downloads for all releases of a specified type for a given artist. It handles pagination to fetch all available releases and adds each album as an independent download job.

```APIDOC
## downloadArtistDiscography — Queue an Entire Discography

Downloads all releases of a given type for an artist, automatically paginating through `has_more` pages before queuing each album as a separate download job.

### Parameters
- `artistResults` (QobuzArtistResults): The artist data object, typically obtained from an API call.
- `setArtistResults` (function): A React state setter function for artist results.
- `fetchMore` (function): An asynchronous function responsible for fetching the next page of results. Expected signature: `async (type: string, artistResults: QobuzArtistResults) => QobuzArtistResults`.
- `releaseType` ('album' | 'epSingle' | 'live' | 'compilation' | 'all'): The type of releases to download.
- `setStatusBar` (function): A callback function to update the status bar with progress information.
- `settings` (SettingsProps): Application settings object.
- `toast` (function): A function to display toast notifications.
- `ffmpegInstance` (FFmpegType): An initialized FFmpeg instance.
- `countryCode` (string, optional): The two-letter country code (e.g., 'DE') to use for the download.

### Returns
- `Promise<void>`: A Promise that resolves when all releases have been queued for download.

### Usage Example
```typescript
import { downloadArtistDiscography } from '@/lib/download-job';

// Queue all albums + EPs for an artist
await downloadArtistDiscography(
    artistResults,       // QobuzArtistResults from /api/get-artist
    setArtistResults,    // React state setter
    fetchMore,           // async function(type, artistResults) that loads next page
    'all',               // 'album' | 'epSingle' | 'live' | 'compilation' | 'all'
    setStatusBar,
    settings,
    toast,
    ffmpegInstance,
    'DE'                 // optional country code
);
// A toast notification is shown when all releases have been queued.
// Each album is added as an independent job to the download queue.
```
```

--------------------------------

### Format Artist List

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Joins all contributing artists into a single string with a specified separator. Useful for displaying artist information.

```typescript
// formatArtists: joins all contributing artists
formatArtists(track, ' & ');  // "Daft Punk & Pharrell Williams"
```

--------------------------------

### Configure Multi-Country Token Support

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Populate `tokenCountriesMap` to serve users from different geographic regions with separate Qobuz accounts. This map overrides `QOBUZ_AUTH_TOKENS` and resolves tokens based on the country code. The `getTokenForCountry` function provides exact match or random fallback resolution.

```typescript
// config/token-countries.ts
import { getRandomToken } from '@/lib/qobuz-dl-server';

export type TokenCountry = {
    code: string;   // ISO 3166-1 alpha-2
    token: string;  // Qobuz user auth token
};

export const tokenCountriesMap: TokenCountry[] = [
    { code: 'US', token: 'us_user_token_here' },
    { code: 'GB', token: 'gb_user_token_here' },
    { code: 'FR', token: 'fr_user_token_here' },
];

// Token resolution: exact country match, or random fallback
export const getTokenForCountry = (country: string): string =>
    tokenCountriesMap.find((c) => c.code.toUpperCase() === country.toUpperCase())?.token
    || getRandomToken();

```

--------------------------------

### Format Duration in Human-Readable Format

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Converts a duration in seconds into a human-readable string (e.g., '1h 9m 7s'). Useful for displaying track or album lengths.

```typescript
// formatDuration
formatDuration(4147);  // "1h 9m 7s"
```

--------------------------------

### Download Artist Discography with downloadArtistDiscography

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Queues all releases of a specified type for an artist, paginating through results and adding each album as a separate download job. A toast notification appears when all releases are queued.

```tsx
import { downloadArtistDiscography } from '@/lib/download-job';

// Queue all albums + EPs for an artist
await downloadArtistDiscography(
    artistResults,       // QobuzArtistResults from /api/get-artist
    setArtistResults,    // React state setter
    fetchMore,           // async function(type, artistResults) that loads next page
    'all',               // 'album' | 'epSingle' | 'live' | 'compilation' | 'all'
    setStatusBar,
    settings,
    toast,
    ffmpegInstance,
    'DE'                 // optional country code
);
// A toast notification is shown when all releases have been queued.
// Each album is added as an independent job to the download queue.

```

--------------------------------

### fixMD5Hash

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Repairs the MD5 checksum in FLAC files, which can be zeroed by Qobuz when files are transcoded from Hi-Res. It re-encodes the FLAC file using a browser-based libFLAC WebWorker to restore a valid MD5 checksum.

```APIDOC
## fixMD5Hash — Repair FLAC MD5 Checksum

When Qobuz delivers FLAC files that have been transcoded from Hi-Res, the MD5 hash in the FLAC stream header can be zeroed. `fixMD5Hash` re-encodes the FLAC file through a browser-based libFLAC WebWorker to restore a valid MD5 checksum, ensuring compliance with strict FLAC validators.

### Parameters
- `processedBuffer` (ArrayBuffer): The buffer containing the FLAC audio data.
- `setStatusBar` (function): A callback function to report progress. Expected signature: `(status: { description: string, progress: number }) => void`.

### Returns
- `Promise<Blob>`: A Promise that resolves to a Blob containing the fixed FLAC data. For album batching, call `.arrayBuffer()` on the returned Blob.

### Usage Example
```typescript
import { fixMD5Hash } from '@/lib/ffmpeg-functions';

// Assuming processedBuffer is obtained from a previous step like applyMetadata
let processedBuffer: ArrayBuffer = await applyMetadata(trackBuffer, track, ffmpeg, settings);

if (settings.outputCodec === 'FLAC' && settings.fixMD5) {
    // Returns a Blob (single-track) or call .arrayBuffer() for album batching
    const fixedBlob: Blob = await fixMD5Hash(processedBuffer, setStatusBar);
    // Progress is reported via setStatusBar: { description: 'Fixing MD5 hash...', progress: 0–100 }
    saveAs(fixedBlob, 'track.flac');

    // For album batching (need ArrayBuffer):
    const fixedBuffer: ArrayBuffer = await (await fixMD5Hash(processedBuffer)).arrayBuffer();
}
```
```

--------------------------------

### Fix FLAC MD5 Hash with fixMD5Hash

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Re-encodes FLAC files to repair a zeroed MD5 checksum in the header. Call this after applying metadata if outputCodec is FLAC and settings.fixMD5 is true. Progress is reported via setStatusBar.

```tsx
import { fixMD5Hash } from '@/lib/ffmpeg-functions';

// Typically called after applyMetadata when outputCodec === 'FLAC' && settings.fixMD5
let processedBuffer: ArrayBuffer = await applyMetadata(trackBuffer, track, ffmpeg, settings);

if (settings.outputCodec === 'FLAC' && settings.fixMD5) {
    // Returns a Blob (single-track) or call .arrayBuffer() for album batching
    const fixedBlob: Blob = await fixMD5Hash(processedBuffer, setStatusBar);
    // Progress is reported via setStatusBar: { description: 'Fixing MD5 hash...', progress: 0–100 }
    saveAs(fixedBlob, 'track.flac');

    // For album batching (need ArrayBuffer):
    const fixedBuffer: ArrayBuffer = await (await fixMD5Hash(processedBuffer)).arrayBuffer();
}
```

--------------------------------

### Clean File Name

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Replaces filesystem-unsafe characters in a string with underscores. Use to ensure file names are valid across different operating systems.

```typescript
// cleanFileName: replace filesystem-unsafe characters with underscores
cleanFileName('AC/DC - Back in Black');  // "AC_DC - Back in Black"
```

--------------------------------

### Resize Image using Canvas

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Performs JPEG downscaling of an image using the browser's Canvas API. This function is browser-only and returns a data URL. Use for optimizing image sizes before display or upload.

```typescript
// resizeImage: canvas-based JPEG downscale (browser only)
const dataUrl = await resizeImage('https://...org.jpg', 1400, 0.92);
```

--------------------------------

### Discriminate Union Type

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Determines the type of a Qobuz object (track, album, artist). Use for conditional logic based on the object's type.

```typescript
// getType: discriminate union type
getType(track);   // "tracks"
getType(album);   // "albums"
getType(artist);  // "artists"
```

--------------------------------

### Filter Explicit Content

Source: https://context7.com/qobuzdl/qobuz-dl/llms.txt

Removes parental advisory items (explicit tracks/albums) from a list when the explicit content filter is disabled. Use to sanitize search results or library views.

```typescript
// filterExplicit: strip parental-advisory items when explicit is disabled
const cleaned = filterExplicit(searchResults, false);  // removes explicit tracks/albums
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.