Privacy & Control

No reliance on public instances. All traffic stays between you and YouTube. You control the logs and data retention.

Performance

Dedicated resources mean faster processing and downloads. No rate limits from shared public APIs.

Part 1: yt-dlp Service (Docker)

To enable downloads, you need a backend service. While we provide a public instance, self-hosting ensures better performance and privacy.

1Prerequisites

Docker & Docker Compose installed on your server or local machine.
Basic knowledge of command line interface.
(Optional) A domain name with HTTPS (recommended for secure access).

2Quick Start

Clone the repository and navigate to the service directory:

git clone https://github.com/Microck/tuneport.git
cd tuneport/yt-dlp-service

3Configure Authentication

Edit the docker-compose.yml file to set your secure token. You will need this token later in the extension settings.

version: '3.8'
services:
  yt-dlp:
    build: .
    ports:
      - "3001:5000"
    volumes:
      - ./data:/data
      - ./config:/config
    environment:
      - YTDLP_TOKEN=change-me-to-a-secure-random-token

4Run the Service

Start the container in detached mode:

docker-compose up -d --build

Verify it's running:

curl http://localhost:3001/health
# Output: {"status": "ok"}

5Connect Extension

Open TunePort Settings in your browser extension.
Under "Download Provider", ensure yt-dlp is selected.
In "Instance URL", enter your server URL (e.g., http://localhost:3001 or your HTTPS domain).
In "API Token", enter the YTDLP_TOKEN you configured in step 3.

Advanced: Bypassing Bot Detection

If you encounter "Sign in to confirm you're not a bot" errors, you need to provide cookies.

Export your YouTube cookies to a cookies.txt file (using an extension like "Get cookies.txt LOCALLY").
Place the file in yt-dlp-service/config/cookies.txt on your server.
Restart the container: docker-compose restart.

Part 2: Relay Bridge (Local Files)

The Relay Bridge allows the Chrome extension to communicate with your local Spotify desktop client via Spicetify. This enables "Local Files" syncing.

1Install Spicetify

Spicetify is a CLI tool that patches the Spotify desktop client. Install it first:

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex

# macOS/Linux (Bash)
curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh

Run spicetify backup apply after installation to patch Spotify.

2Install TunePort Bridge Extension

Two options:

Option A: Marketplace

Open Spicetify Marketplace in Spotify and search for "TunePort Bridge".

Option B: Manual

# Copy tuneport.js to extensions
spicetify config extensions tuneport.js
spicetify apply

3Run the Relay Server

The relay server bridges the Chrome extension and Spotify. We host a public instance at wss://relay.micr.dev, or self-host:

cd tuneport/relay-server
npm install
npm start

The server listens on port 8080 by default. Set PORT env var to change it.

# Verify it's running
curl http://localhost:8080/health
# Output: {"status": "ok"}

4Generate and Sync Token

Open TunePort Extension Settings → Bridge Mode.
Click "Generate Token". A random 32-character hex token is created.
Copy this token.
In Spotify Desktop, click your profile menu → "TunePort Bridge Token".
Paste the token and reload Spotify.

5Enable Local Files in Spotify

Open Spotify Desktop → Settings → scroll to "Local Files".
Enable "Show Local Files".
Add Downloads/TunePort as a source folder (or wherever TunePort saves files).

How It Works

When you download a track via TunePort:

File saves to Downloads/TunePort on your machine.
Extension sends a WebSocket message to the relay with the filename and playlist ID.
Spicetify extension receives the message, refreshes Local Files, and matches the filename.
Track is added to your chosen Spotify playlist automatically.

Troubleshooting

Bridge not connecting: Ensure both extension and Spicetify use the same token.
Track not found: Verify the file is in a folder Spotify monitors. Try restarting Spotify.
Self-hosted relay: Update RELAY_BASE in tuneport.js to your server URL.
Check relay status: curl http://localhost:8080/status/YOUR_TOKEN shows connected clients.