mudio 1.0.0__tar.gz

mudio-1.0.0/.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Project-specific
+logs/
+*.log
+test_artifacts/
+
+venv/
+benchmark_results.png

mudio-1.0.0/LICENSE

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

mudio-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mudio
+Version: 1.0.0
+Summary: Friendly command-line music-metadata editor and Python library
+Project-URL: Homepage, https://github.com/mdeik/mudio
+Project-URL: Repository, https://github.com/mdeik/mudio
+Author-email: Matthew Deik <131482791+mdeik@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: mutagen>=1.47.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mudio
+
+**mudio** is a powerful, friendly command-line music metadata editor and Python library. It provides a unified API for handling metadata across MP3, FLAC, M4A, and more, making batch processing and automation simple and safe.
+
+## Features
+
+-   **Unified API**: Write code once, run it on MP3, FLAC, M4A, WAV, OGG, OPUS, WMA, and WavPack.
+-   **Batch Processing**: robust CLI for processing thousands of files.
+-   **Parallel Execution**: Automatically uses multi-threading for large batches.
+-   **Safety First**: Built-in **backup** system, **dry-run** mode, and careful validation.
+-   **Powerful Operations**:
+    -   **Find & Replace**: Regex-supported search and replace in tags.
+    -   **Mass Edits**: Set, overwrite, append, prefix, or clear tags.
+    -   **Filtering**: Apply changes only to files matching specific criteria (e.g. `artist="The Beatles"`).
+
+## Supported Formats
+
+-   **MP3** (`.mp3`) - ID3v2.3/v2.4
+-   **FLAC** (`.flac`) - Vorbis Comments
+-   **M4A / MP4** (`.m4a`, `.mp4`) - MP4 Tags
+-   **Ogg Vorbis** (`.ogg`)
+-   **Opus** (`.opus`)
+-   **WAV** (`.wav`)
+-   **Windows Media Audio** (`.wma`)
+-   **WavPack** (`.wv`)
+
+## Installation
+
+```bash
+pip install mudio
+```
+
+## CLI Usage
+
+`mudio` is designed for efficient batch operations.
+
+### Basic Commands
+
+```bash
+# View metadata
+mudio song.mp3 --mode view
+
+# Set Album and Date
+mudio *.mp3 --mode set --album "New Album" --date "2024"
+
+# View metadata (truncated if long)
+mudio song.mp3 --mode print
+
+# Overwrite Title
+mudio song.flac --mode overwrite --fields title --value "My Song"
+```
+
+### Advanced Batch Operations
+
+```bash
+# Regex Find & Replace (Fix features)
+# Changes "feat." -> "ft." in title and artist
+mudio /music --recursive \
+  --mode find-replace --find "feat\." --replace "ft." --regex \
+  --fields title,artist
+
+For full command details, see the [CLI Reference](docs/cli_reference.md).
+For code API details, see the [API Reference](docs/api_reference.md).
+
+# Append to Comment
+mudio *.m4a --mode append --fields comment --value " [Remastered]"
+
+# Filtered Processing
+# Only add "Rock" genre to tracks by "Led Zeppelin"
+mudio /library --recursive \
+  --filter "artist=Led Zeppelin" \
+  --mode overwrite --fields genre --value "Rock"
+```
+
+### Safety Features
+
+```bash
+# Dry Run (See what would happen without modifying files)
+mudio *.mp3 --mode set --album "Test" --dry-run
+
+# Create Backups (Saved to ./backups/)
+mudio *.flac --mode clear --fields comment --backup ./backups
+```
+
+## Python Library Usage
+
+`mudio` provides a Pythonic wrapper around `mutagen` for scripts and tools.
+
+```python
+from mudio import SimpleMusic
+
+# Reading
+with SimpleMusic("song.flac") as sm:
+    print(sm.read_fields())
+    # {'artist': ['The Band'], 'title': ['The Song'], ...}
+
+# Writing
+with SimpleMusic("song.mp3") as sm:
+    sm.write_fields({
+        'title': ['New Title'],
+        'genre': ['Pop', 'Rock']  # Multi-value support
+    })
+
+# Error handling is managed by the context manager
+```
+
+## Comparison with Alternatives
+
+### vs. **Mutagen**
+-   **Mutagen** is the low-level library that `mudio` uses. It is powerful but requires learning different APIs for ID3, Vorbis, and MP4 tags.
+-   **mudio** abstracts these differences. Use `mudio` if you want a simple, unified API (e.g. `sm.write_fields({'title': ...})` works on everything). Use `mutagen` if you need byte-level control or support for obscure frame types.
+
+### vs. **Beets**
+-   **Beets** is a complete library manager with a centralized database, autotagger, and plugin system. It implies a workflow where it "owns" your library.
+-   **mudio** is a stateless tool. It modifies files directly without a database. Use `mudio` for quick fixes, batch scripting, or if you prefer managing your file structure manually.
+
+### vs. **Picard**
+-   **MusicBrainz Picard** is a GUI application focused on matching files to the MusicBrainz database.
+-   **mudio** is a CLI/Library tool. It's better for automation, headless servers, or mass-editing tags based on patterns rather than database matching.
+
+### vs. **music_tag**
+-   **music_tag** is a library primarily for Python scripts, offering a dictionary-like interface. It is excellent for simple script usage.
+-   **mudio** offers similar library features but includes a **robust CLI** for batch processing, filtering, and safety operations (backups, dry-runs) out of the box.
+
+### vs. **EyeD3**
+-   **EyeD3** is excellent but specific to MP3/ID3.
+-   **mudio** supports FLAC, M4A, OGG, and more with the same commands.
+
+## Development
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```

mudio-1.0.0/README.md

@@ -0,0 +1,137 @@
+# mudio
+
+**mudio** is a powerful, friendly command-line music metadata editor and Python library. It provides a unified API for handling metadata across MP3, FLAC, M4A, and more, making batch processing and automation simple and safe.
+
+## Features
+
+-   **Unified API**: Write code once, run it on MP3, FLAC, M4A, WAV, OGG, OPUS, WMA, and WavPack.
+-   **Batch Processing**: robust CLI for processing thousands of files.
+-   **Parallel Execution**: Automatically uses multi-threading for large batches.
+-   **Safety First**: Built-in **backup** system, **dry-run** mode, and careful validation.
+-   **Powerful Operations**:
+    -   **Find & Replace**: Regex-supported search and replace in tags.
+    -   **Mass Edits**: Set, overwrite, append, prefix, or clear tags.
+    -   **Filtering**: Apply changes only to files matching specific criteria (e.g. `artist="The Beatles"`).
+
+## Supported Formats
+
+-   **MP3** (`.mp3`) - ID3v2.3/v2.4
+-   **FLAC** (`.flac`) - Vorbis Comments
+-   **M4A / MP4** (`.m4a`, `.mp4`) - MP4 Tags
+-   **Ogg Vorbis** (`.ogg`)
+-   **Opus** (`.opus`)
+-   **WAV** (`.wav`)
+-   **Windows Media Audio** (`.wma`)
+-   **WavPack** (`.wv`)
+
+## Installation
+
+```bash
+pip install mudio
+```
+
+## CLI Usage
+
+`mudio` is designed for efficient batch operations.
+
+### Basic Commands
+
+```bash
+# View metadata
+mudio song.mp3 --mode view
+
+# Set Album and Date
+mudio *.mp3 --mode set --album "New Album" --date "2024"
+
+# View metadata (truncated if long)
+mudio song.mp3 --mode print
+
+# Overwrite Title
+mudio song.flac --mode overwrite --fields title --value "My Song"
+```
+
+### Advanced Batch Operations
+
+```bash
+# Regex Find & Replace (Fix features)
+# Changes "feat." -> "ft." in title and artist
+mudio /music --recursive \
+  --mode find-replace --find "feat\." --replace "ft." --regex \
+  --fields title,artist
+
+For full command details, see the [CLI Reference](docs/cli_reference.md).
+For code API details, see the [API Reference](docs/api_reference.md).
+
+# Append to Comment
+mudio *.m4a --mode append --fields comment --value " [Remastered]"
+
+# Filtered Processing
+# Only add "Rock" genre to tracks by "Led Zeppelin"
+mudio /library --recursive \
+  --filter "artist=Led Zeppelin" \
+  --mode overwrite --fields genre --value "Rock"
+```
+
+### Safety Features
+
+```bash
+# Dry Run (See what would happen without modifying files)
+mudio *.mp3 --mode set --album "Test" --dry-run
+
+# Create Backups (Saved to ./backups/)
+mudio *.flac --mode clear --fields comment --backup ./backups
+```
+
+## Python Library Usage
+
+`mudio` provides a Pythonic wrapper around `mutagen` for scripts and tools.
+
+```python
+from mudio import SimpleMusic
+
+# Reading
+with SimpleMusic("song.flac") as sm:
+    print(sm.read_fields())
+    # {'artist': ['The Band'], 'title': ['The Song'], ...}
+
+# Writing
+with SimpleMusic("song.mp3") as sm:
+    sm.write_fields({
+        'title': ['New Title'],
+        'genre': ['Pop', 'Rock']  # Multi-value support
+    })
+
+# Error handling is managed by the context manager
+```
+
+## Comparison with Alternatives
+
+### vs. **Mutagen**
+-   **Mutagen** is the low-level library that `mudio` uses. It is powerful but requires learning different APIs for ID3, Vorbis, and MP4 tags.
+-   **mudio** abstracts these differences. Use `mudio` if you want a simple, unified API (e.g. `sm.write_fields({'title': ...})` works on everything). Use `mutagen` if you need byte-level control or support for obscure frame types.
+
+### vs. **Beets**
+-   **Beets** is a complete library manager with a centralized database, autotagger, and plugin system. It implies a workflow where it "owns" your library.
+-   **mudio** is a stateless tool. It modifies files directly without a database. Use `mudio` for quick fixes, batch scripting, or if you prefer managing your file structure manually.
+
+### vs. **Picard**
+-   **MusicBrainz Picard** is a GUI application focused on matching files to the MusicBrainz database.
+-   **mudio** is a CLI/Library tool. It's better for automation, headless servers, or mass-editing tags based on patterns rather than database matching.
+
+### vs. **music_tag**
+-   **music_tag** is a library primarily for Python scripts, offering a dictionary-like interface. It is excellent for simple script usage.
+-   **mudio** offers similar library features but includes a **robust CLI** for batch processing, filtering, and safety operations (backups, dry-runs) out of the box.
+
+### vs. **EyeD3**
+-   **EyeD3** is excellent but specific to MP3/ID3.
+-   **mudio** supports FLAC, M4A, OGG, and more with the same commands.
+
+## Development
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```

