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.
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.gitignore +13 -0
- audiolibrarian-0.17.0/.readthedocs.yaml +30 -0
- audiolibrarian-0.17.0/CONTRIBUTING.md +3 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/Makefile +14 -1
- audiolibrarian-0.17.0/PKG-INFO +74 -0
- audiolibrarian-0.17.0/README.md +48 -0
- audiolibrarian-0.17.0/docs/api/audiolibrarian.md +56 -0
- audiolibrarian-0.17.0/docs/development/contributing.md +108 -0
- audiolibrarian-0.17.0/docs/index.md +36 -0
- audiolibrarian-0.17.0/docs/user-guide/advanced.md +15 -0
- audiolibrarian-0.17.0/docs/user-guide/changelog.md +17 -0
- audiolibrarian-0.17.0/docs/user-guide/configuration.md +95 -0
- audiolibrarian-0.17.0/docs/user-guide/getting-started.md +151 -0
- audiolibrarian-0.17.0/docs/user-guide/installation.md +104 -0
- audiolibrarian-0.17.0/mkdocs.yml +90 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/pyproject.toml +6 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/scripts/update_links.sh +11 -12
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/__init__.py +2 -2
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/__init__.py +1 -2
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/audiofile.py +1 -1
- audiolibrarian-0.17.0/src/audiolibrarian/audiofile/formats/__init__.py +17 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/flac.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/m4a.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/formats/mp3.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiofile/tags.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/audiosource.py +3 -3
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/base.py +86 -39
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/cli.py +1 -2
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/commands.py +10 -10
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/genremanager.py +4 -4
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/musicbrainz.py +2 -2
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/output.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/records.py +1 -1
- audiolibrarian-0.17.0/src/audiolibrarian/settings.py +114 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/sh.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/audiolibrarian/text.py +1 -1
- audiolibrarian-0.17.0/tools/__init__.py +17 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/tools/diff.py +1 -1
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/tools/show_tags.py +1 -1
- audiolibrarian-0.17.0/uv.lock +1141 -0
- audiolibrarian-0.16.4/CONTRIBUTING.md +0 -10
- audiolibrarian-0.16.4/PKG-INFO +0 -333
- audiolibrarian-0.16.4/README.md +0 -308
- audiolibrarian-0.16.4/src/audiolibrarian/audiofile/formats/__init__.py +0 -1
- audiolibrarian-0.16.4/src/audiolibrarian/settings.py +0 -79
- audiolibrarian-0.16.4/tools/__init__.py +0 -1
- audiolibrarian-0.16.4/uv.lock +0 -646
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.github/workflows/main.yml +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/.python-version +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/COPYING +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/LICENSE +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/git_hooks/README.md +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/git_hooks/pre-push +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/README.md +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/__init__.py +0 -0
- {audiolibrarian-0.16.4 → audiolibrarian-0.17.0}/src/picard_src/textencoding.py +0 -0
@@ -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
|
@@ -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
|
+
[](https://pypi.org/project/audiolibrarian/)
|
30
|
+
[](https://www.gnu.org/licenses/gpl-3.0)
|
31
|
+
[](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
|
+
[](https://pypi.org/project/audiolibrarian/)
|
4
|
+
[](https://www.gnu.org/licenses/gpl-3.0)
|
5
|
+
[](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
|
+
```
|