Skip to main content

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 (tested with 0.41.0)
  • A truecolor-capable terminal for full-quality album art (falls back gracefully otherwise)

Install

From PyPI

pip install zenplayer

From source

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

Usage

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:

{
  "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

Metadata

Release files for zenplayer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zenplayer 0.1.0
File Size Uploaded Provenance Actions
zenplayer-0.1.0.tar.gz 27.6 kB With provenance Details for zenplayer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zenplayer 0.1.0
File Interpreter ABI Platform Actions
zenplayer-0.1.0-py3-none-any.whl Python 3 none any Details for zenplayer-0.1.0-py3-none-any.whl

Total release size: 61.7 kB

Release files / zenplayer-0.1.0.tar.gz

Download URL zenplayer-0.1.0.tar.gz
Size 27.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a171d0718b9bcf24786a224147a66c796f7872fa02c820cf2c5a62fa2d36644b
BLAKE2b-256 checksum
How to use checksums
203c411d19f5cf0f8e34a440677503cd0ab5b28f0781d97083fd785fc1330ec8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

Release files / zenplayer-0.1.0-py3-none-any.whl

Download URL zenplayer-0.1.0-py3-none-any.whl
Size 34.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f53cf4ca29e9b90131139a929be2741541fcff094172ddab7f9c3814635da6c4
BLAKE2b-256 checksum
How to use checksums
982ffda964d5db826183535073428de680051227d54b772e8dc7aa993c2d7701
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

Security for zenplayer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zenplayer-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page