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, browsebrand_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, lowdefault_volume = 80 # 0-100autoplay = true # auto-play next on track endseek_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 skip
[ui]album_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 = 30col_album = 25col_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)
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.
[logging]level = "INFO" # DEBUG, INFO, WARNING, ERRORmax_bytes = 1048576 # 1 MB per log file before rotationbackup_count = 5 # number of rotated logs to keep
theme.toml
Base colors (primary, background, etc.) come from the active Textual theme — switch themes with Ctrl+P. The theme.toml file overrides app-specific colors only:
[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)
