tuiman 1.0.0__tar.gz

tuiman-1.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: tuiman
+Version: 1.0.0
+Summary: A TUI music player for your favourite local mp3 albums!
+License: MIT
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mutagen>=1.47.0
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pygame-ce>=2.5.7
+Requires-Dist: rich-pixels>=3.0.1
+Requires-Dist: textual>=8.2.4
+Requires-Dist: textual-autocomplete>=4.0.6
+Requires-Dist: textual-dev>=1.8.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+

tuiman-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["uv_build"]
+backend-path = []
+build-backend = "uv_build"
+
+[project]
+name = "tuiman"
+version = "1.0.0"
+description = "A TUI music player for your favourite local mp3 albums!"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.14"
+dependencies = [
+    "aiofiles>=25.1.0",
+    "httpx>=0.28.1",
+    "mutagen>=1.47.0",
+    "platformdirs>=4.9.6",
+    "pygame-ce>=2.5.7",
+    "rich-pixels>=3.0.1",
+    "textual>=8.2.4",
+    "textual-autocomplete>=4.0.6",
+    "textual-dev>=1.8.0",
+]
+
+[project.scripts]
+my-cli = "tuiman.app:main"

tuiman-1.0.0/src/tuiman/app.py

@@ -0,0 +1,145 @@
+import random
+from pathlib import Path
+from textual.app import App, ComposeResult
+from textual.color import Color
+from textual.containers import Horizontal, Vertical
+from textual.css.scalar import Scalar, Unit
+from textual.events import Click
+from textual.screen import ModalScreen
+from textual.widgets import Footer, Input, Label, Button, OptionList
+from textual_autocomplete import PathAutoComplete
+from modules.bottom_box import BottomBox, PlayControls, QueueOptions
+from modules.top_box import TopBox, AlbumList
+from utils.models import ReversibleIterator
+from utils.player import init_player, pause, resume
+from utils.caching import Cache
+
+
+init_player()
+path_cacher = Cache()
+
+class DirectoryDialog(ModalScreen[str]):
+    def compose(self) -> ComposeResult:
+        with Vertical(id="dialog-container"):
+            yield Label(" Enter albums folder path:")
+            input_widget = Input(placeholder="/path/to/albums", id="modal_input")
+            yield input_widget
+            yield PathAutoComplete(target=input_widget, path="../..")
+            with Horizontal(id="dialog-buttons"):
+                yield Button("Load", variant="primary", id="dia-sub")
+                yield Button("Load previous path", variant="primary", id="dia-prev")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "dia-sub":
+            raw = self.query_one(Input).value.strip().strip("'\"")
+            if raw:
+                path = Path(raw).expanduser().resolve()
+
+                if path.is_dir():
+                    path_cacher.create_path_cache(path = str(path))
+                    self.dismiss(str(path))
+                else:
+                    self.query_one(Label).update(" ❌ Invalid path, try again:")
+        # load previous path
+        elif event.button.id == "dia-prev":
+            path = path_cacher.find_path_cache()
+            if path:
+                self.dismiss(str(path))
+
+
+class Tuiman(App):
+    """main App class"""
+    def __init__(self):
+        super().__init__()
+        self.library_path: str = ""
+
+    CSS_PATH = "music.tcss"
+    BINDINGS = [
+        ("n", "backward", "Backward"),
+        ("space", "pause", "Pause"),
+        ("m", "forward", "Forward"),
+        ("q", "show_queue", "Show Queue"),
+        ("alt+q", "shuffle_queue", "Shuffle Queue"),
+    ]
+    AUTO_FOCUS: str | None = "#modal_input"
+
+    def compose(self) -> ComposeResult:
+        # yield Header()
+        yield Footer()
+        # topbox
+        yield BottomBox()
+
+    def action_pause(self) -> None:
+        self.query_one(PlayControls).query("Button")[1].press()
+    def action_forward(self) -> None:
+        self.query_one(PlayControls).query("Button")[2].press()
+    def action_backward(self) -> None:
+        self.query_one(PlayControls).query("Button")[0].press()
+    def action_show_queue(self) -> None:
+        self.query_one(QueueOptions).query_one("#show-queue").press()
+    def action_shuffle_queue(self) -> None:
+        self.query_one(QueueOptions).query_one("#shuffle-queue").press()
+
+    def on_mount(self) -> None:
+        self.push_screen(DirectoryDialog(), self.on_directory_chosen)
+        # pass
+
+    def on_directory_chosen(self, path: str) -> None:
+        self.library_path = path
+        self.mount(TopBox(self.library_path), before=self.query_one(BottomBox))
+        # set library here
+
+    def on_button_pressed(self, event: Button.Pressed)->None:
+        """handle button presses"""
+
+        # show Queue if button pressed
+        if event.button.id == "show-queue":
+            album_obj = self.query_one(AlbumList)
+            # logger(f"{album_obj.styles.width.value}, {album_obj.styles.width.unit}, {album_obj.styles.width.percent_unit}")
+            if album_obj.styles.width == Scalar(value=100.0, unit=Unit.WIDTH ,percent_unit=Unit.WIDTH):
+                album_obj.styles.width = Scalar(value=40.0, unit=Unit.WIDTH ,percent_unit=Unit.WIDTH)
+            else:
+                album_obj.styles.width = Scalar(value=100.0, unit=Unit.WIDTH ,percent_unit=Unit.WIDTH)
+
+        # play/pause, forward backward buttons
+        if event.button.id == "pause":
+            if event.button.label == "||":
+                event.button.label = "▶"
+                event.button.styles.border = ("round", "yellow")
+                event.button.styles.color = "deeppink"
+                pause()
+            else:
+                event.button.label = "||"
+                event.button.styles.border = ("round", "deeppink")
+                event.button.styles.color = Color(255, 255, 255, 0.7)
+                resume()
+
+        if "playback" in event.button.classes:
+            tb = self.query_one(TopBox)
+            # forward backward logic
+            queue = getattr(tb, "queue_iterator", None)
+
+            if queue is not None:
+                if event.button.id == "backward":
+                    queue.pos = (queue.pos - 2) % len(queue.lst)
+                tb.song_manager(song_name=next(queue))
+
+        if "queue-btn" in event.button.classes:
+            tb = self.query_one(TopBox)
+            # shuffle logic, shuffles the queue, updates queue iterator and plays song using it.
+            if tb.song_queue:
+                if event.button.id == "shuffle-queue":
+                    random.shuffle(tb.song_queue)
+                    tb.queue_iterator = ReversibleIterator(lst=tb.song_queue)
+                    tb.song_manager(song_name=next(tb.queue_iterator))
+
+    def on_click(self, event: Click) -> None:
+        if not isinstance(event.widget, (Input, OptionList)):
+            self.screen.set_focus(None)
+            for option_list in self.query(OptionList):
+                option_list.highlighted = None
+
+
+def main():
+    app = Tuiman()
+    app.run()

