flow-twinx 0.4.0__tar.gz → 0.4.2__tar.gz

flow_twinx-0.4.2/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: flow-twinx
+Version: 0.4.2
+Summary: A terminal music player with online and offline modes
+Project-URL: Homepage, https://github.com/philast-015/flow/
+Project-URL: Issues, https://github.com/philast-015/flow/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-vlc
+Requires-Dist: yt_dlp
+Requires-Dist: ytmusicapi
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+
+# 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-dlp` and `python-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 `-d` flag
+- **Repeat & shuffle** — Loop tracks n times 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
+- **Background play** — Play music in background and return to your shell
+- **Audio-reactive bars** — Real-time spectrum analyzer with configurable width, height, and spacing
+- **Synced lyrics** — Display color-coded lyrics that scroll with the song
+
+## Requirements
+
+- Python 3
+- [VLC](https://www.videolan.org/vlc/) media player (for `python-vlc` bindings)
+
+## Installation
+
+```bash
+git clone https://github.com/Philast-015/Flow.git
+cd flow
+uv run flow_twinx/main.py
+```
+
+Or through pip:
+
+```bash
+pip install flow-twinx
+flow
+```
+
+### Note: Make sure you vlc installed or it will not play music.
+
+## Usage
+
+```bash
+flow
+```
+
+OR if you cloned the repo:
+
+```bash
+cd flow_twinx
+uv run main.py
+```
+
+### Flags
+
+| Flag    | Description                                                           |
+| ------- | --------------------------------------------------------------------- |
+| `-bg`   | Play in background and exit to shell                                  |
+| `-kill` | Kill all background VLC processes                                     |
+| `-i`    | Use it in help command to show detailed help                          |
+| `-s`    | Use it shuffle or play random songs                                   |
+| `-i`    | Use it to repeat songs no of time [ -t n ] [ -t ] ( n = no of times ) |
+
+### Shell Mode
+
+Run commands directly from your shell without entering interactive mode.
+Play-like commands (`-pl`, `-rd`) automatically run in background.
+
+```bash
+flow -pl never gonna give you up    # play (auto-bg)
+flow -rd daft punk                  # radio (auto-bg)
+flow -sh daft punk                  # search (show results, exit)
+flow -kill                          # kill VLC
+```
+
+Also works with positional commands:
+
+```bash
+flow play never gonna give you up
+flow radio daft punk
+flow search daft punk
+```
+
+Shell shortcuts use your user-defined shortcuts with `-` prefix:
+
+```bash
+flow -svn hello                     # svn → savan
+flow -dl never gonna give you up    # dl → download
+```
+
+### 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         |
+| `radio <name> [#]`     | Generate a radio mix, or play specific track      |
+| `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/`
+- User shortcuts are stored in `~/.flow/shortcuts.json`
+- Config file: `~/.flow/config.json`
+
+### 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: `config <target> <value>`
+
+## Project Structure
+
+```
+flow/
+├── flow_twinx/
+│   ├── __init__.py
+│   ├── config.py
+│   ├── imports.py
+│   ├── main.py
+│   ├── ping.py
+│   ├── tui.py
+│   ├── lyrics.py               # Synced lyrics fetching
+│   ├── visualizer.py           # Audio-reactive bars
+│   ├── 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.

flow_twinx-0.4.2/README.md

@@ -0,0 +1,157 @@
+# 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-dlp` and `python-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 `-d` flag
+- **Repeat & shuffle** — Loop tracks n times 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
+- **Background play** — Play music in background and return to your shell
+- **Audio-reactive bars** — Real-time spectrum analyzer with configurable width, height, and spacing
+- **Synced lyrics** — Display color-coded lyrics that scroll with the song
+
+## Requirements
+
+- Python 3
+- [VLC](https://www.videolan.org/vlc/) media player (for `python-vlc` bindings)
+
+## Installation
+
+```bash
+git clone https://github.com/Philast-015/Flow.git
+cd flow
+uv run flow_twinx/main.py
+```
+
+Or through pip:
+
+```bash
+pip install flow-twinx
+flow
+```
+
+### Note: Make sure you vlc installed or it will not play music.
+
+## Usage
+
+```bash
+flow
+```
+
+OR if you cloned the repo:
+
+```bash
+cd flow_twinx
+uv run main.py
+```
+
+### Flags
+
+| Flag    | Description                                                           |
+| ------- | --------------------------------------------------------------------- |
+| `-bg`   | Play in background and exit to shell                                  |
+| `-kill` | Kill all background VLC processes                                     |
+| `-i`    | Use it in help command to show detailed help                          |
+| `-s`    | Use it shuffle or play random songs                                   |
+| `-i`    | Use it to repeat songs no of time [ -t n ] [ -t ] ( n = no of times ) |
+
+### Shell Mode
+
+Run commands directly from your shell without entering interactive mode.
+Play-like commands (`-pl`, `-rd`) automatically run in background.
+
+```bash
+flow -pl never gonna give you up    # play (auto-bg)
+flow -rd daft punk                  # radio (auto-bg)
+flow -sh daft punk                  # search (show results, exit)
+flow -kill                          # kill VLC
+```
+
+Also works with positional commands:
+
+```bash
+flow play never gonna give you up
+flow radio daft punk
+flow search daft punk
+```
+
+Shell shortcuts use your user-defined shortcuts with `-` prefix:
+
+```bash
+flow -svn hello                     # svn → savan
+flow -dl never gonna give you up    # dl → download
+```
+
+### 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         |
+| `radio <name> [#]`     | Generate a radio mix, or play specific track      |
+| `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/`
+- User shortcuts are stored in `~/.flow/shortcuts.json`
+- Config file: `~/.flow/config.json`
+
+### 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: `config <target> <value>`
+
+## Project Structure
+
+```
+flow/
+├── flow_twinx/
+│   ├── __init__.py
+│   ├── config.py
+│   ├── imports.py
+│   ├── main.py
+│   ├── ping.py
+│   ├── tui.py
+│   ├── lyrics.py               # Synced lyrics fetching
+│   ├── visualizer.py           # Audio-reactive bars
+│   ├── 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.

{flow_twinx-0.4.0 → flow_twinx-0.4.2}/flow_twinx/Offline/commands.py

@@ -1,7 +1,7 @@
+import os
 import random
 from ..imports import config, merge_flags, is_connected
 from .. import shortcuts
-from .. import help_detail
 from . import file as lib
 from . import player
 
@@ -17,6 +17,20 @@ m = lambda t: print(f"{M}{t}{R}")
 e = lambda t: print(f"{E}{t}{R}")
 i = lambda t: print(f"{P if config.Mode == 'Online' else S}{t}{R}")
 
+
+def _fork_bg(label):
+    config.kill_stored()
+    pid = os.fork()
+    if pid > 0:
+        config.save_pid(pid)
+        i(f"{label} in background (PID: {pid})")
+        return False
+    devnull = os.open(os.devnull, os.O_RDWR)
+    os.dup2(devnull, 0)
+    os.dup2(devnull, 1)
+    os.dup2(devnull, 2)
+    return True
+
 try:
     import readline
     _HAS_READLINE = True
@@ -77,7 +91,6 @@ def _setup_completion():
 def run(cmd: str, extra: list[str], args):
     _setup_completion()
     cmd = shortcuts.resolve(cmd)
-    inf = "-i" in extra
     extra, args = merge_flags(extra, args)
     if cmd == "play":
         play(extra, args)
@@ -90,7 +103,7 @@ def run(cmd: str, extra: list[str], args):
     elif cmd == "switch":
         switch_mode()
     elif cmd == "help":
-        show_help(inf)
+        show_help()
     elif cmd == "short":
         shortcuts.cmd_short(extra, m)
     elif cmd == "config":
@@ -137,41 +150,95 @@ def play(extra: list[str], args):
             return
 
     _last_played = song_path
+    if getattr(args, "bg", False):
+        if not _fork_bg("Now playing"):
+            return
     player.play_file(song_path, song_path.stem, args)
 
 
 def _play_liked(args):
+    global _last_played
     liked = lib.get_liked_songs()
     if not liked:
         e("No liked songs yet")
         return
-    if getattr(args, "s", False):
-        random.shuffle(liked)
-    for song in liked:
-        _last_played = song
-        player.play_file(song, song.stem, args)
+    songs = list(liked)
+    if getattr(args, "shuffle", False):
+        random.shuffle(songs)
+    repeat = getattr(args, "repeat", False)
+    repeat_count = getattr(args, "repeat_count", 0)
+    iteration = 0
+    if getattr(args, "bg", False):
+        if not _fork_bg("Playing liked songs"):
+            return
+    try:
+        while True:
+            for song in songs:
+                _last_played = song
+                player.play_file(song, song.stem, args)
+            if not repeat:
+                break
+            iteration += 1
+            if repeat_count > 0 and iteration >= repeat_count:
+                break
+    except KeyboardInterrupt:
+        pass
 
 def _play_all(args):
-    all = lib.get_all_songs()
-    if not all:
+    global _last_played
+    all_songs = lib.get_all_songs()
+    if not all_songs:
         e("No downloaded songs yet")
         return
-    if getattr(args, "s", False):
-        random.shuffle(all)
-    for song in all:
-        _last_played = song
-        player.play_file(song, song.stem, args)
+    songs = list(all_songs)
+    if getattr(args, "shuffle", False):
+        random.shuffle(songs)
+    repeat = getattr(args, "repeat", False)
+    repeat_count = getattr(args, "repeat_count", 0)
+    iteration = 0
+    if getattr(args, "bg", False):
+        if not _fork_bg("Playing all songs"):
+            return
+    try:
+        while True:
+            for song in songs:
+                _last_played = song
+                player.play_file(song, song.stem, args)
+            if not repeat:
+                break
+            iteration += 1
+            if repeat_count > 0 and iteration >= repeat_count:
+                break
+    except KeyboardInterrupt:
+        pass
 
 def _play_album(album: str, args):
+    global _last_played
     songs = lib.get_album_songs(album)
     if not songs:
         e(f"No songs found in album '{album}'")
         return
-    if getattr(args, "s", False):
-        random.shuffle(songs)
-    for song in songs:
-        _last_played = song
-        player.play_file(song, song.stem, args)
+    tracks = list(songs)
+    if getattr(args, "shuffle", False):
+        random.shuffle(tracks)
+    repeat = getattr(args, "repeat", False)
+    repeat_count = getattr(args, "repeat_count", 0)
+    iteration = 0
+    if getattr(args, "bg", False):
+        if not _fork_bg(f"Playing album: {album}"):
+            return
+    try:
+        while True:
+            for song in tracks:
+                _last_played = song
+                player.play_file(song, song.stem, args)
+            if not repeat:
+                break
+            iteration += 1
+            if repeat_count > 0 and iteration >= repeat_count:
+                break
+    except KeyboardInterrupt:
+        pass
 
 
 def like_track():
@@ -223,20 +290,25 @@ def list_library():
 
 def switch_mode():
     if is_connected():
-        pass
+        config.Mode = "Online"
     else:
         e("No internet connection")
 
 
-def show_help(inf=False):
-    if inf:
-        print(f"{T}Offline Commands (detailed):{R}")
-        for cmd, lines in help_detail.OFFLINE_HELP.items():
-            for line in lines:
-                print(f"  {line}")
-            print()
-    else:
-        print(f"{T}Offline Commands:{R}")
-        for cmd, desc in COMMANDS.items():
-            print(f"  {T}{cmd:12s}{R} {G}{desc}{R}")
-        print(f"{G}  Use 'help -i' for detailed usage{R}")
+def show_help():
+    print(f"{T}Offline Commands:{R}")
+    for cmd, desc in COMMANDS.items():
+        print(f"  {T}{cmd:12s}{R} {G}{desc}{R}")
+    print(f"\n{T}Config:{R}")
+    print(f"  {T}config{R}      {G}Configure colors, display mode, bars{R}")
+    print(f"    {G}config help       Show all config targets and colors{R}")
+    print(f"    {G}config display    Set display: none, bars, lyrics{R}")
+    print(f"    {G}config primary    Set primary color (online songs){R}")
+    print(f"    {G}config secondary  Set secondary color (offline songs){R}")
+    print(f"    {G}config tertiary   Set tertiary color (labels){R}")
+    print(f"    {G}config barwidth   Bar count: 4-80 (current: {config.BarWidth}){R}")
+    print(f"    {G}config barheight  Bar height: 2-16 (current: {config.BarHeight}){R}")
+    print(f"    {G}config barspacing 0-4, min, fit, max (current: {config.BarSpacing}){R}")
+    print(f"\n{T}Display Modes:{R}")
+    print(f"  {G}bars{R}   Audio-reactive spectrum analyzer (needs audio output){R}")
+    print(f"  {G}none{R}   No display during playback{R}")

flow_twinx-0.4.2/flow_twinx/Offline/player.py

@@ -0,0 +1,81 @@
+import sys
+import time
+import vlc
+from ..imports import config
+from .. import visualizer
+
+P = config.Primary
+S = config.Secondary
+T = config.Tertiary
+M = config.Muted
+E = config.Red
+R = config.Reset
+
+m = lambda t: print(f"{M}{t}{R}")
+e = lambda t: print(f"{E}{t}{R}")
+i = lambda t: print(f"{P if config.Mode == 'Online' else S}{t}{R}")
+t = lambda t: print(f"{T}{t}{R}")
+
+
+def _flags_str(args):
+    if not args:
+        return ""
+    parts = []
+    if getattr(args, "repeat", False):
+        count = getattr(args, "repeat_count", 0)
+        parts.append(f"[Repeat:{'∞' if count < 0 else count}]")
+    if getattr(args, "shuffle", False):
+        parts.append("[Shuffle:On]")
+    return "  ".join(parts)
+
+
+def _display_loop(player, duration=0):
+    display = config.Display
+    if display == "none":
+        return
+
+    if display == "bars":
+        visualizer.start()
+
+    start = time.time()
+    try:
+        while player.get_state() not in (vlc.State.Ended, vlc.State.Error):
+            if display == "bars":
+                bar_str = visualizer.render(color=S, reset=R)
+                sys.stdout.write(f"\r{bar_str}")
+                sys.stdout.flush()
+            time.sleep(0.08)
+    finally:
+        if display == "bars":
+            visualizer.stop()
+        sys.stdout.write("\r" + " " * 60 + "\r\n")
+        sys.stdout.flush()
+
+
+def play_file(filepath, title, args=None):
+    instance = vlc.Instance("--no-video --quiet")
+    player = instance.media_player_new()
+    media = instance.media_new(str(filepath))
+    player.set_media(media)
+    player.play()
+
+    duration = 0
+    for _ in range(50):
+        duration = player.get_length() / 1000
+        if duration > 0:
+            break
+        time.sleep(0.1)
+    if duration <= 0:
+        duration = 0
+    dur_min, dur_sec = divmod(int(duration), 60)
+    flags = _flags_str(args)
+    i(f"\nPlaying : {title}")
+    m(f"    [{dur_min}:{dur_sec:02d}]  {flags}" if flags else f"    [{dur_min}:{dur_sec:02d}]")
+
+    try:
+        _display_loop(player, duration=duration)
+    except KeyboardInterrupt:
+        player.stop()
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+        raise