# Playback TUI

A fully local terminal-based music player to play and download Spotify/SoundCloud playlists.

![Playback TUI Screenshot](image.png)

## Installation

### 1. Install FFmpeg

FFmpeg is required for downloading and processing audio.

**macOS:**
```bash
brew install ffmpeg
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt update && sudo apt install ffmpeg
```

**Linux (Fedora):**
```bash
sudo dnf install ffmpeg
```

**Windows:**
```cmd
choco install ffmpeg
```
Or download from [ffmpeg.org](https://ffmpeg.org/download.html)

### 2. Install Playback TUI

```bash
uv tool install playback-tui
```

## Setup

After installation, open the settings to configure your playlists and Spotify credentials:

1. Run `playback-tui`
2. Press `:` to open the command palette
3. Type `settings` (or `set`) and press Enter
4. Configure:
   - **Playlists JSON**: Path to your playlists configuration file
   - **Spotify Client ID**: Your Spotify API client ID
   - **Spotify Client Secret**: Your Spotify API client secret

To get Spotify credentials:
1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)
2. Create a new app
3. Copy the Client ID and Client Secret into settings

## Commands

### Quick Commands

| Key | Action |
|-----|--------|
| `Space` | Play/pause |
| `n` | Next song |
| `p` | Previous song |
| `q` | Open queue |
| `j` / `k` | Navigate up/down |
| `g` / `G` | Go to top/bottom |
| `/` | Search songs |
| `:` | Open command palette |

### Command Palette (`:` commands)

| Command | Aliases | Description |
|---------|---------|-------------|
| `:shuffle` | `:s`, `:sh` | Shuffle current playlist |
| `:shuffle-all` | `:sa`, `:shall` | Shuffle all songs |
| `:download-status` | `:ds`, `:status` | Show download status |
| `:settings` | `:set`, `:config` | Open settings |
| `:quit` | `:q`, `:x`, `:exit` | Quit application |
| `:help` | `:h`, `:?` | Show all commands |

## Features

- Browse and play local music playlists
- Download playlists from Spotify and SoundCloud
- Shuffle and queue management
- Volume control and progress tracking
- Search functionality
- Cross-platform support (Windows, macOS, Linux)