tuiman-1.0.0/src/tuiman/modules/bottom_box.py

@@ -0,0 +1,68 @@
+from textual.app import ComposeResult
+from textual.color import Gradient
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Button, Label, ProgressBar
+from src.tuiman.utils.player import get_progress, get_current
+
+
+class PlayControls(Widget):
+    """Pause/resume, forward/backward controls"""
+    def compose(self) -> ComposeResult:
+        yield Button("⏮", id="backward", classes="playback", variant="primary", flat=True)
+        yield Button("||", id="pause",variant="success", flat=True)
+        yield Button("⏭", id="forward", classes="playback",variant="primary", flat=True)
+
+
+class Playback(Widget):
+    """Displays playing bar. Everything from updating the Playing: to the progressbar seems to be autonomous (depends
+    on output give by player.py)"""
+    current_song = reactive("-----")
+
+    def compose(self) -> ComposeResult:
+        gradient = Gradient.from_colors("#881177","#aa3355","#cc6666","#ee9944","#eedd00","#99dd55","#44dd88","#22ccbb","#00bbcc","#0099cc","#3366bb","#663399",)
+        yield Label("Playing: -----", id="song-name")
+        yield ProgressBar(total=100, show_eta=False, gradient=gradient)
+
+    def on_mount(self) -> None:
+        """Progress bar"""
+        self.set_interval(1 /30, self.make_progress)
+        self.set_interval(1/30 , self.sync_song)
+
+    def make_progress(self) -> None:
+        """Called automatically to advance the progress bar."""
+        progress = 0
+        time_stamps = get_progress()
+        if not time_stamps[2]:
+            try:
+                progress = int((time_stamps[0]/time_stamps[1]) * 100)
+            except ZeroDivisionError:
+                progress = 0
+        self.query_one(ProgressBar).update(progress=progress)
+
+    def sync_song(self)->None:
+        c_song = get_current().get("song")
+        if c_song != self.current_song:
+            self.current_song = c_song
+
+    def watch_current_song(self, song):
+        self.query_one("#song-name", Label).update(f"Playing: {song}")
+
+class QueueOptions(Widget):
+    """show/ hide queue, shuffle options"""
+
+    def compose(self) -> ComposeResult:
+        yield Button("Queue", variant="primary", flat=True, classes="queue-btn", id="show-queue")
+        yield Button("Shuffle", variant="primary", flat=True, classes="queue-btn" ,id="shuffle-queue")
+
+
+    def on_mount(self) -> None:
+        self.query_one("#show-queue").border_title = "Show"
+        self.query_one("#shuffle-queue").border_subtitle = "queue"
+
+class BottomBox(Widget):
+    """Class containing play controls and playback bar"""
+    def compose(self) -> ComposeResult:
+        yield PlayControls()
+        yield Playback()
+        yield QueueOptions()

