Metadata-Version: 2.4
Name: zenplayer
Version: 0.1.0
Summary: Minimal terminal YouTube Music client with album art now-playing display
License-Expression: MIT
Project-URL: Homepage, https://github.com/bjornramberg/zenplayer
Project-URL: Repository, https://github.com/bjornramberg/zenplayer
Project-URL: Issues, https://github.com/bjornramberg/zenplayer/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.41.0
Requires-Dist: yt-dlp>=2023.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow>=10.0
Dynamic: license-file

# zenplayer

A terminal-based YouTube Music client with an album-art now-playing display.

## Features

- **Search & play** YouTube music directly from the terminal
- **Album art now-playing** — the current track's thumbnail rendered as truecolor half-block art that fills the player panel, with a title/artist/progress-bar overlay
- **Bass-reactive glow** — the overlay background pulses with the music's low-end energy (40–240 Hz)
- **Dual-screen layout** — player view with search sidebar toggled via `ctrl+p`
- **mpv-backed playback** with seek, volume, pause, next/previous (commands dispatched over a dedicated thread)
- **Thumbnail caching** — cover art cached on disk for instant replays
- **Debounced, cached search** — async results with a 5-minute cache TTL and 300 ms debounce; result depth is configurable via `search_limit` (default 30)
- **Search preview** — arrow through results to see a square thumbnail and word-wrapped description (title, artist, duration, YouTube description) in the sidebar
- **Volume persistence** — volume changes are saved to the config file
- **History** — last played tracks stored with playback position; browse, play, remove, or clear entries
- **Session persistence** — quitting saves the current track + position (−10s); on restart, press `r` to resume where you left off
- **Zen mode** — minimal, visually dampened full-screen view with just title, artist, and basic controls
- **Stall-resistant output** — a non-blocking terminal writer with drop detection that self-recovers on slow terminals

## Requirements

- Python 3.11+
- [mpv](https://mpv.io/) (tested with 0.41.0)
- A truecolor-capable terminal for full-quality album art (falls back gracefully otherwise)

## Install

### From PyPI

```bash
pip install zenplayer
```

### From source

```bash
git clone https://github.com/bjornramberg/zenplayer.git
cd zenplayer
pip install .
```

## Usage

```bash
zenplayer
```

The search bar is focused on startup — just start typing to search. Press `escape` to unfocus it and use keyboard shortcuts.

### Controls

Keyboard shortcuts (also shown in the footer):

| Key | Action |
|---|---|
| `ctrl+p` | Toggle player / search screen |
| `ctrl+f` or `/` | Focus search input |
| `space` | Play / Pause |
| `→` / `←` | Seek forward / backward 5s |
| `+` / `-` | Volume up / down |
| `n` / `p` | Next / Previous track |
| `h` | Toggle history screen |
| `r` | Resume last session |
| `f1` | Toggle zen mode |
| `q` | Quit |

The play/pause, next, and previous buttons in the controls bar are also clickable.

### Zen mode

Press `f1` to toggle zen mode — a minimal, visually dampened view that hides the search panel, album art, queue, and controls bar. Only the track title, artist, duration, and prev/play/next buttons are shown. Press `f1` again to return to the full view.

### History

Press `h` to open the history screen — a full-screen overlay showing all previously played tracks (newest first). Select a track and press `enter` to play it from where you last left off.

| Key | Action |
|---|---|
| `enter` | Play selected track |
| `backspace` / `delete` | Remove selected entry |
| `ctrl+x` | Clear all history |
| `escape` | Close history |

### Session persistence

When you quit the app (`q`), the current track and playback position (−10s) are saved. On the next startup, a notification appears: "Press r to resume where you left off". Press `r` to continue from the saved position.

## Architecture

```
zenplayer/
├── app.py              # App shell, CSS, keybindings, bass-reactive tick
├── config.py           # JSON config (~/.config/zenplayer/config.json)
├── diagnostics.py      # Stall sampler + tick/state logging (troubleshooting)
├── nonblocking_output.py  # Non-blocking terminal writer w/ drop detection
├── audio/
│   ├── analyzer.py     # AudioCapture FFT + bass-power extraction
│   ├── capture.py      # Soundcard capture thread (via ffmpeg/arecord)
│   ├── player.py       # mpv subprocess manager (IPC over Unix socket)
│   └── extractor.py    # yt-dlp search + TrackInfo dataclass
├── screens/
│   ├── player_screen.py   # Main player layout (album art + controls + search sidebar)
│   ├── search_screen.py   # Full-screen search overlay
│   └── history_screen.py  # Full-screen history overlay
├── widgets/
│   ├── _art.py             # Shared half-block render helpers (quantize, run-merge)
│   ├── album_art.py        # AlbumArt — full-panel truecolor art (quantized, run-merged)
│   ├── search_preview.py   # SearchPreview — square thumbnail + description on highlight
│   ├── now_playing.py      # NowPlayingOverlay — title/artist/progress + bass glow
│   ├── zen_now_playing.py  # ZenNowPlaying — minimal centered view for zen mode
│   ├── controls.py         # Playback controls bar
│   ├── queue_view.py       # Current playlist queue
│   └── search_results.py   # Search result list items
└── utils/
    ├── cache.py          # Search result disk cache with TTL
    ├── history.py        # Play history persistence with positions
    ├── thumbnail.py      # Thumbnail fetch + disk cache
    └── format.py         # Duration formatting helpers
```

## How the album art works

1. When a track starts, `AlbumArt` kicks off a background worker that fetches the YouTube thumbnail (`hqdefault.jpg`) and caches it at `~/.cache/zenplayer/thumbs/`
2. The image is center-cropped to the player panel's aspect ratio, downscaled to `W×2H` pixels (W×H terminal cells), and quantized to a 128-color palette (no dithering)
3. Each cell is rendered with the `▀` half-block: the top pixel as foreground color and the bottom pixel as background color, giving full 2× vertical resolution. Consecutive cells sharing the same color pair are run-length-merged into a single span, so a 188×78 panel renders ~1.2k spans instead of ~14.7k (about 12× fewer rich styles and ~12× faster repaints)
4. A `NowPlayingOverlay` docked at the bottom shows the title, artist, and a progress bar; its background glows and tints red in sync with bass energy from a 40–240 Hz FFT band
5. While a thumbnail loads (or if none is available) a deterministic gradient cover derived from the track id is shown instead; pausing appends "(paused)" to the artist line

## Configuration

`~/.config/zenplayer/config.json`:

```json
{
  "volume": 50,
  "reactive_fps": 24,
  "search_limit": 30,
  "history_limit": 100
}
```

- `volume` — initial volume (0–100); also updated when you change it in-app
- `reactive_fps` — how often the bass analysis runs and the glow updates (default 24)
- `search_limit` — how many results each search fetches (default 30)
- `history_limit` — max entries stored in play history (default 100)

## License

MIT
