track-id 0.1.3__tar.gz

track_id-0.1.3/.cursor/rules/uv-track-id-setup.mdc

@@ -0,0 +1,25 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+# Cursor Rules for track-id project
+
+## Project Setup
+- This is a Python project using uv for dependency management
+- Main package: `track_id`
+- Entry point: `track_id.track_id:app`
+- Python version: >=3.9
+
+## Commands
+- Install dependencies: `uv sync`
+- Run the app: `uv run track-id`
+- Run tests: `uv run pytest`
+- Add dependency: `uv add <package>`
+- Add dev dependency: `uv add --dev <package>`
+
+## Code Style
+- Follow Python conventions
+- Use type hints where appropriate
+- Keep functions focused and testable

track_id-0.1.3/.github/workflows/package-validation.yml

@@ -0,0 +1,34 @@
+name: Package Validation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate-package:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*

track_id-0.1.3/.github/workflows/publish-pypi.yml

@@ -0,0 +1,47 @@
+name: publish-pypi
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Target repository (testpypi or pypi)"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/track-id
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ inputs.repository == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}

track_id-0.1.3/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test files
+.coverage
+
+# MacOS files
+.DS_Store
+
+# Audio files
+*.mp3
+*.m4a
+*.flac
+*.wav
+*.ogg
+*.aac
+*.m4b
+*.m4p
+*.m4a

track_id-0.1.3/.python-version

@@ -0,0 +1 @@
+3.9