tuiman-1.0.0/src/tuiman/modules/top_box.py

@@ -0,0 +1,306 @@
+import asyncio
+from rich_pixels import Pixels
+from textual import work
+from textual.app import ComposeResult, RenderResult
+from textual.containers import VerticalScroll
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Input, OptionList, RadioSet, RadioButton, Markdown
+from src.tuiman.utils.caching import Cache
+from src.tuiman.utils.library_manager import search_function, load_library
+from src.tuiman.utils.lyrics import extract_lyrics
+from src.tuiman.utils.models import ReversibleIterator
+from src.tuiman.utils.player import get_progress, play_song
+
+cache = Cache()
+
+class AlbumCover(Widget):
+    """using rich renderable to render ascii album cover"""
+    path: reactive[str] = reactive("./media/unknown.png")
+
+    def __init__(self):
+        super().__init__()
+        self._album_cover = None
+
+    def on_mount(self) -> None:
+        self._album_cover = Pixels.from_image_path("./media/unknown.png", resize=(20, 15))
+
+    def watch_path(self, new_path: str) -> None:
+        self._album_cover = Pixels.from_image_path(new_path or "./media/unknown.png", resize=(20, 15))
+        self.refresh()
+
+    def render(self) -> RenderResult:
+        return self._album_cover
+
+class AlbumList(Widget):
+    """Lists user albums"""
+
+    data: reactive[dict] = reactive({}, init=False)
+    def __init__(self, data: dict) -> None:
+        super().__init__()
+        self.albums = [*data.keys()]
+
+    def compose(self) -> ComposeResult:
+        yield Input(placeholder="Search album name", type="text")
+        yield OptionList(
+            *self.albums
+        )
+
+    def on_mount(self) -> None:
+        self.border_title = "Albums"
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        search_function(self, event, self.albums)
+
+    def watch_data(self, data: dict) -> None:
+        """"""
+        self.albums = [*data.keys()]
+        option_list = self.query_one(OptionList)
+        option_list.clear_options()
+        for album in self.albums:
+            option_list.add_option(album)
+
+
+class SongList(Widget):
+    """Lists album songs"""
+
+    def __init__(self, song_data: dict) -> None:
+        super().__init__()
+        self.song_data = song_data
+        self.current_songs: list = [] # these are songs in currently selected album
+
+    def compose(self) -> ComposeResult:
+        yield Input(placeholder="Search song name", type="text")
+        yield OptionList(
+        )
+
+    def on_mount(self) -> None:
+        self.border_title = "Songs"
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        all_songs = self.current_songs
+        search_function(self, event, all_songs)
+
+    def update_song_list(self, album_name: str) -> None:
+        """
+        updates the SongList Ui when album is selected
+        :param album_name: passed by event handler
+        """
+        songs = self.song_data.get(album_name, {}).get("songs", [])
+        # clear and repopulate the OptionList
+        option_list = self.query_one(OptionList)
+        option_list.clear_options()
+        self.current_songs = []
+        for song in sorted(songs):
+            self.current_songs.append(song)
+            option_list.add_option(song)
+
+class RightPane(Widget):
+    pass
+class LyricBox(Widget):
+    """Display song lyrics"""
+
+    current_index: reactive[int] = reactive(-1)
+    current_song_path: reactive[str] = reactive("")
+    def __init__(self):
+        super().__init__()
+        self.parsed_lyrics = []
+
+    def watch_current_song_path(self, path: str) -> None:
+        self.current_index = -1
+        self.parsed_lyrics = []
+        self.query_one(Markdown).update("")
+
+        if path:
+            self.load_lyrics(path)
+
+    @work(exclusive=True, group="lyrics", exit_on_error=False)
+    async def load_lyrics(self, path: str) -> None:
+        try:
+            cached_lyrics = await cache.find_cache(song_path=path)
+            if cached_lyrics is not None:
+                lyrics = cached_lyrics
+            else:
+                lyrics = (await extract_lyrics(path=path)).get("lyrics", [])
+
+        except Exception:
+            lyrics = []
+        if path != self.current_song_path:
+            return
+
+        self.parsed_lyrics = lyrics
+
+    def compose(self) -> ComposeResult:
+        yield Markdown("")
+
+    def on_mount(self) -> None:
+        self.border_title = "Lyrics"
+        # Poll every 1/30ms
+        self.set_interval(1/30, self.update_lyrics)
+
+    def update_lyrics(self) -> None:
+        if not self.parsed_lyrics:
+            return
+
+        progress = get_progress()
+
+        if progress[2]: # song ended
+            return
+
+        now = progress[0]  # how much the song has finished
+
+        # Find the latest lyric whose time <= now
+        idx = -1
+        for i, (t, _) in enumerate(self.parsed_lyrics):
+            if t <= now:
+                idx = i
+            else:
+                break
+
+        if idx != self.current_index:
+            self.current_index = idx
+
+    def watch_current_index(self, idx: int) -> None:
+        """Called automatically when current_index changes"""
+        if not self.parsed_lyrics or idx == -1:
+            self.query_one(Markdown).update("")
+            return
+
+        lyrics = self.parsed_lyrics
+
+        prev_text = f"*{lyrics[idx - 1][1]}*  " if idx > 0 else ""
+        curr_text = f"**{lyrics[idx][1]}**  "
+        next_text = f"*{lyrics[idx + 1][1]}*  " if idx < len(lyrics) - 1 else ""
+
+        content = "\n".join(filter(bool, [prev_text, curr_text, next_text]))
+        self.query_one(Markdown).update(content)
+
+class LeftPane(Widget):
+    pass
+class QueueBox(VerticalScroll):
+    """View the current song queue"""
+    def compose(self) -> ComposeResult:
+        yield RadioSet(disabled=True)
+
+    def on_mount(self) -> None:
+        self.border_title = "Queue"
+        # self.query_one(RadioSet).mount(RadioButton("Hello"))
+
+class TopBox(Widget):
+    """Class containing album and song list"""
+
+    song_over: reactive = reactive(False, init=False)
+    def __init__(self, path: str) -> None:
+        super().__init__()
+        self.path = path
+        self.current_album: str = ""
+        self.queue_iterator: ReversibleIterator = None
+        self.data_dict: dict = {}
+        self.song_queue = []
+
+    def compose(self) -> ComposeResult:
+        with LeftPane():
+            yield AlbumList(self.data_dict)
+            yield QueueBox()
+        with RightPane():
+            yield SongList(self.data_dict)
+            yield LyricBox()
+        yield AlbumCover()
+
+    def on_mount(self) -> None:
+        # worker that loads library
+        self.load_library_data()
+        self.set_interval(1/30, self.song_status)
+
+    @work(thread=True, exit_on_error=False)
+    def load_library_data(self) -> None:
+        """runs load_library() asynchronously, calls finish_loading() at end."""
+        library = asyncio.run(load_library(self.path, cache=cache))
+        self.app.call_from_thread(
+            self.finish_loading,
+            library
+        )
+
+    def finish_loading(self, library: dict) -> None:
+        self.data_dict = library
+        album_data = list(self.data_dict.values())
+        if album_data:
+            self.query_one(AlbumCover).path = album_data[0]["album_art"]
+        else:
+            self.query_one(AlbumCover).path = "./media/unknown.png"
+        self.query_one(AlbumList).data = library
+        self.query_one(SongList).song_data = library
+
+    ## HELPER FUNCTIONS ##
+
+    def update_queue_box(self, song_name:str):
+        qb = self.query_one(QueueBox).query_one(RadioSet)
+        qb.remove_children()
+        for song in self.song_queue:
+            if song == song_name:
+                qb.mount(RadioButton(f"{song}", value=True))
+            else:
+                qb.mount(RadioButton(f"{song}"))
+
+    def song_manager(self, song_name: str) -> None:
+        """ plays song, updates queue, loads lyrics"""
+        # play song using player
+        if not play_song(data_dict=self.data_dict, song_name=song_name):
+            return
+        # load song lyrics
+        path = self.data_dict.get(self.current_album, {}).get("songs", {}).get(song_name, "")
+        self.query_one(LyricBox).current_song_path = path
+        # update queue box
+        self.update_queue_box(song_name=song_name)
+
+    def set_album_queue(self, song_name: str):
+        album = self.data_dict.get(self.current_album)
+        if not album:
+            return
+        songs = album.get("songs", {})
+        if song_name not in songs:
+            return
+        song_list = sorted(songs.keys())
+        idx = song_list.index(song_name)
+        self.song_queue = song_list[idx:] + song_list[:idx]
+
+## HELPER FUNCTIONS END ##
+
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        # Make sure the event came from AlbumList, not SongList's OptionList
+        if event.control in self.query_one(AlbumList).query(OptionList):
+            album_name = str(event.option.prompt)
+            self.current_album = album_name
+            # Update SongList UI
+            song_list_obj = self.query_one(SongList)
+            song_list_obj.update_song_list(album_name)
+            song_list_obj.query_one(Input).clear()
+            # Update Album Cover Display
+            self.query_one(AlbumCover).path = self.data_dict.get(album_name).get('album_art')
+
+        # If SongList option, selected, play song
+        if event.control in self.query_one(SongList).query(OptionList):
+            song_name = str(event.option.prompt)
+            # generating song queue
+            self.set_album_queue(song_name=song_name)
+            self.queue_iterator = ReversibleIterator(lst=self.song_queue)
+            self.song_manager(song_name=next(self.queue_iterator))
+
+    def song_status(self):
+        """checks if song is over"""
+        progress = get_progress()
+        if progress[2] and progress[1] != 0.0:
+            self.song_over = True
+
+    def watch_song_over(self)->None:
+        """watches song_over flag, if changed, plays next song in queue"""
+        if not self.song_over:
+            return
+
+        self.song_over = False
+        if self.queue_iterator is None:
+            return
+
+        self.song_manager(song_name=next(self.queue_iterator))
+