mudio-1.0.0/docs/api_reference.md

@@ -0,0 +1,175 @@
+# mudio API Reference
+
+This document provides a detailed reference for the internal Python API of `mudio`. It is useful for developers who want to use `mudio` as a library in their own scripts or applications.
+
+## Core (`mudio.core`)
+
+The core module handles the abstraction layer for reading and writing metadata across different audio formats.
+
+### `SimpleMusic`
+
+The primary interface for interacting with audio files. It automatically handles format detection (MP3, FLAC, M4A, etc.) and provides a unified dictionary-based API for tags.
+
+```python
+from mudio.core import SimpleMusic, managed_simple_music
+
+# Recommended: Use context manager to ensure files are closed safely
+with managed_simple_music("path/to/song.mp3") as sm:
+    fields = sm.read_fields()
+    sm.write_fields({"title": ["New Title"]})
+```
+
+#### Class Reference
+
+**`SimpleMusic(path: Union[str, Path])`**
+*   **path**: The file path to open.
+*   **Raises**:
+    *   `FormatError`: If the file format is unsupported or corrupted.
+    *   `RuntimeError`: If the file does not exist.
+
+**`SimpleMusic.read_fields(mode: str = 'canonical') -> Dict[str, List[str]]`**
+Reads metadata fields from the file.
+*   **mode**:
+    *   `'canonical'` (default): Returns a standardized dictionary using `mudio`'s canonical field names (e.g. `title`, `artist`, `date`).
+    *   `'raw'`: Returns the raw mapping of tags as they appear in the file (e.g. `TIT2` for MP3 title, `©nam` for MP4).
+    *   `'extended'`: Returns all canonical fields **plus** any other fields found in the file that didn't map to a canonical one (e.g. `acoustid_id`, custom TXXX frames).
+*   **Returns**: A dictionary where keys are field names and values are a **list of strings**.
+    *   **Note**: `mudio` uses a unified list-based structure for I/O consistency. However, fields have semantic cardinality:
+        *   **Single-valued** (e.g. `title`, `date`, `track`): Logic operations will typically use only the first value.
+        *   **Multi-valued** (e.g. `artist`, `genre`): Logic operations maintain the full list.
+    *   See `mudio.operations` for field definitions.
+
+**`SimpleMusic.write_fields(fields: Dict[str, List[str]])`**
+Writes metadata to the file.
+*   **Raises**:
+    *   `PermissionError`: If the file is not writable.
+    *   `RuntimeError`: If no file is loaded.
+*   **fields**: A dictionary of fields to write. Keys can be canonical field names (like `title`, `artist`) or **any custom string**.
+*   **Behavior**:
+    *   **Custom Fields**: Arbitrary keys are written as format-specific custom tags (TXXX for ID3, comments for Vorbis, freeform atoms for MP4).
+    *   Existing fields not in the input dictionary are **preserved**. (To delete a field, use `delete_fields` or pass an empty list `[]` as the value).
+    *   This method transparently handles format-specific details.
+
+**`SimpleMusic.delete_fields(fields: List[str])`**
+Deletes the specified fields from the file.
+*   **fields**: List of canonical or custom field names to remove.
+
+**`SimpleMusic.close()`**
+Closes the underlying file handle. Automatically called when using the context manager.
+
+**`SimpleMusic.parse_list_string(s: Optional[str], delimiter: str = ';') -> List[str]`**
+Static utility method to split a string into a list based on a delimiter.
+*   **s**: The string to parse.
+*   **delimiter**: The delimiter character (default `;`).
+*   **Returns**: List of strings, stripped of whitespace.
+
+---
+
+## Processor (`mudio.processor`)
+
+The processor module handles high-level batch processing, including parallel execution, file validation, backups, and error reporting.
+
+### Batch Processing Functions
+
+**`process_files(files: Iterable[Path], ops: FieldOperationsType, targeted_fields: List[str], ...)`**
+The main entry point for processing a batch of files. It automatically chooses between sequential and parallel processing based on the number of files and configuration.
+
+*   **files**: An iterable of `Path` objects to process.
+*   **ops**: A dictionary mapping field names to operation functions (see `mudio.operations`).
+*   **targeted_fields**: A list of fields being modified (used for verification).
+*   **max_workers** (int): Number of threads to use (default: CPU count).
+*   **dry_run** (bool): If `True`, calculates changes but does not write to disk.
+*   **backup_dir** (str): Path to directory for storing backups.
+*   **force** (bool): If `True`, overwrites existing backups/files where necessary.
+*   **verbose** (bool): Enables progress printing.
+*   **filters** (List): A list of filters to apply before processing.
+
+**`process_file(path: str, ops: FieldOperationsType, targeted_fields: List[str], ...)`**
+Processes a single file.
+1.  Validates file (permissions, format).
+2.  Applies filters.
+3.  Computes new tag values using `ops`.
+4.  Creates backup (if requested).
+5.  Writes changes.
+6.  Verifies changes by re-reading the file.
+
+### Validation
+
+**`validate_file(path: Path) -> Tuple[bool, str]`**
+Performs comprehensive checks:
+*   Existence and file type.
+*   Read/Write permissions.
+*   File size (checks for empty files or files exceeding limits).
+*   Format validity (can `mutagen` parse it?).
+
+---
+
+## Operations (`mudio.operations`)
+
+This module defines how field values are transformed. It provides the logic for "Set", "Append", "Regex Replace", etc.
+
+### `FieldOperations` Class
+
+**`FieldOperations.normalize_values(field_name: str, values: List[str]) -> List[str]`**
+Ensures field values are consistent.
+*   **Multi-valued fields** (artist, genre, etc.): Deduplicates values while preserving order (case-insensitive).
+*   **Single-valued fields** (title, date, track): Takes only the first value.
+
+### Operation Factories
+
+These functions return a callable `op(values: List[str]) -> List[str]` that transforms existing values into new ones.
+
+*   **`op_overwrite(field, value, delimiter=';')`**: Replaces existing values. Splits strings on `delimiter` for multi-valued fields.
+*   **`op_append(field, value, delimiter=';')`**:
+    *   Single-valued: Appends string.
+    *   Multi-valued: Adds new item(s) (split by `delimiter`) if not present.
+*   **`op_prefix(field, value)`**: Prepends string to values.
+*   **`op_find_replace(field, find, replace, regex=False, delimiter=';')`**: Performs string substitution. If result contains `delimiter`, splits into multiple values (for multi-valued fields).
+*   **`op_enlist(field, value, delimiter=';')`**: Enlists value(s) (split by `delimiter`) to a multi-valued field list only if it doesn't already exist.
+*   **`op_delist(field, value, delimiter=';')`**: Delists (removes) specific value(s) from a multi-valued field.
+*   **`op_clear(field)`**: Returns `[""]` (empty string), setting the tag to empty but keeping the key.
+*   **`op_delete(field)`**: Returns `[]` (empty list), removing the tag key entirely.
+
+    > **Note**: Behavior of empty values varies by format. ID3 tags may store empty frames; Vorbis comments typically omit empty values.
+
+---
+
+## Utilities (`mudio.utils`)
+
+**`Config`**
+Global configuration settings, loaded from environment variables.
+*   `MUDIO_MAX_WORKERS`: Default thread count.
+*   `MUDIO_BACKUP_DIR`: Default backup location.
+*   `MUDIO_VERBOSE`: Default verbosity.
+
+**`get_file_hash(path: Path)`**
+Calculates SHA-256 hash of a file for verification.
+
+---
+
+## Types and Errors
+
+### Error Hierarchy
+
+The API defines a hierarchy of exceptions for robust error handling:
+
+```python
+class MudioError(Exception): ...
+class ValidationError(MudioError): ...      # Invalid arguments or state
+class FormatError(MudioError): ...          # File format issues
+class PermissionError(MudioError): ...      # Filesystem permission issues
+class VerificationError(MudioError): ...    # Post-write verification failed
+```
+
+### Type Definitions
+
+Common type aliases used in function signatures:
+
+```python
+FieldOperationsType = Dict[str, Callable[[List[str]], List[str]]]
+FieldValuesType = Dict[str, List[str]]
+FilterType = Tuple[str, str, bool]
+```
+
+*   **`FieldOperationsType`**: Maps target field names to transformation functions.
+*   **`FieldValuesType`**: Standard dictionary for metadata (Field -> List of Strings).