ytmusic-cli 0.3.1

A terminal YouTube Music player built with Rust, Ratatui, mpv, yt-dlp, and rs-ytmusic-api
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# ytmusic-cli

Rust terminal YouTube Music player using Ratatui, `rust-ytmusic-api`, mpv IPC, yt-dlp cache, queue, history, favorites, playlists, and synced lyrics.

## Runtime dependencies

```bash
sudo pacman -S mpv yt-dlp
```

## Run

```bash
cargo run
```

## Features

- Search songs through `rust-ytmusic-api`
- Play tracks with `mpv`
- Control mpv through JSON IPC over Unix socket
- Cache audio to `~/Music/ytmusic.cli` using `yt-dlp`
- Queue with non-destructive playback index
- First played track is inserted into the queue and becomes the active queue item
- Auto queue refill when upcoming tracks after the current queue index are below 5
- Autoplay next track when mpv reports the current track has finished
- Auto queue mode refills from `fetch_watch_queue()` when the remaining upcoming list is below 5
- Playlist playback mode stays limited to selected playlist tracks and never refills from YouTube Music
- History and favorites saved locally
- Local playlists saved locally
- Lyrics tab with LRCLIB synced lyrics first, YouTube Music lyrics fallback second
- Non-blocking lyrics fetch; the TUI stays responsive while lyrics load
- File-based lyrics cache at `~/Music/ytmusic.cli/{video_id}-lyrics.txt`
- Synced lyric line highlight based on mpv `time-pos`

## Lyrics behavior

Lyrics are resolved in this order:

1. Local lyrics text file from `~/Music/ytmusic.cli/{video_id}-lyrics.txt`
2. Legacy JSON cache from `~/.local/share/ytmusic-cli/lyrics.json` if it exists, then migrate to the text file cache
3. LRCLIB `/api/get` with `track_name`, `artist_name`, and `duration`
4. LRCLIB `/api/search` fallback
5. YouTube Music lyrics through `rust-ytmusic-api`

LRCLIB synced lyrics are parsed from LRC timestamps and highlighted in the lyrics tab according to mpv playback position. Fetching runs in a Tokio task, so pressing `6` shows a loading message instead of freezing the UI.

## Keybinds

```txt
/        search mode
Enter    search / play selected
1        search tab
2        queue tab
3        history tab
4        favorites tab
5        playlists tab
6        lyrics tab
Tab      switch playlist focus between playlist list and playlist tracks
j/Down   next item
k/Up     previous item
J        move queue item down
K        move queue item up
a        enqueue selected
n        next track
b        previous track
r        refill auto queue from current track
f        toggle favorite
p        add selected/current track to default playlist
P        create playlist
c        cache selected track
Space    pause/resume
s        stop
h/Left   seek -5s
l/Right  seek +5s
+        volume up
-        volume down
q/Esc    quit
```

## Data paths

```txt
~/.local/share/ytmusic-cli/history.json
~/.local/share/ytmusic-cli/favorites.json
~/.local/share/ytmusic-cli/playlists.json
~/.local/share/ytmusic-cli/lyrics.json   # legacy/migration cache
~/Music/ytmusic.cli/{video_id}-lyrics.txt
~/Music/ytmusic.cli/{video_id}.m4a
```

## Auto queue dedupe

Auto refill uses a session-level `queued_video_ids` set. A track that was already added to the queue, played in the current session, or exists in previous/current queue state will not be added again by `fetch_watch_queue()`.

Playlist playback does not call `fetch_watch_queue()` and keeps queue limited to the selected playlist.