# beets-cdman
This [beets][beets-docs]
plugin lets you easily manage your collection of CDs.
You can define CDs in your beets config and with
[CD definition files][cd-def-example],
and easily add, remove, or reorder folders.
`cdman` can't burn CDs, but this can be done by other software such as
[Brasero][brasero-page] on GNOME, or [K3b][k3b-page] on KDE.
- [beets-cdman](#beets-cdman)
- [Install](#install)
- [Usage](#usage)
- [MP3 CDs](#mp3-cds)
- [Audio CDs](#audio-cds)
- [CD Definition Files](#cd-definition-files)
- [Credits](#credits)
## Install
Run this in your beets environment:
```bash
pip install beets-cdman
```
Setup your beets config:
```yml
plugins:
...
- cdman
cdman:
# Path to where you want your CDs to be stored.
path: ~/Music/CDs # optional, default ~/Music/CDs
# The bitrate to use when populating MP3 CDs. This value is in kliobits.
mp3_bitrate: 192 # optional, default 192
# How audio CDs should be populated.
# - copy: Copy the file from your library to the CD directory
# - hard_link: Hard links the file from your library to the CD directory
# - soft_link: Soft links the file from your library to the CD directory
# - NOTE: Not all filesystems support this
audio_populate_mode: copy # optional, defaults to copy
# How many threads to allocate. Unless you know what you're doing, you should leave this undefined.
# threads: 12 # optional, default is your hardware thread count
# This points to CD definitions made in external files
# Don't use relative paths, as sometimes the system won't be able to find your definitions.
# You can use `~` to indicate your home directory.
cd_files: # optional
- /path/to/my/cd_file.yml
- ./dont/use/relative/paths.yml
# This defines CDs to populate with tracks
cds: # optional
# This will create a CD directory in ~/Music/CDs/mp3-cd-name
mp3-cd-name:
# What type of CD this is.
# - mp3: An MP3 CD is defined by folders, and converts all tracks to MP3.
# - audio: The classic CD standard, simply plops files inside the folder.
type: mp3
# You can define the MP3 bitrate to use per-CD if you want.
# This value overrides your config
bitrate: 192 # optional, defaults to config
folders:
__root__: # This is a special name that puts tracks inside of this folder directly into the CD folder instead.
tracks:
# Tracks can be defined with Beets queries or playlist files
# There is no limit to the number of query or playlist fields, and they can be intermixed.
- query: "'artist:Daft Punk'"
- playlist: "/path/to/playlist_file.m3u"
foals:
# You can explicitly define your folder name here.
# Leaving it undefined simply uses the key used to define this folder,
# which is `foals` in this case.
name: "Backwards Foals" # optional, defaults to folder key
tracks:
# Track order matters! This will order the CD so that Part 2 plays before Part 1.
- query: "'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 2'"
- query: "'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 1'"
```
Note the use of double *and* single quotes.
The double quotes are to ensure YAML doesn't get confused.
The single quotes are to send singular expressions to beets.
For example, `"'artist:Daft Punk' 'album:Discovery'"`
would match all songs in the Discovery album and made by Daft Punk.
## Usage
To create your CDs, simply run
```bash
beet cdman
```
This will look through your beets config for any CDs defined in there.
If any are found, it will then create a folder in your `path`
and place files inside the created folder.
You can also pass in paths to [CD definition files](#cd-definition-files),
or directories containing CD definition files:
```bash
beet cdman daft-punk.yml rock.yml cd-definitions/
```
## MP3 CDs
When `cdman` encounters an MP3 CD definition, it will create folders inside
the CD folder and then convert all music files found from the configured
tracks to an MP3. You can configure the bitrate of these MP3s
with the `mp3_bitrate` config field, changing the `bitrate` field in the CD definition,
or by passing `--bitrate` into the command.
For example, an MP3 CD definition that looks like this:
```yml
discoveries:
type: mp3
bitrate: 128
folders:
daft-punk:
name: "Daft Punk"
tracks:
- query: "'artist:Daft Punk' 'album:Discovery'"
Fantom87:
tracks:
- query: "'artist:Fantom87' 'album:Discovery'"
the-french-house:
type: mp3
bitrate: 256
folders:
Joshua:
tracks:
- query: "'artist:French79' 'album:Joshua'"
Teenagers:
tracks:
- query: "'artist:French79' 'album:Teenagers'"
```
Would create a directory structure like this:
```
/path/to/cds_path:
├── discoveries
│ ├── 01 Daft Punk
│ │ ├── 01 One More Time.mp3
│ │ ├── 02 Aerodynamic.mp3
│ │ └── ...
│ └── 02 Fantom87
│ ├── 01 Pay Phone.mp3
│ ├── 02 Oh, Dreamer.mp3
│ └── ...
└── the-french-house
├── 01 Joshua
│ ├── 01 Remedy.mp3
│ ├── 02 Hold On.mp3
│ └── ...
└── 02 Teenagers
├── 01 One for Wendy.mp3
├── 02 Burning Legend.mp3
└── ...
```
## Audio CDs
When `cdman` encounters an Audio CD definition, it will simply populate the CD folder
with all music files found from the configured tracks.
It can either copy, soft link, or hard link the files.
You can configure this behavior with the `audio_populate_mode` config field,
changing the `populate_mode` field in the CD definition, or by passing `--populate-mode`
into the command.
For example, an Audio CD definition that looks like this:
```yml
not-saved-part-1:
type: audio
populate_mode: soft_link
tracks:
- query: "'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 1'"
not-saved-part-1:
type: audio
populate_mode: copy
tracks:
- query: "'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 2'"
```
Would create a directory structure like this:
```
/path/to/cds_path:
├── not-saved-part-1
│ ├── 01 Moonlight.flac -> /path/to/Moonlight.flac
│ ├── 02 Exits.flac -> /path/to/Exits.flac
│ └── ...
└── not-saved-part-2
├── 01 Red Desert.m4a
├── 02 The Runner.m4a
└── ...
```
## CD Definition Files
CD definition files let you define CDs in external files, to help keep your
beets config file less cluttered. CD definition files follow the same format
as the beets config `cds` field.
You can find an example CD definition file [here][cd-def-example]
## Credits
The music files used for testing are all created by [Scott Buckley][scott-buckley],
and is protected under [CC-BY 4.0][cc-by-4.0].
[beets-docs]: https://beets.readthedocs.io/en/latest/index.html
[cd-def-example]: https://github.com/TacticalLaptopBag/beets-cdman/blob/main/example-cdman-definition.yml
[beets-alt-plugin]: https://github.com/geigerzaehler/beets-alternatives/
[brasero-page]: https://wiki.gnome.org/Apps/Brasero/
[k3b-page]: https://apps.kde.org/k3b/
[scott-buckley]: https://www.scottbuckley.com.au/
[cc-by-4.0]: https://creativecommons.org/licenses/by/4.0/deed.en
Raw data
{
"_id": null,
"home_page": "https://github.com/TacticalLaptopBag/beets-cdman",
"name": "beets-cdman",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.12",
"maintainer_email": null,
"keywords": "beets, cdman, cd, mp3, audio, cli, command-line, command, line, tool, yml, yaml",
"author": "Tactical Laptop Bag",
"author_email": "tacticallaptopbag@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/20/7a/39b5fc36240337ae7d1fa9ef0a7e55332696ce7dcd10e94213208eb1fc54/beets_cdman-1.0.3.tar.gz",
"platform": null,
"description": "# beets-cdman\nThis [beets][beets-docs]\nplugin lets you easily manage your collection of CDs.\nYou can define CDs in your beets config and with\n[CD definition files][cd-def-example],\nand easily add, remove, or reorder folders.\n\n`cdman` can't burn CDs, but this can be done by other software such as\n[Brasero][brasero-page] on GNOME, or [K3b][k3b-page] on KDE.\n\n\n- [beets-cdman](#beets-cdman)\n - [Install](#install)\n - [Usage](#usage)\n - [MP3 CDs](#mp3-cds)\n - [Audio CDs](#audio-cds)\n - [CD Definition Files](#cd-definition-files)\n - [Credits](#credits)\n\n\n## Install\nRun this in your beets environment:\n```bash\npip install beets-cdman\n```\n\nSetup your beets config:\n```yml\nplugins:\n ...\n - cdman\n\ncdman:\n # Path to where you want your CDs to be stored.\n path: ~/Music/CDs # optional, default ~/Music/CDs\n\n # The bitrate to use when populating MP3 CDs. This value is in kliobits.\n mp3_bitrate: 192 # optional, default 192\n\n # How audio CDs should be populated.\n # - copy: Copy the file from your library to the CD directory\n # - hard_link: Hard links the file from your library to the CD directory\n # - soft_link: Soft links the file from your library to the CD directory\n # - NOTE: Not all filesystems support this\n audio_populate_mode: copy # optional, defaults to copy\n\n # How many threads to allocate. Unless you know what you're doing, you should leave this undefined.\n # threads: 12 # optional, default is your hardware thread count\n\n # This points to CD definitions made in external files\n # Don't use relative paths, as sometimes the system won't be able to find your definitions.\n # You can use `~` to indicate your home directory.\n cd_files: # optional\n - /path/to/my/cd_file.yml\n - ./dont/use/relative/paths.yml\n\n # This defines CDs to populate with tracks\n cds: # optional\n # This will create a CD directory in ~/Music/CDs/mp3-cd-name\n mp3-cd-name:\n # What type of CD this is.\n # - mp3: An MP3 CD is defined by folders, and converts all tracks to MP3.\n # - audio: The classic CD standard, simply plops files inside the folder.\n type: mp3\n\n # You can define the MP3 bitrate to use per-CD if you want.\n # This value overrides your config\n bitrate: 192 # optional, defaults to config\n\n folders:\n __root__: # This is a special name that puts tracks inside of this folder directly into the CD folder instead.\n tracks:\n # Tracks can be defined with Beets queries or playlist files\n # There is no limit to the number of query or playlist fields, and they can be intermixed.\n - query: \"'artist:Daft Punk'\"\n - playlist: \"/path/to/playlist_file.m3u\"\n foals:\n # You can explicitly define your folder name here.\n # Leaving it undefined simply uses the key used to define this folder,\n # which is `foals` in this case.\n name: \"Backwards Foals\" # optional, defaults to folder key\n tracks:\n # Track order matters! This will order the CD so that Part 2 plays before Part 1.\n - query: \"'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 2'\"\n - query: \"'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 1'\"\n```\nNote the use of double *and* single quotes.\nThe double quotes are to ensure YAML doesn't get confused.\nThe single quotes are to send singular expressions to beets.\nFor example, `\"'artist:Daft Punk' 'album:Discovery'\"`\nwould match all songs in the Discovery album and made by Daft Punk.\n\n\n## Usage\nTo create your CDs, simply run\n```bash\nbeet cdman\n```\nThis will look through your beets config for any CDs defined in there.\nIf any are found, it will then create a folder in your `path`\nand place files inside the created folder.\n\nYou can also pass in paths to [CD definition files](#cd-definition-files),\nor directories containing CD definition files:\n```bash\nbeet cdman daft-punk.yml rock.yml cd-definitions/\n```\n\n\n## MP3 CDs\nWhen `cdman` encounters an MP3 CD definition, it will create folders inside\nthe CD folder and then convert all music files found from the configured\ntracks to an MP3. You can configure the bitrate of these MP3s\nwith the `mp3_bitrate` config field, changing the `bitrate` field in the CD definition,\nor by passing `--bitrate` into the command.\n\nFor example, an MP3 CD definition that looks like this:\n```yml\ndiscoveries:\n type: mp3\n bitrate: 128\n folders:\n daft-punk:\n name: \"Daft Punk\"\n tracks:\n - query: \"'artist:Daft Punk' 'album:Discovery'\"\n Fantom87:\n tracks:\n - query: \"'artist:Fantom87' 'album:Discovery'\"\n\nthe-french-house:\n type: mp3\n bitrate: 256\n folders:\n Joshua:\n tracks:\n - query: \"'artist:French79' 'album:Joshua'\"\n Teenagers:\n tracks:\n - query: \"'artist:French79' 'album:Teenagers'\"\n```\nWould create a directory structure like this:\n```\n/path/to/cds_path:\n \u00a0\u00a0 \u251c\u2500\u2500 discoveries\n \u2502\u00a0 \u251c\u2500\u2500 01 Daft Punk\n \u2502\u00a0 \u2502 \u251c\u2500\u2500 01 One More Time.mp3\n \u2502\u00a0 \u2502 \u251c\u2500\u2500 02 Aerodynamic.mp3\n \u2502 \u2502\u00a0 \u2514\u2500\u2500 ...\n \u2502\u00a0 \u2514\u2500\u2500 02 Fantom87\n \u2502\u00a0 \u251c\u2500\u2500 01 Pay Phone.mp3\n \u2502\u00a0 \u251c\u2500\u2500 02 Oh, Dreamer.mp3\n \u2502 \u00a0 \u2514\u2500\u2500 ...\n \u2514\u2500\u2500 the-french-house\n \u00a0 \u251c\u2500\u2500 01 Joshua\n \u00a0 \u2502 \u251c\u2500\u2500 01 Remedy.mp3\n \u00a0 \u2502 \u251c\u2500\u2500 02 Hold On.mp3\n \u2502\u00a0 \u2514\u2500\u2500 ...\n \u00a0 \u2514\u2500\u2500 02 Teenagers\n \u00a0 \u251c\u2500\u2500 01 One for Wendy.mp3\n \u00a0 \u251c\u2500\u2500 02 Burning Legend.mp3\n \u00a0 \u2514\u2500\u2500 ...\n```\n\n\n## Audio CDs\nWhen `cdman` encounters an Audio CD definition, it will simply populate the CD folder\nwith all music files found from the configured tracks.\nIt can either copy, soft link, or hard link the files.\nYou can configure this behavior with the `audio_populate_mode` config field,\nchanging the `populate_mode` field in the CD definition, or by passing `--populate-mode`\ninto the command.\n\nFor example, an Audio CD definition that looks like this:\n```yml\nnot-saved-part-1:\n type: audio\n populate_mode: soft_link\n tracks:\n - query: \"'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 1'\"\n\nnot-saved-part-1:\n type: audio\n populate_mode: copy\n tracks:\n - query: \"'artist:Foals' 'album:Everything Not Saved Will Be Lost, Part 2'\"\n```\n\nWould create a directory structure like this:\n```\n/path/to/cds_path:\n \u00a0\u00a0 \u251c\u2500\u2500 not-saved-part-1\n \u2502\u00a0 \u251c\u2500\u2500 01 Moonlight.flac -> /path/to/Moonlight.flac\n \u2502\u00a0 \u251c\u2500\u2500 02 Exits.flac -> /path/to/Exits.flac\n \u2502 \u2514\u2500\u2500 ...\n \u2514\u2500\u2500 not-saved-part-2\n \u00a0 \u251c\u2500\u2500 01 Red Desert.m4a\n \u00a0 \u251c\u2500\u2500 02 The Runner.m4a\n \u2514\u2500\u2500 ...\n```\n\n\n## CD Definition Files\nCD definition files let you define CDs in external files, to help keep your\nbeets config file less cluttered. CD definition files follow the same format\nas the beets config `cds` field.\n\nYou can find an example CD definition file [here][cd-def-example]\n\n\n## Credits\nThe music files used for testing are all created by [Scott Buckley][scott-buckley],\nand is protected under [CC-BY 4.0][cc-by-4.0].\n\n\n[beets-docs]: https://beets.readthedocs.io/en/latest/index.html\n[cd-def-example]: https://github.com/TacticalLaptopBag/beets-cdman/blob/main/example-cdman-definition.yml\n[beets-alt-plugin]: https://github.com/geigerzaehler/beets-alternatives/\n[brasero-page]: https://wiki.gnome.org/Apps/Brasero/\n[k3b-page]: https://apps.kde.org/k3b/\n[scott-buckley]: https://www.scottbuckley.com.au/\n[cc-by-4.0]: https://creativecommons.org/licenses/by/4.0/deed.en\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Easily manage your CD collection with beets",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/TacticalLaptopBag/beets-cdman",
"Issues": "https://github.com/TacticalLaptopBag/beets-cdman/issues",
"Repository": "https://github.com/TacticalLaptopBag/beets-cdman"
},
"split_keywords": [
"beets",
" cdman",
" cd",
" mp3",
" audio",
" cli",
" command-line",
" command",
" line",
" tool",
" yml",
" yaml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d22e7356aee9e1b262509c2b5ee8b5924dd0faf8d4fa4d615cc5396e7b1f54a",
"md5": "e0ed6a485b3305307f9dd40eea6427d4",
"sha256": "2d59ba2fa2fb756c7c7b8cd6644f994c1b672f4b7b713082c41c2f17db699cea"
},
"downloads": -1,
"filename": "beets_cdman-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0ed6a485b3305307f9dd40eea6427d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.12",
"size": 35249,
"upload_time": "2025-11-03T23:23:14",
"upload_time_iso_8601": "2025-11-03T23:23:14.902453Z",
"url": "https://files.pythonhosted.org/packages/7d/22/e7356aee9e1b262509c2b5ee8b5924dd0faf8d4fa4d615cc5396e7b1f54a/beets_cdman-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "207a39b5fc36240337ae7d1fa9ef0a7e55332696ce7dcd10e94213208eb1fc54",
"md5": "6a44226d42fada87bb9f93f6cf388c23",
"sha256": "a318c428afeb69d43c4041b15d9839a7240d1fe8e10c24640332209c79e8e2f4"
},
"downloads": -1,
"filename": "beets_cdman-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6a44226d42fada87bb9f93f6cf388c23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.12",
"size": 31050,
"upload_time": "2025-11-03T23:23:15",
"upload_time_iso_8601": "2025-11-03T23:23:15.814626Z",
"url": "https://files.pythonhosted.org/packages/20/7a/39b5fc36240337ae7d1fa9ef0a7e55332696ce7dcd10e94213208eb1fc54/beets_cdman-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 23:23:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TacticalLaptopBag",
"github_project": "beets-cdman",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "beets-cdman"
}
JSON
