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.1
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.1.tar.gz | 157.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| flow_twinx-0.8.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 319.8 kB
Release files / flow_twinx-0.8.1.tar.gz
| Download URL | flow_twinx-0.8.1.tar.gz |
|---|---|
| Size | 157.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
023d8d85406d33041895b5bf3899e2dd61e8aabe91425698f19da699282f020a
|
|
BLAKE2b-256 checksum How to use checksums |
e76d3a030f3350e98776305255721cb553c1cdfb0f2a82631d359dbe1881f397
|
| 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.1-py3-none-any.whl
| Download URL | flow_twinx-0.8.1-py3-none-any.whl |
|---|---|
| Size | 162.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28a4d143a39634f59800d24fc9daea4b49e7e54fca3de40a029a5ed8686e0795
|
|
BLAKE2b-256 checksum How to use checksums |
6602254c0943256219b25870d8edc76091774345ec1a0c5c7eb891bd51c2259a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
