How unclereeemus/ytmp works
Project Type & Purpose
• ytmp is a shell script–based, CLI/keyboard centric tool for music management. It searches YouTube (and local files), plays music via mpv, manages queues, downloads songs, and even integrates with UI widgets (via eww) and vim.
• Its purpose is to provide a flexible command-line interface for music playback, queue management, and multimedia control using several external command-line utilities (fzf, yt-dlp, mpv, socat, etc.).
File Structure & Core Components
• At the top level you have key files/directories:
• The main scripts: “ytmp” (main executable), “run_on_next” (script to run at the start of each song), “ytmp.vim” (vim configuration for keybindings), “ytmp.gum” (wrapper integrating mpv with gum for status display), and “ytmpsuite” (for one-liners and automation).
• “conf”: directory for configuration variables and script setups.
• “eww/”: contains subdirectories and files for eww widgets (used to display music status, avatar style themes, and layouts for the UI on the desktop), which follow a separate mini-structure (themes, src for yuck and scss code).
• “termux/”: branch of the code customized for Termux environments with additional features.
• Helper scripts such as “mightfinduseful”, “mpv_socket_commands”, and others for network/socket/command management.
• The repository organizes external integrations (like eww and termux) from the core logic, suggesting a loosely coupled structure where each component works either as an independent script or as an integration layer.
Main Components & Their Relationships
a. User Interface / Entry Points:
• CLI terminal – the user interacts with ytmp primarily via command-line. ytmp exposes various command-line options to search, play, manage the queue, etc.
• FZF interface – many commands leverage fzf for fuzzy searching (for song selection, playlist selection, and queue management) and even integrate with nvim.
• Optional UI integrations – eww widgets (providing visual/current-playback info in a desktop widget) and vim configuration (for an in-editor music management experience).
b. Core Application Logic:
• The “ytmp” main script acts as the controller: processing user commands, managing search and selection logic, and orchestrating interactions between the tools.
• “run_on_next” is responsible for setting or resetting mpv parameters at the start of each song.
• “ytmpsuite” and “ytmp.gum” serve as additional helpers for advanced playlist manipulation and mpv control respectively.
c. External Dependencies/Services:
• yt-dlp – invoked for searching and retrieving content metadata as well as for downloads.
• mpv – the media playback tool that is controlled via an IPC socket (communicated with using socat or “mpv_socket_commands”).
• socat – used to send commands over mpv’s IPC socket.
• fzf, pipe-viewer, dmenu – used to navigate the queue and search results.
• External libraries/tools like gum (for a status/status-line interface) and core utilities.
• The configuration (“conf”) and plain text queue/history files serve as the persistence layers.
d. Adaptation & Integration Layers:
• “eww” directory contains sub-modules for widget UI using eww and “yuck” (layout description language) along with SCSS for styling.
• “termux” directory shows a parallel branch with adjustments for mobile (termux) environments.
Important Architectural Patterns and Principles
• Modular design: Script components are separated by function (one for main logic, one for UI interactions, one for termux adaptations, etc.).
• Loose coupling: External utilities and scripts interact via well-defined interfaces (e.g., plain text files, IPC socket, and command-line arguments).
• Config-driven behavior: The “conf” directory and config files control environment-specific settings (like location of queue files, volume defaults, and mpv paths).
• Extensibility: The project makes it easy to add new features or modifications (as seen by its forked nature and integrated extended scripts like ytmp.gum and termux adaptations).