parole-tui 1.0.0__tar.gz

parole_tui-1.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: parole-tui
+Version: 1.0.0
+Summary: Parole is a TUI tool to display lyrics from the song you are currently playing !
+Author: skueee
+Author-email: skueee <skueee@outlook.com>
+Requires-Dist: dbus-next>=0.2.3 ; sys_platform == 'linux'
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: textual>=8.2.8
+Requires-Dist: winsdk>=1.0.0b10 ; sys_platform == 'win32'
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# parole
+Parole is a TUI tool to display lyrics from the song you are currently playing !
+
+![GitHub commit activity](https://img.shields.io/github/commit-activity/t/skueee/parole?label=total%20commits)
+![GitHub Issues](https://img.shields.io/github/issues/skueee/parole)
+![GitHub Repo stars](https://img.shields.io/github/stars/skueee/parole?style=flat&color=yellow)
+
+> [!NOTE]
+> While this tool is meant to be compatible with Windows, it could be more unstable due to less testing.
+
+[![asciicast](https://asciinema.org/a/1267969.png)](https://asciinema.org/a/1267969)
+
+## Quick start
+**1. Dependencies**
+
+You will need pipx or pip to run this program
+
+**2. Download the program**
+```
+pipx install parole-lyrics
+```
+or if you don't have pipx
+```
+pip install parole-lyrics
+```
+**3. Launch the program**
+```
+parole
+```
+
+## Usage
+Here is a list of the arguments that it can take :
+```
+-h, --help                Show the available arguments
+--delay DELAY             Delay at which the program will update lyrics
+--no-song-infos           Don't show song infos at the start of the song
+--no-ansi                 Don't use terminal colors
+--line-count LINE_COUNT   Number of lyrics shown before and after the current one
+```
+
+## Features
+- Show lyrics in terminal
+- Multiplatform - Uses MPRIS or winsdk depending on your OS
+- Some customization options
+- Sync lyrics with music
+
+## Development
+You can see infos on how to contribute and develop on the CONTRIBUTING.md file
+
+## How does that works ?
+The program takes the current song using two ways, depending on the OS. If it runs on Linux, it will create a LinuxMediaProvider which uses MPRIS (through dbus-next) to get infos, while on Windows it uses a WindowsMediaProvider that uses winsdk to get infos. If the song changed, it sends a request to LRCLib to get the lyrics and display them !
+
+## Stardance
+This tool was made for Stardance, a program ran by [Hack Club](https://hackclub.com/)
+
+[My project page](https://stardance.hackclub.com/projects/63249) | [Hack Club](https://hackclub.com/) | [Stardance Program](https://stardance.hackclub.com/)
+
+## AI Notice
+
+AI was used to do research in this project, but the code was always rewritten and edited by an human. 
+
+## Credit
+
+### Libraries
+- **dbus-next, to interact with MPRIS on Linux :** [pypi.org/project/dbus-next](https://pypi.org/project/dbus-next/)
+- **Winsdk, to interact with Windows :** [pypi.org/project/winsdk](https://pypi.org/project/winsdk/)
+- **Textual, to display the TUI :** [textual.textualize.io](https://textual.textualize.io/)
+
+### API
+- **LRCLib, to get the lyrics :** [lrclib.net](https://lrclib.net/)
+
+### Project management
+- **UV, to manage the project :** [docs.astral.sh/uv](https://docs.astral.sh/uv/)
+- **uv-script, to create custom scripts (lint, format...) :** [pypi.org/project/uv-script](https://pypi.org/project/uv-script/)
+- **Ruff, to lint and format :** [docs.astral.sh/ruff](https://docs.astral.sh/ruff/)
+- **Deptry, to check dependencies problems :** [deptry.com](https://deptry.com/)

parole_tui-1.0.0/README.md

@@ -0,0 +1,76 @@
+# parole
+Parole is a TUI tool to display lyrics from the song you are currently playing !
+
+![GitHub commit activity](https://img.shields.io/github/commit-activity/t/skueee/parole?label=total%20commits)
+![GitHub Issues](https://img.shields.io/github/issues/skueee/parole)
+![GitHub Repo stars](https://img.shields.io/github/stars/skueee/parole?style=flat&color=yellow)
+
+> [!NOTE]
+> While this tool is meant to be compatible with Windows, it could be more unstable due to less testing.
+
+[![asciicast](https://asciinema.org/a/1267969.png)](https://asciinema.org/a/1267969)
+
+## Quick start
+**1. Dependencies**
+
+You will need pipx or pip to run this program
+
+**2. Download the program**
+```
+pipx install parole-lyrics
+```
+or if you don't have pipx
+```
+pip install parole-lyrics
+```
+**3. Launch the program**
+```
+parole
+```
+
+## Usage
+Here is a list of the arguments that it can take :
+```
+-h, --help                Show the available arguments
+--delay DELAY             Delay at which the program will update lyrics
+--no-song-infos           Don't show song infos at the start of the song
+--no-ansi                 Don't use terminal colors
+--line-count LINE_COUNT   Number of lyrics shown before and after the current one
+```
+
+## Features
+- Show lyrics in terminal
+- Multiplatform - Uses MPRIS or winsdk depending on your OS
+- Some customization options
+- Sync lyrics with music
+
+## Development
+You can see infos on how to contribute and develop on the CONTRIBUTING.md file
+
+## How does that works ?
+The program takes the current song using two ways, depending on the OS. If it runs on Linux, it will create a LinuxMediaProvider which uses MPRIS (through dbus-next) to get infos, while on Windows it uses a WindowsMediaProvider that uses winsdk to get infos. If the song changed, it sends a request to LRCLib to get the lyrics and display them !
+
+## Stardance
+This tool was made for Stardance, a program ran by [Hack Club](https://hackclub.com/)
+
+[My project page](https://stardance.hackclub.com/projects/63249) | [Hack Club](https://hackclub.com/) | [Stardance Program](https://stardance.hackclub.com/)
+
+## AI Notice
+
+AI was used to do research in this project, but the code was always rewritten and edited by an human. 
+
+## Credit
+
+### Libraries
+- **dbus-next, to interact with MPRIS on Linux :** [pypi.org/project/dbus-next](https://pypi.org/project/dbus-next/)
+- **Winsdk, to interact with Windows :** [pypi.org/project/winsdk](https://pypi.org/project/winsdk/)
+- **Textual, to display the TUI :** [textual.textualize.io](https://textual.textualize.io/)
+
+### API
+- **LRCLib, to get the lyrics :** [lrclib.net](https://lrclib.net/)
+
+### Project management
+- **UV, to manage the project :** [docs.astral.sh/uv](https://docs.astral.sh/uv/)
+- **uv-script, to create custom scripts (lint, format...) :** [pypi.org/project/uv-script](https://pypi.org/project/uv-script/)
+- **Ruff, to lint and format :** [docs.astral.sh/ruff](https://docs.astral.sh/ruff/)
+- **Deptry, to check dependencies problems :** [deptry.com](https://deptry.com/)

parole_tui-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "parole-tui"
+version = "1.0.0"
+description = "Parole is a TUI tool to display lyrics from the song you are currently playing !"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "dbus-next>=0.2.3 ; sys_platform == 'linux'",
+    "httpx>=0.28.1",
+    "textual>=8.2.8",
+    "winsdk>=1.0.0b10 ; sys_platform == 'win32'",
+]
+
+[[project.authors]]
+name = "skueee"
+email = "skueee@outlook.com"
+
+[project.scripts]
+parole = "parole:main"
+
+[tool.uvs.scripts]
+format = "uv run ruff format"
+lint = "uv run ruff check"
+fix = "uv run ruff check --fix"
+deps_check = "deptry ."
+checks = [
+    "fix",
+    "format",
+    "lint",
+    "deps_check",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "deptry>=0.25.1",
+    "ruff>=0.16.8",
+    "textual-dev>=1.8.0",
+    "uv-script>=0.1.9",
+]

parole_tui-1.0.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "parole-tui"
+version = "1.0.0"
+description = "Parole is a TUI tool to display lyrics from the song you are currently playing !"
+readme = "README.md"
+authors = [
+    { name = "skueee", email = "skueee@outlook.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "dbus-next>=0.2.3 ; sys_platform == 'linux'",
+    "httpx>=0.28.1",
+    "textual>=8.2.8",
+    "winsdk>=1.0.0b10 ; sys_platform == 'win32'",
+]
+
+[project.scripts]
+parole = "parole:main"
+
+[tool.uvs.scripts]
+format = "uv run ruff format"
+lint = "uv run ruff check"
+fix = "uv run ruff check --fix"
+deps_check = "deptry ."
+checks = ["fix", "format", "lint", "deps_check"]
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "deptry>=0.25.1",
+    "ruff>=0.16.8",
+    "textual-dev>=1.8.0",
+    "uv-script>=0.1.9",
+]

parole_tui-1.0.0/src/parole_tui/__init__.py

@@ -0,0 +1,4 @@
+from . import lrclib, monitor, parole
+from .parole import main
+
+__all__ = ["lrclib", "main", "monitor", "parole"]

parole_tui-1.0.0/src/parole_tui/lrclib.py

@@ -0,0 +1,34 @@
+import asyncio
+import time
+
+import httpx
+
+rate_limit_timeout: int = 0
+endpoint = "https://lrclib.net"
+
+
+async def get(url: str, params: httpx.ParamsType = None) -> httpx.Response:
+    global rate_limit_timeout
+
+    if int(time.time()) < rate_limit_timeout:
+        await asyncio.sleep(int(time.time()) - rate_limit_timeout)
+
+    async with httpx.AsyncClient() as client:
+        r = await client.get(url, params=params)
+
+    # Handle rate limit
+    if r.status_code == 429:
+        rate_limit_timeout = int(time.time()) + int(r.headers["Retry-After"])
+        r = await get(url, params)
+
+    return r
+
+
+async def get_lyrics(artist: str, title: str, album: str | None = None):
+    if album != None:
+        parameters = {"track_name": title, "artist_name": artist, "album_name": album}
+    else:
+        parameters = {"track_name": title, "artist_name": artist}
+
+    response = await get(endpoint + "/api/get", params=parameters)
+    return response.json()

parole_tui-1.0.0/src/parole_tui/monitor.py

@@ -0,0 +1,221 @@
+import abc
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+if sys.platform == "linux":
+    from dbus_next.aio import MessageBus
+elif sys.platform == "win32":
+    from winsdk.windows.media.control import (
+        GlobalSystemMediaTransportControlsSessionManager as MediaManager,
+    )
+    from winsdk.windows.media.control import (
+        GlobalSystemMediaTransportControlsSessionPlaybackStatus as PlaybackStatus,
+    )
+else:
+    MessageBus = None
+
+
+class NoMPRISException(Exception):
+    def __init__(self):
+        super().__init__(
+            "MPRIS was not found on your system\nIf you are not on Linux, this error is intended"
+        )
+
+
+class MPRISNotConnectedException(Exception):
+    def __init__(self):
+        super().__init__("The MPRIS client is not connected")
+
+
+@dataclass
+class TrackMetadata:
+    active: bool
+    title: str | None = None
+    album: str | None = None
+    artist: str | None = None
+
+
+class BaseMediaProvider(abc.ABC):
+    @abc.abstractmethod
+    async def init(self):
+        """Initialize the provider"""
+
+    async def get_metadata(self) -> TrackMetadata | None:
+        """Fetch current song details."""
+
+    async def get_position(self) -> float | None:
+        """Get current position"""
+
+
+class LinuxMediaProvider(BaseMediaProvider):
+    def __init__(self):
+        self.bus = None
+
+    async def init(self):
+        if not self.bus:
+            return await self.connect()
+
+    async def connect(self):
+        if not MessageBus:
+            raise NoMPRISException
+        try:
+            # Connect to the Linux Session D-Bus
+            self.bus = await MessageBus().connect()
+            return True
+        except Exception:  # noqa: BLE001
+            raise NoMPRISException
+
+    async def get_active_player_name(self) -> str | None:
+        if not self.bus:
+            raise MPRISNotConnectedException
+
+        introspection = await self.bus.introspect(
+            "org.freedesktop.DBus", "/org/freedesktop/DBus"
+        )
+
+        dbus_obj = self.bus.get_proxy_object(
+            "org.freedesktop.DBus", "/org/freedesktop/DBus", introspection
+        )
+        dbus_iface = dbus_obj.get_interface("org.freedesktop.DBus")
+        names = await dbus_iface.call_list_names()
+
+        for name in names:
+            if name.startswith("org.mpris.MediaPlayer2."):
+                return name
+        return None
+
+    async def get_metadata(self) -> TrackMetadata:
+        player_name = await self.get_active_player_name()
+        if not player_name:
+            return TrackMetadata(active=False)
+
+        introspection = await self.bus.introspect(
+            player_name, "/org/mpris/MediaPlayer2"
+        )
+        obj = self.bus.get_proxy_object(
+            player_name, "/org/mpris/MediaPlayer2", introspection
+        )
+
+        props = obj.get_interface("org.freedesktop.DBus.Properties")
+
+        metadata_variant = await props.call_get(
+            "org.mpris.MediaPlayer2.Player", "Metadata"
+        )
+
+        metadata = metadata_variant.value
+
+        artist_var = metadata.get("xesam:artist", [None])
+        title_var = metadata.get("xesam:title", None)
+        album_var = metadata.get("xesam:album", None)
+
+        title = title_var.value if title_var else None
+        album = album_var.value if album_var else None
+        artist = None
+        try:
+            artist = artist_var.value[0]
+        except AttributeError:
+            artist = artist_var[0]
+
+        return TrackMetadata(
+            active=True,
+            title=title,
+            album=album,
+            artist=artist,
+        )
+
+    async def get_position(self) -> float | None:
+        player_name = await self.get_active_player_name()
+        if not player_name:
+            return None
+
+        introspection = await self.bus.introspect(
+            player_name, "/org/mpris/MediaPlayer2"
+        )
+        obj = self.bus.get_proxy_object(
+            player_name, "/org/mpris/MediaPlayer2", introspection
+        )
+        props = obj.get_interface("org.freedesktop.DBus.Properties")
+        position_variant = await props.call_get(
+            "org.mpris.MediaPlayer2.Player", "Position"
+        )
+
+        position = getattr(position_variant, "value", position_variant)
+        return position / 1_000_000.0
+
+
+class WindowsMediaProvider(BaseMediaProvider):
+    def __init__(self):
+        self.manager = None
+
+    async def init(self):
+        if not self.manager:
+            await self.connect()
+
+    async def connect(self):
+        try:
+            self.manager = await MediaManager.request_async()
+        except OSError:
+            self.manager = None
+
+    async def get_metadata(self) -> TrackMetadata | None:
+        session = self.manager.get_current_session()
+        if not session:
+            return TrackMetadata(active=False)
+
+        try:
+            info = await session.try_get_media_properties_async()
+        except PermissionError:
+            return TrackMetadata(active=False)
+
+        return TrackMetadata(
+            active=True,
+            title=info.title,
+            album=info.album_title,
+            artist=info.artist,
+        )
+
+    async def get_position(self) -> float | None:
+        session = self.manager.get_current_session()
+        if not session:
+            return None
+
+        timeline = session.get_timeline_properties()
+        playback_info = session.get_playback_info()
+
+        base_position = timeline.position.total_seconds()
+
+        if playback_info.playback_status != PlaybackStatus.PLAYING:
+            return base_position
+
+        last_updated = timeline.last_updated_time
+        now = datetime.now(UTC)
+        elapsed = (now - last_updated).total_seconds()
+
+        rate = getattr(playback_info, "playback_rate", None)
+        if rate is None:
+            rate = 1.0
+        current_position = base_position + (elapsed * rate)
+
+        end_time = timeline.end_time.total_seconds()
+        return min(current_position, end_time)
+
+
+class PlatformNotSupportedError(Exception):
+    def __init__(self, platform: str) -> None:
+        super().__init__(f"Platform not supported: {platform}")
+
+
+_cached_provider: BaseMediaProvider | None = None
+
+
+def get_provider() -> BaseMediaProvider:
+    global _cached_provider
+    if _cached_provider is None:
+        if sys.platform == "linux":
+            _cached_provider = LinuxMediaProvider()
+        elif sys.platform == "win32":
+            _cached_provider = WindowsMediaProvider()
+        else:
+            raise PlatformNotSupportedError(sys.platform)
+    return _cached_provider

parole_tui-1.0.0/src/parole_tui/parole.py

@@ -0,0 +1,240 @@
+import argparse
+import bisect
+import random
+import re
+from array import array
+from typing import ClassVar
+
+from textual.app import App, Binding, ComposeResult
+from textual.widgets import Label
+
+from . import lrclib, monitor
+
+current_lyrics: array[str] | None
+current_timestamps: array[float] | None
+current_infos: array | None
+trackid: str | None = None
+active: bool
+
+
+async def get_lyrics(title, artist, album: str | None = None):
+    lyrics = await lrclib.get_lyrics(title=title, artist=artist, album=album)
+    if "syncedLyrics" in lyrics:
+        return {"lyrics": lyrics["syncedLyrics"]}
+    else:
+        return None
+
+
+async def get_metadata():
+    provider = monitor.get_provider()
+    await provider.init()
+    metadata = await provider.get_metadata()
+    if metadata.artist == None and metadata.title == None and metadata.album == None:
+        run = False
+    else:
+        run = True
+    return [run, metadata.artist, metadata.title, metadata.album]
+
+
+async def get_position():
+    provider = monitor.get_provider()
+    await provider.init()
+    position = await provider.get_position()
+    return position
+
+
+async def check_if_new_song():
+    global trackid, active, current_lyrics, current_timestamps, current_infos
+    trackid = None if not isinstance(trackid, str) else trackid
+    metadata = await get_metadata()
+    if trackid == None or trackid != f"{metadata[1]}__{metadata[2]}":
+        if metadata[0] == True:
+            trackid = f"{metadata[1]}__{metadata[2]}"
+            lyrics = await get_lyrics(metadata[2], metadata[1])
+            current_lyrics = []
+            current_timestamps = []
+
+            TIMESTAMP_REGEX = re.compile(r"\[(\d{1,2}):(\d{2})(?:\.(\d{2,3}))?\]")
+            try:
+                for i in lyrics["lyrics"].splitlines():
+                    match = TIMESTAMP_REGEX.search(i)
+
+                    if not match:
+                        current_lyrics = None
+                        break
+
+                    # Transform the timestamp into a position in seconds (because playerctl only outputs the position in seconds)
+                    seconds = (
+                        int(match.group(1)) * 60
+                        + int(match.group(2))
+                        + int(match.group(3) or 0) / 100
+                    )
+                    current_timestamps.append(seconds)
+
+                    # Check if the lyric is not empty and then append it
+                    lyric = TIMESTAMP_REGEX.sub("", i).strip()
+                    if not lyric:
+                        lyric = random.choice(["♫", "♪"])
+
+                    current_lyrics.append(lyric)
+            except AttributeError, TypeError:
+                current_lyrics = None
+
+            active = True
+            current_infos = [metadata[1], metadata[2]]
+
+        else:
+            current_timestamps = None
+            current_infos = None
+            trackid = None
+            current_lyrics = None
+            active = False
+
+
+async def get_current_lyrics(show_infos: bool, line_count: int):
+    if active:
+        if current_lyrics == None:
+            return ["Can't find lyrics for this song"]
+        pos = float(await get_position())
+
+        index = bisect.bisect_right(current_timestamps, pos) - 1
+
+        prev_lines = []
+        for offset in range(line_count, 0, -1):
+            target_idx = index - offset
+            prev_lines.append(
+                current_lyrics[target_idx]
+                if 0 <= target_idx < len(current_lyrics)
+                else ""
+            )
+
+        curr_line = (
+            current_lyrics[index]
+            if 0 <= index < len(current_lyrics)
+            else (f"{current_infos[0]} - {current_infos[1]}" if show_infos else "")
+        )
+
+        next_lines = []
+        for offset in range(1, line_count + 1):
+            target_idx = index + offset
+            next_lines.append(
+                current_lyrics[target_idx]
+                if 0 <= target_idx < len(current_lyrics)
+                else ""
+            )
+
+        return [prev_lines, curr_line, next_lines]
+    else:
+        return ["No song is playing"]
+
+
+async def get_thing_to_display(show_infos: bool, lines_count: int):
+    await check_if_new_song()
+    return await get_current_lyrics(show_infos, lines_count)
+
+
+class ParoleApp(App):
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding("ctrl+c", "quit", "Quit", show=True, priority=True),
+    ]
+    CSS_PATH = "textual.tcss"
+
+    def __init__(self, delay_ms: float, show_infos: bool, ansi: bool, line_count: int):
+        super().__init__()
+        self.delay_seconds = delay_ms / 1000.0
+        self.show_infos = show_infos
+        self.ansi_color = ansi
+        self.line_count = line_count
+
+    def compose(self) -> ComposeResult:
+        if self.line_count > 0:
+            for i in range(self.line_count):
+                yield Label(
+                    " ", id=f"before-label-{i}", classes="secundary-label before-label"
+                )
+        yield Label("Loading...", id="main-label")
+        if self.line_count > 0:
+            for i in range(self.line_count):
+                yield Label(
+                    " ", id=f"after-label-{i}", classes="secundary-label after-label"
+                )
+
+    def on_mount(self) -> ComposeResult:
+        self.set_interval(self.delay_seconds, self.update_label)
+
+    async def update_label(self) -> None:
+        main_label = self.query_one("#main-label", Label)
+        before_labels = self.query(".before-label")
+        after_labels = self.query(".after-label")
+
+        lyrics = await get_thing_to_display(self.show_infos, self.line_count)
+        try:
+            before_lines, current_line, after_lines = lyrics
+        except ValueError:
+            current_line = lyrics[0]
+            before_lines = []
+            after_lines = []
+
+        main_label.update(current_line)
+
+        for label, text in zip(before_labels, before_lines):
+            label.display = True
+            label.update(text)
+
+        for label, text in zip(after_labels, after_lines):
+            label.display = True
+            label.update(text)
+
+        if len(before_lines) == 0:
+            for label in before_labels:
+                label.display = False
+
+        if len(after_lines) == 0:
+            for label in after_labels:
+                label.display = False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Parole is a TUI tool to display lyrics from the song you are currently playing"
+    )
+    parser.add_argument(
+        "--delay",
+        type=float,
+        default=100,
+        help="Delay at which the program will update lyrics",
+    )
+    parser.add_argument(
+        "--no-song-infos",
+        dest="show_infos",
+        action="store_false",
+        default=True,
+        help="Don't show song infos at the start of the song",
+    )
+    parser.add_argument(
+        "--no-ansi",
+        dest="ansi",
+        action="store_false",
+        default=True,
+        help="Don't use terminal colors",
+    )
+    parser.add_argument(
+        "--line-count",
+        dest="line_count",
+        default=1,
+        type=int,
+        help="Number of lyrics shown before and after the current one",
+    )
+
+    args = parser.parse_args()
+    app = ParoleApp(
+        delay_ms=args.delay,
+        show_infos=args.show_infos,
+        ansi=args.ansi,
+        line_count=args.line_count,
+    )
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

parole_tui-1.0.0/src/parole_tui/textual.tcss

@@ -0,0 +1,17 @@
+Screen {
+    align: center middle;
+}
+
+#main-label {
+    text-style: bold;
+    text-align: center;
+    content-align: center middle;
+    width: 100%;
+}
+
+.secundary-label {
+    opacity: 50%;
+    text-align: center;
+    content-align: center middle;
+    width: 100%;
+}