# Beets-audible: Organize Your Audiobook Collection With Beets
This is a plugin that allows Beets to manage audiobook collections.
It fetches audiobook metadata via the Audible and [Audnex API](https://github.com/laxamentumtech/audnexus). With this data, it ensures books have the correct tags and makes the collection ready to be served by Plex, Audiobookshelf or Booksonic.
## Motivation
[seanap's audiobook organization guide](https://github.com/seanap/Plex-Audiobook-Guide) describes a workflow for adding tags to audiobooks and moving the files to the right folders.
However, it relies on using Mp3tag, a gui tool which does not lend itself to automation. Mp3tag works only on Windows.
This Beets plugin solves both problems.
## Installation
1. Install via pip: `pip install beets-audible beets-copyartifacts3` (copyartifacts is optional but recommended). See the next section instead if you're running Beets in Docker (highly recommended as it makes it easier to maintain a separate Beets installation dedicated to audiobooks).
2. Use a separate beets config and database for managing audiobooks. This is the recommended Beets config for this plugin:
```yaml
# add audible to the list of plugins
# copyartifacts is optional but recommended if you're manually specifying metadata via metadata.yml, see the "Importing non-audible content" section
plugins: audible copyartifacts edit fromfilename scrub
directory: /audiobooks
# Place books in their own folders to be compatible with Booksonic and Audiobookshelf servers
paths:
# For books that belong to a series
"albumtype:audiobook series_name::.+ series_position::.+": $albumartist/%ifdef{series_name}/%ifdef{series_position} - $album%aunique{}/$track - $title
"albumtype:audiobook series_name::.+": $albumartist/%ifdef{series_name}/$album%aunique{}/$track - $title
# Stand-alone books
"albumtype:audiobook": $albumartist/$album%aunique{}/$track - $title
default: $albumartist/$album%aunique{}/$track - $title
singleton: Non-Album/$artist - $title
comp: Compilations/$album%aunique{}/$track - $title
albumtype_soundtrack: Soundtracks/$album/$track $title
# disables musicbrainz lookup, as it doesn't help for audiobooks
musicbrainz:
enabled: no
audible:
# if the number of files in the book is the same as the number of chapters from Audible,
# attempt to match each file to an audible chapter
match_chapters: true
source_weight: 0.0 # disable the source_weight penalty
fetch_art: true # whether to retrieve cover art
include_narrator_in_artists: true # include author and narrator in artist tag. Or just author
write_description_file: true # output desc.txt
write_reader_file: true # output reader.txt
copyartifacts:
extensions: .yml # so that metadata.yml is copied, see below
scrub:
auto: yes # optional, enabling this is personal preference
```
3. Run the `beet --version` command and verify that the audible plugin appears in the list of plugins.
### With Docker
1. Create the following folder structure:
```
beets
config/
scripts/
install-deps.sh # see step 3
docker-compose.yml # see step 2
```
2. Save the following as the docker-compose file:
```yaml
---
version: "3"
services:
beets:
image: lscr.io/linuxserver/beets:latest
container_name: beets
environment:
# Update as needed
- PUID=1000
- PGID=1000
- TZ=Asia/Singapore
volumes:
- ./config:/config
- ./scripts:/config/custom-cont-init.d
- /path/to/audiobooks:/audiobooks
- /path/to/import/books/from:/input
restart: unless-stopped
```
3. Save the following under `scripts/install-deps.sh`:
```sh
#!/bin/bash
echo "Installing dependencies..."
# copyartifacts is optional but recommended
pip install --no-cache-dir beets-audible beets-copyartifacts3
```
4. Spin up the container: `docker-compose up -d`
5. Update the config in `config/config.yaml` as described above.
6. In the docker container, run the `beet --version` command and verify that the audible plugin appears in the list of plugins.
## Usage
When importing audiobooks into Beets, ensure that the files for each book are in its own folder, even if the audiobook only consists of a single file. This is so that the files for a book are treated as an album by Beets. Avoid putting files from multiple books in the same folder.
When ready, start the import by executing the following command in the container:
```sh
beet import /path/to/audiobooks
```
The following sources of information are used to search for book matches in order of preference:
1. A file containing book info named `metadata.yml` (see below)
2. Album and artist tags
3. If tags are missing from the file, enabling the fromfilename plugin will attempt to deduce album and artist from file names
4. If all else fails, use the folder name as the query string
If you're not getting a match for a book, try the following:
1. Check the tags on the files being imported. The album and artist tags should be set to the book title and author respectively.
2. Press `E` when Beets prompts you about not being able to find a match. This prompts for the artist and album name. If the wrong book is being matched because there are other books with similar names on Audible, try using the audiobook's asin as the artist and title as the album.
3. Specify the book's data by using `metadata.yml` if it isn't on Audible (see the next section).
The plugin gets chapter data of each book and tries to match them to the imported files if and only if the number of imported files is the same as the number of chapters from Audible. This can fail and cause inaccurate track assignments if the lengths of the files don't match Audible's chapter data. If this happens, set the config option `match_chapters` to `false` temporarily and try again, and remember to uncomment that line once done.
### Goodreads for original work first published date
The plugin can search Goodreads to find the original publication date of the work the audiobook is based on by searching on the ASIN. To enable this option you need a Goodreads API key and you must set that key in the audible plugin config
```
audible:
goodreads_apikey: [APIKEYHERE] #optional
```
If you want this date used as the release date for the audiobook, you must set [original_date](https://beets.readthedocs.io/en/stable/reference/config.html#original-date) to yes in your beets config
### Importing Non-Audible Content
The plugin looks for a file called `metadata.yml` in each book's folder during import. If this file is present, it exclusively uses the info in it for tagging and skips the Audible lookup.
This is meant for importing audio content that isn't on Audible.
Here's an example of what `metadata.yml` should look like:
```yaml
---
# These are all required fields
title: The Lord of the Rings (BBC Dramatization)
authors: ["J. R. R. Tolkien", "Brian Sibley", "Michael Bakewell"]
narrators:
- "Ian Holm (as Frodo)"
- "Sir Michael Hordern (as Gandalf)"
- "Robert Stephens (as Aragorn)"
- "John Le Mesurier"
description: |
This audio set includes: The Fellowship of the Ring; The Two Towers; and The Return of the King.
Undertaking the adaptation of J.R.R. Tolkien's best-known work was an enormous task, but with its first broadcast on BBC Radio 4 on March 8, 1981, this dramatized tale of Middle Earth became an instant global classic. Thrilling dramatization by Brian Sibley and Michael Bakewell it boasts a truly outstanding cast including Ian Holm (as Frodo), Sir Michael Hordern (as Gandalf), Robert Stephens (as Aragorn), and John Le Mesurier. Tolkiens tale relates the perilous attempt by Frodo Baggins and company to defeat the evil Saruman and dispose of the Ruling Ring. Brian Sibley wrote the opening and closing narration for the character of Frodo, played by Ian Holm, who now stars as Bilbo in the feature films based on The Lord of the Rings.
genres: ["fantasy"]
releaseDate: 2008-08-19
publisher: BBC Audiobooks
# optional fields
language: English # defaults to "English" if not specified
subtitle: "some subtitle"
series: The Lord Of The Rings
seriesPosition: "1-3"
```
The copyartifacts plugin ensures that `metadata.yml` is copied over during the import, as it gets left in the source folder otherwise.
## Folder Structure
The config above places books according to this folder structure, which can be changed by editing the path config.
```
Terry Goodkind/
Sword of Truth/
1 - Wizards First Rule/
cover.png
desc.txt
reader.txt
wizards first rule.m4b
George Orwell/
Animal Farm/
Animal Farm.m4b
cover.png
desc.txt
reader.txt
```
Desc.txt and reader.txt contain the book description and narrator populated from Audible.
## Tags Written
Beets-audible writes the following tags:
| ID3 Tag | Audible.com Value |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `TIT1` (CONTENTGROUP) | Series, Book # |
| `TALB` (ALBUM) | Title |
| `TIT3` (SUBTITLE) | Subtitle |
| `TPE1` (ARTIST) | Author, Narrator |
| `TPE2` (ALBUMARTIST) | Author |
| `TCOM` (COMPOSER) | Narrator |
| `TCON` (GENRE) | Genre1/Genre2 |
| `TDRC` and `TDRL` (release date) | audio publication date |
| `COMM` or `desc` for m4b files (COMMENT) | Publisher's Summary |
| `TSOA` (ALBUMSORT) | If ALBUM only, then %Title%<br>If ALBUM and SUBTITLE, then %Title% - %Subtitle%<br>If Series, then %Series% %Series-part% - %Title% |
| `TPUB` (PUBLISHER) | Publisher |
| `ASIN` (ASIN) | Amazon Standard Identification Number |
| `stik` (media type), m4b only | 2 (audiobook) |
| `shwm` (show movement), m4b only | 1 if part of a series |
| `MVNM` (MOVEMENTNAME) | Series |
| `MVIN` / `MVI` for m4b files (MOVEMENT) | Series Book # |
| `TXXX_SERIES` (SERIES) | Series |
| `TXXX_SERIES-PART` | Series position |
## Known Limitations
1. Anything that would cause Beets to move data (e.g, if performing an update after changing the path format) only moves the audio files and cover, leaving desc.txt and reader.txt behind. They need to be moved manually. This is because Beets doesn't associate these files with the album in its database.
## Plex Integration
If the directory where Beets imports audiobooks to is also where you've set Plex to serve content from, you can enable the [plexupdate plugin](https://beets.readthedocs.io/en/stable/plugins/plexupdate.html) to notify Plex when new books are imported.
Raw data
{
"_id": null,
"home_page": "https://github.com/Neurrone/beets-audible",
"name": "beets-audible",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "beets,audible",
"author": "Dickson Tan",
"author_email": "dickson.tan.2013@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7b/e0/f67512d753aed7563db97dd38b1b90df9262e0ec9210ca16930afd18c8ab/beets-audible-0.1.0.tar.gz",
"platform": null,
"description": "# Beets-audible: Organize Your Audiobook Collection With Beets\n\nThis is a plugin that allows Beets to manage audiobook collections.\n\nIt fetches audiobook metadata via the Audible and [Audnex API](https://github.com/laxamentumtech/audnexus). With this data, it ensures books have the correct tags and makes the collection ready to be served by Plex, Audiobookshelf or Booksonic.\n\n## Motivation\n\n[seanap's audiobook organization guide](https://github.com/seanap/Plex-Audiobook-Guide) describes a workflow for adding tags to audiobooks and moving the files to the right folders.\n\nHowever, it relies on using Mp3tag, a gui tool which does not lend itself to automation. Mp3tag works only on Windows.\n\nThis Beets plugin solves both problems.\n\n## Installation\n\n1. Install via pip: `pip install beets-audible beets-copyartifacts3` (copyartifacts is optional but recommended). See the next section instead if you're running Beets in Docker (highly recommended as it makes it easier to maintain a separate Beets installation dedicated to audiobooks).\n2. Use a separate beets config and database for managing audiobooks. This is the recommended Beets config for this plugin:\n\n ```yaml\n # add audible to the list of plugins\n # copyartifacts is optional but recommended if you're manually specifying metadata via metadata.yml, see the \"Importing non-audible content\" section\n plugins: audible copyartifacts edit fromfilename scrub\n\n directory: /audiobooks\n\n # Place books in their own folders to be compatible with Booksonic and Audiobookshelf servers\n paths:\n # For books that belong to a series\n \"albumtype:audiobook series_name::.+ series_position::.+\": $albumartist/%ifdef{series_name}/%ifdef{series_position} - $album%aunique{}/$track - $title\n \"albumtype:audiobook series_name::.+\": $albumartist/%ifdef{series_name}/$album%aunique{}/$track - $title\n # Stand-alone books\n \"albumtype:audiobook\": $albumartist/$album%aunique{}/$track - $title\n default: $albumartist/$album%aunique{}/$track - $title\n singleton: Non-Album/$artist - $title\n comp: Compilations/$album%aunique{}/$track - $title\n albumtype_soundtrack: Soundtracks/$album/$track $title\n\n # disables musicbrainz lookup, as it doesn't help for audiobooks\n musicbrainz:\n enabled: no\n\n audible:\n # if the number of files in the book is the same as the number of chapters from Audible,\n # attempt to match each file to an audible chapter\n match_chapters: true\n source_weight: 0.0 # disable the source_weight penalty\n fetch_art: true # whether to retrieve cover art\n include_narrator_in_artists: true # include author and narrator in artist tag. Or just author\n write_description_file: true # output desc.txt\n write_reader_file: true # output reader.txt\n\n copyartifacts:\n extensions: .yml # so that metadata.yml is copied, see below\n\n scrub:\n auto: yes # optional, enabling this is personal preference\n ```\n\n3. Run the `beet --version` command and verify that the audible plugin appears in the list of plugins.\n\n### With Docker\n\n1. Create the following folder structure:\n\n ```\n beets\n config/\n scripts/\n install-deps.sh # see step 3\n docker-compose.yml # see step 2\n ```\n\n2. Save the following as the docker-compose file:\n\n ```yaml\n ---\n version: \"3\"\n services:\n beets:\n image: lscr.io/linuxserver/beets:latest\n container_name: beets\n environment:\n # Update as needed\n - PUID=1000\n - PGID=1000\n - TZ=Asia/Singapore\n volumes:\n - ./config:/config\n - ./scripts:/config/custom-cont-init.d\n - /path/to/audiobooks:/audiobooks\n - /path/to/import/books/from:/input\n restart: unless-stopped\n ```\n\n3. Save the following under `scripts/install-deps.sh`:\n\n ```sh\n #!/bin/bash\n echo \"Installing dependencies...\"\n # copyartifacts is optional but recommended\n pip install --no-cache-dir beets-audible beets-copyartifacts3\n ```\n\n4. Spin up the container: `docker-compose up -d`\n5. Update the config in `config/config.yaml` as described above.\n6. In the docker container, run the `beet --version` command and verify that the audible plugin appears in the list of plugins.\n\n## Usage\n\nWhen importing audiobooks into Beets, ensure that the files for each book are in its own folder, even if the audiobook only consists of a single file. This is so that the files for a book are treated as an album by Beets. Avoid putting files from multiple books in the same folder.\n\nWhen ready, start the import by executing the following command in the container:\n\n```sh\nbeet import /path/to/audiobooks\n```\n\nThe following sources of information are used to search for book matches in order of preference:\n\n1. A file containing book info named `metadata.yml` (see below)\n2. Album and artist tags\n3. If tags are missing from the file, enabling the fromfilename plugin will attempt to deduce album and artist from file names\n4. If all else fails, use the folder name as the query string\n\nIf you're not getting a match for a book, try the following:\n\n1. Check the tags on the files being imported. The album and artist tags should be set to the book title and author respectively.\n2. Press `E` when Beets prompts you about not being able to find a match. This prompts for the artist and album name. If the wrong book is being matched because there are other books with similar names on Audible, try using the audiobook's asin as the artist and title as the album.\n3. Specify the book's data by using `metadata.yml` if it isn't on Audible (see the next section).\n\nThe plugin gets chapter data of each book and tries to match them to the imported files if and only if the number of imported files is the same as the number of chapters from Audible. This can fail and cause inaccurate track assignments if the lengths of the files don't match Audible's chapter data. If this happens, set the config option `match_chapters` to `false` temporarily and try again, and remember to uncomment that line once done.\n\n### Goodreads for original work first published date\n\nThe plugin can search Goodreads to find the original publication date of the work the audiobook is based on by searching on the ASIN. To enable this option you need a Goodreads API key and you must set that key in the audible plugin config\n\n```\n audible:\n goodreads_apikey: [APIKEYHERE] #optional\n```\n\nIf you want this date used as the release date for the audiobook, you must set [original_date](https://beets.readthedocs.io/en/stable/reference/config.html#original-date) to yes in your beets config\n\n### Importing Non-Audible Content\n\nThe plugin looks for a file called `metadata.yml` in each book's folder during import. If this file is present, it exclusively uses the info in it for tagging and skips the Audible lookup.\n\nThis is meant for importing audio content that isn't on Audible.\n\nHere's an example of what `metadata.yml` should look like:\n\n```yaml\n---\n# These are all required fields\ntitle: The Lord of the Rings (BBC Dramatization)\nauthors: [\"J. R. R. Tolkien\", \"Brian Sibley\", \"Michael Bakewell\"]\nnarrators:\n - \"Ian Holm (as Frodo)\"\n - \"Sir Michael Hordern (as Gandalf)\"\n - \"Robert Stephens (as Aragorn)\"\n - \"John Le Mesurier\"\ndescription: |\n This audio set includes:\u00a0The Fellowship of the Ring; The Two Towers;\u00a0and\u00a0The Return of the King.\n\n Undertaking the adaptation of J.R.R. Tolkien's best-known work was an enormous task, but with its first broadcast on BBC Radio 4 on March 8, 1981, this dramatized tale of Middle Earth became an instant global classic. Thrilling dramatization by Brian Sibley and Michael Bakewell it boasts a truly outstanding cast including Ian Holm (as Frodo), Sir Michael Hordern (as Gandalf), Robert Stephens (as Aragorn), and John Le Mesurier. Tolkiens tale relates the perilous attempt by Frodo Baggins and company to defeat the evil Saruman and dispose of the Ruling Ring. Brian Sibley wrote the opening and closing narration for the character of Frodo, played by Ian Holm, who now stars as Bilbo in the feature films based on\u00a0The Lord of the Rings.\ngenres: [\"fantasy\"]\nreleaseDate: 2008-08-19\npublisher: BBC Audiobooks\n\n# optional fields\nlanguage: English # defaults to \"English\" if not specified\nsubtitle: \"some subtitle\"\nseries: The Lord Of The Rings\nseriesPosition: \"1-3\"\n```\n\nThe copyartifacts plugin ensures that `metadata.yml` is copied over during the import, as it gets left in the source folder otherwise.\n\n## Folder Structure\n\nThe config above places books according to this folder structure, which can be changed by editing the path config.\n\n```\nTerry Goodkind/\n Sword of Truth/\n 1 - Wizards First Rule/\n cover.png\n desc.txt\n reader.txt\n wizards first rule.m4b\nGeorge Orwell/\n Animal Farm/\n Animal Farm.m4b\n cover.png\n desc.txt\n reader.txt\n```\n\nDesc.txt and reader.txt contain the book description and narrator populated from Audible.\n\n## Tags Written\n\nBeets-audible writes the following tags:\n\n| ID3 Tag | Audible.com Value |\n| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `TIT1` (CONTENTGROUP) | Series, Book # |\n| `TALB` (ALBUM) | Title |\n| `TIT3` (SUBTITLE) | Subtitle |\n| `TPE1` (ARTIST) | Author, Narrator |\n| `TPE2` (ALBUMARTIST) | Author |\n| `TCOM` (COMPOSER) | Narrator |\n| `TCON` (GENRE) | Genre1/Genre2 |\n| `TDRC` and `TDRL` (release date) | audio publication date |\n| `COMM` or `desc` for m4b files (COMMENT) | Publisher's Summary |\n| `TSOA` (ALBUMSORT) | If ALBUM only, then %Title%<br>If ALBUM and SUBTITLE, then %Title% - %Subtitle%<br>If Series, then %Series% %Series-part% - %Title% |\n| `TPUB` (PUBLISHER) | Publisher |\n| `ASIN` (ASIN) | Amazon Standard Identification Number |\n| `stik` (media type), m4b only | 2 (audiobook) |\n| `shwm` (show movement), m4b only | 1 if part of a series |\n| `MVNM` (MOVEMENTNAME) | Series |\n| `MVIN` / `MVI` for m4b files (MOVEMENT) | Series Book # |\n| `TXXX_SERIES` (SERIES) | Series |\n| `TXXX_SERIES-PART` | Series position |\n\n## Known Limitations\n\n1. Anything that would cause Beets to move data (e.g, if performing an update after changing the path format) only moves the audio files and cover, leaving desc.txt and reader.txt behind. They need to be moved manually. This is because Beets doesn't associate these files with the album in its database.\n\n## Plex Integration\n\nIf the directory where Beets imports audiobooks to is also where you've set Plex to serve content from, you can enable the [plexupdate plugin](https://beets.readthedocs.io/en/stable/plugins/plexupdate.html) to notify Plex when new books are imported.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Beets plugin for audiobook management",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/Neurrone/beets-audible",
"Repository": "https://github.com/Neurrone/beets-audible"
},
"split_keywords": [
"beets",
"audible"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c1966660fb50914b1f7a091e5bdb23a84f94cf90f1bd564fc819f24ec61f275",
"md5": "01d9ccbfac439309e9744d550d81edc6",
"sha256": "b23b50e9565a4efd13d443b97164bb04080fd03f30e16ef202ad982194679c9c"
},
"downloads": -1,
"filename": "beets_audible-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01d9ccbfac439309e9744d550d81edc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 16426,
"upload_time": "2022-11-27T13:39:58",
"upload_time_iso_8601": "2022-11-27T13:39:58.566104Z",
"url": "https://files.pythonhosted.org/packages/6c/19/66660fb50914b1f7a091e5bdb23a84f94cf90f1bd564fc819f24ec61f275/beets_audible-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7be0f67512d753aed7563db97dd38b1b90df9262e0ec9210ca16930afd18c8ab",
"md5": "3bf681da45ea31ce40c056a45c6716a5",
"sha256": "5d24a7ad08bee683edb155544fb224217cbd796b1f19e8f6fadd54d7695d616f"
},
"downloads": -1,
"filename": "beets-audible-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3bf681da45ea31ce40c056a45c6716a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 16179,
"upload_time": "2022-11-27T13:39:56",
"upload_time_iso_8601": "2022-11-27T13:39:56.560393Z",
"url": "https://files.pythonhosted.org/packages/7b/e0/f67512d753aed7563db97dd38b1b90df9262e0ec9210ca16930afd18c8ab/beets-audible-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-27 13:39:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Neurrone",
"github_project": "beets-audible",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "beets-copyartifacts3",
"specs": []
},
{
"name": "markdownify",
"specs": []
},
{
"name": "natsort",
"specs": []
}
],
"tox": true,
"lcname": "beets-audible"
}
JSON
