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/liked.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

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 and library are stored in ~/.flow/downloads/
• Liked songs (online) are saved to ~/.flow/liked.json
• Liked songs (offline) are copied to ~/.flow/downloads/liked songs/
• User shortcuts are stored in ~/.flow/shortcuts.json
• Config file: ~/.flow/config.json

Project Structure

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

License

Use however you want just mention me for inspiration.