Flow

A terminal-based music player with online streaming and offline library modes. Auto-detects your connection and switches seamlessly between YouTube and your local files.

Download Read the Docs

# Why Flow?

Flow was built to give you a beautiful, feature-rich music experience right in your terminal. No Electron, no bloat — just a fast, colorful TUI that gets out of your way.

Dual-Mode

Automatically detects your internet connection and switches between online YouTube streaming and offline local playback.

Download & Listen

Save tracks from YouTube to your local library with the -d flag. Your music, always available.

Audio-Reactive Bars

Real-time spectrum analyzer with configurable width, height, and spacing for a visual music experience.

Synced Lyrics

Color-coded lyrics that scroll with the song, keeping you in sync with every beat.

Repeat & Shuffle

Loop tracks n times or shuffle your playlist. Full control over your listening experience.

Web GUI

Prefer a graphical interface? Launch a pixel-themed web UI with flow --web.

# Quick Start

Get Flow running in under a minute. Install via pip and start listening immediately.

Terminal

pip install flow-twinx

Then launch Flow:

Terminal

flow

Tip

Make sure VLC is installed on your system. Flow uses python-vlc for playback.

# How It Works

Flow automatically detects your network status and switches between online and offline mode. Customize colors, visualizer settings, and shortcuts through the config file at ~/.flow/config.json.

~/.flow/config.json

{
  "primary": "cyan",
  "secondary": "magenta",
  "tertiary": "yellow",
  "display": "bars",
  "barwidth": "20",
  "barheight": "8",
  "barspacing": "2"
}

Note

Changes to your config are applied on next launch. Use the config command inside Flow for quick adjustments.

# Shell Mode

Run commands directly from your shell without entering interactive mode. Play-like commands 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

# What's Next?

Dive deeper into Flow by exploring the documentation, or download it now and start listening.

Explore Docs Get Flow