hifi-api

The manifest returned by GET /video/ is a base64-encoded JSON string. To use it, you must decode it to obtain the HLS stream URLs.

Decoded Manifest Structure:

{
  "mimeType": "application/vnd.apple.mpegurl",
  "urls": [
    "https://.../manifest.m3u8?token=..."
  ]
}

These URLs are standard HLS (.m3u8) manifests that can be played in compatible media players.

{
  "mimeType":"application/vnd.apple.mpegurl",
  "urls":[
    "https://im-fa.manifest.tidal.com/1/manifests/CAESCDQ4MjA0MTA2IhZXRWp2UUJ0Z0xhX1hjc0c1NGdra3ZBIhY2MDVpTzFpODBOVnlFenZUdFN5NkpBIhY4dXlxeUZjbDNkOUlrMnpSZ3d2RFhnIhZETU5RdEN2clNqaEdBWnNwNUVnaHpnIhY0NmJ1Z3hkWEpOY0I4ZmRjYmRkYjRRKAEwAlAB.m3u8?token=1772574630~MjUyODQzZjFjNjBlYjRhNjJlYWU0MTEzNzMwMDQ2ZmMzNzExZmY0OA=="
  ]
}

The API returns Dolby Atmos content by default if available. Because most web browsers cannot play Atmos, you should explicitly specify all desired formats except Atmos formats in your request to avoid playback issues.

Example of an Atmos response (contains EAC3_JOC):

{
  "version": "2.7",
  "data": {
    "data": {
      "id": "434493254",
      "type": "trackManifests",
      "attributes": {
        "trackPresentation": "FULL",
        "uri": "https://im-fa.manifest.tidal.com/...",
        "hash": "P9JIfU1+7xwdasgo84AJa...",
        "formats": [
          "EAC3_JOC"
        ]
      }
    }
  }
}

To set up the hifi-api, you must first authenticate with Tidal to generate credentials, then install the project dependencies.

1. Authenticate with Tidal:
   • Navigate to the tidal_auth/ directory.
   • Install requirements: pip install -r requirements.txt.
   • Run the authentication script: python3 tidal_auth.py and follow the on-screen instructions. This creates or updates a token.json file.
2. Install API Dependencies:
   • Navigate to the project root.
   • Install the main dependencies: pip install -r requirements.txt.
3. Run the Server:
   • Execute python3 main.py. By default, the server listens on 0.0.0.0:8000.

# In tidal_auth/ directory
pip install -r requirements.txt
python3 tidal_auth.py

# In project root
pip install -r requirements.txt
python3 main.py

You can manage proxy usage via environment variables or an .env file to mitigate account ban risks or handle network restrictions.

• USE_PROXIES (default: False): Enables proxy support.
• PROXIES_FILE (default: proxies.txt): Path to a text file containing proxies, one per line in the format http(s)://user:pass@hostname:port.
• ROTATE_PROXIES_ON_REFRESH (default: False): If True, rotates to a new proxy when refreshing the Tidal token.
• MAX_RETRIES (default: 2): Number of retry attempts with a new proxy if the current one fails.
• FALLBACK_TO_DIRECT_CONNECTION (default: False): WARNING: If True, the application will use the host's direct IP if all proxies fail or if proxies.txt is misconfigured.

You can deploy the hifi-api service using Docker Compose. The service is configured to run on port 8000 and requires a .env file for environment variables and a token.json file for authentication.

Key Configuration Details:

• Port Mapping: The service binds to 0.0.0.0:8000 on the host.
• Authentication: The file ./token.json must exist in the same directory as the docker-compose.yml and will be mounted as a read-only (ro) volume at /app/token.json inside the container.
• Environment Variables: Configuration is loaded from a .env file.
• Restart Policy: The service is set to unless-stopped.

services:
  web:
    build: .
    env_file:
      - .env
    ports:
      - "0.0.0.0:8000:8000"
    volumes:
      - ./token.json:/app/token.json:ro
    restart: unless-stopped

networks:
  default:
    driver: bridge

Retrieve a mix (similar to recommendations, typically containing ~60 tracks) using its unique ID.

Parameters:

• id (string, required): The unique ID of the mix.

Response: Returns a 200 OK status with a JSON object containing:

• mix: Metadata about the mix (ID, title, subtitle, graphic info, image URLs, etc.).
• items: An array of track objects included in the mix.

// Example Response Structure
{
  "version": "2.6",
  "mix": {
    "id": "0019a6f811ccf59fd0346967a1dea7",
    "title": "Subterranean Homesick Alien",
    "subTitle": "Radiohead",
    "mixType": "TRACK_MIX",
    "images": { ... }
  },
  "items": [
    {
      "id": 58990513,
      "title": "Subterranean Homesick Alien",
      "duration": 267,
      "artists": [{ "id": 64518, "name": "Radiohead" }],
      "audioQuality": "LOSSLESS"
    }
  ]
}

Retrieve cover images for a specific track or via a search query.

Parameters:

• id (int, optional): The track ID.
• q (str, optional): A track search query.

{
  "version": "2.6",
  "covers": [
    {
      "id": 311222965,
      "name": "Broke with Expensive Taste",
      "1280": "https://resources.tidal.com/images/c50c9146/3c7a/44e6/a1bc/55b20516eb29/1280x1280.jpg",
      "640": "https://resources.tidal.com/images/c50c9146/3c7a/44e6/a1bc/55b20516eb29/640x640.jpg",
      "80": "https://resources.tidal.com/images/c50c9146/3c7a/44e6/a1bc/55b20516eb29/80x80.jpg"
    }
  ]
}

The GET /album/ endpoint retrieves information about a specific album.

Parameters:

• id (int, required): The album ID.
• limit (int, optional, default 100, min 1, max 500): Number of items to return.
• offset (int, optional, default 0, min 0): Item offset for pagination.

Response: 200 OK.

GET /album/?id={album_id}&limit=100