Flow Documentation

Everything you need to install, configure, and use Flow — a terminal music player with online streaming and offline library support.

# Installation

Flow requires Python 3 and VLC media player. Install VLC first, then install Flow via pip.

Terminal

pip install flow-twinx

Or clone and run from source:

Terminal

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

Tip

Make sure VLC is installed or Flow will not play music. Download it from videolan.org.

# Usage

Launch Flow by running flow in your terminal. You'll be dropped into an interactive session where you can search, play, download, and more.

Terminal

flow

Shell Mode

Run commands directly from your shell without entering interactive mode. Play-like commands (-pl, -rd) automatically run in the background.

Terminal

flow -pl never gonna give you up    # play (auto-bg)
flow love me not                    # plays one song
flow -rd daft punk                  # radio (auto-bg)
flow -sh daft punk                  # search (show results, exit)
flow -kill                          # kill VLC

# Commands

These are the interactive commands available inside Flow.

Interactive Commands

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 commands with detailed explanation

# Flags

CLI Flags

-bg     Play in background and exit to shell
-kill   Kill all background VLC processes
-i      Show detailed help
-s      Shuffle / play random songs
-r      Repeat songs (n times: -r n, or infinite: -r)
-d      Download songs

Note

Shell shortcuts use your user-defined shortcuts with a - prefix, e.g. flow -svn hello maps to your "savan" shortcut.

# Configuration

Flow stores its configuration and data in ~/.flow/. Customize colors, display mode, and visualizer settings.

Config Options

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 inside Flow:

Terminal

config display bars
config barwidth 30
config primary cyan

File Locations

~/.flow/downloads/              Downloads and library
~/.flow/liked.txt               Liked songs (online)
~/.flow/downloads/liked songs/  Liked songs (offline)
~/.flow/shortcuts.json          User shortcuts
~/.flow/config.json             Config file

# Web GUI

Flow includes a pixel-themed web UI powered by Flask. Launch it with the --web flag.

Terminal

flow --web

# Project Structure

Source Layout

flow/
├── flow_twinx/
│   ├── __init__.py
│   ├── config.py
│   ├── imports.py
│   ├── main.py
│   ├── ping.py
│   ├── tui.py
│   ├── lyrics.py
│   ├── visualizer.py
│   ├── Online/
│   │   ├── commands.py
│   │   ├── player.py
│   │   └── youtube.py
│   └── Offline/
│       ├── commands.py
│       ├── file.py
│       ├── player.py
│       └── youtube.py
├── pyproject.toml
└── README.md

For more details, check out the GitHub repository.