audiolibrarian 0.16.4__tar.gz → 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.gitignore +13 -0
  2. audiolibrarian-0.17.0/.readthedocs.yaml +30 -0
  3. audiolibrarian-0.17.0/CONTRIBUTING.md +3 -0
  4. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/Makefile +14 -1
  5. audiolibrarian-0.17.0/PKG-INFO +74 -0
  6. audiolibrarian-0.17.0/README.md +48 -0
  7. audiolibrarian-0.17.0/docs/api/audiolibrarian.md +56 -0
  8. audiolibrarian-0.17.0/docs/development/contributing.md +108 -0
  9. audiolibrarian-0.17.0/docs/index.md +36 -0
  10. audiolibrarian-0.17.0/docs/user-guide/advanced.md +15 -0
  11. audiolibrarian-0.17.0/docs/user-guide/changelog.md +17 -0
  12. audiolibrarian-0.17.0/docs/user-guide/configuration.md +95 -0
  13. audiolibrarian-0.17.0/docs/user-guide/getting-started.md +151 -0
  14. audiolibrarian-0.17.0/docs/user-guide/installation.md +104 -0
  15. audiolibrarian-0.17.0/mkdocs.yml +90 -0
  16. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/pyproject.toml +6 -1
  17. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/scripts/update_links.sh +11 -12
  18. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/__init__.py +2 -2
  19. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/__init__.py +1 -2
  20. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/audiofile.py +1 -1
  21. audiolibrarian-0.17.0/src/audiolibrarian/audiofile/formats/__init__.py +17 -0
  22. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/flac.py +1 -1
  23. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/m4a.py +1 -1
  24. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/mp3.py +1 -1
  25. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/tags.py +1 -1
  26. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiosource.py +3 -3
  27. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/base.py +86 -39
  28. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/cli.py +1 -2
  29. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/commands.py +10 -10
  30. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/genremanager.py +4 -4
  31. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/musicbrainz.py +2 -2
  32. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/output.py +1 -1
  33. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/records.py +1 -1
  34. audiolibrarian-0.17.0/src/audiolibrarian/settings.py +114 -0
  35. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/sh.py +1 -1
  36. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/text.py +1 -1
  37. audiolibrarian-0.17.0/tools/__init__.py +17 -0
  38. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/tools/diff.py +1 -1
  39. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/tools/show_tags.py +1 -1
  40. audiolibrarian-0.17.0/uv.lock +1141 -0
  41. audiolibrarian-0.16.4/CONTRIBUTING.md +0 -10
  42. audiolibrarian-0.16.4/PKG-INFO +0 -333
  43. audiolibrarian-0.16.4/README.md +0 -308
  44. audiolibrarian-0.16.4/src/audiolibrarian/audiofile/formats/__init__.py +0 -1
  45. audiolibrarian-0.16.4/src/audiolibrarian/settings.py +0 -79
  46. audiolibrarian-0.16.4/tools/__init__.py +0 -1
  47. audiolibrarian-0.16.4/uv.lock +0 -646
  48. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.github/workflows/main.yml +0 -0
  49. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.python-version +0 -0
  50. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/COPYING +0 -0
  51. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/LICENSE +0 -0
  52. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/git_hooks/README.md +0 -0
  53. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/git_hooks/pre-push +0 -0
  54. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/README.md +0 -0
  55. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/__init__.py +0 -0
  56. {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/textencoding.py +0 -0
@@ -16,3 +16,16 @@ workdir/
16
16
  venv/
17
17
 
18
18
  NOTES.md
19
+
20
+ # MkDocs build output
21
+ site/
22
+ .cache/
23
+
24
+ # Local development
25
+ .mkdocs/
26
+
27
+ # IDE
28
+ .idea/
29
+ .vscode/
30
+ *.swp
31
+ *~
@@ -0,0 +1,30 @@
1
+ # .readthedocs.yaml
2
+ # Read the Docs configuration file
3
+ # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4
+
5
+ version: 2
6
+
7
+ # Build settings
8
+ build:
9
+ os: ubuntu-22.04
10
+ tools:
11
+ python: "3.13"
12
+ jobs:
13
+ pre_create_environment:
14
+ - asdf plugin add uv
15
+ - asdf install uv latest
16
+ - asdf global uv latest
17
+ create_environment:
18
+ - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
19
+ install:
20
+ - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group dev
21
+
22
+ # MkDocs configuration
23
+ mkdocs:
24
+ configuration: mkdocs.yml
25
+ fail_on_warning: false
26
+
27
+ # Build PDF and ePub output
28
+ formats:
29
+ - pdf
30
+ - epub
@@ -0,0 +1,3 @@
1
+ # Contributing to audiolibrarian
2
+
3
+ For detailed contribution guidelines, please see our [Contributing Guide](docs/development/contributing.md).
@@ -44,11 +44,24 @@ clean: ## Clean up.
44
44
  @rm -rf htmlcov .coverage
45
45
  @rm -rf .pytype
46
46
  @rm -rf .ruff_cache .mypy_cache
47
+ @rm -rf site .cache .mkdocs
47
48
  @$(UV) clean
48
49
  @rm -rf dist
49
50
 
51
+ .PHONY: docs
52
+ docs: docs-build ## Build and serve the documentation
53
+ @mkdocs serve
54
+
55
+ .PHONY: docs-build
56
+ docs-build: dep ## Build the documentation
57
+ @mkdocs build --clean
58
+
59
+ .PHONY: docs-deploy
60
+ docs-deploy: dep ## Deploy the documentation to GitHub Pages
61
+ @mkdocs gh-deploy --force
62
+
50
63
  .PHONY: dep
51
- dep: ## Install dependencies.
64
+ dep: uv.lock ## Install dependencies.
52
65
  @$(UV) sync --locked --all-extras --dev
53
66
 
54
67
  .PHONY: dep-upgrade
@@ -0,0 +1,74 @@
1
+ Metadata-Version: 2.4
2
+ Name: audiolibrarian
3
+ Version: 0.17.0
4
+ Summary: Manage my audio library.
5
+ Project-URL: Repository, https://github.com/toadstule/audiolibrarian
6
+ Author-email: Steve Jibson <steve@jibson.com>
7
+ License-File: COPYING
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
11
+ Classifier: Programming Language :: Python
12
+ Requires-Python: <3.14,>=3.12
13
+ Requires-Dist: ansicolors
14
+ Requires-Dist: discid
15
+ Requires-Dist: ffmpeg-normalize
16
+ Requires-Dist: filelock
17
+ Requires-Dist: fuzzywuzzy
18
+ Requires-Dist: musicbrainzngs
19
+ Requires-Dist: mutagen
20
+ Requires-Dist: pydantic-settings
21
+ Requires-Dist: python-levenshtein
22
+ Requires-Dist: pyyaml
23
+ Requires-Dist: requests
24
+ Requires-Dist: xdg-base-dirs
25
+ Description-Content-Type: text/markdown
26
+
27
+ # audiolibrarian
28
+
29
+ [![PyPI](https://img.shields.io/pypi/v/audiolibrarian)](https://pypi.org/project/audiolibrarian/)
30
+ [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
31
+ [![Documentation Status](https://readthedocs.org/projects/audiolibrarian/badge/?version=latest)](https://audiolibrarian.readthedocs.io/)
32
+
33
+ `audiolibrarian` is a command-line tool for ripping audio from CDs (or taking
34
+ high-quality audio from local files), tagging them with comprehensive metadata from MusicBrainz,
35
+ converting them to multiple formats, and organizing them in a clean directory structure.
36
+
37
+ ## Features
38
+
39
+ - **CD Ripping**: Extract audio from CDs with accurate metadata lookup
40
+ - **Audio Conversion**: Convert between multiple audio formats (FLAC, M4A, MP3)
41
+ - **Metadata Management**: Automatically fetch and apply rich metadata from MusicBrainz
42
+ - **File Organization**: Intelligently organize music files into a clean directory structure
43
+ - **Batch Processing**: Handle multiple files and directories efficiently
44
+
45
+ ## Basic Usage
46
+
47
+ ```bash
48
+ # Rip audio from a CD
49
+ audiolibrarian rip
50
+
51
+ # Convert audio files
52
+ audiolibrarian convert /path/to/audio/files
53
+
54
+ # Get help
55
+ audiolibrarian --help
56
+ ```
57
+
58
+ ## Documentation
59
+
60
+ For complete documentation, including installation instructions, configuration, and advanced usage, visit:
61
+
62
+ [https://audiolibrarian.readthedocs.io/](https://audiolibrarian.readthedocs.io/)
63
+
64
+ ## License
65
+
66
+ This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
67
+
68
+ ## Contributing
69
+
70
+ Contributions are welcome! Please see our [contributing guide](CONTRIBUTING.md) for details.
71
+
72
+ ## Support
73
+
74
+ For support, please [open an issue](https://github.com/toadstule/audiolibrarian/issues) on GitHub.
@@ -0,0 +1,48 @@
1
+ # audiolibrarian
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/audiolibrarian)](https://pypi.org/project/audiolibrarian/)
4
+ [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
5
+ [![Documentation Status](https://readthedocs.org/projects/audiolibrarian/badge/?version=latest)](https://audiolibrarian.readthedocs.io/)
6
+
7
+ `audiolibrarian` is a command-line tool for ripping audio from CDs (or taking
8
+ high-quality audio from local files), tagging them with comprehensive metadata from MusicBrainz,
9
+ converting them to multiple formats, and organizing them in a clean directory structure.
10
+
11
+ ## Features
12
+
13
+ - **CD Ripping**: Extract audio from CDs with accurate metadata lookup
14
+ - **Audio Conversion**: Convert between multiple audio formats (FLAC, M4A, MP3)
15
+ - **Metadata Management**: Automatically fetch and apply rich metadata from MusicBrainz
16
+ - **File Organization**: Intelligently organize music files into a clean directory structure
17
+ - **Batch Processing**: Handle multiple files and directories efficiently
18
+
19
+ ## Basic Usage
20
+
21
+ ```bash
22
+ # Rip audio from a CD
23
+ audiolibrarian rip
24
+
25
+ # Convert audio files
26
+ audiolibrarian convert /path/to/audio/files
27
+
28
+ # Get help
29
+ audiolibrarian --help
30
+ ```
31
+
32
+ ## Documentation
33
+
34
+ For complete documentation, including installation instructions, configuration, and advanced usage, visit:
35
+
36
+ [https://audiolibrarian.readthedocs.io/](https://audiolibrarian.readthedocs.io/)
37
+
38
+ ## License
39
+
40
+ This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
41
+
42
+ ## Contributing
43
+
44
+ Contributions are welcome! Please see our [contributing guide](CONTRIBUTING.md) for details.
45
+
46
+ ## Support
47
+
48
+ For support, please [open an issue](https://github.com/toadstule/audiolibrarian/issues) on GitHub.
@@ -0,0 +1,56 @@
1
+ # API Reference
2
+
3
+ ::: audiolibrarian
4
+ options:
5
+ show_root_heading: true
6
+ show_root_full_path: false
7
+ show_root_members_full_path: false
8
+ show_object_full_path: false
9
+ show_category_heading: false
10
+ show_if_no_docstring: true
11
+ separate_signature: true
12
+ merge_init_into_class: true
13
+ heading_level: 2
14
+
15
+ ## Modules
16
+
17
+ ### Core Modules
18
+
19
+ - `audiolibrarian.cli` - Command-line interface implementation
20
+ - `audiolibrarian.config` - Configuration management
21
+ - `audiolibrarian.audio` - Audio file handling and processing
22
+ - `audiolibrarian.metadata` - Metadata management and MusicBrainz integration
23
+ - `audiolibrarian.organize` - File organization and renaming
24
+ - `audiolibrarian.utils` - Utility functions and helpers
25
+
26
+ ## Examples
27
+
28
+ ### Basic Usage
29
+
30
+ ```python
31
+ from audiolibrarian import AudioLibrarian
32
+
33
+ # Initialize with custom config
34
+ al = AudioLibrarian(config_path="custom_config.yaml")
35
+
36
+ # Scan a directory
37
+ al.scan("/path/to/music")
38
+
39
+
40
+ # Organize files
41
+ al.organize("/source/path", "/destination/path")
42
+ ```
43
+
44
+ ### Working with Metadata
45
+
46
+ ```python
47
+ from audiolibrarian.metadata import get_metadata
48
+
49
+ # Get metadata from MusicBrainz
50
+ track_info = get_metadata(artist="Artist Name", title="Track Title")
51
+ print(f"Found track: {track_info.title} from {track_info.album}")
52
+ ```
53
+
54
+ ## Contributing
55
+
56
+ If you want to contribute to the development of audiolibrarian, please read our [contributing guidelines](../development/contributing.md).
@@ -0,0 +1,108 @@
1
+ # Contributing to audiolibrarian
2
+
3
+ We welcome contributions from the community! Whether it's bug reports, feature requests, or code
4
+ contributions, we appreciate your help in making audiolibrarian better.
5
+
6
+ ## How to Contribute
7
+
8
+ 1. **Fork** the repository on GitHub
9
+ 2. **Clone** your fork locally
10
+ 3. **Create a branch** for your changes
11
+ 4. **Commit** your changes
12
+ 5. **Push** to your fork
13
+ 6. Submit a **Pull Request**
14
+
15
+ ## Development Setup
16
+
17
+ 1. Clone the repository:
18
+
19
+ ```bash
20
+ git clone https://github.com/toadstule/audiolibrarian.git
21
+ cd audiolibrarian
22
+ ```
23
+
24
+ 2. Install dependencies using the Makefile:
25
+
26
+ ```bash
27
+ make dep
28
+ ```
29
+
30
+ This will install all required dependencies in a virtual environment.
31
+
32
+ ## Development Workflow
33
+
34
+ ### Running Tests
35
+
36
+ Run the test suite:
37
+
38
+ ```bash
39
+ make test
40
+ ```
41
+
42
+ For tests with coverage report:
43
+
44
+ ```bash
45
+ make test-coverage
46
+ ```
47
+
48
+ ### Code Style and Linting
49
+
50
+ We use `ruff` for code formatting and linting. The Makefile provides these helpful commands:
51
+
52
+ ```bash
53
+ make format # Format the code and sort imports
54
+ make lint # Run all linters and type checking
55
+ ```
56
+
57
+ ### Building Documentation
58
+
59
+ To build and serve the documentation locally:
60
+
61
+ ```bash
62
+ make docs
63
+ ```
64
+
65
+ This will start a local server at `http://127.0.0.1:8000` where you can preview the documentation.
66
+
67
+ ### Building the Package
68
+
69
+ To build the package:
70
+
71
+ ```bash
72
+ make build
73
+ ```
74
+
75
+ ### Updating Dependencies
76
+
77
+ To upgrade all dependencies:
78
+
79
+ ```bash
80
+ make dep-upgrade
81
+ ```
82
+
83
+ ## Reporting Issues
84
+
85
+ When reporting issues, please include:
86
+
87
+ - A clear description of the problem
88
+ - Steps to reproduce the issue
89
+ - Expected behavior
90
+ - Actual behavior
91
+ - Your operating system and Python version
92
+ - Any relevant error messages
93
+
94
+ ## Feature Requests
95
+
96
+ We welcome feature requests! Please open an issue and describe:
97
+
98
+ - The feature you'd like to see
99
+ - Why this feature would be useful
100
+ - Any suggestions for implementation
101
+
102
+ ## Available Make Commands
103
+
104
+ For a complete list of available commands, run:
105
+
106
+ ```bash
107
+ make help
108
+ ```
@@ -0,0 +1,36 @@
1
+ # Welcome to audiolibrarian
2
+
3
+ `audiolibrarian` is a command-line tool for ripping audio from CDs (or taking
4
+ high-quality audio from local files), tagging them with comprehensive metadata from [MusicBrainz][],
5
+ converting them to multiple formats, and organizing them in a clean directory structure.
6
+
7
+ ## Features
8
+
9
+ - 📀 **CD Ripping**: Extract audio from CDs with accurate metadata lookup.
10
+ - 🔄 **Audio Conversion**: Output multiple audio formats (FLAC, M4A, MP3).
11
+ - 📋 **Metadata Management**: Automatically fetch and apply rich metadata from [MusicBrainz][].
12
+ - 📁 **File Organization**: Intelligently organize music files into a clean directory structure.
13
+ - ⚙️ **Batch Processing**: Handle multiple files and directories efficiently.
14
+ - 🎵 **Genre Management**: Work with [MusicBrainz][] genres and tags.
15
+ - 🔧 **Flexible Configuration**: Customize behavior through config files and environment variables.
16
+
17
+ ## Why audiolibrarian?
18
+
19
+ - **Consistent Quality**: Maintains audio quality through the conversion process.
20
+ - **Accurate Metadata**: Leverages [MusicBrainz][] for comprehensive music information.
21
+ - **Automated Workflow**: Reduces manual work in organizing and tagging music.
22
+ - **Open Source**: Free to use and modify under the GPL-3.0 license.
23
+
24
+ ## Quick Start
25
+
26
+ 1. [Install audiolibrarian](user-guide/installation.md).
27
+ 2. [Get started](user-guide/getting-started.md) with basic commands.
28
+ 3. Explore the [API Reference](api/audiolibrarian.md) for advanced usage.
29
+
30
+ ## Get Involved
31
+
32
+ - Found a bug? [Open an issue](https://github.com/toadstule/audiolibrarian/issues).
33
+ - Want to contribute? Read our [contributing guide](development/contributing.md).
34
+ - Check out the [changelog](user-guide/changelog.md) to see what's new.
35
+
36
+ [MusicBrainz]: https://musicbrainz.org
@@ -0,0 +1,15 @@
1
+ # Advanced Topics
2
+
3
+ ## The Source Directory
4
+
5
+ The `source` directory contains a lossless copy of the original source files, with no
6
+ normalization. The source files are tagged with MusicBrainz tags to make re-converting them
7
+ easier.
8
+
9
+ For example, if you're not happy with the normalization level performed by `audiolibrarian`,
10
+ you can update the normalization settings, then re-convert all the files in your library by
11
+ running `audiolibrarian reconvert` on the `source` directory.
12
+
13
+ When backing up your library, you may choose to only back up the `source` directory. The rest
14
+ of your files can be re-generated from the `source` directory using `audiolibrarian reconvert`,
15
+ after you've restored from your backup.
@@ -0,0 +1,17 @@
1
+ # Change Log
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.17.0] - 2025-06-22
9
+
10
+ ### Added
11
+
12
+ - Support for `ffmpeg-normalize` for normalization (optional)
13
+
14
+ ### Changed
15
+
16
+ - Configuration options for normalization selection
17
+ - Configuration options for `ffmpeg-normalize`
@@ -0,0 +1,95 @@
1
+ # Configuration
2
+
3
+ `audiolibrarian` uses a flexible configuration system that supports multiple configuration sources,
4
+ listed in order of precedence:
5
+
6
+ ## Configuration Sources
7
+
8
+ ### 1. Environment Variables (highest precedence)
9
+
10
+ - **Prefix**: `AUDIOLIBRARIAN__`
11
+ - **Nested fields**: Use `__` as delimiter (e.g., `AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME`)
12
+ - **Example**:
13
+
14
+ ```bash
15
+ # Override library directory (library_dir)
16
+ export AUDIOLIBRARIAN__LIBRARY_DIR="/mnt/music/library"
17
+
18
+ # Set MusicBrainz credentials (musicbrainz.username and musicbrainz.password)
19
+ export AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME="your_username"
20
+ export AUDIOLIBRARIAN__MUSICBRAINZ__PASSWORD="your_password"
21
+ ```
22
+
23
+ ### 2. YAML Configuration File (medium precedence)
24
+
25
+ - **Default location**: `~/.config/audiolibrarian/config.yaml`
26
+ - **Example**:
27
+
28
+ ```yaml
29
+ # Base directory for your music library
30
+ library_dir: "~/music/library"
31
+
32
+ # Cache and working directory
33
+ work_dir: "~/.cache/audiolibrarian"
34
+
35
+ # CD/DVD device path (use null for default device)
36
+ discid_device: null
37
+
38
+ # Audio normalization settings
39
+ normalize:
40
+ normalizer: "auto" # "auto", "wavegain", "ffmpeg", or "none"
41
+ ffmpeg:
42
+ target_level: -13 # Target LUFS level for ffmpeg normalization
43
+ wavegain:
44
+ gain: 5 # dB gain for wavegain normalization (0-10)
45
+ preset: "radio" # "album" or "radio"
46
+
47
+ # MusicBrainz API settings (optional)
48
+ musicbrainz:
49
+ username: "your_username" # For personal genre preferences
50
+ password: "your_password" # Will be stored securely
51
+ rate_limit: 1.5 # Seconds between API requests
52
+ ```
53
+
54
+ ### 3. Default Values (lowest precedence)
55
+
56
+ - Built-in defaults from the application
57
+
58
+ ## Available Settings
59
+
60
+ | Setting | Default | Description |
61
+ |---------------------------------|------------------|-------------------------------------------|
62
+ | `library_dir` | `./library` | Directory for storing audio files |
63
+ | `work_dir` | (see below)[^wd] | Directory for temporary files |
64
+ | `discid_device` | `null` | CD device path (null for default device) |
65
+ | `normalize.normalizer` | `"auto"` | "auto", "wavegain", "ffmpeg", or "none" |
66
+ | `normalize.ffmpeg.target_level` | `-13` | Target LUFS level (ffmpeg) |
67
+ | `normalize.wavegain.gain` | `5` | Normalization gain in dB (0-10, wavegain) |
68
+ | `normalize.wavegain.preset` | `"radio"` | "album" or "radio" (wavegain) |
69
+ | `musicbrainz.username` | (not set) | MusicBrainz username[^mb] |
70
+ | `musicbrainz.password` | (not set) | MusicBrainz password[^mb] |
71
+ | `musicbrainz.rate_limit` | `1.5` | Seconds between requests |
72
+
73
+ [^wd]: The `work_dir` default is `$XDG_CACHE_HOME/audiolibrarian`, which defaults
74
+ to `~/.cache/audiolibrarian` on Linux and macOS.
75
+
76
+ [^mb]: The `musicbrainz` username and password are optional but recommended for accessing personal genre
77
+ preferences on [MusicBrainz](https://musicbrainz.org/).
78
+
79
+ ## Audio Normalization
80
+
81
+ Audio normalization ensures consistent volume levels across tracks. The following options are available:
82
+
83
+ - `auto` (default): Automatically selects the best available normalizer (prefers wavegain)
84
+ - `wavegain`: Uses the `wavegain` command-line tool (recommended for better album normalization)
85
+ - `ffmpeg`: Uses the `ffmpeg-normalize` Python package
86
+ - `none`: Skips normalization entirely
87
+
88
+ ### Wavegain Settings
89
+
90
+ - `gain`: Adjusts the target volume level (in dB, typically 0-10)
91
+ - `preset`: "album" (loudness normalization) or "radio" (peak normalization)
92
+
93
+ ### FFmpeg Settings
94
+
95
+ - `target_level`: Target LUFS level (typically between -16 and -12)
@@ -0,0 +1,151 @@
1
+ # Getting Started
2
+
3
+ This guide will help you get up and running with audiolibrarian.
4
+
5
+ ## Directory Structure
6
+
7
+ `audiolibrarian` organizes files in the following structure:
8
+
9
+ **Processed audio files** (organized by format):
10
+
11
+ ```text
12
+ library/
13
+ ├── flac/
14
+ │ └── Artist/
15
+ │ └── YYYY__Album/
16
+ │ ├── 01__Track_Title.flac
17
+ │ └── 02__Another_Track.flac
18
+ ├── m4a/
19
+ │ └── Artist/
20
+ │ └── YYYY__Album/
21
+ │ ├── 01__Track_Title.m4a
22
+ │ └── 02__Another_Track.m4a
23
+ ├── mp3/
24
+ │ └── Artist/
25
+ │ └── YYYY__Album/
26
+ │ ├── 01__Track_Title.mp3
27
+ │ └── 02__Another_Track.mp3
28
+ └── source/
29
+ └── Artist/
30
+ └── YYYY__Album/
31
+ ├── 01__Track_Title.flac
32
+ ├── 02__Another_Track.flac
33
+ └── Manifest.yaml
34
+ ```
35
+
36
+ > NOTE: the `source` directory is explained in
37
+ > [The Source Directory](./advanced.md#the-source-directory) section of
38
+ > [Advanced Topics](./advanced.md).
39
+
40
+ ## Basic Commands
41
+
42
+ ### View Help
43
+
44
+ ```bash
45
+ audiolibrarian --help
46
+ ```
47
+
48
+ ### Add Audio from a CD
49
+
50
+ ```bash
51
+ audiolibrarian rip
52
+ ```
53
+
54
+ This will:
55
+
56
+ 1. Read the CD
57
+ 2. Look up metadata on MusicBrainz
58
+ 3. Show a preview of the rip
59
+ 4. Prompt for confirmation
60
+ 5. Rip the CD and add audio to your library
61
+
62
+ **Sample output:**
63
+
64
+ ```text
65
+ $ audiolibrarian rip
66
+
67
+ Gathering search information...
68
+ Finding MusicBrainz release information...
69
+ ╔══════════════════════════════════════════════════════════════════════════════════╗
70
+ ║ Album: I-Empire ║
71
+ ║ Artist(s): Angels & Airwaves ║
72
+ ║ MB Release: https://musicbrainz.org/release/374cb6ec-8d62-456f-aa9b-55fb4f85d22d ║
73
+ ║ Disc: 1 of 1 ║
74
+ ╠══════════════╤═══════════════════════╤═══════════════════════════════════════════╣
75
+ ║ Source │ Destination │ Title ║
76
+ ╠══════════════╪═══════════════════════╪═══════════════════════════════════════════╣
77
+ ║ track01.cdda │ 01__Call_to_Arms │ 01: Call to Arms ║
78
+ ║ track02.cdda │ 02__Everythings_Magic │ 02: Everything's Magic ║
79
+ ║ track03.cdda │ 03__Breathe │ 03: Breathe ║
80
+ ║ track04.cdda │ 04__Love_Like_Rockets │ 04: Love Like Rockets ║
81
+ ║ track05.cdda │ 05__Sirens │ 05: Sirens ║
82
+ ║ track06.cdda │ 06__Secret_Crowds │ 06: Secret Crowds ║
83
+ ║ track07.cdda │ 07__Star_of_Bethlehem │ 07: Star of Bethlehem ║
84
+ ║ track08.cdda │ 08__True_Love │ 08: True Love ║
85
+ ║ track09.cdda │ 09__Lifeline │ 09: Lifeline ║
86
+ ║ track10.cdda │ 10__Jumping_Rooftops │ 10: Jumping Rooftops ║
87
+ ║ track11.cdda │ 11__Rite_of_Spring │ 11: Rite of Spring ║
88
+ ║ track12.cdda │ 12__Heaven │ 12: Heaven ║
89
+ ╚══════════════╧═══════════════════════╧═══════════════════════════════════════════╝
90
+ Confirm [N,y]: y
91
+
92
+ Making 12 flac files...............
93
+ Normalizing wav files...
94
+ Making 12 flac files...............
95
+ Making 12 m4a files...............
96
+ Making 12 mp3 files...............
97
+ Wrote /home/user/library/source/Angels_and_Airwaves/2007__I-Empire/Manifest.yaml
98
+ ```
99
+
100
+ ### Add Audio from Files
101
+
102
+ ```bash
103
+ audiolibrarian convert /path/to/audio/files
104
+ ```
105
+
106
+ This will:
107
+
108
+ 1. Prompt you for a MusicBrainz release ID (UUID or URL)
109
+ 2. Preview the source and destination names
110
+ 3. Prompt for confirmation
111
+ 4. Convert the audio and add it to your library
112
+
113
+ **Sample output:**
114
+
115
+ ```text
116
+ $ ls APP__VULTURE_CULTURE
117
+ '1-lets talk about me.flac' '4-sooner or later.flac' '7-somebody out there.flac'
118
+ '2-separate lives.flac' '5-vulture culture.flac' '8-same old sun.flac'
119
+ '3-days are numbers.flac' 6-hawkeye.flac
120
+
121
+
122
+ $ audiolibrarian convert APP__VULTURE_CULTURE
123
+ Gathering search information...
124
+ Finding MusicBrainz release information...
125
+ MusicBrainz Release ID: https://musicbrainz.org/release/415f07fb-47de-3d4e-bbf9-683791188b75
126
+ ╔═══════════════════════════════════════════════════════════════════════════════════════════════════╗
127
+ ║ Album: Vulture Culture ║
128
+ ║ Artist(s): Parsons, Alan, Project, The ║
129
+ ║ MB Release: https://musicbrainz.org/release/415f07fb-47de-3d4e-bbf9-683791188b75 ║
130
+ ║ Disc: 1 of 1 ║
131
+ ╠══════════════════════╤═════════════════════════════════════╤══════════════════════════════════════╣
132
+ ║ Source │ Destination │ Title ║
133
+ ╠══════════════════════╪═════════════════════════════════════╪══════════════════════════════════════╣
134
+ ║ 1-lets talk about me │ 01__Lets_Talk_About_Me │ 01: Let's Talk About Me ║
135
+ ║ 2-separate lives │ 02__Separate_Lives │ 02: Separate Lives ║
136
+ ║ 3-days are numbers │ 03__Days_Are_Numbers__The_Traveller │ 03: Days Are Numbers (The Traveller) ║
137
+ ║ 4-sooner or later │ 04__Sooner_or_Later │ 04: Sooner or Later ║
138
+ ║ 5-vulture culture │ 05__Vulture_Culture │ 05: Vulture Culture ║
139
+ ║ 6-hawkeye │ 06__Hawkeye │ 06: Hawkeye ║
140
+ ║ 7-somebody out there │ 07__Somebody_Out_There │ 07: Somebody Out There ║
141
+ ║ 8-same old sun │ 08__The_Same_Old_Sun │ 08: The Same Old Sun ║
142
+ ╚══════════════════════╧═════════════════════════════════════╧══════════════════════════════════════╝
143
+ Confirm [N,y]: y
144
+ Making 8 wav files...........
145
+ Making 8 flac files...........
146
+ Normalizing wav files...
147
+ Making 8 flac files...........
148
+ Making 8 m4a files...........
149
+ Making 8 mp3 files...........
150
+ Wrote /home/user/library/source/Parsons,_Alan,_Project,_The/1985__Vulture_Culture/Manifest.yaml
151
+ ```