127 lines
3.1 KiB
Markdown
127 lines
3.1 KiB
Markdown
# Tidal Proxy Server
|
|
|
|
Self-hosted proxy for Tidal API that provides lossless audio manifests. Compatible with Monochrome and SpotiFLAC-Mobile clients.
|
|
|
|
## Features
|
|
|
|
- Proxy Tidal playback info requests (`/v1/dl/tid2`)
|
|
- UA validation (compatible with SpotiFLAC-Mobile format)
|
|
- Quality enforcement (rejects LOW/HIGH responses when lossless requested)
|
|
- Format extraction from DASH manifests
|
|
- Health check endpoint
|
|
|
|
## Requirements
|
|
|
|
- Go 1.21+ (for building from source)
|
|
- Docker (optional, for containerized deployment)
|
|
- A valid Tidal access token (from user login)
|
|
|
|
## Quick Start
|
|
|
|
### Run with Go
|
|
|
|
```bash
|
|
cd tidal-proxy
|
|
go build -o tidal-proxy
|
|
./tidal-proxy
|
|
```
|
|
|
|
### Run with Docker
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### Run with Docker (custom config)
|
|
|
|
```bash
|
|
docker run -d \
|
|
-p 8080:8080 \
|
|
-e REQUIRED_UA_PREFIX="SpotiFLAC-Mobile/" \
|
|
-e ALLOW_ANY_QUALITY=false \
|
|
-e COUNTRY_CODE=US \
|
|
tidal-proxy
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Environment Variable | Default | Description |
|
|
|---------------------|---------|-------------|
|
|
| `PORT` | `:8080` | Server listen address |
|
|
| `REQUIRED_UA_PREFIX` | `SpotiFLAC-Mobile/` | Required User-Agent prefix |
|
|
| `ALLOW_ANY_QUALITY` | `false` | If true, don't reject LOW/HIGH responses |
|
|
| `COUNTRY_CODE` | `US` | Tidal country code for requests |
|
|
|
|
## API Endpoints
|
|
|
|
### `POST /v1/dl/tid2`
|
|
|
|
Get track playback info and manifest.
|
|
|
|
**Headers:**
|
|
- `User-Agent`: Must start with `REQUIRED_UA_PREFIX` (e.g., `SpotiFLAC-Mobile/4.5.5`)
|
|
- `Authorization`: `Bearer <your-tidal-token>` (or use `X-Tidal-Token` header)
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"id": "356965156",
|
|
"quality": "LOSSLESS"
|
|
}
|
|
```
|
|
|
|
**Quality values:** `LOW`, `HIGH`, `LOSSLESS`, `HI_RES_LOSSLESS`
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": "{\"trackId\":356965156,\"audioQuality\":\"LOSSLESS\",\"manifest\":\"...\",\"formats\":[\"FLAC\"]}"
|
|
}
|
|
```
|
|
|
|
### `GET /health`
|
|
|
|
Health check endpoint.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"uptime": "2h30m15s"
|
|
}
|
|
```
|
|
|
|
### `GET /auth`
|
|
|
|
Returns auth instructions.
|
|
|
|
## Getting a Tidal Token
|
|
|
|
This proxy requires a valid Tidal access token. You can obtain one by:
|
|
|
|
1. **Using the Tidal web app**: Open browser dev tools while logged into Tidal, find the `Authorization` header from any API request
|
|
2. **Using OAuth**: Register a Tidal developer app at https://developer.tidal.com and use the PKCE flow
|
|
3. **From Monochrome**: The token is stored in your browser's localStorage after login
|
|
|
|
**Important:** Tokens expire. The proxy does not handle token refresh - you need to provide a valid token with each request.
|
|
|
|
## Integration with Monochrome
|
|
|
|
Update your Monochrome settings to use the self-hosted proxy:
|
|
|
|
1. Go to Settings > Tidal Web
|
|
2. Set Proxy URL to `http://localhost:8080`
|
|
3. The proxy will use your existing Tidal token from Monochrome's localStorage
|
|
|
|
Or programmatically:
|
|
```javascript
|
|
tidalWebSettings.setProxyUrl('http://localhost:8080');
|
|
```
|
|
|
|
## Security Notes
|
|
|
|
- **Never expose this proxy publicly** without proper authentication
|
|
- The proxy forwards your Tidal token to Tidal's API
|
|
- UA validation provides minimal protection - consider adding API keys for production use
|
|
- Tokens are not logged or stored by the proxy
|