track_id-0.1.3/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Track-ID** is a Python CLI tool for music metadata enrichment and search. It searches tracks across multiple music data sources (Bandcamp, MusicBrainz), displays MP3 file info, and enriches MP3 files with metadata from external music databases.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the CLI
+uv run track-id search "Artist - Title"
+uv run track-id info path/to/file.mp3
+uv run track-id enrich path/to/file.mp3
+
+# Run tests
+uv run pytest
+uv run pytest tests/test_bandcamp_api.py -v   # single file
+uv run pytest -m unit                          # unit tests only
+uv run pytest -m integration                   # integration tests only
+uv run pytest -m "not slow"                    # exclude slow tests
+uv run pytest --cov=track_id --cov-report=term-missing
+
+# Type checking
+mypy track_id/
+```
+
+## Architecture
+
+### Data Source Plugin System
+
+New music sources are added by subclassing `DataSource` in `data_sources.py` and registering with `DataSourceRegistry`. Each source must implement:
+- `search(search_text)` — call external API, return raw response
+- `find_matching_track(search_results, artist, title)` — select best match
+- `extract_metadata(track_data)` — normalize to ID3 tag dict
+- `enrich_mp3_file(file_path)` — orchestrates enrichment end-to-end
+
+`unified_api.py` initializes all sources and aggregates results across them.
+
+### Data Flow
+
+```
+CLI (track_id.py)
+  → unified_api.py        # aggregates across sources
+    → DataSourceRegistry  # dispatches to each source
+      → BandcampDataSource / MusicBrainzDataSource
+    → MP3File (mp3_utils.py)  # reads/writes ID3 tags via mutagen
+  → display.py            # Rich console output
+```
+
+### Key Files
+
+| File | Role |
+|------|------|
+| `track_id/track_id.py` | CLI commands (Typer app) |
+| `track_id/unified_api.py` | Orchestrates search/enrich across all sources |
+| `track_id/data_sources.py` | Abstract base class + registry |
+| `track_id/mp3_utils.py` | `MP3File` class — ID3 read/write, filename parsing |
+| `track_id/display.py` | All Rich console output |
+| `track_id/enrichment_handlers.py` | Shared logic reused by concrete data sources |
+
+### MP3File
+
+`MP3File` in `mp3_utils.py` is the core data object. It wraps mutagen for ID3 tag access, parses `Artist - Title` filenames, caches metadata, and handles artwork download. Pass it between layers rather than raw file paths wherever possible.
+
+### ID3 Tags
+
+`id3_tags.py` holds the canonical mapping of tag names used across the project. When adding new metadata fields, update this file first.

track_id-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 track-id contributors
+
+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.

track_id-0.1.3/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: track-id
+Version: 0.1.3
+Summary: CLI for searching and enriching MP3 metadata from Bandcamp, MusicBrainz, and Discogs
+Project-URL: Homepage, https://github.com/vtasca/track-id
+Project-URL: Repository, https://github.com/vtasca/track-id
+Project-URL: Issues, https://github.com/vtasca/track-id/issues
+Author: track-id contributors
+License: MIT License
+        
+        Copyright (c) 2026 track-id contributors
+        
+        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.
+License-File: LICENSE
+Keywords: bandcamp,cli,discogs,id3,metadata,mp3,music,musicbrainz
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: mutagen>=1.47.0
+Requires-Dist: requests>=2.32.4
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.16.0
+Requires-Dist: urllib3<2.0.0
+Description-Content-Type: text/markdown
+
+# track-id
+
+A Python CLI tool for music metadata enrichment and search. Searches tracks across Bandcamp, MusicBrainz, and Discogs, displays MP3 file info, and enriches MP3 files with metadata from external music databases.
+
+## Features
+
+- **Search**: Search for tracks across Bandcamp, MusicBrainz, and Discogs
+- **Info**: Display detailed information about an MP3 file including all ID3 tags
+- **Enrich**: Automatically populate an MP3 file's metadata (artist, album, genre, label, styles, track number, artwork, etc.) from Bandcamp, MusicBrainz, and Discogs
+
+## Installation
+
+### Using uv
+
+Install from PyPI as a tool:
+```bash
+uv tool install track-id
+track-id --version
+track-id search "Chaos In The CBD"
+```
+
+### Using pip
+
+Install from PyPI with pip:
+```bash
+pip install track-id
+track-id --version
+track-id search "Chaos In The CBD"
+track-id info "path/to/your/file.mp3"
+track-id enrich "path/to/your/file.mp3"
+```
+
+### Clone and install locally
+
+Mainly for development purposes:
+```bash
+# Clone the repository
+git clone https://github.com/vtasca/track-id
+cd track-id
+
+# Install dependencies
+uv sync
+```
+
+## Usage
+
+### Search for tracks
+
+Search across Bandcamp, MusicBrainz, and Discogs simultaneously:
+
+```bash
+track-id search "Chaos In The CBD"
+track-id search "Burial - Archangel" --top 5
+```
+
+The `--top` / `-t` flag controls how many results are shown per source (default: 3).
+
+### Display MP3 file information
+
+```bash
+track-id info "path/to/your/file.mp3"
+```
+
+### Enrich an MP3 file with metadata
+
+Queries Bandcamp, MusicBrainz, and Discogs for a matching track and writes the retrieved metadata directly into the file's ID3 tags:
+
+```bash
+track-id enrich "path/to/your/file.mp3"
+```
+
+The file must have either existing `Artist` and `Title` ID3 tags, or an `Artist - Title` filename so the tool knows what to search for. All three sources are tried and their results merged — existing tags are never overwritten.
+
+Tags populated across sources include: `Title`, `Artist`, `Album Artist`, `Album`, `Year`, `Track Number`, `Genre`, `Publisher/Label`, `Style` (Discogs community tags), `Artwork`, and a `Discogs URL` reference.
+
+## Development
+
+### Setting up the development environment
+
+```bash
+uv sync --dev
+```
+
+### Running tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=track_id --cov-report=term-missing
+
+# Run a specific file
+uv run pytest tests/test_data_sources.py -v
+```
+
+## Project Structure
+
+```
+track-id/
+├── track_id/
+│   ├── track_id.py           # CLI commands (Typer app)
+│   ├── unified_api.py        # Orchestrates search/enrich across all sources
+│   ├── data_sources.py       # Abstract base class + registry
+│   ├── bandcamp_api.py       # Bandcamp data source
+│   ├── musicbrainz_api.py    # MusicBrainz data source
+│   ├── discogs_api.py        # Discogs data source
+│   ├── enrichment_handlers.py# Shared enrichment logic
+│   ├── mp3_utils.py          # MP3File class — ID3 read/write, filename parsing
+│   ├── display.py            # Rich console output
+│   ├── id3_tags.py           # Canonical ID3 tag name mapping
+│   └── __init__.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_data_sources.py
+│   ├── test_bandcamp_api.py
+│   ├── test_musicbrainz_api.py
+│   ├── test_discogs_api.py
+│   ├── test_artwork.py
+│   ├── test_id3_tags.py
+│   ├── test_track_id.py
+│   └── test_integration.py
+├── pyproject.toml
+└── README.md
+```
+
+## Contributing
+
+1. Write tests for new features
+2. Ensure all tests pass
+3. Follow the existing code style
+4. Update documentation as needed

