beets-quicktag 0.1.0__py3-none-any.whl

beets_quicktag-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: beets-quicktag
+Version: 0.1.0
+Summary: A beets plugin for quickly tagging tracks with customizable attributes
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: beets>=2.3.0
+Requires-Dist: just-playback>=0.1.8
+Requires-Dist: textual>=3.2.0
+
+# Beets QuickTag Plugin
+
+This is a plugin for [beets](https://beets.io/) that scratches my own itch to categorize my music using custom tags, for DJing, as efficiently as possible. If it's not at a 1.0 release, it's probably not stable for use by others, though I'll still try and look at issues if for some reason you've found this (hi!).
+
+It's a work in progress though much of the functionality is already there. I initially prototyped this using Claude 3.7 and Gemini 2.5 Pro Preview but ended up re-working quite a bit of it.
+
+TODO:
+- add tests
+- add rating or energy level widget
+- consider bundling libmpv
+- automate releases
+- test on Windows
+- summarize changes after QuickTag finishes running
+- consider bundling libmpv
+
+## Requirements
+
+You must have `libmpv` installed.
+
+## Configuration
+
+Add a `quicktag` section to your beets `config.yaml`. Here's an example:
+
+```yaml
+
+quicktag:
+  autoplay_at_launch: yes
+  autoplay_on_track_change: no
+  autosave_on_quit: yes
+  categories:
+    collection:
+      - DJ
+      - Sample
+    mood:
+      - happy
+      - sad
+      - bright
+      - dark
+      - angry
+```
+
+## Credits
+
+This was inspired by the Quick Tag functionality in [One Tagger](https://onetagger.github.io/), which is an excellent application. One Tagger also has [a spreadsheet](https://docs.google.com/spreadsheets/d/1wYokScjoS5Xb1IvqFMXbSbknrXJ7bySLLihTucOS4qY/edit?gid=0#gid=0) that might provide inspiration from existing systems to categorize tracks in this way. I believe the One Tagger system, or at least the default categories it has, are inspired by [a reddit post by u/nonomomomo](https://www.reddit.com/r/DJs/comments/c3o2jk/my_ultimate_track_tagging_system_the_little_data/).

beets_quicktag-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+beetsplug/quicktag/__init__.py,sha256=VVZL0EsW-OVcc2AYErRngmINqrLV8lSw8biow6qRO5c,2596
+beetsplug/quicktag/app.py,sha256=Cxkcbgw80CC_MCIReoeav-ajwI054FirGgFC05R9BLw,17309
+beetsplug/quicktag/widgets/custom_selection_list.py,sha256=rWUQAsopKU9shr1kGso3aypfQsUV6KuLTwaiiKq5SSE,2945
+beetsplug/quicktag/widgets/input_with_label.py,sha256=QGa6CHEWYoZ8UxEj_sL4aLYladbthbvsE3YT38315EA,911
+beetsplug/quicktag/widgets/playback.py,sha256=_AHzwuqDadid173LOHxH3mORwrZorZibVYST1IJA8NI,6724
+beetsplug/quicktag/widgets/playback_progress.py,sha256=R0x31d4uSZ8Xpv4E7izrSO4vZUe8RQQBZYY5ZcKDxT0,3510
+beets_quicktag-0.1.0.dist-info/METADATA,sha256=DEEUv8e-3AySiAjHk6QM0b_Mzktrdy9cfYl0VrywAn0,2000
+beets_quicktag-0.1.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+beets_quicktag-0.1.0.dist-info/top_level.txt,sha256=za8u6CXAGbgac8cUyn9NlsgXqqq-_4HHZcNmJnfmyWc,10
+beets_quicktag-0.1.0.dist-info/RECORD,,

beets_quicktag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

beets_quicktag-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+beetsplug

beetsplug/quicktag/__init__.py

@@ -0,0 +1,76 @@
+import optparse
+
+from beets import ui
+from beets.dbcore.db import Results as BeetsResults
+from beets.library import Library as BeetsLibrary
+from beets.plugins import BeetsPlugin
+
+from .app import QuickTagApp
+
+
+class QuickTagPlugin(BeetsPlugin):
+    def __init__(self):
+        super(QuickTagPlugin, self).__init__()
+        self.config.add(
+            {
+                "categories": {},
+                "autoplay_on_track_change": False,
+                "autoplay_at_launch": False,
+                "autonext_at_track_end": False,
+                "autosave_on_quit": False,
+                "keep_playing_on_track_change_if_playing": True,
+            }
+        )
+
+    def commands(self):
+        cmd = ui.Subcommand(
+            "quicktag",
+            help="Quickly tag tracks with predefined options.",
+            aliases=["qt"],
+        )
+        cmd.func = self.run_quicktag
+        return [cmd]
+
+    def run_quicktag(self, lib: BeetsLibrary, opts: optparse.Values, args):
+        query = ui.decargs(args)
+        items: BeetsResults = lib.items(query)
+
+        if not items:
+            ui.print_("No tracks found to tag.")
+            return
+
+        categories_config = self.config["categories"].get(dict)
+        autoplay_on_track_change_enabled = self.config["autoplay_on_track_change"].get(
+            bool
+        )
+        autoplay_at_launch_enabled = self.config["autoplay_at_launch"].get(bool)
+        autonext_at_track_end_enabled = self.config["autonext_at_track_end"].get(bool)
+        autosave_on_quit_enabled = self.config["autosave_on_quit"].get(bool)
+        keep_playing_on_track_change_if_playing_enabled = self.config["keep_playing_on_track_change_if_playing"].get(bool)
+
+        if not categories_config:
+            ui.print_(
+                "No categories defined in the configuration. Please configure the quicktag plugin."
+            )
+            ui.print_("Example configuration:")
+            ui.print_("quicktag:")
+            ui.print_("  categories:")
+            ui.print_("    mood: [happy, sad, energetic, calm]")
+            ui.print_(
+                "    genre_custom: [electronic, ambient, experimental, soundtrack]"
+            )
+            return
+
+        categories = list(categories_config.items())
+
+        app = QuickTagApp(
+            lib,
+            items,
+            categories,
+            autoplay_on_track_change_enabled,
+            autoplay_at_launch_enabled,
+            autonext_at_track_end_enabled,
+            autosave_on_quit_enabled,
+            keep_playing_on_track_change_if_playing_enabled,
+        )
+        app.run()

beetsplug/quicktag/app.py

@@ -0,0 +1,439 @@
+from enum import Enum
+from typing import Optional
+
+from beets.dbcore.db import Results as BeetsResults
+from beets.library import Item as BeetsItem
+from beets.library import Library as BeetsLibrary
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.dom import NoMatches
+from textual.widgets import Footer, Static
+from textual.widgets.selection_list import Selection
+
+from .widgets.custom_selection_list import CustomSelectionList
+from .widgets.input_with_label import InputWithLabel
+from .widgets.playback import PlaybackEnded, PlaybackWidget
+
+
+class NavigateDirection(Enum):
+    """Enum for seek direction."""
+
+    FORWARD = 1
+    BACKWARD = -1
+
+
+class HeaderWidget(Vertical):
+    """A custom widget for the application header, now including a playback widget."""
+
+    DEFAULT_CSS = """
+    HeaderWidget {
+        dock: top;
+        width: 100%;
+        height: auto; /* Adjusts to content: title line + playback widget */
+        background: $panel;
+        color: $text;
+        padding: 0 1;
+    }
+    #header_text_content {
+        width: 100%;
+        height: 1;
+    }
+    """
+
+    def __init__(self, playback_widget: PlaybackWidget, item=None, **kwargs):
+        super().__init__(**kwargs)
+        self.item: BeetsItem = item
+        self._header_text_display = Static(id="header_text_content")
+        self.playback_widget = playback_widget
+
+    def compose(self) -> ComposeResult:
+        """Compose the header with text and the playback widget."""
+        yield self._header_text_display
+        yield self.playback_widget
+
+    def on_mount(self) -> None:
+        """Set the header text when the widget is mounted."""
+        self.update_header()
+
+    def update_header(self, item: Optional[BeetsItem] = None) -> None:
+        """Updates the header text."""
+        if item:
+            self.item = item
+
+        header_text_value = "QuickTag"
+        if self.item:
+            header_text_value = f"Tagging: {self.item.artist} - {self.item.title}"
+
+        self._header_text_display.update(header_text_value)
+
+
+class QuickTagApp(App):
+    BINDINGS = [
+        Binding("escape", "quit", "Quit", show=True, priority=True),
+        Binding("left", "previous_item", "Previous", show=True, priority=True),
+        Binding("right", "next_item", "Next", show=True, priority=True),
+        ("/", "play_pause_current_item", "Play/Pause"),
+        ("<", "seek_backward(5)", "Seek -5s"),
+        (">", "seek_forward(5)", "Seek +5s"),
+    ]
+
+    DEFAULT_CSS = """
+    Screen {
+        align: center middle;
+    }
+
+    SelectionList {
+        padding: 1;
+        border: solid $accent;
+        /* width: 80%; */
+        /* height: 80%; */
+    }
+    """
+
+    def __init__(
+        self,
+        lib: BeetsLibrary,
+        items: BeetsResults,
+        categories: list[tuple[str, list[str]]],
+        autoplay_on_track_change_enabled: bool,
+        autoplay_at_launch_enabled: bool,
+        autonext_at_track_end_enabled: bool,
+        autosave_on_quit_enabled: bool,
+        keep_playing_on_track_change_if_playing_enabled: bool,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.lib = lib
+        self.items = items
+        self.categories = categories
+        self.autoplay_on_track_change_enabled = autoplay_on_track_change_enabled
+        self.autoplay_at_launch_enabled = autoplay_at_launch_enabled
+        self.autonext_at_track_end_enabled = autonext_at_track_end_enabled
+        self.autosave_on_quit_enabled = autosave_on_quit_enabled
+        self.keep_playing_on_track_change_if_playing_enabled = keep_playing_on_track_change_if_playing_enabled
+
+        self.current_item_index = 0
+        self.item = items[0] if items else None
+        self.playback_widget = PlaybackWidget()
+        self.header_widget = HeaderWidget(
+            item=self.item, playback_widget=self.playback_widget
+        )
+
+        self.log.info("QuickTagApp initialized.")
+
+    async def on_mount(self) -> None:
+        """Called when the app is mounted."""
+        self.theme = "gruvbox"
+        await self._set_item(self.item, save_current_item_tags=False)
+        if not self.autoplay_at_launch_enabled:
+            self.playback_widget.pause()
+
+    async def on_unmount(self) -> None:
+        """Called when the app is unmounted."""
+        self.log.info("QuickTagApp unmounted.")
+
+    def compose(self) -> ComposeResult:
+        yield self.header_widget
+
+        if self.item:
+            for category_name, options in self.categories:
+                selection_options = [
+                    Selection(option_text, option_idx)
+                    for option_idx, option_text in enumerate(options)
+                ]
+                category_selection_list = CustomSelectionList(
+                    *selection_options, id=f"selection-{category_name}"
+                )
+                category_selection_list.border_title = category_name
+                yield category_selection_list
+            yield InputWithLabel(input_label="Comments:", id="comments-input")
+        else:
+            yield Static("No items to tag.")
+
+        yield Footer()
+
+    async def action_quit(self) -> None:
+        """Action to quit the application."""
+        self.log.info(
+            f"action_quit called. autosave_on_quit_enabled: {self.autosave_on_quit_enabled}"
+        )
+        if self.autosave_on_quit_enabled and self.item:
+            self.log.info("Autosaving tags before quitting.")
+            await self._save_current_item_tags()
+        self.exit()
+
+    async def _load_current_item_for_playback(self) -> None:
+        """Load the current item for playback."""
+
+        item_path_bytes = self.item.path
+
+        try:
+            item_path_str = item_path_bytes.decode("utf-8", "surrogateescape")
+        except AttributeError:
+            item_path_str = item_path_bytes
+        except Exception as e:
+            self.log.error(f"Error decoding item path: {e}")
+            return
+
+        self.playback_widget.load_track(item_path_str)
+
+    async def _set_item(self, item: BeetsItem, save_current_item_tags=True) -> None:
+        """Handle changes to the current item."""
+        # Capture the current playback state before changing items
+        was_playing_before = self.playback_widget.is_playing()
+        
+        if save_current_item_tags:
+            await self._save_current_item_tags()
+        self.item = item
+        self.header_widget.update_header(item)
+        await self._load_tags_for_current_item()
+        self.log.info(f"Item set to: {item.artist} - {item.title}")
+
+        if self.categories:
+            first_category_name, _ = self.categories[0]
+            try:
+                self.query_one(
+                    f"#selection-{first_category_name}", CustomSelectionList
+                ).focus()
+            except NoMatches:
+                pass
+
+        # Load the new track (this doesn't start playback automatically)
+        await self._load_current_item_for_playback()
+
+        # Determine whether to start playing the new track
+        should_play = False
+        
+        if was_playing_before and self.keep_playing_on_track_change_if_playing_enabled:
+            # If we were playing before and the setting allows it, continue playing the new track
+            should_play = True
+            self.log.info("Continuing playback with new track (was playing before and keep_playing_on_track_change_if_playing enabled)")
+        elif self.autoplay_on_track_change_enabled:
+            # If autoplay is enabled, start playing regardless of previous state
+            should_play = True
+            self.log.info("Starting playback due to autoplay_on_track_change setting")
+        else:
+            # We were paused or keep_playing_on_track_change_if_playing is disabled, stay paused
+            self.log.info("Keeping playback paused (was paused, autoplay disabled, or keep_playing_on_track_change_if_playing disabled)")
+
+        if should_play:
+            self.playback_widget.play()
+        else:
+            # Ensure we're paused if we shouldn't be playing
+            if self.playback_widget.is_playing():
+                self.playback_widget.pause()
+
+    async def _navigate(self, direction: NavigateDirection) -> None:
+        """Navigates through the items list in the specified direction."""
+        # TODO: Do we need this?
+        # TODO: should be exception?
+        if not self.item:
+            return
+
+        # TODO: do we stop here or elsewhere?
+        # self.playback_widget.stop()
+        # self.log.info("Playback stopped for next item.")
+
+        if direction == NavigateDirection.FORWARD:
+            if self.current_item_index < len(self.items) - 1:
+                self.current_item_index += 1
+            else:
+                self.header_widget._header_text_display.update(
+                    "All items processed. Press Esc to quit."
+                )
+                return
+        elif direction == NavigateDirection.BACKWARD:
+            if self.current_item_index > 0:
+                self.current_item_index -= 1
+            else:
+                # We don't want to loop back to the last item
+                return
+        else:
+            # this should never happen...
+            error_message = f"Invalid direction: {direction}. Use {NavigateDirection.FORWARD} (NavigateDirection.FORWARD) or {NavigateDirection.BACKWARD} (NavigateDirection.BACKWARD)."
+            self.log.error(error_message)
+            raise ValueError(error_message)
+
+        await self._set_item(self.items[self.current_item_index])
+
+    async def action_next_item(self) -> None:
+        """Saves tags for the current item and moves to the next item."""
+        await self._navigate(NavigateDirection.FORWARD)
+        self.log.info("action_next_item called.")
+
+    async def action_previous_item(self) -> None:
+        """Saves tags for the current item and moves to the previous item."""
+        await self._navigate(NavigateDirection.BACKWARD)
+        self.log.info("action_previous_item called.")
+
+    async def action_play_pause_current_item(self) -> None:
+        """Toggles play/pause for the current item."""
+        # might not need to check if item exists if we validate earlier
+        # but the path does need to exist
+        # TODO: check if path exists, probably not here though
+        if not self.item or not hasattr(self.item, "path"):
+            self.log.warning("No item selected or item has no path.")
+            return
+
+        self.playback_widget.play_pause()
+        self.log.info("Requested play/pause for current item.")
+
+    async def action_seek_forward(self, seconds: int = 5) -> None:
+        """Seeks forward in the current track."""
+        if self.item:
+            self.playback_widget.seek_relative(seconds)
+
+    async def action_seek_backward(self, seconds: int = 5) -> None:
+        """Seeks backward in the current track."""
+        if self.item:
+            self.playback_widget.seek_relative(-seconds)
+
+    async def on_playback_widget_track_ended(self, message: PlaybackEnded) -> None:
+        """Handles the TrackEnded message from PlaybackWidget."""
+        self.log.info(
+            f"PlaybackWidget.TrackEnded message received. Autoplay next: {self.autoplay_on_track_change_enabled}"
+        )
+        if self.autonext_at_track_end_enabled:
+            if self.current_item_index < len(self.items) - 1:
+                self.log.info("Autoplaying next item due to TrackEnded.")
+                await self.action_next_item()
+            else:
+                self.log.info("Track ended, but already at the last item.")
+        else:
+            self.playback_widget.pause()
+            self.playback_widget.seek(0)
+
+    async def _save_current_item_tags(self) -> None:
+        """Saves the tags for the current item based on selections."""
+        if not self.item:
+            self.log.warning("_save_current_item_tags: No item to save.")
+            return
+
+        self.log.info(
+            f"_save_current_item_tags: Attempting to save tags for {self.item.artist} - {self.item.title}"
+        )
+        changed = False
+        for category_name, options_list in self.categories:
+            try:
+                selection_list = self.query_one(
+                    f"#selection-{category_name}", CustomSelectionList
+                )
+            except NoMatches:
+                self.log.error(
+                    f"Could not find SelectionList for category: {category_name} during save."
+                )
+                continue
+
+            selected_indices_in_list = selection_list.selected
+            selected_values = [options_list[i] for i in selected_indices_in_list]
+
+            current_tag_value = ", ".join(selected_values) if selected_values else None
+            old_value = self.item.get(category_name)
+            self.log.debug(
+                f"Category {category_name} for '{self.item.title}': current_tag_value: '{current_tag_value}', old_value: '{old_value}'"
+            )
+
+            if current_tag_value:
+                if old_value != current_tag_value:
+                    self.log.info(
+                        f"Updating tag {category_name} from '{old_value}' to '{current_tag_value}' for {self.item.title}"
+                    )
+                    self.item[category_name] = current_tag_value
+                    changed = True
+            elif old_value is not None:
+                self.log.info(
+                    f"Removing tag {category_name} (was '{old_value}') for {self.item.title}"
+                )
+                del self.item[category_name]
+                changed = True
+
+        # Save comments using InputWithLabel
+        try:
+            comments_widget = self.query_one("#comments-input", InputWithLabel)
+            new_comments = comments_widget.value
+            old_comments = self.item.get(
+                "comments", ""
+            )  # Use get with default for comments
+            if isinstance(old_comments, bytes):  # Ensure old_comments is a string
+                old_comments = old_comments.decode("utf-8", "ignore")
+
+            if old_comments != new_comments:
+                self.log.info(
+                    f"Updating comments from '{old_comments}' to '{new_comments}' for {self.item.title}"
+                )
+                if new_comments:
+                    self.item["comments"] = new_comments
+                elif "comments" in self.item:  # Only delete if it exists
+                    del self.item["comments"]
+                changed = True
+        except NoMatches:
+            self.log.error("Could not find comments input for saving.")
+
+        if changed:
+            self.log.info(
+                f"Changes detected for '{self.item.artist} - {self.item.title}'. Storing item."
+            )
+            try:
+                self.item.store()
+                self.log.info(
+                    f"Successfully stored item: {self.item.artist} - {self.item.title}"
+                )
+            except Exception as e:
+                self.log.error(
+                    f"Error storing item {self.item.artist} - {self.item.title}: {e}"
+                )
+        else:
+            self.log.info(
+                f"No changes detected for '{self.item.artist} - {self.item.title}'. Nothing to store."
+            )
+
+    async def _load_tags_for_current_item(self) -> None:
+        """Loads the tags for the current item into the selection lists."""
+        # TODO: I think we should validate earlier that we have a valid items
+        if not self.item:
+            return
+
+        for category_name, options_list in self.categories:
+            try:
+                selection_list = self.query_one(
+                    f"#selection-{category_name}", CustomSelectionList
+                )
+            except NoMatches:
+                self.log.error(
+                    f"Could not find SelectionList for category: {category_name} during load."
+                )
+                continue
+
+            selection_list.deselect_all()
+
+            current_tag_string = self.item.get(category_name)
+            if not current_tag_string:
+                continue
+
+            tagged_values_for_category = {
+                val.strip() for val in current_tag_string.split(",")
+            }
+
+            newly_selected_indices_in_list = []
+            for i, option_text_in_list in enumerate(options_list):
+                if option_text_in_list in tagged_values_for_category:
+                    newly_selected_indices_in_list.append(i)
+
+            if newly_selected_indices_in_list:
+                for index_to_select in newly_selected_indices_in_list:
+                    selection_list.select(index_to_select)
+
+            selection_list.scroll_to_highlight()
+
+        # Load comments using InputWithLabel
+        try:
+            comments_widget = self.query_one("#comments-input", InputWithLabel)
+            current_comments = self.item.get(
+                "comments", ""
+            )  # Use get with default for comments
+            if isinstance(current_comments, bytes):  # Ensure comments is a string
+                current_comments = current_comments.decode("utf-8", "ignore")
+            comments_widget.value = current_comments
+        except NoMatches:
+            self.log.error("Could not find comments input for loading.")

beetsplug/quicktag/widgets/custom_selection_list.py

@@ -0,0 +1,66 @@
+from textual.widgets import SelectionList
+from textual import events
+
+class CustomSelectionList(SelectionList):
+    """
+    A custom SelectionList that handles quick selection via alphanumeric key presses.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.search_char: str | None = None
+
+    async def on_key(self, event: events.Key) -> None:
+        """Handle key presses for quick selection.
+        Pressing an alphanumeric key attempts to jump to the next item in this
+        SelectionList (relative to the currently highlighted item) that starts
+        with that character, wrapping around if necessary.
+        """
+        if not event.character or not event.character.isalnum() or len(event.character) != 1:
+            # If the key is not a single alphanumeric character, let Textual's default
+            # event handling take care of it (e.g., for arrow keys, Enter).
+            return
+
+        pressed_char = event.character.lower()
+
+        # The character to search for is the one just pressed.
+        self.search_char = pressed_char 
+
+        if not self.options:
+            # No options to search through.
+            event.stop() # Consume the event as it's handled
+            return
+
+        # Determine the starting point for the search.
+        # If nothing is highlighted, effectively start from index -1.
+        # The search will then begin at index 0 after adding 1.
+        current_highlight_idx = self.highlighted if self.highlighted is not None else -1
+
+        num_options = len(self.options)
+        
+        # Start searching from the item *after* the currently highlighted one.
+        # If current_highlight_idx is -1, start_search_from_idx will be 0.
+        # Otherwise, it's (highlighted_index + 1).
+        start_search_from_idx = (current_highlight_idx + 1) % num_options
+
+        # Iterate through all options once, effectively wrapping around the list.
+        # The loop runs num_options times to check every item starting from start_search_from_idx.
+        for i in range(num_options):
+            check_idx = (start_search_from_idx + i) % num_options
+            
+            selection_item = self.options[check_idx]
+            # Assuming selection_item.prompt is always a string or Text-compatible object
+            option_text = str(selection_item.prompt).lower()
+
+            if option_text.startswith(self.search_char):
+                # Match found. Highlight it and stop the event.
+                self.highlighted = check_idx
+                self.scroll_to_highlight()
+                event.stop()
+                return
+        
+        # If the loop completes, no item starting with self.search_char was found
+        # (from the position after the current highlight, wrapping around).
+        # The current highlight remains unchanged.
+        event.stop() # Consume the event even if no match is found to prevent other actions.
+

beetsplug/quicktag/widgets/input_with_label.py

@@ -0,0 +1,38 @@
+from textual.widget import Widget
+from textual.widgets import Input, Label
+from textual.app import ComposeResult
+
+
+class InputWithLabel(Widget):
+    """An input with a label."""
+
+    DEFAULT_CSS = """
+    InputWithLabel {
+        layout: horizontal;
+        height: auto;
+    }
+    InputWithLabel Label {
+        padding: 1;
+        width: 12;
+        text-align: right;
+    }
+    InputWithLabel Input {
+        width: 1fr;
+    }
+    """
+
+    def __init__(self, input_label: str, id: str | None = None) -> None:
+        self.input_label = input_label
+        super().__init__(id=id)
+
+    def compose(self) -> ComposeResult:  
+        yield Label(self.input_label)
+        yield Input(placeholder="Enter comments here...")
+
+    @property
+    def value(self) -> str:
+        return self.query_one(Input).value
+
+    @value.setter
+    def value(self, value: str) -> None:
+        self.query_one(Input).value = value

beetsplug/quicktag/widgets/playback.py

@@ -0,0 +1,182 @@
+from just_playback import Playback
+from textual.app import ComposeResult
+from textual.message import Message
+from textual.widget import Widget
+from textual.timer import Timer
+
+from .playback_progress import PlaybackProgressWidget
+
+
+class PlaybackEnded(Message):
+    """Posted when playback finishes (EOF)."""
+
+    pass
+
+
+class PlaybackWidget(Widget):
+    DEFAULT_CSS = """
+    PlaybackWidget {
+        width: 100%;
+        height: 1;
+    }
+    """
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._current_path: str | None = None
+        self._eof_check_timer: Timer | None = None
+
+        try:
+            self.player = Playback()
+            self._playback_progress = PlaybackProgressWidget(player=self.player)
+            # self.log.info("just_playback Player initialized in PlaybackWidget")
+        except Exception:
+            # self.log.error(f"Failed to initialize just_playback player in PlaybackWidget: {e}")
+            self.player = None
+
+    async def on_mount(self) -> None:
+        # Start a timer to check for end-of-file conditions since just_playback doesn't have property observation
+        self._eof_check_timer = self.set_interval(0.5, self._check_eof)
+
+    async def on_unmount(self) -> None:
+        await self._terminate_player()
+
+    def compose(self) -> ComposeResult:
+        yield self._playback_progress
+
+    def render(self):
+        return "hi"
+
+    def _check_eof(self) -> None:
+        """Check if playback has reached end of file and post PlaybackEnded message if so."""
+        if (
+            self.player
+            and self._current_path
+            and hasattr(self.player, 'duration')
+            and hasattr(self.player, 'curr_pos')
+            and self.player.duration
+            and self.player.curr_pos is not None
+        ):
+            # Check if we've reached the end (within 0.5 seconds tolerance)
+            if (
+                not self.player.active
+                and self.player.curr_pos >= (self.player.duration - 0.5)
+            ):
+                self.log.info(
+                    f"just_playback: End of file - {self._current_path or 'Unknown file'}"
+                )
+                self.post_message(PlaybackEnded())
+
+    async def _terminate_player(self) -> None:
+        if self._eof_check_timer:
+            self._eof_check_timer.stop()
+            self._eof_check_timer = None
+        
+        if self.player:
+            try:
+                self.player.stop()
+                self.log.info("just_playback player stopped from PlaybackWidget.")
+            except Exception as e:
+                self.log.error(f"Error stopping just_playback player in PlaybackWidget: {e}")
+            self.player = None
+        self._current_path = None
+
+    def load_track(self, new_path: str) -> None:
+        """Loads a track for playback. Does not start playing immediately."""
+        if not self.player:
+            self.log.warning("just_playback player not available. Cannot load track.")
+            return
+        if not new_path:
+            self.log.warning("No path provided to load_track.")
+            self.stop()  # Clear current state if path is None
+            return
+
+        if self._current_path != new_path:
+            try:
+                self.player.load_file(new_path)
+                self._current_path = new_path
+                self.log.info(f"just_playback: Loaded track {new_path}")
+            except Exception as e:
+                self.log.error(f"just_playback: Error loading track {new_path}: {e}")
+                self._current_path = None
+        else:
+            self.log.info(f"just_playback: Track {new_path} already loaded.")
+
+    def play(self) -> None:
+        """Starts or resumes playback of the currently loaded track."""
+        if not self.player:
+            self.log.warning("just_playback player not available for play.")
+            return
+        if not self._current_path:
+            self.log.warning("No track loaded to play.")
+            return
+
+        try:
+            if self.player.paused:
+                self.player.resume()
+                self.log.info(
+                    f"just_playback: Resumed play for {self._current_path} via play() method."
+                )
+            elif not self.player.playing:
+                self.player.play()
+                self.log.info(
+                    f"just_playback: Started play for {self._current_path} via play() method."
+                )
+            else:
+                self.log.info(
+                    f"just_playback: Already playing {self._current_path}. play() called."
+                )
+        except Exception as e:
+            self.log.error(f"just_playback: Error during play for {self._current_path}: {e}")
+
+    def pause(self) -> None:
+        """Pauses playback of the currently playing track."""
+        if not self.player:
+            self.log.warning("just_playback player not available for pause.")
+            return
+        if not self.is_player_active() or self.player.paused:
+            self.log.warning("No track playing or already paused. Cannot pause.")
+            return
+
+        try:
+            self.player.pause()
+            self.log.info(
+                f"just_playback: Paused playback for {self._current_path}. Player pause state: {self.player.paused}"
+            )
+        except Exception as e:
+            self.log.error(f"just_playback: Error during pause for {self._current_path}: {e}")
+
+    def play_pause(self) -> None:
+        """Toggles play/pause for the currently loaded track."""
+        if not self.player:
+            self.log.warning("just_playback player not available for play/pause.")
+            return
+        if not self._current_path:
+            self.log.warning("No track loaded to play/pause.")
+            return
+
+        if self.is_playing():
+            self.pause()
+        else:
+            self.play()
+
+    def stop(self) -> None:
+        if self.player and self._current_path:
+            self.log.info(
+                f"just_playback: Stopping playback for {self._current_path or 'unknown file'}"
+            )
+            self.player.stop()
+
+        self._current_path = None
+
+    def seek_relative(self, seconds: int) -> None:
+        if self.player and hasattr(self.player, 'curr_pos') and hasattr(self.player, 'duration'):
+            if self.player.duration and self.player.curr_pos is not None:
+                new_position = max(0, min(self.player.curr_pos + seconds, self.player.duration))
+                self.player.seek(new_position)
+
+    def is_playing(self) -> bool:
+        return bool(self.player and self.player.playing)
+
+    def is_player_active(self) -> bool:
+        return bool(self.player and self.player.active)

beetsplug/quicktag/widgets/playback_progress.py

@@ -0,0 +1,100 @@
+import math
+
+from just_playback import Playback
+from textual.app import ComposeResult
+from textual.containers import Horizontal
+from textual.timer import Timer
+from textual.widget import Widget
+from textual.widgets import ProgressBar, Static
+
+# TODO: update progress bar with timer
+
+
+def format_seconds_to_time_str(seconds: float | None) -> str:
+    """Format seconds into MM:SS string."""
+    if seconds is None:
+        return "--:--"
+    if seconds < 0:
+        seconds = 0
+    total_seconds = int(math.floor(seconds))
+    mins = total_seconds // 60
+    secs = total_seconds % 60
+    return f"{mins:02d}:{secs:02d}"
+
+
+class PlaybackProgressWidget(Widget):
+    DEFAULT_CSS = """
+    #playback_progress_bar_container {
+        layout: horizontal;
+        width: 100%;
+        height: 1;
+    }
+    #playback_progress {
+        width: 1fr;
+        height: 1;
+    }
+    #time_remaining_text {
+        width: auto;
+        min-width: 5; /* For MM:SS format */
+        height: 1;
+        padding: 0 0 0 1; /* Padding on the left of time */
+        text-align: right;
+    }
+    """
+
+    def __init__(self, player: Playback):
+        super().__init__()
+        self.player = player
+        self._playback_timer: Timer | None = None
+        self._progress_bar = ProgressBar(show_percentage=False, show_eta=False)
+        self._time_remaining_display = Static("", id="time_remaining_text")
+        # Note: just_playback doesn't have property observation, so we'll use polling
+
+    async def on_mount(self) -> None:
+        self._playback_timer = self.set_interval(1 / 2, self._update_progress_display)
+        self._progress_bar.progress = 0
+        self._progress_bar.total = 100
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="playback_progress_bar_container"):
+            yield self._progress_bar
+            yield self._time_remaining_display
+
+    def _update_progress_display(self, *args, **kwargs) -> None:
+        if (
+            self.player
+            and hasattr(self.player, 'duration')
+            and hasattr(self.player, 'curr_pos')
+            and self.player.duration is not None
+            and self.player.duration > 0
+        ):
+            duration = self.player.duration
+            time_pos = self.player.curr_pos if self.player.curr_pos is not None else 0
+            time_remaining_seconds = duration - time_pos if time_pos is not None else None
+
+            self._progress_bar.total = duration
+            self._progress_bar.progress = time_pos
+            self._progress_bar.visible = True
+
+            self._time_remaining_display.update(
+                f"-{format_seconds_to_time_str(time_remaining_seconds)}"
+            )
+            self._time_remaining_display.visible = True
+
+            # Check if playback has ended
+            if (
+                not self.player.active
+                and time_pos is not None
+                and time_pos >= (duration - 0.5)
+            ):
+                self._progress_bar.progress = self._progress_bar.total
+                self._time_remaining_display.update("00:00")
+                if self._playback_timer:
+                    self._playback_timer.pause()
+        else:
+            if self._progress_bar.visible or self._time_remaining_display.visible:
+                self._progress_bar.progress = 0
+                self._progress_bar.total = 100
+                self._progress_bar.visible = False
+                self._time_remaining_display.update("")
+                self._time_remaining_display.visible = False