tuiman-1.0.0/src/tuiman/music.tcss

@@ -0,0 +1,145 @@
+AlbumList {
+    border-title-style: bold;
+    border: dashed round mediumslateblue;
+    width: 100%;
+    dock: left;
+}
+
+QueueBox {
+    border: dashed round deeppink;
+}
+
+SongList {
+    border-title-style: bold;
+    border: dashed round mediumslateblue;
+    width: 100%;
+    height: 1fr;
+}
+
+SongList > OptionList {
+    height: 1fr;
+}
+
+LyricBox {
+    border: dashed round deeppink;
+    width: 100%;
+    height: 5;
+    background: black 10%;
+}
+
+LyricBox > Markdown {
+    margin: 0;
+    padding: 0;
+    background: transparent;
+}
+
+TopBox {
+    margin-right: 1;
+    margin-left: 1;
+    height: 1fr;
+    layers: below above;
+    align: right bottom;
+}
+
+LeftPane {
+    width: 30%;
+    layout: horizontal;
+    dock: left;
+}
+
+RightPane {
+    width: 70.5%;
+    dock: right;
+    layout: vertical;
+}
+
+BottomBox {
+    border: solid round white;
+    height: 5;
+    dock: bottom;
+    margin-bottom: 1;
+    margin-right: 1;
+    margin-left: 1;
+    layout: horizontal;   /* buttons and bar inline */
+}
+
+PlayControls {
+    width: 32;
+    dock: left;
+    layout: horizontal;
+    margin-left: 1;
+    align-horizontal: left;
+}
+
+Playback {
+    width: 100%;
+}
+
+QueueOptions {
+    layout: horizontal;
+    align-horizontal: right;
+    margin-right: 1;
+    width: 23;
+    dock: right;
+}
+
+Button {
+    border: round deeppink;
+    min-width: 10;
+    text-align: center;
+    width: 7;
+    height: 3;
+    color: white 70%;
+    background: red 0%;
+}
+
+#song-name {
+    margin-bottom: 1;
+}
+
+AlbumCover {
+    layer: above;
+    width: 22;
+    height: 10;
+    border: round gainsboro;
+    background: transparent;
+}
+
+DirectoryDialog {
+    align: center middle;
+}
+
+Horizontal > Button{
+    border: solid round gainsboro;
+}
+
+#modal_input{
+    width: 100%;
+}
+
+#dia-prev {
+    width: auto;
+}
+
+#dialog-container {
+    width: 50%;
+    height: auto;
+}
+
+#dialog-buttons {
+    height: auto;
+    width: 100%;
+}
+
+.queue-btn{
+    min-width: 11;
+    border: round ansi_bright_yellow;
+}
+
+#show-queue{
+    border-title-align: left;
+}
+
+#shuffle-queue{
+    border-subtitle-align: right;
+}

