smclipy 0.1.0__tar.gz

smclipy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  checks-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Typecheck
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: checks-and-build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Publish to TestPyPI
+        run: >-
+          uv publish
+          --publish-url https://test.pypi.org/legacy/
+          --check-url https://test.pypi.org/simple/
+
+  publish-pypi:
+    needs: checks-and-build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Publish to PyPI
+        run: uv publish

smclipy-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# smclipy
+.temp/
+Music/
+config.json
+temp.txt
+roadmap.md

smclipy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

smclipy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joaquin Larroca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smclipy-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: smclipy
+Version: 0.1.0
+Summary: Simple music CLI to download, tag, and organize music from YouTube
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: climage>=0.2.2
+Requires-Dist: mutagen>=1.47.0
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: yt-dlp[default]>=2026.3.17
+Description-Content-Type: text/markdown
+
+# smclipy
+
+**simple music cli py** is a Python script designed to streamline downloading, tagging, and organizing music from YouTube. It allows you to batch-download audio, manually set metadata (including multiple artists and cover art).
+
+## Features
+
+- **Batch Downloading:** Queue up as many YouTube URLs as you want before processing.
+- **Interactive Tagging:** Prompts you for the track Title and Artists (has autocompletion). Both come prefilled: the title from the video's title, and the artists from the channel name, corrected against your known authors.
+- **Cover Art Cropping:** Easily crop your cover art to a perfect 1:1 square ratio during the tagging process.
+- **Clean Cleanup:** Uses a `.temp` directory during the download and tagging process to keep your main library clean.
+
+## Requirements
+
+- **Python 3.12+** (handled automatically if you use `uv`).
+- **FFmpeg** — required by yt-dlp to extract the audio to MP3 and embed the cover art.
+- **[Deno](https://docs.deno.com/runtime/getting_started/installation/)** — required by yt-dlp (2025.11+) to solve YouTube's JavaScript challenges during extraction. Without it, downloads may fail or have limited format availability.
+
+## Installation
+
+Install it as a standalone CLI tool:
+
+```bash
+uv tool install smclipy
+```
+
+or, if you prefer pipx:
+
+```bash
+pipx install smclipy
+```
+
+## Configuration
+
+smclipy relies on a configuration file to know where to organize your files.
+
+On first run, a default config file is created at `~/.config/smclipy/config.json` and the program exits so you can edit it to your liking. To store it somewhere else, set the `SMCLIPY_CONFIG` environment variable to your preferred path (respects `$XDG_CONFIG_HOME`).
+
+```json
+{
+  "name": "smclipy",
+  "path_to_music_folder": "./Music",
+  "description_max_lines": 5
+}
+```
+
+### Config Breakdown
+
+- `name`: The master folder name (`smclipy`) that will be created inside your music folder to hold all the organized artists.
+- `path_to_music_folder`: The base directory where your music library lives (default is `./Music`, relative to wherever you run the command from).
+- `description_max_lines`: How many lines of the video description to show while tagging (default is 5).
+
+## Usage
+
+Run it from your music library's parent directory:
+
+```bash
+smclipy <command>
+```
+
+### Commands
+
+- **`smclipy download`** — Batch download and tag songs from YouTube.
+- **`smclipy crop`** — Scan saved covers for pillarboxed art, crop to 1:1, and re-embed into the matching MP3s.
+
+### Download flow
+
+1. **Queue URLs:** Paste your YouTube URLs one by one (enter an empty line to finish).
+2. **Tagging Flow (Per Track):**
+   - The script will download the current track to `.temp`.
+   - If a cover image is found, you will be prompted to crop it to a 1:1 ratio.
+   - Enter the **Title** of the track (prefilled with the video's title).
+   - Enter the **Artist/s** (prefilled from the channel name; if it matches an author already in `authors.txt` — ignoring case and spaces — your existing spelling is kept). To tag multiple artists, separate them using a backslash `\` (e.g., `Artist 1\Artist 2\Artist 3`).
+
+3. **Completion:** Once tagged, the final music file is moved to your designated music folder, using the following filename artist-title.mp3 (e.g., `Rick Astley-Never Gonna Give You Up.mp3`).
+
+## Folder Structure Example
+
+After running the script and tagging a few songs, your output directory will look something like this:
+
+```text
+📁 ./.temp                 <-- (Used temporarily during processing)
+📁 ./Music
+├──🎵 artist1-title1.mp3
+├──🎵 artist1-title2.mp3
+├──🎵 artist2-title1.mp3
+├──🎵 artist3-title1.mp3
+└── ...
+```
+
+## Development
+
+Clone the repo and run it from the project root with uv (set `SMCLIPY_CONFIG` to use your existing `config.json`):
+
+```bash
+uv run smclipy <command>
+```

smclipy-0.1.0/README.md

@@ -0,0 +1,96 @@
+# smclipy
+
+**simple music cli py** is a Python script designed to streamline downloading, tagging, and organizing music from YouTube. It allows you to batch-download audio, manually set metadata (including multiple artists and cover art).
+
+## Features
+
+- **Batch Downloading:** Queue up as many YouTube URLs as you want before processing.
+- **Interactive Tagging:** Prompts you for the track Title and Artists (has autocompletion). Both come prefilled: the title from the video's title, and the artists from the channel name, corrected against your known authors.
+- **Cover Art Cropping:** Easily crop your cover art to a perfect 1:1 square ratio during the tagging process.
+- **Clean Cleanup:** Uses a `.temp` directory during the download and tagging process to keep your main library clean.
+
+## Requirements
+
+- **Python 3.12+** (handled automatically if you use `uv`).
+- **FFmpeg** — required by yt-dlp to extract the audio to MP3 and embed the cover art.
+- **[Deno](https://docs.deno.com/runtime/getting_started/installation/)** — required by yt-dlp (2025.11+) to solve YouTube's JavaScript challenges during extraction. Without it, downloads may fail or have limited format availability.
+
+## Installation
+
+Install it as a standalone CLI tool:
+
+```bash
+uv tool install smclipy
+```
+
+or, if you prefer pipx:
+
+```bash
+pipx install smclipy
+```
+
+## Configuration
+
+smclipy relies on a configuration file to know where to organize your files.
+
+On first run, a default config file is created at `~/.config/smclipy/config.json` and the program exits so you can edit it to your liking. To store it somewhere else, set the `SMCLIPY_CONFIG` environment variable to your preferred path (respects `$XDG_CONFIG_HOME`).
+
+```json
+{
+  "name": "smclipy",
+  "path_to_music_folder": "./Music",
+  "description_max_lines": 5
+}
+```
+
+### Config Breakdown
+
+- `name`: The master folder name (`smclipy`) that will be created inside your music folder to hold all the organized artists.
+- `path_to_music_folder`: The base directory where your music library lives (default is `./Music`, relative to wherever you run the command from).
+- `description_max_lines`: How many lines of the video description to show while tagging (default is 5).
+
+## Usage
+
+Run it from your music library's parent directory:
+
+```bash
+smclipy <command>
+```
+
+### Commands
+
+- **`smclipy download`** — Batch download and tag songs from YouTube.
+- **`smclipy crop`** — Scan saved covers for pillarboxed art, crop to 1:1, and re-embed into the matching MP3s.
+
+### Download flow
+
+1. **Queue URLs:** Paste your YouTube URLs one by one (enter an empty line to finish).
+2. **Tagging Flow (Per Track):**
+   - The script will download the current track to `.temp`.
+   - If a cover image is found, you will be prompted to crop it to a 1:1 ratio.
+   - Enter the **Title** of the track (prefilled with the video's title).
+   - Enter the **Artist/s** (prefilled from the channel name; if it matches an author already in `authors.txt` — ignoring case and spaces — your existing spelling is kept). To tag multiple artists, separate them using a backslash `\` (e.g., `Artist 1\Artist 2\Artist 3`).
+
+3. **Completion:** Once tagged, the final music file is moved to your designated music folder, using the following filename artist-title.mp3 (e.g., `Rick Astley-Never Gonna Give You Up.mp3`).
+
+## Folder Structure Example
+
+After running the script and tagging a few songs, your output directory will look something like this:
+
+```text
+📁 ./.temp                 <-- (Used temporarily during processing)
+📁 ./Music
+├──🎵 artist1-title1.mp3
+├──🎵 artist1-title2.mp3
+├──🎵 artist2-title1.mp3
+├──🎵 artist3-title1.mp3
+└── ...
+```
+
+## Development
+
+Clone the repo and run it from the project root with uv (set `SMCLIPY_CONFIG` to use your existing `config.json`):
+
+```bash
+uv run smclipy <command>
+```

smclipy-0.1.0/config.example.json

@@ -0,0 +1,5 @@
+{
+    "name": "smclipy",
+    "path_to_music_folder": "./Music",
+    "description_max_lines": 5
+}

smclipy-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "smclipy"
+version = "0.1.0"
+description = "Simple music CLI to download, tag, and organize music from YouTube"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "climage>=0.2.2",
+    "mutagen>=1.47.0",
+    "pillow>=12.2.0",
+    "prompt-toolkit>=3.0.52",
+    "yt-dlp[default]>=2026.3.17",
+]
+
+[project.scripts]
+smclipy = "smclipy.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.14.0",
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["smclipy"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4"]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["smclipy"]
+
+[[tool.mypy.overrides]]
+module = ["yt_dlp.*", "climage.*"]
+ignore_missing_imports = true

smclipy-0.1.0/smclipy/__init__.py

@@ -0,0 +1,3 @@
+"""smclipy - simple music cli py."""
+
+__version__ = "0.1.0"

smclipy-0.1.0/smclipy/__main__.py

@@ -0,0 +1,4 @@
+from smclipy.cli import main
+
+if __name__ == "__main__":
+    main()

smclipy-0.1.0/smclipy/cli.py

@@ -0,0 +1,201 @@
+import argparse
+import sys
+
+from smclipy.config import Settings, init, settings
+from smclipy.downloader import (
+    VideoDownloadError,
+    download,
+    extract_video_ids,
+    get_yt_channel_author,
+)
+from smclipy.helpers import (
+    get_list_from_split_str,
+    get_unique_items,
+    resolve_known_authors,
+)
+from smclipy.images import crop_image_1_to_1, display_image, is_image_pillarbox
+from smclipy.metadata import (
+    change_cover,
+    get_all_names,
+    get_image_from_file,
+    save_all_authors,
+    save_all_covers,
+    save_all_songs_info,
+    save_song_temp_to_main,
+)
+from smclipy.storage import append_unique_lines, read_lines, write_lines
+from smclipy.ui import (
+    prompt_authors,
+    prompt_crop,
+    prompt_resume,
+    prompt_title,
+    show_yt_video_info,
+)
+
+
+def collect_video_ids() -> list[str]:
+    print("Enter '' as url to finish inputting url's")
+    videos_id_list: list[str] = []
+    while True:
+        try:
+            url = input("Enter your URL: ")
+            if url == "":
+                break
+            videos_id_list.extend(extract_video_ids(url))
+        except KeyboardInterrupt:
+            print("\nExiting...")
+            sys.exit(0)
+    return videos_id_list
+
+
+def process_video(video_id: str, authors_list: list[str]) -> None:
+    s = settings()
+    temp_mp3 = s.temp_folder.joinpath("temp.mp3")
+    temp_png = s.temp_folder.joinpath("temp.png")
+
+    for temp_file in (temp_mp3, temp_png):
+        if temp_file.is_file():
+            temp_file.unlink()
+
+    info_dictionary = download(video_id)
+    has_cover = get_image_from_file(temp_mp3, s.temp_folder, "temp.png")
+
+    if has_cover:
+        print("\n\n")
+        display_image(temp_png)
+
+        if prompt_crop(default="False"):
+            crop_image_1_to_1(temp_png)
+
+    print("\n\n")
+    title = prompt_title(default=str(info_dictionary.get("title", "")))
+
+    print("\n\n")
+    show_yt_video_info(info_dictionary)
+
+    yt_artists = get_yt_channel_author(info_dictionary)
+    authors_default = "\\".join(resolve_known_authors(yt_artists, authors_list))
+    authors = prompt_authors(authors_list, default=authors_default)
+
+    current_authors_list = get_list_from_split_str(authors, "\\")
+    for item in get_unique_items(current_authors_list, authors_list):
+        authors_list.append(item)
+
+    save_song_temp_to_main(temp_mp3, temp_png, title, authors)
+
+    append_unique_lines(s.authors_file, current_authors_list)
+    append_unique_lines(s.songs_info, [f"{title} - {', '.join(current_authors_list)}"])
+
+
+def filter_processed_ids(pending_ids: list[str], processed_ids: list[str]) -> list[str]:
+    processed_set = set(processed_ids)
+    return [video_id for video_id in pending_ids if video_id not in processed_set]
+
+
+def _collect_new_queue(s: Settings) -> tuple[list[str], list[str]]:
+    pending_ids = collect_video_ids()
+    write_lines(s.pending_ids_file, pending_ids)
+    write_lines(s.processed_ids_file, [])
+    return pending_ids, []
+
+
+def cmd_download(args: argparse.Namespace) -> None:
+    s = init()
+
+    print("Scanning music files...")
+    save_all_authors()
+    save_all_songs_info()
+
+    print("Fetching all authors names...")
+    authors_list: list[str] = get_all_names()
+
+    pending_ids = read_lines(s.pending_ids_file)
+    processed_ids = read_lines(s.processed_ids_file)
+    remaining_ids = filter_processed_ids(pending_ids, processed_ids)
+
+    if remaining_ids and prompt_resume():
+        pending_ids, processed_ids = remaining_ids, []
+    else:
+        pending_ids, processed_ids = _collect_new_queue(s)
+
+    print(f"Preparing to download {len(pending_ids)} vid/s")
+    skipped_ids: list[str] = []
+    for video_id in pending_ids:
+        try:
+            process_video(video_id, authors_list)
+        except VideoDownloadError as exc:
+            print(f"Skipping '{video_id}': {exc}")
+            skipped_ids.append(video_id)
+            continue
+        except KeyboardInterrupt:
+            print("\nInterrupted, exiting...")
+            break
+        append_unique_lines(s.processed_ids_file, [video_id])
+        processed_ids.append(video_id)
+
+    if skipped_ids:
+        print(
+            f"Finished with {len(skipped_ids)} skipped vid/s "
+            f"(still pending for a retry): {skipped_ids}"
+        )
+
+
+def cmd_crop(args: argparse.Namespace) -> None:
+    s = init()
+
+    print("Scanning music files...")
+    save_all_covers()
+
+    print("Scanning images files...")
+    covers_to_crop: list[str] = [
+        file.stem
+        for file in s.covers_folder.glob("*.png")
+        if file.is_file() and is_image_pillarbox(file)
+    ]
+
+    print(f"Reading {s.false_positives_file.name}...")
+    false_positives = read_lines(s.false_positives_file)
+
+    if not covers_to_crop:
+        print("No images to crop...")
+    else:
+        for filename in covers_to_crop:
+            if filename.strip() in false_positives:
+                continue
+            cover = s.covers_folder.joinpath(f"{filename}.png")
+            display_image(cover)
+            if prompt_crop(default="True"):
+                crop_image_1_to_1(cover)
+                mp3_file = s.music_folder.joinpath(f"{filename}.mp3")
+                if mp3_file.is_file():
+                    change_cover(cover, mp3_file)
+                else:
+                    print(f"{filename}: MP3 not found, skipping cover re-embed")
+            else:
+                false_positives.append(filename)
+            print("\n\n")
+    append_unique_lines(s.false_positives_file, false_positives)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="smclipy",
+        description="Download, tag, and organize music from YouTube.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser(
+        "download",
+        help="Batch download songs from YouTube and tag them interactively.",
+    )
+    subparsers.add_parser(
+        "crop",
+        help="Crop pillarboxed cover images to a 1:1 ratio and re-embed them.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "download":
+        cmd_download(args)
+    elif args.command == "crop":
+        cmd_crop(args)

smclipy-0.1.0/smclipy/config.py

@@ -0,0 +1,76 @@
+import json
+import os
+from pathlib import Path
+
+from smclipy.helpers import sanitize_filename
+
+DEFAULT_CONFIG = {
+    "name": "smclipy",
+    "path_to_music_folder": "./Music",
+    "description_max_lines": 5,
+}
+CONFIG_PATH = Path(
+    os.environ.get(
+        "SMCLIPY_CONFIG",
+        Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+        / "smclipy"
+        / "config.json",
+    )
+)
+
+
+class Settings:
+    """Resolved, per-run configuration."""
+
+    def __init__(self, raw: dict, base_dir: Path = Path(".")) -> None:
+        self.raw = raw
+        self.music_folder = Path(str(raw.get("path_to_music_folder", ".")))
+        self.temp_folder = base_dir.joinpath(".temp")
+        self.pending_ids_file = self.temp_folder.joinpath("pending_ids.txt")
+        self.processed_ids_file = self.temp_folder.joinpath("processed_ids.txt")
+        self.script_folder = self.music_folder.joinpath(
+            sanitize_filename(str(raw.get("name", "smclipy")))
+        )
+        self.authors_file = self.script_folder.joinpath("authors.txt")
+        self.songs_info = self.script_folder.joinpath("songs_info.txt")
+        self.false_positives_file = self.script_folder.joinpath(
+            "cropping_tool_false_positives.txt"
+        )
+        self.covers_folder = self.script_folder.joinpath("covers")
+        self.description_max_lines = int(raw.get("description_max_lines", 5))
+
+
+# Global settings singleton. This is a CLI: a single settings object lives for
+# the whole process, created lazily by init()/settings() and shared across
+# modules. Tests monkeypatch config._settings to isolate runs.
+_settings: Settings | None = None
+
+
+def _load_raw_config() -> dict:
+    if not CONFIG_PATH.exists():
+        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        CONFIG_PATH.write_text(json.dumps(DEFAULT_CONFIG, indent=4), encoding="utf-8")
+        print(
+            "Looks like its your first time executing the script, "
+            "please modify config.json to your liking! and read the README.md file"
+        )
+        raise SystemExit(0)
+    return json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+
+
+def setup_folders() -> None:
+    s = settings()
+    for folder in (s.script_folder, s.covers_folder, s.temp_folder):
+        folder.mkdir(parents=True, exist_ok=True)
+
+
+def init() -> Settings:
+    global _settings
+    if _settings is None:
+        _settings = Settings(_load_raw_config())
+        setup_folders()
+    return _settings
+
+
+def settings() -> Settings:
+    return _settings if _settings is not None else init()