A terminal-based music player with online streaming and offline library modes.
- Dual-mode operation — It will automatically detect internet and switch between online streaming and offline playback.
- Online mode — Search and stream audio from YouTube via
yt-dlpandpython-vlc - Offline mode — Play local audio files with album support, search, and a liked-songs collection
- Download — Save tracks from YouTube to your local library with the
-dflag - Repeat & shuffle — Loop tracks n times or play in random order
- Like/unlike — Save favorites to a dedicated playlist
- Tab completion — Auto-complete commands and song names in offline mode
- Colored TUI — Cyan theme for online, magenta for offline, with borders and banners
- Background play — Play music in background and return to your shell
- Audio-reactive bars — Real-time spectrum analyzer with configurable width, height, and spacing
- Synced lyrics — Display color-coded lyrics that scroll with the song
- Gui for GUI lovers - Get a gui in web using flask for you to enjoy
- Python 3
- VLC media player (for
python-vlcbindings)
git clone https://github.com/Philast-015/Flow.git
cd flow
uv run flow_twinx/main.pyOr through pip:
pip install flow-twinx
flowflowOR if you cloned the repo:
cd flow_twinx
uv run main.py| Flag | Description |
|---|---|
-bg |
Play in background and exit to shell |
-kill |
Kill all background VLC processes |
-i |
Use it in help command to show detailed help |
-s |
Use it shuffle or play random songs |
-r |
Use it to repeat songs no of time [ -r n ] [ -r ] ( n = no of times ) |
-d |
Use it to download songs |
Run commands directly from your shell without entering interactive mode.
Play-like commands (-pl, -rd) automatically run in background.
flow -pl never gonna give you up # play (auto-bg)
flow -rd daft punk # radio (auto-bg)
flow -sh daft punk # search (show results, exit)
flow -kill # kill VLCAlso works with positional commands:
flow play never gonna give you up
flow radio daft punk
flow search daft punkShell shortcuts use your user-defined shortcuts with - prefix:
flow -svn hello # svn → savan
flow -dl never gonna give you up # dl → downloadTo launch gui mode just type :
flow --web| Command | Description |
|---|---|
play <name or #> |
Play a song by name or search result number |
search <query> |
Search YouTube (online) or library (offline) |
list |
Show all songs, albums, or liked tracks |
like <name or #> |
Add a song to your liked collection |
download <name or #> |
Save a streamed song to the local library |
radio <name> [#] |
Generate a radio mix, or play specific track |
switch |
Toggle between online and offline mode |
help |
Show available commands |
help -i |
Show available commands with detailed explanation |
| Target | Description | Range |
|---|---|---|
primary |
Color for online songs | Any color |
secondary |
Color for offline songs | Any color |
tertiary |
Color for labels | Any color |
display |
Playback display mode | none, bars, lyrics |
barwidth |
Number of bars in visualizer | 4-80 |
barheight |
Height of bars | 2-16 |
barspacing |
Space between bars | 0-4 |
Usage: config <target> <value>
- Downloads and library are stored in
~/.flow/downloads/ - Liked songs (online) are saved to
~/.flow/liked.txt - Liked songs (offline) are copied to
~/.flow/downloads/liked songs/ - User shortcuts are stored in
~/.flow/shortcuts.json - Config file:
~/.flow/config.json
flow/
├── flow_twinx/
│ ├── __init__.py
│ ├── config.py
│ ├── imports.py
│ ├── main.py
│ ├── ping.py
│ ├── tui.py
│ ├── lyrics.py # Synced lyrics fetching
│ ├── visualizer.py # Audio-reactive bars
│ ├── Online/
│ │ ├── __init__.py
│ │ ├── commands.py
│ │ ├── player.py
│ │ └── youtube.py
│ └── Offline/
│ ├── __init__.py
│ ├── commands.py
│ ├── file.py
│ ├── player.py
│ └── youtube.py
├── pyproject.toml
└── README.md
Use however you want just mention me for inspiration.