███████╗██╗      ██████╗ ██╗    ██╗
██╔════╝██║     ██╔═══██╗██║    ██║
█████╗  ██║     ██║   ██║██║ █╗ ██║
██╔══╝  ██║     ██║   ██║██║███╗██║
██║     ███████╗╚██████╔╝╚███╔███╔╝
╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝
  

Flow

A modern terminal music player with online streaming, an offline library, a TUI and a web GUI.

Installation · Quick start · Documentation · Plugins · Contributing

---

Overview

Flow is a terminal music player with two modes. Online mode streams from YouTube (through yt-dlp and VLC) and JioSaavn. Offline mode plays the songs you have already downloaded. Flow checks your connection on startup and picks the right mode for you; switch flips it whenever you like.

Everything Flow stores (downloads, likes, playlists, history, settings) lives in a single folder, ~/.flow/, and is shared by every interface. Like a song in the TUI and it is liked in the web GUI and the shell too.

▶ Watch the demo

Features

Playback

• Automatic online/offline detection with a manual switch
• YouTube search and streaming, radio mixes and JioSaavn (savan)
• Offline library with search, tab completion and liked songs
• Repeat (-r [n]), shuffle (-s) and background play (-bg)
• Audio-reactive spectrum visualizer, or synced lyrics, while a track plays

Library

• Downloads from YouTube (-d) as webm, opus, m4a or mp3
• Playlists: create, edit, merge, dedupe, reorder, and export or import .m3u
• Like and unlike, with optional auto-download on like
• Play counts in both modes, flow summary in the CLI and a History panel in the web GUI
• Rename a misspelt title once and every surface, lyrics search included, uses the new name
• Play by tag: lang punjabi or artist karan plays matching songs from your library

Lyrics

• Synced lines from LRCLIB, with YouTube Music as a fallback
• Printed in the terminal in lyrics display mode, or scrolled with the track in the web GUI

Interfaces

• An interactive CLI shell, a full-screen TUI and a local web GUI
• flow-min, a plain non-interactive CLI for scripts, ssh and agents (see below)

Extensible

• Community plugins that run as isolated processes and talk to Flow through a typed, host-validated API

Interfaces

Command	What it is
flow	Interactive shell with commands, tab completion and one-shot playback flags
flow-tui	Full-screen Textual UI with a track list and Now Playing panel
flow-web	Local web GUI served on 127.0.0.1, on the first free port from 5000 to 5005
flow-min	Plain output, no colour, spinner or prompt: one line or one --json document per command, documented exit codes, safe in pipes

All four share the same library and settings, and playback control works across them: flow-min next skips a track started from the shell, the TUI or the web GUI. See Interfaces for how to use the TUI and web GUI.

Requirements

• Linux or macOS. Flow uses Unix-only APIs, so on Windows run it under WSL.
• Python 3.14+
• VLC, used through python-vlc for all audio playback
• ffmpeg (optional), only needed to download in a format other than webm
• git (optional), only needed to install plugins

Installation

From PyPI:

pip install flow-twinx
flow

From source, with uv:

git clone https://github.com/flow-twinx/flow.git
cd flow
uv sync            # or: pip install .
uv run flow

Check that your environment is ready:

flow --check

This prints a pass/fail table for ffmpeg, VLC, yt-dlp and the other core dependencies. There is no setup step: Flow creates ~/.flow/ on demand. More detail is in Installation.

Quick start

flow -pl "never gonna give you up"        # stream from YouTube (foreground)
flow -pl "never gonna give you up" -bg    # ...in the background
flow -sh "daft punk"                      # search and show results
flow --play-off "my song"                 # play from the local library
flow --radio-off                          # shuffle-loop the whole library
flow                                      # interactive shell (type `help`)
flow-tui                                  # full-screen TUI
flow-web                                  # web GUI at http://127.0.0.1:5000
flow-min status --json                    # one JSON document, script-friendly

-pl and -sh are built-in shortcuts for play and search. You can add your own with the short command (see Command line).

Playback control works across interfaces, from any terminal:

flow --status      # show the current track
flow --pause       # play/pause the running player
flow --next        # skip
flow --seek 30     # seek 30 seconds forward

Inside the shell, help lists every command and help -i explains them in detail. The full reference is in Command line.

Plugins

Plugins are small programs installed from git repositories. They run in their own processes and use only the flow_api module, which Flow provides, to read the current track, control playback and change a safe set of settings.

flow plugins list              # browse available plugins
flow install <name>            # install by name
flow install owner/repo        # install from GitHub
flow run <name>                # run in the background (-t for foreground)
flow plugin kill <name>        # stop a running plugin

Read the user guide to use plugins, or the developer guide to write one.

Documentation

• User guide: commands and flags, TUI and web usage, configuration and storage, plugins
• Developer guide: architecture, online and offline internals, storage schemas, the control protocol, interfaces

Development

uv sync                    # install dependencies
uv run flow --check        # verify the environment
uv run pytest              # run the test suite

The tests run against a scratch HOME, so they never touch your real ~/.flow/. The backend in backend/ owns all logic; the cli/, tui/, web/ and minimal/ packages are thin front ends over it. Read CONTRIBUTING.md before opening a pull request.

Contributing

Bug reports, feature ideas and pull requests are welcome. Please read the contributing guide and the code of conduct first. To report a security issue, follow SECURITY.md rather than opening a public issue.

Disclaimer

Flow is a personal-use tool. It is not affiliated with or endorsed by YouTube, JioSaavn, VLC or any other service it connects to. You are responsible for following the terms of service of those services and the copyright laws that apply to you when you stream or download content.

Acknowledgements

Flow is built on the work of many open-source projects, including yt-dlp, VLC and python-vlc, Textual, Flask, ytmusicapi and questionary. Synced lyrics come from LRCLIB.

License

Flow is released under the MIT License. You can use, modify and share it freely, as long as the copyright notice stays with it.