Skip to content

Commit 5e1a29b

Browse files
committed
Update README with usage tutorial
1 parent ac09aed commit 5e1a29b

1 file changed

Lines changed: 28 additions & 1 deletion

File tree

README.md

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ YouTube Cache is the only current Provider. TMU keeps a narrow internal Provider
1414

1515
YouTube URL Download stores downloaded audio in the YouTube Cache without adding it to the Queue. Users are responsible for downloading and keeping only content they have the right to download and keep.
1616

17+
The cache lives at `$XDG_CACHE_HOME/tmu/youtube-cache`, or `~/.cache/tmu/youtube-cache` when `XDG_CACHE_HOME` is not set. TMU manages the files in this directory; use the Library actions to rename or delete Tracks.
18+
1719
## Install and run
1820

1921
Node.js and npm are TMU's runtime and installation requirements. TMU requires Node.js 24 or newer. Run it directly from the npm package:
@@ -31,7 +33,32 @@ tmu
3133

3234
The npm package contains a prebuilt JavaScript executable, so no TypeScript loader or build step is needed after installation. Linux, macOS, and WSL (through Linux behavior) are supported; native Windows is not supported.
3335

34-
`mpv` and `yt-dlp` are separate External Tools discovered through TMU Config and dependency health checks. They are not Node packages or npm runtime requirements. When either is missing, only its corresponding feature is disabled.
36+
`mpv` and `yt-dlp` are separate command-line External Tools used for playback and downloading, respectively. They must be available on `PATH` or configured explicitly, and are not installed by npm. When either is missing, TMU keeps running and disables only the corresponding feature.
37+
38+
## Quick tutorial
39+
40+
1. Start TMU with `npx tmu`. It opens on the Playback Tab, labeled `Player`. TMU requires a terminal at least 60 columns by 16 rows.
41+
2. Press `]` twice to open Downloads. Paste a YouTube, YouTube Music, or `youtu.be` video URL and press `Enter`. Explicit playlist URLs are also supported and require confirmation before the batch starts.
42+
3. Wait for the batch summary, then press `[` to open Library. Downloading caches Tracks but does not add them to the Queue automatically.
43+
4. Select a Track with `j`/`k` or the arrow keys. Press `Enter` to Play Now, `a` to add it to the end of the Queue without playing, or `N` to make it Play Next.
44+
5. Press `[` to return to Player. Use `j`/`k` to select a queued Track, `Enter` to play it, and `Space` to pause or resume.
45+
46+
Useful global controls include `n`/`p` for next/previous, `h`/`l` to seek five seconds, `+`/`-` for volume, and `q` to quit. Press `?` outside a text input for the complete shortcut reference. Use `Esc` or `Tab` to leave a focused search or URL input first.
47+
48+
Cache Search is local: press `/`, type part of a title, channel, or YouTube video ID, and press `Enter` to return focus to the results.
49+
50+
## Configuration
51+
52+
TMU reads optional JSON configuration from `$XDG_CONFIG_HOME/tmu/config.json`, or `~/.config/tmu/config.json` when `XDG_CONFIG_HOME` is not set. No file is required for the defaults. For example, External Tool commands can be overridden when they are not on `PATH`:
53+
54+
```json
55+
{
56+
"helpers": {
57+
"mpv": "/path/to/mpv",
58+
"ytDlp": "/path/to/yt-dlp"
59+
}
60+
}
61+
```
3562

3663
## Development
3764

0 commit comments

Comments
 (0)