tuiman-1.0.0/src/tuiman/utils/caching.py

@@ -0,0 +1,77 @@
+import hashlib
+import os
+from json import JSONDecodeError
+
+from platformdirs import PlatformDirs
+import json
+import aiofiles
+
+
+DIRS = PlatformDirs("lyric_cache", "TUIman")
+
+class Cache:
+    def __init__(self):
+        self.lyric_cache_path = DIRS.user_cache_path / "lyrics.json"
+        self.album_cache_path = DIRS.user_cache_path / "last_used_path.txt"
+        self.album_art_path = DIRS.user_cache_path / "album_art"
+        self.init_cache()
+
+    def init_cache(self):
+        """Ensure cache directories exist."""
+        DIRS.user_cache_path.mkdir(parents=True, exist_ok=True)
+        self.album_art_path.mkdir(parents=True, exist_ok=True)
+
+    async def _load(self) -> dict:
+        if not self.lyric_cache_path.exists():
+            return {}
+
+        try:
+            async with aiofiles.open(self.lyric_cache_path, "r") as f:
+                raw = await f.read()
+            return json.loads(raw) if raw.strip() else {}
+        except (JSONDecodeError, OSError):
+            return {}
+
+    async def create_cache(self, song_path: str, lyrics: list) -> None:
+        data = await self._load()
+        data[song_path] = lyrics
+
+        self.lyric_cache_path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = self.lyric_cache_path.with_suffix(".json.tmp")
+
+        async with aiofiles.open(temp_path, "w") as f:
+            await f.write(json.dumps(data, indent=2))
+
+        os.replace(temp_path, self.lyric_cache_path)
+
+    def create_path_cache(self, path: str):
+        with open(self.album_cache_path, "w") as f:
+            f.write(path)
+
+    def find_path_cache(self):
+        try:
+            with open(self.album_cache_path, "r") as f:
+                return f.read().strip()
+        except FileNotFoundError:
+            return ""
+
+    async def find_cache(self, song_path: str) -> list | None:
+        return (await self._load()).get(song_path)
+
+    async def find_album_art_cache(self, album_path: str) -> str | None:
+        """Return cached image path if it exists on disk, else None."""
+        cache_dir = self.album_art_path
+        # Use a hash of the album path as the filename to avoid collisions
+        key = hashlib.md5(album_path.encode()).hexdigest()
+        cached = cache_dir / f"{key}.jpg"
+        return str(cached) if cached.exists() else None
+
+    async def create_album_art_cache(self, album_path: str, image_data: bytes) -> str:
+        """Write image bytes to cache and return the cached file path."""
+        cache_dir = self.album_art_path
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        key = hashlib.md5(album_path.encode()).hexdigest()
+        cached = cache_dir / f"{key}.jpg"
+        async with aiofiles.open(cached, "wb") as f:
+            await f.write(image_data)
+        return str(cached)

