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.

Project structure

flow/
├── backend/          # Engine: config, library, playlists, players, web API
│   ├── Online/       # Online mode (youtube, savan, streaming player)
│   ├── Offline/      # Offline mode (local files, offline player)
│   └── web/          # Flask app + templates (GUI mode)
├── flow_twinx/       # CLI launcher shell that links to backend
│   ├── main.py       # entry point (`flow`)
│   └── tui.py        # banner + prompt chrome
└── flow_twinx_tui/   # Full-screen Textual UI
    └── main.py       # entry point (`flowt`)

The backend holds all the logic; flow_twinx is the thin CLI shell that imports it.

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

TUI Mode:

Launch the full-screen Textual interface with:

flowt

It shows the local (or online) library on the left and the Now Playing panel on the right, including a live progress bar, time, mode, repeat/shuffle state and volume.

flowt also accepts the control flags:

While playing, the TUI publishes its state to ~/.flow/status.json, so flow --status (and flow --pause / --next / --previous) work against a running TUI. Its pid is tracked in ~/.flow/tui.pid.

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.