plavno-0.1.0 is not a library.

plavno

A lightweight TUI player for Linux with music streams from popular services, library shuffle, and mouse controls.

Features · Quick start · Services · Controls

Features

MPRIS desktop integration — control playback with media keys, desktop media widgets, or playerctl. Track information and album artwork appear in desktop controls.
Service waves and shuffle — Yandex My Vibe, VK recommendations, library shuffle, and Wave Shuffle across connected services.
Likes and dislikes — like/unlike in Yandex or VK, exclude unwanted tracks, and undo dislikes.
Mouse and hotkeys — click controls, drag to seek, scroll for volume, and select track text to copy.
Listening history — search past plays by title or artist and replay tracks.
RAM buffering and prefetch — start playback while downloading; cache adjacent tracks for seeking and replay.
Audio-reactive visuals — an animated wave with album artwork, toggled with v.

Quick start

Requires Rust, pkg-config, ALSA and D-Bus headers: libasound2-dev libdbus-1-dev (Debian/Ubuntu) or alsa-lib-devel dbus-devel (Fedora). Audio uses the ALSA default device; PipeWire/PulseAudio needs its ALSA plugin. Install ffmpeg for HLS playback.

cargo build --release
export PATH="$PWD/target/release:$PATH"
plavno sources

Connect a service below, then start it with plavno --source SOURCE. For development, use cargo run or cargo check and keep the build cache.

Services

Service	Source key	Stable	Playback	Connection
Yandex Music	`yandex`	🟢	My Vibe, favorites shuffle, flow presets	OAuth token; full tracks require account access / Yandex Plus
VK Music	`vk`	🟢	Recommendations, My Music shuffle, flow presets	Installed Chrome/Chromium or manual session import
SoundCloud	`soundcloud`	—	Track stations	Browser sign-in or a public seed track
Spotify	`spotify`	—	Track radio	Optional Rust helper; Premium and OAuth
YouTube Music	`ytmusic`	—	Home mixes and track radio	Optional Rust helper; cookies or a public seed

Yandex Music

Get an OAuth token from the token guide, paste it into plavno login yandex, then run plavno --source yandex.

VK Music

Run plavno login vk and sign in through installed Chrome/Chromium, then run plavno --source vk. Alternatively, import a session manually with plavno login vk --manual.

SoundCloud

Run plavno login soundcloud, sign in through Chrome/Chromium, and choose a seed track when prompted. Start with plavno --source soundcloud. Manual setup also supports public track stations.

Spotify

Build the Spotify helper, then run plavno login spotify and paste a JSON profile with a seed track URI, OAuth token with streaming scope, and client ID. Premium is required. Start with plavno --source spotify.

YouTube Music

Build the YouTube helper, then run plavno login ytmusic and paste {"cookies":"/absolute/path/youtube-cookies.txt"} using a Netscape cookie export, or {"seed":"VIDEO_ID_OR_URL"} for public radio. Start with plavno --source ytmusic.

See service setup for profile examples and troubleshooting.

Run

plavno sources                         # List supported services and connection status
plavno --source yandex                  # Yandex Music My Vibe
plavno --source yandex --favorites      # Shuffle Yandex favorites
plavno --source vk                      # VK recommendations
plavno --source vk --favorites          # Shuffle VK My Music
plavno --source mixed                   # Mix waves from connected services
plavno --file /path/to/track.flac        # Play a local file
plavno --no-wave                        # Start without visualization

Controls

Buttons display their hotkeys and support mouse clicks.

Key	Action
Space / x	Pause or resume / stop
p / n	Previous / next track
← / →	Seek 5 seconds; Shift or Ctrl: 30 seconds
Home / End	Start / end of track
+ / -	Volume; also click beside the percentage
l	Like / unlike in Yandex favorites or VK My Music
d / u	Dislike and skip / undo dislike
h or /	History: type to search, ↑/↓ select, Enter play
s / m	Choose a service / mix service waves
w / f	New wave / library shuffle (VK: My Music)
g	Flow: Calm, Balanced, Energetic, Work; choose with 1–4 or a click
v	Toggle visualization
Ctrl+C	Copy selected text; quit when nothing is selected
Esc / q	Clear selection or close a view / quit

Click or drag the progress bar to seek. Scroll over it to seek; elsewhere scroll changes volume. Drag over the title or artist and press Ctrl+C to copy (requires terminal OSC 52 support). In History and Sources, click to select, double-click to play, scroll to navigate, and right-click to close.

Flow changes recommendations. Work requests calm ambient without vocals on Yandex and calm instrumental tracks on VK. w returns from library shuffle to a new wave; VK filters recent tracks to avoid repeating the initial queue.

Playback and data

Playback starts while downloading, at the highest available supported quality. Previous, current, and next audio files stay in RAM for seeking and replay; RAM use depends on track size. Service audio is not saved to disk.

Configuration lives in ~/.config/plavno; history and permanent dislikes live in ~/.local/state/plavno. XDG_CONFIG_HOME and XDG_STATE_HOME override these roots. History stores metadata for the last 2000 plays. Yandex and VK also receive account dislikes; u undoes them. Volume starts at 100%.

Media keys and playerctl work through session D-Bus, for example: playerctl -p plavno play-pause or playerctl -p plavno position 5+.

Checks

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings

Release steps: Publishing to crates.io.

License

Apache License 2.0.

plavno 0.1.0