Metadata-Version: 2.4
Name: flow-twinx
Version: 0.8.4
Summary: A terminal music player with online and offline modes songs sourced from youtube.
Keywords: youtube,music,cli,tui,web,musicplayer,youtube-client,flow
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: dbus-fast>=5.0.22
Requires-Dist: dbus-python>=1.4.0
Requires-Dist: flask
Requires-Dist: numpy
Requires-Dist: psutil>=7.2.2
Requires-Dist: pygobject>=3.58.0
Requires-Dist: python-vlc
Requires-Dist: questionary
Requires-Dist: sounddevice
Requires-Dist: textual>=8.2.8
Requires-Dist: tile-twinx>=1.0.1
Requires-Dist: yt-dlp>=2026.8.19
Requires-Dist: ytmusicapi

<div align="center">
  <img src="web/templates/Logo.png" alt="Flow Logo" width="120"/>

  <h1>Flow</h1>

  <p><b>A modern terminal based music player with TUI and web support also.</b></p>
</div>

---

## Overview

Flow is a terminal music player with online streaming and offline library modes.

Flow detects your connection and picks automatically: **online mode**
streams from YouTube (via `yt-dlp` and `python-vlc`) and JioSaavn, **offline
mode**. All state —
downloads, likes, playlists, settings — lives in one folder and is shared
between the CLI shell, the Textual TUI, and the web GUI.

---

## Features

- **Dual-mode** — automatic offline/online detection with manual `switch`
- **Online mode** — YouTube search/stream, radio mixes, JioSaavn (`savan`)
- **Offline mode** — local library with search, liked songs, and tab completion
- **Downloads** — save tracks from YouTube (`-d`), formats: webm/opus/m4a/mp3
- **Repeat & shuffle** — `-r [n]` loops, `-s` randomizes
- **Playlists** — create, edit, merge, dedupe, reorder, export/import `.m3u`
- **Like/unlike** — favorites in `~/.flow/library.db`, auto-download on like
- **Play history** — per-song play counts in both modes, an online play log, `flow summary` on the CLI and a **History** panel in the web GUI
- **Background play** — play in the background and go back to your shell
- **Visualizer** — audio-reactive spectrum bars (or synced lyrics) while playing
- **Lyrics** — synced lines from [LRCLIB](https://lrclib.net) (YouTube Music as fallback): the `lyrics` display mode prints them in the terminal, the web GUI's lyrics button (`l`) scrolls them with the track
- **Rename** — correct a misspelt title once (`rename` in the CLI, `R` in the TUI, the ⋮ menu in the web GUI) and every surface, including lyrics search, shows the new name
- **Play by tag** — every download stores a one-word language and the credited artist, trimmed out of the video's metadata: `lang punjabi` plays your punjabi songs, `artist karan` every Karan Aujla one (`tags` to see what you have, `tags scan`/`tags apply` to tag the back catalogue)
- **Three interfaces** — interactive CLI shell, full-screen [TUI](docs/user/interface.md), and a [web GUI](docs/user/interface.md) on port 5000
- **Scriptable** — `flow-min` runs the same commands with no colour, spinner or prompt: one plain line (or one `--json` document) per command, documented exit codes, safe in pipes, over ssh and for agents
- **Plugins** — community plugins run in isolated processes

## Requirements

- Python 3.14+
- [VLC](https://www.videolan.org/vlc/) (for `python-vlc` audio playback)
- ffmpeg (optional, only for non-webm download formats)

## Installation

```bash
git clone https://github.com/Twinx015/Flow.git
cd Flow
uv sync            # or: pip install .
uv run flow
```

Or from PyPI:

```bash
pip install flow-twinx
flow
```

Verify with `flow --check`. See [Installation](docs/user/installation.md)
for details.

## Quick start

```bash
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, show results
flow --play-off "my song"            # play from the local library (auto-bg)
flow --radio-off                     # shuffle-loop the whole library (auto-bg)
flow                                 # interactive shell (type `help`)
flow-tui                             # full-screen TUI
flow-web                             # web GUI → http://127.0.0.1:5000
flow-min status --json               # plain non-interactive: one JSON document
```

Playback control works across interfaces from any terminal:

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

## Documentation

- **User guide** — [docs/user/](docs/user/index.md): commands and flags,
  TUI/web usage, configuration and storage, plugins
- **Developer guide** — [docs/dev/](docs/dev/index.md): architecture, mode
  internals, storage schemas, control protocol, interfaces

## License

Use however you want, just mention me for inspiration.
