Flow

A modern terminal based music player with TUI and web support also.

Overview

Flow is a terminal music player with online streaming and offline library modes.

Flow detects your connection and picks automatically: online mode streams from YouTube (via yt-dlp and python-vlc) and JioSaavn, offline mode. All state — downloads, likes, playlists, settings — lives in one folder and is shared between the CLI shell, the Textual TUI, and the web GUI.

Features

• Dual-mode — automatic offline/online detection with manual switch
• Online mode — YouTube search/stream, radio mixes, JioSaavn (savan)
• Offline mode — local library with search, liked songs, and tab completion
• Downloads — save tracks from YouTube (-d), formats: webm/opus/m4a/mp3
• Repeat & shuffle — -r [n] loops, -s randomizes
• Playlists — create, edit, merge, dedupe, reorder, export/import .m3u
• Like/unlike — favorites in ~/.flow/library.db, auto-download on like
• Play history — per-song play counts in both modes, an online play log, flow summary on the CLI and a History panel in the web GUI
• Background play — play in the background and go back to your shell
• Visualizer — audio-reactive spectrum bars (or synced lyrics) while playing
• Lyrics — synced lines from LRCLIB (YouTube Music as fallback): the lyrics display mode prints them in the terminal, the web GUI's lyrics button (l) scrolls them with the track
• Rename — correct a misspelt title once (rename in the CLI, R in the TUI, the ⋮ menu in the web GUI) and every surface, including lyrics search, shows the new name
• Play by tag — every download stores a one-word language and the credited artist, trimmed out of the video's metadata: lang punjabi plays your punjabi songs, artist karan every Karan Aujla one (tags to see what you have, tags scan/tags apply to tag the back catalogue)
• Three interfaces — interactive CLI shell, full-screen TUI, and a web GUI on port 5000
• Scriptable — flow-min runs the same commands with no colour, spinner or prompt: one plain line (or one --json document) per command, documented exit codes, safe in pipes, over ssh and for agents
• Plugins — community plugins run in isolated processes

Requirements

• Python 3.14+
• VLC (for python-vlc audio playback)
• ffmpeg (optional, only for non-webm download formats)

Installation

git clone https://github.com/Twinx015/Flow.git
cd Flow
uv sync            # or: pip install .
uv run flow

Or from PyPI:

pip install flow-twinx
flow

Verify with flow --check. See Installation for details.

Quick start

flow -pl "never gonna give you up"   # stream from YouTube (foreground)
flow -pl "never gonna give you up" -bg   # ...in the background
flow -sh "daft punk"                 # search, show results
flow --play-off "my song"            # play from the local library (auto-bg)
flow --radio-off                     # shuffle-loop the whole library (auto-bg)
flow                                 # interactive shell (type `help`)
flow-tui                             # full-screen TUI
flow-web                             # web GUI → http://127.0.0.1:5000
flow-min status --json               # plain non-interactive: one JSON document

Playback control works across interfaces from any terminal:

flow --status      # show the current track
flow --pause       # play/pause the running player
flow --next        # skip
flow --seek 30     # seek 30s forward

Documentation

• User guide — docs/user/: commands and flags, TUI/web usage, configuration and storage, plugins
• Developer guide — docs/dev/: architecture, mode internals, storage schemas, control protocol, interfaces

License

Use however you want, just mention me for inspiration.