audiolibrarian 0.16.2__py3-none-any.whl

audiolibrarian-0.16.2.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: audiolibrarian
+Version: 0.16.2
+Summary: Manage my audio library.
+Project-URL: Repository, https://bitbucket.org/toadstule/audiolibrarian/
+Author-email: Steve Jibson <steve@jibson.com>
+License-File: COPYING
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python
+Requires-Python: ==3.13.*
+Requires-Dist: ansicolors
+Requires-Dist: discid
+Requires-Dist: filelock
+Requires-Dist: fuzzywuzzy
+Requires-Dist: musicbrainzngs
+Requires-Dist: mutagen
+Requires-Dist: pydantic-settings
+Requires-Dist: python-levenshtein
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: xdg-base-dirs
+Description-Content-Type: text/markdown
+
+# audiolibrarian #
+
+## Overview ##
+
+`audiolibrarian` is a powerful command-line tool for managing digital music libraries. It provides a streamlined 
+workflow for ripping, converting, organizing, and tagging audio files with high-quality metadata from MusicBrainz.
+
+### Key Features ###
+
+- **CD Ripping**: Extract audio from CDs with accurate metadata lookup
+- **Audio Conversion**: Convert between multiple audio formats (FLAC, M4A, MP3)
+- **Metadata Management**: Automatically fetch and apply rich metadata from MusicBrainz
+- **File Organization**: Intelligently organize music files into a clean directory structure
+- **Batch Processing**: Handle multiple files and directories efficiently
+- **Genre Management**: Work with MusicBrainz genres and tags
+- **Flexible Configuration**: Customize behavior through config files and environment variables
+
+### Why audiolibrarian? ###
+
+- **Consistent Quality**: Maintains audio quality through the conversion process
+- **Accurate Metadata**: Leverages MusicBrainz for comprehensive music information
+- **Automated Workflow**: Reduces manual work in organizing and tagging music
+- **Scriptable**: Perfect for automating large music library management tasks
+- **Open Source**: Free to use and modify under the GPL-3.0 license
+
+Whether you're digitizing a CD collection, organizing existing music files, or managing a large digital library, 
+`audiolibrarian` provides the tools you need to keep your music collection well-organized and properly tagged.
+
+
+## Installation ##
+
+### External Requirements ###
+
+`audiolibrarian` uses a few command-line tools to run:
+
+* `cd-paranoia`: [cd-paranoia](https://www.gnu.org/software/libcdio/)
+* `eject`: [util-linux](https://github.com/util-linux/util-linux)
+* `faad`: [faad2](https://github.com/knik0/faad2)
+* `fdkaac`: [fdkaac](https://github.com/nu774/fdkaac)
+* `flac`: [flac](https://github.com/xiph/flac)
+* `lame`: [lame](https://lame.sourceforge.io/)
+* `mpg123`: [mpg123](https://www.mpg123.de/)
+* `sndfile-convert`: [libsndfile](https://github.com/libsndfile/libsndfile)
+* `wavegain`: [wavegain](https://rarewares.org/others.php) 
+
+### Install from PyPI ###
+
+`audiolibrarian` is not available on PyPI, but it can be installed from a local PyPI.
+
+```bash
+pip install --user --extra-index-url=https://pypi.example.com/simple audiolibrarian
+```
+
+### Install from Bitbucket ###
+
+```bash
+pip install --user git+https://bitbucket.org/toadstule/audiolibrarian
+```
+
+## Configuration ##
+
+`audiolibrarian` uses a flexible configuration system that supports multiple configuration sources, listed in order of precedence:
+
+1. **Environment Variables** (highest precedence)
+   - Prefix: `AUDIOLIBRARIAN__`
+   - Nested fields: Use `__` as delimiter (e.g., `AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME`)
+   - Example:
+     ```bash
+     # Override library directory
+     export AUDIOLIBRARIAN__LIBRARY_DIR="/mnt/music/library"
+     
+     # Set MusicBrainz credentials
+     export AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME="your_username"
+     export AUDIOLIBRARIAN__MUSICBRAINZ__PASSWORD="your_password"
+     ```
+
+2. **YAML Configuration File**
+   - Location: `~/.config/audiolibrarian/config.yaml` (or `$XDG_CONFIG_HOME/audiolibrarian/config.yaml` if set)
+   - Example:
+     ```yaml
+     # Base directory for your music library
+     library_dir: "~/music/library"
+     
+     # Cache and working directory
+     work_dir: "~/.cache/audiolibrarian"
+     
+     # CD/DVD device path (use null for default device)
+     discid_device: null
+     
+     # Audio normalization settings
+     normalize_gain: 5  # dB gain for normalization
+     normalize_preset: "radio"  # "album" or "radio"
+     
+     # MusicBrainz API settings (optional)
+     musicbrainz:
+       username: "your_username"  # For personal genre preferences
+       password: "your_password"  # Will be stored securely
+       rate_limit: 1.5  # Seconds between API requests
+     ```
+
+3. **Default Values** (lowest precedence)
+   - Built-in defaults from the application
+
+### Available Settings ###
+
+| Setting                  | Default                          | Description                               |
+|--------------------------|----------------------------------|-------------------------------------------|
+| `library_dir`            | `library` (in the current dir)   | Directory for storing audio files         |
+| `work_dir`               | `$XDG_CACHE_HOME/audiolibrarian` | Directory for temporary files             |
+| `discid_device`          | `null`                           | CD device path (null for default device)  |
+| `normalize_gain`         | `5`                              | Normalization gain in dB                  |
+| `normalize_preset`       | `"radio"`                        | Normalization preset ("album" or "radio") |
+| `musicbrainz.username`   | (not set)                        | MusicBrainz username                      |
+| `musicbrainz.password`   | (not set)                        | MusicBrainz password                      |
+| `musicbrainz.rate_limit` | `1.5`                            | Seconds between requests                  |
+
+> **Note**: The `musicbrainz` section is optional but recommended for accessing personal genre preferences on [MusicBrainz](https://musicbrainz.org/).
+
+## Usage ##
+
+### Basic Commands ###
+
+```bash
+# Rip audio from a CD
+audiolibrarian rip
+
+# Convert audio files
+audiolibrarian convert /path/to/audio/files
+
+# Create or update manifest files
+audiolibrarian manifest /path/to/audio/files
+
+# Reconvert files from existing source
+audiolibrarian reconvert /path/to/source/directories
+
+# Rename files based on tags
+audiolibrarian rename /path/to/audio/directories
+
+# Manage MusicBrainz genres
+audiolibrarian genre /path/to/audio/directories --tag  # Update tags with MB genres
+
+# Show help for all commands
+audiolibrarian --help
+```
+
+### Combining Configuration Sources ###
+
+Configuration sources are combined with the following precedence (highest to lowest):
+1. Environment variables
+2. YAML configuration file
+3. Default values
+
+For example, with this `config.yaml`:
+
+```yaml
+# config.yaml
+library_dir: /media/music/library
+normalize_gain: 5.0
+```
+
+And this environment variable:
+```bash
+export AUDIOLIBRARIAN__NORMALIZE_GAIN="8.0"
+```
+
+The effective value of `normalize_gain` will be `8.0` (from the environment variable), while `library_dir` will be set to `/media/music/library` from the YAML file.
+
+### Advanced Usage ###
+
+1. **Ripping CDs**
+
+```bash
+# Basic CD rip
+audiolibrarian rip
+
+# Specify artist and album
+audiolibrarian rip --artist "Artist Name" --album "Album Name"
+
+# Specify MusicBrainz release ID (for better metadata)
+audiolibrarian rip --mb-release-id "12345678-1234-1234-1234-123456789012"
+
+# Specify disc number for multi-disc sets
+audiolibrarian rip --disc "1/2"  # First disc of two
+```
+
+2. **Converting Audio Files**
+
+```bash
+# Convert with specific artist and album
+audiolibrarian convert --artist "Artist Name" --album "Album Name" /path/to/audio/files
+
+# Convert with MusicBrainz release ID
+audiolibrarian convert --mb-release-id "12345678-1234-1234-1234-123456789012" /path/to/audio/files
+
+# Convert multi-disc release
+audiolibrarian convert --disc "1/2" /path/to/disc1/files
+```
+
+2. **Working with Manifests**
+
+```bash
+# Create manifest for existing files
+audiolibrarian manifest /path/to/audio/files
+
+# Specify CD as source
+audiolibrarian manifest --cd /path/to/audio/files
+
+# Specify MusicBrainz artist and release IDs
+audiolibrarian manifest --mb-artist-id "12345678-1234-1234-1234-123456789012" \
+    --mb-release-id "12345678-1234-1234-1234-123456789012" /path/to/audio/files
+```
+
+3. **Reconverting Files**
+
+```bash
+# Reconvert all files in directory
+audiolibrarian reconvert /path/to/source/directories
+
+# Reconvert with dry run (no changes)
+audiolibrarian reconvert --dry-run /path/to/source/directories
+```
+
+4. **Renaming Files**
+
+```bash
+# Rename files based on tags
+audiolibrarian rename /path/to/audio/directories
+
+# Preview renames without making changes
+audiolibrarian rename --dry-run /path/to/audio/directories
+```
+
+5. **Using Different Normalization Presets**
+
+```bash
+# Use radio normalization preset (default)
+export AUDIOLIBRARIAN__NORMALIZE_PRESET="radio"
+
+# Use album normalization preset
+export AUDIOLIBRARIAN__NORMALIZE_PRESET="album"
+```
+
+### Troubleshooting ###
+
+1. **Increasing Verbosity**
+
+```bash
+# Show more detailed output
+audiolibrarian --log-level INFO cd
+
+# Show debug information
+audiolibrarian --log-level DEBUG cd
+```
+
+2. **Checking Dependencies**
+
+```bash
+# Verify all required tools are installed
+audiolibrarian --log-level DEBUG cd
+```
+
+3. **MusicBrainz Issues**
+
+If you encounter MusicBrainz-related errors:
+
+1. Verify your credentials are correct
+2. Check your internet connection
+3. Use the debug log level to get more information
+4. Increase the rate limit if you're hitting rate limits
+
+```bash
+export AUDIOLIBRARIAN__MUSICBRAINZ__RATE_LIMIT="2.0"
+```
+
+### Directory Structure ###
+
+`audiolibrarian` organizes files in the following structure:
+
+1. **Source files** (original audio files):
+   ```
+   library/source/
+   └── Artist/
+       └── YYYY__Album/
+           ├── 01__Track_Title.flac
+           ├── 02__Another_Track.flac
+           └── Manifest.yaml
+   ```
+
+2. **Processed audio files** (organized by format):
+   ```
+   library/
+   ├── flac/
+   │   └── Artist/
+   │       └── YYYY__Album/
+   │           ├── 01__Track_Title.flac
+   │           └── 02__Another_Track.flac
+   ├── m4a/
+   │   └── Artist/
+   │       └── YYYY__Album/
+   │           ├── 01__Track_Title.m4a
+   │           └── 02__Another_Track.m4a
+   └── mp3/
+       └── Artist/
+           └── YYYY__Album/
+               ├── 01__Track_Title.mp3
+               └── 02__Another_Track.mp3
+   ```
+
+Each track filename follows the format: `track_number__track_name.extension` (e.g., `01__Call_to_Arms.flac`).

audiolibrarian-0.16.2.dist-info/RECORD

@@ -0,0 +1,28 @@
+audiolibrarian/__init__.py,sha256=NAyvdXQNHBEMka12z9FEosPLDRdFPkrB6aPPdZ2MweM,787
+audiolibrarian/audiosource.py,sha256=EtoSQb6R2zfHUwxiR9ZqGwjxrX2mTB5gPpmKangps4s,8573
+audiolibrarian/base.py,sha256=54s_NacDvyGpvc_uOJO5apmQin4HKUGfPrlw0XFiJoI,19428
+audiolibrarian/cli.py,sha256=azX49RO2t4q8qyUJ9WTOlDqUO13p17mq0wNmEdl6QGw,4211
+audiolibrarian/commands.py,sha256=8R9aagOaaLE798lGYPWknW-NiIHkxEbQbiM43RZrPTU,11166
+audiolibrarian/genremanager.py,sha256=ZciuJb3GoaM31h33_khowNg8iv4MVGkjJM-beijSF3k,7357
+audiolibrarian/musicbrainz.py,sha256=DAodaLVySqq6nSbGCLfUktXSAm95OfPhkOXyyexMj6w,19312
+audiolibrarian/output.py,sha256=JHuttwEMEzUxty7P8e2jaL6702q52fTWAdZEgb85bxQ,1702
+audiolibrarian/records.py,sha256=BovHwNVd0nTTwQPYkhOAOIVASWz9l47j6cGdXAx5VjM,7929
+audiolibrarian/settings.py,sha256=qKQ9JYfKr2k_JceWfYPiMlpBKylujCQI_2pmxWpsGFo,2550
+audiolibrarian/sh.py,sha256=tVTuKXlMH738jTopjnMWqidTaH02_EyHau3q9kQ6mYE,1912
+audiolibrarian/text.py,sha256=05q_E22w9hMsy01_A5XlU2pqQIMlM5RF4DXzYuLCcYo,4026
+audiolibrarian/audiofile/__init__.py,sha256=BRjf4iu_cogB3A5oIVE4BjIgUGCH0dAzPG4A_48rOUM,894
+audiolibrarian/audiofile/audiofile.py,sha256=IhTIzFzYeKfJmsgOG7bN62KWD06ehOGRoVv3eCf-_vw,4352
+audiolibrarian/audiofile/tags.py,sha256=42oyqHZ6jRokmQskD2p53NMgKxJR7xkidXImOhUzszY,1785
+audiolibrarian/audiofile/formats/__init__.py,sha256=ZV5urTtQQ4ZX_K2s9qFsSzDunvdQaQ43K7CE-BPPtEo,25
+audiolibrarian/audiofile/formats/flac.py,sha256=3MfzdgnAqTVSbAraAVde2BSHwdAyi-fKkc55OvuRNSc,9708
+audiolibrarian/audiofile/formats/m4a.py,sha256=S0aFZxMzgwpzkwYE2D_K_US0Dnh0objK21ph1S_8rJk,10552
+audiolibrarian/audiofile/formats/mp3.py,sha256=ipuanK7CIYSk9LqW0AvAgKAUZeU9ecwK0uZf2AhAGXo,12881
+picard_src/README.md,sha256=TTnzIGmZ8_G11G1VCz5DHdlidIrtkGFYxWFooyTKcbI,403
+picard_src/__init__.py,sha256=acu0-oac_qfEgiB0rw0RvuL---O15-rOckWboVMxWtM,198
+picard_src/textencoding.py,sha256=0MRHFwhqEwauQbjTTz6gpgzo6YH1VDPfdJqQoCWHtjM,26234
+audiolibrarian-0.16.2.dist-info/METADATA,sha256=EIrFJiGcWJVgqQcCCO8dwKDtiWU52kEA3Bp2I_l5WP8,10756
+audiolibrarian-0.16.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+audiolibrarian-0.16.2.dist-info/entry_points.txt,sha256=reubnr_SGbTTDXji8j7z8aTmIL0AEQKVSLcnmFG3YYY,59
+audiolibrarian-0.16.2.dist-info/licenses/COPYING,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
+audiolibrarian-0.16.2.dist-info/licenses/LICENSE,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
+audiolibrarian-0.16.2.dist-info/RECORD,,

audiolibrarian-0.16.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

audiolibrarian-0.16.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audiolibrarian = audiolibrarian:cli.main