tuiman-1.0.0/src/tuiman/utils/library_manager.py

@@ -0,0 +1,98 @@
+from pprint import pprint
+from textual.widgets import Input, OptionList
+from mutagen.id3 import ID3, APIC
+from pathlib import Path
+from src.tuiman.utils.caching import Cache
+
+SUPPORTED_AUDIO_EXTENSIONS = {".mp3"}
+SUPPORTED_IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png"}
+
+
+def search_function(object, event: Input.Changed, iterables) -> None:
+    """search helper function
+        :param object: self instance of class Input
+        :param event: event of class Input
+        :param iterables: the song/ album list
+    """
+    query = event.value.lower()
+
+    filtered = [a for a in iterables if query in a.lower()]
+
+    option_list = object.query_one(OptionList)
+    option_list.clear_options()
+    for song_or_album in filtered:
+        option_list.add_option(song_or_album)
+
+async def _extract_album_art(album_path: Path, songs: dict, cache: Cache) -> str:
+    """Try cache first, then extract from ID3 tags, store result in cache."""
+    cached = await cache.find_album_art_cache(str(album_path))
+    if cached:
+        return cached
+
+    for song_path in songs.values():
+        try:
+            tags = ID3(song_path)
+            for tag in tags.values():
+                if isinstance(tag, APIC):
+                    return await cache.create_album_art_cache(str(album_path), tag.data)
+        except Exception:
+            continue
+
+    return ""
+
+
+def _load_album(album_path: Path) -> dict | None:
+    songs = {}
+
+    for extension in SUPPORTED_AUDIO_EXTENSIONS:
+        for entry in album_path.glob(f"*{extension}"):
+            songs[entry.stem] = str(entry)
+
+    if not songs:
+        return None
+
+    # Sort by filename for consistent ordering
+    songs = dict(sorted(songs.items(), key=lambda kv: kv[0].casefold()))
+    return {"songs": songs, "album_art": ""}
+
+
+async def load_library(root_dir: str, cache: Cache) -> dict:
+    library = {}
+    seen_names = {}  # name -> count of times seen
+    root_path = Path(root_dir).expanduser().resolve()
+
+    album_paths = set()
+    for extension in SUPPORTED_AUDIO_EXTENSIONS:
+        for match in root_path.rglob(f"*{extension}"):
+            album_paths.add(match.parent)
+
+    if not album_paths:
+        album_paths = {root_path}
+
+    for album_path in sorted(album_paths, key=lambda e: e.name.casefold()):
+        album = _load_album(album_path)
+        if album is None:
+            continue
+
+        album["album_art"] = await _extract_album_art(album_path, album["songs"], cache)
+
+        name = album_path.name
+        if name not in seen_names:
+            seen_names[name] = 0
+            library[name] = album
+        else:
+            seen_names[name] += 1
+            library[f"{name} ({seen_names[name]})"] = album
+
+    return library
+
+
+if "__main__" == __name__:
+    library = load_library("../../../data")
+    # print(*library.get("album2", []).keys())
+    pprint(library)
+    # print(list(library.values())[0]['album_art'])
+    # print([*library.keys()])
+    # for album in library:
+    #     print(album)
+    #print(next((songs["Chic 'N' Stu.mp3"] for album in library.values() for songs in [album['songs']] if "Chic 'N' Stu.mp3" in songs), ""))

