# unclereeemus/ytmp architecture

> Architecture diagram of the GitHub repository unclereeemus/ytmp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unclereeemus/ytmp
- Repository: https://github.com/unclereeemus/ytmp

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        User["User / CLI"]:::ui
        FZF["FZF/dmenu Interface"]:::external
    end

    %% Core Application Logic
    subgraph "Core Application Logic"
        Controller["Main Controller (ytmp script)"]:::script
        RunOnNext["Run-on-Next Module (run_on_next)"]:::script
        VimIntegration["Vim Integration (ytmp.vim)"]:::script
        GumWrapper["Gum Wrapper for mpv Status (ytmp.gum)"]:::script
        Suite["Suite of One-Liners/Automation Utilities (ytmpsuite)"]:::script
        Config["Configuration Management (conf)"]:::conf
        Helper["Helper Script (mightfinduseful)"]:::script
        IPCModule["mpv IPC Command Module (mpv_socket_commands)"]:::script
    end

    %% External Dependencies
    subgraph "External Dependencies"
        YtDlp["yt-dlp"]:::external
        MPV["MPV Playback Process"]:::external
        Socat["socat"]:::external
        OtherUtil["Other Tools (pipe-viewer, etc.)"]:::external
        Queue["PlainText Queue/History"]:::storage
    end

    %% UI & Adaptation Layers
    subgraph "UI & Adaptation Layers"
        Eww["UI Widgets (eww)"]:::ui
        EwwDetails["Eww Themes/Layouts (eww/eww.dharmx)"]:::ui
        Termux["Termux Module (termux)"]:::script
    end

    %% Connections between layers
    User -->|"input_command"| Controller
    FZF -->|"search_select"| Controller

    Controller -->|"retrieve_config"| Config
    Controller -->|"search_download"| YtDlp
    Controller -->|"update_queue"| Queue
    Controller -->|"playback_command"| MPV
    Controller -->|"automation"| Suite
    Controller -->|"vim_binding"| VimIntegration
    Controller -->|"advanced_control"| GumWrapper
    Controller -->|"misc_commands"| Helper
    Controller -->|"mobile_adapt"| Termux
    Controller -->|"IPC_init"| IPCModule

    IPCModule -->|"IPC_commands"| MPV
    RunOnNext -->|"init_song"| MPV
    MPV -->|"status_feedback"| Controller
    Controller -->|"ui_update"| Eww
    Eww -->|"apply_theme"| EwwDetails

    Controller -->|"external_utilities"| OtherUtil

    %% Styles
    classDef script fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ui fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef conf fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef storage fill:#EEE8AA,stroke:#000,stroke-width:1px;

    %% Click Events
    click Controller "https://github.com/unclereeemus/ytmp/tree/main/ytmp"
    click RunOnNext "https://github.com/unclereeemus/ytmp/tree/main/run_on_next"
    click VimIntegration "https://github.com/unclereeemus/ytmp/blob/main/ytmp.vim"
    click GumWrapper "https://github.com/unclereeemus/ytmp/blob/main/ytmp.gum"
    click Suite "https://github.com/unclereeemus/ytmp/tree/main/ytmpsuite"
    click Config "https://github.com/unclereeemus/ytmp/tree/main/conf"
    click IPCModule "https://github.com/unclereeemus/ytmp/tree/main/mpv_socket_commands"
    click Eww "https://github.com/unclereeemus/ytmp/tree/main/eww"
    click EwwDetails "https://github.com/unclereeemus/ytmp/blob/main/eww/eww.dharmx"
    click Termux "https://github.com/unclereeemus/ytmp/tree/main/termux"
    click Helper "https://github.com/unclereeemus/ytmp/tree/main/mightfinduseful"
```
