App-specific color overrides on top of the active Textual theme
auth.json
YouTube Music credentials (auto-generated by ytm setup)
Open the config directory in your editor:
ytm config
config.toml
Every section is optional — anything you don't set falls back to defaults.
[general]
[general]startup_page = "library" # library, search, browseplayback_bar_position = "bottom" # "bottom" or "top"brand_account_id = "" # YouTube Brand Account ID (21-digit; find at myaccount.google.com/brandaccounts)check_for_updates = true # check PyPI once per 24h, surface a one-time toast on new version
[playback]
[playback]audio_quality = "high" # high, medium, lowprefer_audio = true # prefer audio-only streams over video (audio uses less bandwidth)default_volume = 80 # 0-100autoplay = true # auto-play next on track endgapless = true # preload the next track for gapless transitionsseek_step = 5 # seconds per +/- seekapi_timeout = 15 # seconds for ytmusicapi calls before failoverresume_on_launch = true # restore last-playing track + position on app start; press space to continue
resume_on_launch (added v1.7.0) stages the last-playing track + position into the playback bar on startup. Press space to continue from where you were. Set to false to start fresh every time.
[cache]
[cache]enabled = truemax_size_mb = 1024 # 1GB default LRU audio cacheprefetch_next = true # resolve next track's stream URL in background for instant skiplocation = "" # blank = default cache dir; set a path to override
[yt_dlp]
[yt_dlp]cookies_file = "" # Optional: path to yt-dlp Netscape cookies.txtca_bundle = "" # Optional: path to a custom CA cert bundle for SSL-inspecting # corporate proxies (Zscaler, Netskope, etc.)remote_components = "" # Optional: ejs:npm/ejs:github (enables remote JS component downloads)js_runtimes = "" # Optional: bun, bun:/path/to/bun, node, quickjs, etc.
[search]
[search]default_mode = "music" # "music" (songs only) or "all" (all result types)max_history = 500 # number of past search queries to rememberpredictive = true # show search suggestions as you type
[ui]
[ui]theme = "ytm-dark" # startup default Textual theme; runtime changes are saved in session.jsonalbum_art = true # show colored half-block album art in playback barprogress_style = "block" # block or linesidebar_width = 30col_index = 4 # 0 = auto-fill widthcol_title = 0 # 0 = auto-fillcol_artist = 0 # 0 = auto-fillcol_album = 0 # 0 = auto-fillcol_duration = 8bidi_mode = "auto" # auto, reorder, passthrough — RTL text handlingregion = "ZZ" # ISO 3166-1 alpha-2 (or "ZZ" = Global, default) — Browse → Charts. 68 regions selectable; locale-style codes like "ES-ES" auto-normalise to "ES".home_shelves = 3 # number of recommendation shelves on Browse → For You (1–25)show_selection_info = true # show focused-item full name in the row above the playback barsidebar_overflow = "truncate" # "truncate" (1-row + ellipsis) or "wrap" (multi-line names)show_queue_source = true # show "Generated from: …" header on radio/discovery queues
theme is the startup default. Changing theme from Textual's command palette (Ctrl+P → Theme) updates the current session and is saved in session.json, not config.toml. To make the active theme the new default, run Ctrl+P → Set Current Theme as Default.
Per-playlist Shuffle lock state (set via the Shuffle lock toggle in the
Library page playlist header) is persisted separately to
~/.config/ytm-player/shuffle_prefs.json. There's nothing to configure
in config.toml for it.
[notifications]
[notifications]enabled = truetimeout_seconds = 5format = "{title} — {artist}" # template for the now-playing notification body
[mpris]
[mpris]enabled = true
[discord]
[discord]enabled = false # requires `pip install ytm-player[discord]`client_id = "" # blank uses the bundled app; set your own # Discord application ID to publish under it
[logging]level = "WARNING" # DEBUG, INFO, WARNING, ERROR, CRITICALmax_bytes = 5242880 # 5 MB per log file before rotationbackup_count = 3 # number of rotated logs to keepkeep_crashes = 10 # max number of crash files to retain in crashes/
theme.toml
Base colors (primary, background, etc.) come from the active Textual theme. Choose the startup default with [ui] theme, switch the current session with Ctrl+P → Theme, and use theme.toml for app-specific color overrides:
[colors]playback_bar_bg = "#1a1a1a"selected_item = "#2a2a2a"progress_filled = "#ff0000"progress_empty = "#555555"lyrics_played = "#999999"lyrics_current = "#ff4e45" # defaults to the theme accent if unsetlyrics_upcoming = "#aaaaaa"active_tab = "#ffffff"inactive_tab = "#999999"
The lyrics_current color falls back to the active theme's accent (and then to #ff4e45 red as the absolute last-resort default). Override only if you want something different from your theme's accent.
keymap.toml
For custom keybinding overrides, see docs/keybindings.md for the full key list and the customization syntax.
Available filters: songs, videos, albums, artists, playlists, community_playlists, featured_playlists.
Stats and history
ytm stats # Listening stats summaryytm stats --json # Machine-readableytm history # Recent play historyytm history search # Recent search history
Cache management
ytm cache status # Cache size + entry countytm cache clear # Wipe all cached audio
Playback control (IPC, requires TUI running)
ytm play # Resume playbackytm pause # Pause playbackytm next # Skip to next trackytm prev # Previous trackytm seek +10 # Seek forward 10 secondsytm seek -5 # Seek backward 5 secondsytm seek 1:30 # Seek to 1:30 (m:ss or h:mm:ss)
Like / dislike (IPC)
ytm like # Like current trackytm dislike # Dislike current trackytm unlike # Remove like/dislike (sets to INDIFFERENT)
Status (IPC)
ytm now # Current track info (JSON)ytm status # Player status (JSON)ytm queue # Queue contents (JSON)ytm queue add VIDEO_ID # Add track by video IDytm queue clear # Clear queue
Reads track names + artists from the Spotify playlist.
→
2
Match
Searches YouTube Music with fuzzy matching (60% title + 40% artist weighted score).
→
3
Resolve
Tracks scoring 85%+ are auto-matched. Lower scores prompt you to pick from candidates or skip.
→
4
Create
Creates a new private playlist on your YouTube Music account with all matched tracks.
Two import modes
Single mode
Up to ~100 tracks. Best for most playlists.
How: paste one Spotify playlist URL.
Multi mode
100+ tracks. For large playlists, the importer splits the URL list across multiple calls.
How: enter a name + number of parts, then paste a URL for each part.
Run from the TUI or the CLI
From the TUI
Click Import in the footer (or press the import button). A popup lets you paste URLs, choose single or multi mode, and watch import progress in real time.
Interactive flow: fetches tracks, shows match results, lets you resolve ambiguous matches, names the playlist, then creates it.
Extraction methods
1. Spotify Web API
Full pagination, handles any playlist size. Requires a free Spotify Developer app (you set up client_id + client_secret in ~/.config/ytm-player/spotify.json).
→ falls back to →
2. Scraper fallback
No credentials needed. Limited to ~100 tracks. Used automatically if Spotify API credentials aren't configured.
Try the parser
Paste a Spotify playlist URL — see how the importer extracts the playlist ID locally (no network call):
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