tuiman-1.0.0/src/tuiman/utils/lyrics.py

@@ -0,0 +1,109 @@
+import asyncio
+import os
+import re
+import httpx
+import mutagen.id3
+from httpx import ReadTimeout
+from src.tuiman.utils.caching import Cache
+
+BASE_URL = "https://lrclib.net/api/search"
+lyrics_cache = Cache()
+
+async def lrclib(**kwargs)->str:
+    params = {
+    "track_name": kwargs.get("title", None),
+    "artist_name": kwargs.get("artist", None),
+    "album_name": kwargs.get("album", None)
+    }
+
+    async with httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=15.0)) as client:
+        response = await client.get(BASE_URL, params=params)
+        response.raise_for_status()
+        data = response.json()
+        first_match = data[0].get("syncedLyrics") if data else None
+        return first_match
+
+async def parse_lrc_lyrics(lrc_text: str) -> list[tuple[float, str]]:
+    pattern = re.compile(r'\[(\d+):(\d+\.\d+)\]\s*(.*)')
+    results = []
+
+    for line in lrc_text.splitlines():
+        m = pattern.match(line.strip())
+        if not m:
+            continue
+        minutes, seconds, text = int(m.group(1)), float(m.group(2)), m.group(3).strip()
+        if text:
+            ts = round(minutes * 60 + seconds, 2)
+            results.append((ts, text))
+
+    return sorted(results, key=lambda x: x[0])
+
+
+async def extract_lyrics(path: str) -> dict:
+    """
+    Extracts synced lyrics from an mp3's ID3 tags (SYLT frame).
+    Falls back to LRCLIB
+    Stores lyrics in .cache
+    Returns {"lyrics": [(time_ms: float, "text": str), ...]}
+    """
+    if not os.path.exists(path):
+        return {"lyrics": []}
+
+    try:
+        tags = mutagen.id3.ID3(path)
+    except mutagen.id3.ID3NoHeaderError:
+        return {"lyrics": []}
+
+    # synced lyrics — stores (text, timestamp_in_ms) tuples
+    song_meta = {}
+    for key in tags.keys():
+        # synced lyrics found
+        if key.startswith("SYLT"):
+            sylt = tags[key]
+            lyrics = [
+                (round(ms / 1000.0, 3), text.strip())
+                for text, ms in sylt.text
+                if text.strip()
+            ]
+            lyrics.sort(key=lambda x: x[0])
+            # caching those lyrics
+            await lyrics_cache.create_cache(song_path=path, lyrics=lyrics)
+            return {"lyrics": lyrics}
+        else:
+            #track name
+            if key.startswith("TIT2"):
+                song_meta["title"] = tags[key].text
+            #artist name
+            if key.startswith("TPE1"):
+                song_meta["artist"] = tags[key].text
+            #album name
+            if key.startswith("TALB"):
+                song_meta["album"] = tags[key].text
+
+    # Try to fetch lyrics from LRCLIB
+    try:
+        synced_lyrics = await lrclib(**song_meta)
+    except ReadTimeout:
+        synced_lyrics = []
+    if synced_lyrics:
+        lyrics = await parse_lrc_lyrics(lrc_text=synced_lyrics)
+        # caching those lyrics
+        await lyrics_cache.create_cache(song_path=path, lyrics=lyrics)
+        return {"lyrics": lyrics}
+
+    # nothing found, store empty list
+    await lyrics_cache.create_cache(song_path=path, lyrics=[])
+    return {"lyrics": []}
+
+if "__main__" == __name__:
+    # pprint(extract_lyrics("../data/album2/Human Nature - lyrics.mp3"))
+    # {'lyrics': [(10.72, 'Looking out'),
+    #             (13.35, 'Across the nighttime'),
+    # pprint(extract_lyrics(""))
+    lyrics = asyncio.run(lrclib(
+            title="",
+            artist="",
+            album=""
+        ))
+    print(lyrics)
+    # print(asyncio.run(extract_lyrics(path= "../data/exeter/IMAGINARY.mp3")))

