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-dlpandpython-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
-dflag - Repeat & shuffle — Loop tracks or play in random order
- Like/unlike — Save favorites to a dedicated playlist
- Tab completion — Auto-complete commands and song names in offline mode
- Colored TUI — Cyan theme for online, magenta for offline, with borders and banners
Requirements
- Python 3
- VLC media player (for
python-vlcbindings)
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
Note: Make sure you vlc installed or it will not play music.
Usage
cd flow_twinx
uv run main.py
Or direct if you have used pypi
flow
| Flag | Description |
|---|---|
-r |
Repeat mode (loop current track) |
-s |
Shuffle mode (random order) |
-d |
Download mode (save streamed audio to library) |
-i |
Use it in help command to show detailed help |
Commands
| Command | Description |
|---|---|
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 |
switch |
Toggle between online and offline mode |
help |
Show available commands |
help -i |
Show available commands with detailed explanation |
Configuration
- Downloads and library are stored in
~/.flow/downloads/ - Liked songs (online) are saved to
~/.flow/liked.txt - Liked songs (offline) are copied to
~/.flow/downloads/liked songs/
Project Structure
flow/
├── flow_twinx/
│ ├── __init__.py
│ ├── config.py
│ ├── imports.py
│ ├── main.py
│ ├── ping.py
│ ├── tui.py
│ ├── 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
flow_twinx-0.4.0.tar.gz
(15.7 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file flow_twinx-0.4.0.tar.gz.
File metadata
- Download URL: flow_twinx-0.4.0.tar.gz
- Upload date:
- Size: 15.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
49a6e281b0cfb55c1104b2c8d489c40df04dcce39782e43cdd1878d4825d718d
|
|
| MD5 |
0ff801e1b5db6a33a80266531e449548
|
|
| BLAKE2b-256 |
621e2903f49ce281faf64b428e71d39480035bff5f9c7d0986399cd3ac2b273b
|
File details
Details for the file flow_twinx-0.4.0-py3-none-any.whl.
File metadata
- Download URL: flow_twinx-0.4.0-py3-none-any.whl
- Upload date:
- Size: 20.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
431bb7878a2b14ed272a091476c0e3a9446ea2b63ad20237ba6fdfd71851c22e
|
|
| MD5 |
244be3b520e37690dc21a78553738df7
|
|
| BLAKE2b-256 |
ddb1a565049624ec8e2842d6bb3af39683c99738a844c8d9b2c390bb65dd171e
|
