Flow

A terminal-based music player with online streaming and offline library modes.

Features

• 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-dlp and python-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 -d flag
• Repeat & shuffle — Loop tracks n times or play in random order
• Like/unlike — Toggle favorites on/off, stored in ~/.flow/library.json
• Playlist play — Create playlists and play them with playlist play <name>
• 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

Requirements

• Python 3
• VLC media player (for python-vlc bindings)

Installation

git clone https://github.com/Philast-015/Flow.git
cd flow
uv run flow_twinx/main.py

Or through pip:

pip install flow-twinx
flow

Note: Make sure vlc is installed it can break on some PC but mostly work without vlc.

Usage

flow

OR if you cloned the repo:

cd flow_twinx
uv run main.py

Flags

Shell Mode

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 VLC
flow --play-off dil                 # play a local song (offline, auto-bg)
flow --radio-off                    # radio over shuffled local library (auto-bg)
flow --resume                       # replay last track from status.json (auto-bg)

Also works with positional commands:

flow play never gonna give you up
flow radio daft punk
flow search daft punk

Shell shortcuts use your user-defined shortcuts with - prefix:

flow -svn hello                     # svn → savan
flow -dl never gonna give you up    # dl → download

Gui Mode:

To launch gui mode just type :

flow --web

Commands

Config Options

Usage: config <target> <value>

Configuration

• Downloads are stored in ~/.flow/downloads/ (named by video id, e.g. TucWbkH5WX0.opus)
• All per-song data (liked/downloaded/title/paths) lives in the single file ~/.flow/library.json, keyed by video id
• Thumbnails are downloaded on like/download to ~/.flow/downloads/.cache/<video_id>.jpg
• User shortcuts are stored in ~/.flow/shortcuts.json
• Config file: ~/.flow/config.json

License

Use however you want just mention me for inspiration.