Flow
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 plays your local library under ~/.flow/downloads/. 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,-srandomizes - 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 summaryon 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
- Three interfaces — interactive CLI shell, full-screen TUI, and a web GUI on port 5000
- Plugins — community plugins run in isolated processes
Requirements
- Python 3.14+
- VLC (for
python-vlcaudio 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
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.
1 maintainer
Metadata
1 maintainer
Release files for flow-twinx 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| flow_twinx-0.8.0.tar.gz | 149.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| flow_twinx-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 304.3 kB
Release files / flow_twinx-0.8.0.tar.gz
| Download URL | flow_twinx-0.8.0.tar.gz |
|---|---|
| Size | 149.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c694f6281c0cbc65cd6c3292706593a2da2c0832a54e61c8a667844a9c37c90
|
|
BLAKE2b-256 checksum How to use checksums |
7a361201ee8c22ae29e5a45a4d18533ec5b69a728aff624285578c8102012403
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / flow_twinx-0.8.0-py3-none-any.whl
| Download URL | flow_twinx-0.8.0-py3-none-any.whl |
|---|---|
| Size | 154.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0b3d5dea0201522c593166d9664be953ef0a87710e157bb17a6d1791c3dd0d12
|
|
BLAKE2b-256 checksum How to use checksums |
5856928d50f954600b50a2865a0e42ce9f432c5d493601377620813cbd2f709e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
