YouTube & YouTube Music Integration

Use Cliamp to browse YouTube and YouTube Music playlists and play tracks through its audio pipeline. EQ, the visualizer, and other effects apply. Install yt-dlp for playback.

Cliamp automatically sorts playlists into two providers:

Quick start:

  • Cookie-based (zero OAuth): Set cookies_from = "your_browser" in ~/.config/cliamp/config.toml, or select a browser in cliamp setup. cliamp loads playlists through the existing browser session. You do not need OAuth credentials or ytmusic_credentials.json.
  • OAuth-based: Set Google Cloud OAuth credentials as described below. Then press Enter in the provider browser to sign in. cliamp stores credentials in ~/.config/cliamp/ytmusic_credentials.json.

Setup

Option 1: Browser cookies (zero setup)

Add the browser name to ~/.config/cliamp/config.toml, or run cliamp setup:

[ytmusic]
cookies_from = "chrome"

Supported browsers: chrome, firefox, brave, edge, opera, safari, chromium.

You can set a specific profile or path with yt-dlp browser:path syntax. For example, the Zen browser, a Firefox fork, stores its profile outside the default path:

[ytmusic]
cookies_from = "firefox:~/.config/zen"

Option 2: Custom Google Cloud OAuth client

Creating your client ID

  1. Go to console.cloud.google.com and sign in.
  2. Create a project or select an existing project.
  3. Open APIs & Services > Library.
  4. Search for YouTube Data API v3 and click Enable.
  5. Open APIs & Services > Credentials.
  6. Click Create Credentials > OAuth client ID.
  7. If prompted, configure the OAuth consent screen first:
    • User Type: External
    • Enter an app name, such as "cliamp", and an email address.
    • Add scope: https://www.googleapis.com/auth/youtube.readonly
    • Add yourself as a test user. This is required while the app is in "Testing" status.
  8. For the OAuth client ID:
    • Application type: Desktop app
    • Name: Any name, such as "cliamp".
  9. Copy the Client ID and Client Secret.

Configuring cliamp with OAuth

Add the client ID and client secret to ~/.config/cliamp/config.toml:

[ytmusic]
client_id = "your_client_id_here"
client_secret = "your_client_secret_here"

Optional: To play uploaded or private tracks, set the browser for cookie access:

[ytmusic]
client_id = "your_client_id_here"
client_secret = "your_client_secret_here"
cookies_from = "chrome"

Optional: Control whether list= URLs expand a full playlist or resolve as one video:

[ytmusic]
expand_playlist = false

When expand_playlist is true (default), cliamp expands URLs with a list= parameter. This includes auto-generated mixes (RDAMVM, RDMM), album playlists (OLAK), and custom playlists (PL). cliamp loads the first 20 tracks immediately, then gets the remaining tracks in background batches. Set it to false, or pass --no-expand-playlist, to remove the playlist parameter and resolve only one video.

Run cliamp, cliamp --provider ytmusic, or cliamp --provider youtube. Select a provider and press Enter to sign in. cliamp stores credentials in ~/.config/cliamp/ytmusic_credentials.json. Later launches refresh them without a message.

Usage

After authentication, YouTube and YouTube Music appear as separate providers. Press Esc/b to open the provider browser.

Both use the same Google account sign-in. cliamp classifies playlists by video category and stores the result on disk. Later launches use the cached result.

Controls

When focused on the provider panel:

Key Action
Up Down / j k Navigate playlists
Enter Load the selected playlist
Tab Switch between provider and playlist focus
Ctrl+R Refresh playlists from YouTube
Esc / b Open provider browser

After you load a playlist, Cliamp returns to the standard playlist view. Use the usual controls for seek, volume, EQ, shuffle, repeat, queue, search, and lyrics.

Playlists

With OAuth authentication, cliamp splits playlists between the two providers:

YouTube Music shows:

YouTube shows:

For OAuth setups, cliamp samples a video from each playlist and checks its YouTube category. It stores results in ~/.config/cliamp/ytmusic_classification.json and ~/.config/cliamp/ytmusic_cache.json. Delete these files or press Ctrl+R in the TUI to classify again and refresh.

For cookie-backed providers (cookies_from), cliamp adds all custom playlists to both YouTube Music and YouTube results without category classification. It does not create ytmusic_classification.json. It stores results and tracks in memory for the current session. Press Ctrl+R to refresh them.

Troubleshooting

Requirements