tuiman-1.0.0/src/tuiman/utils/models.py

@@ -0,0 +1,13 @@
+class ReversibleIterator:
+    def __init__(self, lst):
+        self.lst = lst
+        self.pos = 0
+        self.delta = 1
+
+    def __next__(self):
+        ret = self.lst[self.pos]
+        self.pos = (self.pos + 1) % len(self.lst)
+        return ret
+
+    def __iter__(self):
+        return self

tuiman-1.0.0/src/tuiman/utils/player.py

@@ -0,0 +1,86 @@
+import mutagen
+import os
+os.environ["PYGAME_HIDE_SUPPORT_PROMPT"] = "1"
+import pygame
+from typing import Optional
+
+# module-level state
+_current_album: Optional[str] = None
+_current_song: Optional[str] = "-----"
+_current_duration: float = 0.0
+_paused: bool = False
+
+def init_player() -> None:
+    """Call once at app startup."""
+    pygame.mixer.init()
+
+def play_song(data_dict: dict, song_name: str) -> bool:
+    """
+    Play a song by name, searching across all albums.
+    Returns True on success, False if song not found.
+    """
+    global _current_album, _current_duration, _current_song, _paused
+
+    for album_name, data in data_dict.items():
+        if song_name not in data["songs"]:
+            continue
+        path = data["songs"][song_name]
+
+        try:
+            pygame.mixer.music.stop()
+            pygame.mixer.music.load(path)
+            pygame.mixer.music.play()
+            audio = mutagen.File(path)
+            _current_duration = audio.info.length if audio and audio.info else 0.0
+        except Exception:
+            _current_duration = 0.0
+            return False
+        _current_album = album_name
+        _current_song = song_name
+        _paused = False
+        return True
+
+    return False
+def pause() -> None:
+    if pygame.mixer.music.get_busy() and not _paused:
+        pygame.mixer.music.pause()
+        globals()['_paused'] = True
+
+def resume() -> None:
+    global _paused
+    if _paused:
+        pygame.mixer.music.unpause()
+        _paused = False
+
+def stop() -> None:
+    global _current_album, _current_song, _paused
+    pygame.mixer.music.stop()
+    _current_album = None
+    _current_song = None
+    _paused = False
+
+def set_volume(level: float) -> None:
+    """level: 0.0 to 1.0"""
+    pygame.mixer.music.set_volume(max(0.0, min(1.0, level)))
+
+def get_current() -> dict:
+    return {
+        "album": _current_album,
+        "song": _current_song,
+        "paused": _paused,
+        "playing": pygame.mixer.music.get_busy()
+    }
+
+def get_progress() -> tuple[float, float, bool]:
+    """Returns (elapsed_seconds, total_seconds, track_ended)."""
+    if _current_song is None:
+        return 0.0, 0.0, False
+
+    track_ended = False
+    raw_pos = pygame.mixer.music.get_pos()
+    elapsed = max(0.0, raw_pos / 1000.0)
+
+    if elapsed > _current_duration:
+        track_ended = True
+
+    return elapsed, _current_duration, track_ended