track_id-0.1.3/README.md

@@ -0,0 +1,132 @@
+# track-id
+
+A Python CLI tool for music metadata enrichment and search. Searches tracks across Bandcamp, MusicBrainz, and Discogs, displays MP3 file info, and enriches MP3 files with metadata from external music databases.
+
+## Features
+
+- **Search**: Search for tracks across Bandcamp, MusicBrainz, and Discogs
+- **Info**: Display detailed information about an MP3 file including all ID3 tags
+- **Enrich**: Automatically populate an MP3 file's metadata (artist, album, genre, label, styles, track number, artwork, etc.) from Bandcamp, MusicBrainz, and Discogs
+
+## Installation
+
+### Using uv
+
+Install from PyPI as a tool:
+```bash
+uv tool install track-id
+track-id --version
+track-id search "Chaos In The CBD"
+```
+
+### Using pip
+
+Install from PyPI with pip:
+```bash
+pip install track-id
+track-id --version
+track-id search "Chaos In The CBD"
+track-id info "path/to/your/file.mp3"
+track-id enrich "path/to/your/file.mp3"
+```
+
+### Clone and install locally
+
+Mainly for development purposes:
+```bash
+# Clone the repository
+git clone https://github.com/vtasca/track-id
+cd track-id
+
+# Install dependencies
+uv sync
+```
+
+## Usage
+
+### Search for tracks
+
+Search across Bandcamp, MusicBrainz, and Discogs simultaneously:
+
+```bash
+track-id search "Chaos In The CBD"
+track-id search "Burial - Archangel" --top 5
+```
+
+The `--top` / `-t` flag controls how many results are shown per source (default: 3).
+
+### Display MP3 file information
+
+```bash
+track-id info "path/to/your/file.mp3"
+```
+
+### Enrich an MP3 file with metadata
+
+Queries Bandcamp, MusicBrainz, and Discogs for a matching track and writes the retrieved metadata directly into the file's ID3 tags:
+
+```bash
+track-id enrich "path/to/your/file.mp3"
+```
+
+The file must have either existing `Artist` and `Title` ID3 tags, or an `Artist - Title` filename so the tool knows what to search for. All three sources are tried and their results merged — existing tags are never overwritten.
+
+Tags populated across sources include: `Title`, `Artist`, `Album Artist`, `Album`, `Year`, `Track Number`, `Genre`, `Publisher/Label`, `Style` (Discogs community tags), `Artwork`, and a `Discogs URL` reference.
+
+## Development
+
+### Setting up the development environment
+
+```bash
+uv sync --dev
+```
+
+### Running tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=track_id --cov-report=term-missing
+
+# Run a specific file
+uv run pytest tests/test_data_sources.py -v
+```
+
+## Project Structure
+
+```
+track-id/
+├── track_id/
+│   ├── track_id.py           # CLI commands (Typer app)
+│   ├── unified_api.py        # Orchestrates search/enrich across all sources
+│   ├── data_sources.py       # Abstract base class + registry
+│   ├── bandcamp_api.py       # Bandcamp data source
+│   ├── musicbrainz_api.py    # MusicBrainz data source
+│   ├── discogs_api.py        # Discogs data source
+│   ├── enrichment_handlers.py# Shared enrichment logic
+│   ├── mp3_utils.py          # MP3File class — ID3 read/write, filename parsing
+│   ├── display.py            # Rich console output
+│   ├── id3_tags.py           # Canonical ID3 tag name mapping
+│   └── __init__.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_data_sources.py
+│   ├── test_bandcamp_api.py
+│   ├── test_musicbrainz_api.py
+│   ├── test_discogs_api.py
+│   ├── test_artwork.py
+│   ├── test_id3_tags.py
+│   ├── test_track_id.py
+│   └── test_integration.py
+├── pyproject.toml
+└── README.md
+```
+
+## Contributing
+
+1. Write tests for new features
+2. Ensure all tests pass
+3. Follow the existing code style
+4. Update documentation as needed

track_id-0.1.3/docs/pypi-release-guide.md

@@ -0,0 +1,53 @@
+# PyPI release guide for `track-id`
+
+This guide documents the release path that is now wired into this repository.
+
+## One-time setup
+
+1. Create and verify accounts:
+   - https://pypi.org
+   - https://test.pypi.org
+2. In both PyPI and TestPyPI, configure a **Trusted Publisher** for this repo:
+   - Owner: `vtasca`
+   - Repository: `track-id`
+   - Workflow file: `publish-pypi.yml`
+   - Environment: leave empty unless you add environment protection rules
+3. Ensure you have permission to create GitHub releases in this repository.
+
+## What this repository now includes
+
+- Package metadata in `pyproject.toml` ready for PyPI.
+- CI package check workflow: `.github/workflows/package-validation.yml`.
+- Publish workflow: `.github/workflows/publish-pypi.yml`.
+
+## Release checklist (every release)
+
+1. Update the version in `pyproject.toml` under `[project].version`.
+2. Commit and push the version change.
+3. Wait for package checks to pass in GitHub Actions.
+4. Publish to **TestPyPI** (recommended dry run):
+   - Run the `publish-pypi` workflow manually.
+   - Choose input `repository = testpypi`.
+5. Verify install from TestPyPI:
+   - `python -m venv /tmp/track-id-test && source /tmp/track-id-test/bin/activate`
+   - `pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ track-id==<version>`
+   - `track-id --version`
+6. Publish to **PyPI**:
+   - Preferred: create a GitHub Release (for example `v0.1.4`), which triggers publish to PyPI.
+   - Alternative: run workflow dispatch with `repository = pypi`.
+7. Verify public install:
+   - `python -m venv /tmp/track-id-prod && source /tmp/track-id-prod/bin/activate`
+   - `pip install track-id==<version>`
+   - `track-id --version`
+
+## Local preflight commands
+
+Run these before making a release:
+
+1. `uv sync --dev`
+2. `uv run pytest`
+3. `rm -rf dist`
+4. `uv build`
+5. `uvx twine check dist/*`
+
+If `twine check` passes and tests are green, the artifact is usually safe to publish.

track_id-0.1.3/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "track-id"
+version = "0.1.3"
+description = "CLI for searching and enriching MP3 metadata from Bandcamp, MusicBrainz, and Discogs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "track-id contributors" },
+]
+keywords = ["mp3", "id3", "metadata", "music", "cli", "bandcamp", "musicbrainz", "discogs"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "requests>=2.32.4",
+    "typer>=0.16.0",
+    "urllib3<2.0.0",
+    "mutagen>=1.47.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vtasca/track-id"
+Repository = "https://github.com/vtasca/track-id"
+Issues = "https://github.com/vtasca/track-id/issues"
+
+[project.scripts]
+track-id = "track_id.track_id:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["track_id"]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.17.1",
+    "types-requests>=2.31.0.6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-v"]

track_id-0.1.3/tests/__init__.py

@@ -0,0 +1 @@
+# Tests package for track-id