# tuitube — Claude Onboarding

tuitube is a terminal music player for curated YouTube channels. It streams audio via mpv, manages a local SQLite library of 8000+ tracks, and exposes an MCP server so Claude can control playback, curate playlists, and manage the library directly.

## What Claude can do

Claude has live MCP tools connected to your library. You can ask things like:

- *"Play something chill"* — Claude searches and streams a track
- *"Make me a late night trap playlist"* — Claude searches, creates the playlist, and adds tracks
- *"Add the 7clouds Chill station and sync it"* — Claude discovers the channel and pulls all tracks
- *"What's in my claude playlist?"* — Claude lists the tracks
- *"Skip / pause / stop"* — Claude controls mpv directly

Claude does not need the TUI open to work. If Claude starts a track, the TUI header shows it automatically. The Logs screen shows recent agent activity in accent color.

## MCP Setup

Register tuitube as an MCP server once — Claude Code handles the rest:

```bash
claude mcp add tuitube tuitube mcp
```

This adds it to `~/.claude.json`. The server starts automatically when Claude Code opens. To remove: `claude mcp remove tuitube`.

> **Note:** `tuitube` must be in your PATH. If you installed via AUR or copied the binary manually, verify with `which tuitube` first.

## MCP tools available

| Tool | Params | What it does |
|------|--------|-------------|
| `search_tracks` | `query`, `favorites_only`, `limit` | Search by artist, title, or both |
| `play_track` | `youtube_id`, `title` | Stream a track via mpv |
| `stop_playback` | — | Stop current track |
| `toggle_favorite` | `track_id` | Favorite or unfavorite a track |
| `list_playlists` | — | List playlists with track counts |
| `create_playlist` | `name` | Create a new playlist |
| `add_to_playlist` | `playlist_id`, `track_ids[]` | Add multiple tracks at once |
| `list_playlist_tracks` | `playlist_id` | List tracks in a playlist |
| `list_stations` | — | List synced YouTube channels |
| `add_station` | `url`, `name`, `sync_now` | Add a channel — set `sync_now: true` to pull tracks immediately |
| `sync_station` | `station_id` | Pull new uploads (omit station_id to sync all) |

## Adding a new YouTube channel

```
add_station(url: "https://www.youtube.com/@ChannelName", name: "Display Name", sync_now: true)
```

Works with any URL format — `@handle`, `/channel/UC...`, `/c/`, `/user/`. With `sync_now: true` the response includes `inserted` (track count) and `sync_log`.

## Checking now-playing state

```bash
tuitube status --json
```

Output shape:
```json
{"playing":true,"paused":false,"youtube_id":"abc123","title":"Heather","artist":"Conan Gray","time_pos":42.1,"duration":198.0}
```

Returns `{"playing":false}` when nothing is active.

## Checking system health

```bash
tuitube doctor
```

Exits `0` if mpv and yt-dlp are found and the DB is reachable. Exits `1` with a human-readable report if anything is missing — check this before running sync or playback if you suspect an issue.

## Managing playlists via SQL

For bulk operations, direct SQL is faster than MCP:

```bash
sqlite3 ~/.local/share/tuitube/tuitube.db
```

```sql
-- list playlists
SELECT id, name FROM playlists;

-- rename a playlist
UPDATE playlists SET name = 'new name' WHERE id = 2;

-- add all tracks from an artist to a playlist
INSERT OR IGNORE INTO playlist_tracks (playlist_id, track_id)
SELECT 2, id FROM tracks WHERE artist LIKE '%Owlh%';

-- see what's in a playlist
SELECT t.song_title, t.artist
FROM playlist_tracks pt JOIN tracks t ON t.id = pt.track_id
WHERE pt.playlist_id = 2 ORDER BY pt.added_at DESC;
```

## Syncing new music

```bash
tuitube sync                        # all stations
tuitube sync --station <station_id> # one station
```

Station IDs from `list_stations` or `SELECT id, name FROM stations;`.

## Database location

Default path is platform-specific:
- Linux: `~/.local/share/tuitube/tuitube.db`
- macOS: `~/Library/Application Support/tuitube/tuitube.db`

Override: `tuitube --db /path/to/your.db`

Two-file model: `catalog.db` (curated tracks, ships with releases) merges into the user DB on launch. User playlists and favorites are never overwritten.

## TUI keybindings

| Key | Action |
|-----|--------|
| `enter` | Play / pause selected track |
| `n` | Next track in queue |
| `p` | Pause / resume |
| `space` | Toggle favorite |
| `f` | Filter favorites only |
| `d` | Download to `~/Music/tuitube` |
| `/` | Search (esc to clear) |
| `← →` | Seek ±5 seconds |
| `v` | Visualizer cycle (matrix → synthwave → off) |
| `s` | Toggle sidebar |
| `ctrl+t` | Cycle theme |
| `?` | Help screen |
| `q` | Quit |
