DOCSEARCHbyAlgolia
Submit Docs

beets-audible

repository·main·Indexed 41 days ago

https://github.com/neurrone/beets-audible

A Beets plugin for automating the organization and tagging of audiobook collections using metadata from Audible and Audnex. Version 1.7.1 supports chapter matching, cover art retrieval, and custom metadata via metadata.yml files for non-Audible content.

Tokens
2.9K
Snippets
9
Records
11
Agent score
2%

What's inside beets-audible

  1. Release process for beets-audible

    main

    Releases are automated via GitHub Actions triggered by git tags. To release a new version, follow these steps:

    1. Update Changelog: Add a new section to CHANGELOG.md with a heading matching the release tag (e.g., ## v1.3.0 (2026-02-08)).
    2. Bump Version: Update the version in pyproject.toml to the matching PEP 440 version (e.g., 1.3.0).
    3. Commit: Commit both the CHANGELOG.md and pyproject.toml changes to the main branch.
    4. Tag and Push: Create and push an annotated tag:
      • git tag -a v1.3.0 -m "v1.3.0"
      • git push origin v1.3.0

    Automation Details: The Release GitHub Actions workflow will automatically run linting, tests, and builds, then publish to PyPI using trusted publishing (OIDC) and create a GitHub Release.

    Critical Requirement: The release workflow will fail if the git tag does not have a corresponding section in CHANGELOG.md.

    git tag -a v1.3.0 -m "v1.3.0"
git push origin v1.3.0

  2. Import non-Audible content using metadata.yml

    main

    If an audiobook is not available on Audible, you can provide metadata manually by placing a metadata.yml file in the book's folder. The plugin will use this file exclusively and skip the Audible lookup.

    Required fields: title, authors (list). Optional fields: narrators (list), description, genres (list), releaseDate, publisher, language, subtitle, series, seriesPosition.

    Example metadata.yml structure:

    ---
title: The Lord of the Rings (BBC Dramatization)
authors: ["J. R. R. Tolkien", "Brian Sibley"]
narrators:
  - "Ian Holm"
description: |
  This audio set includes... 
genres: ["fantasy"]
releaseDate: 2008-08-19
series: The Lord Of The Rings
seriesPosition: "1-3"
    ---
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...
genres: ["fantasy"]
releaseDate: 2008-08-19
publisher: BBC Audiobooks

# optional fields
language: English
subtitle: "some subtitle"
series: The Lord Of The Rings
seriesPosition: "1-3"

  4. Import audiobooks into Beets

    main

    When importing, ensure each book is in its own folder (even if it's a single file) so Beets treats it as an album.

    Run the import command:

    beet import /path/to/audiobooks

    Search Priority:

    1. metadata.yml file in the folder.
    2. Album and artist tags.
    3. Filenames (if fromfilename plugin is enabled).
    4. Folder name.

    Troubleshooting Matches:

    • If no match is found, press E during the prompt to manually enter artist/album names. Using the Audible ASIN as the artist can help resolve ambiguous titles.
    • If the region is incorrect, press N during the prompt to change the Audible region for that specific book.
    • If chapter matching is causing inaccurate track assignments, set match_chapters: false in your config.
    beet import /path/to/audiobooks

  5. Install beets-audible via pip

    main

    To install the plugin directly into your existing Beets environment, use pip:

    pip install beets-audible

    After installation, verify that the plugin is recognized by running beet --version and checking the plugin list.

  6. Install beets-audible using Docker

    main

    It is highly recommended to use a separate Beets installation dedicated to audiobooks via Docker.

    1. Create the following directory structure:
    beets/
  config/
  scripts/
    install-deps.sh
docker-compose.yml
    1. Create scripts/install-deps.sh with the following content to ensure dependencies are installed on container startup:
    #!/bin/bash
echo "Installing dependencies..."
pip install --no-cache-dir beets-audible

    1. Create a docker-compose.yml file (see the full example in the documentation) and run docker-compose up -d to start the container.

    2. Verify the installation inside the container by running beet --version.

  7. Set up a development environment for beets-audible

    main

    To develop on beets-audible, use uv to manage dependencies and run Beets in an isolated environment.

    1. Install Uv.
    2. Install project dependencies using: uv sync --locked --all-extras --dev.
    3. Verify the installation by running Beets from the source environment: uv run beet -v version.

    Note on Plugin Activation: If audible does not appear in the list of plugins shown by the version command, you must manually add it to your Beets configuration file.

    Warning: Installing the beets-copyartifacts3 plugin during development may break the ability to run beets-audible from source.

    uv sync --locked --all-extras --dev
uv run beet -v version

  8. Configure audiobook directory paths

    main

    To ensure compatibility with servers like Booksonic or Audiobookshelf, use specific path patterns in your Beets config. This allows books in a series to be nested correctly and stand-alone books to be organized by artist/album.

    Recommended path patterns:

    • Series books: $albumartist/%ifdef{series_name}/%ifdef{series_position} - $album%aunique{}/$track - $title
    • Stand-alone books: $albumartist/$album%aunique{}/$track - $title
    paths:
  "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
  "albumtype:audiobook": $albumartist/$album%aunique{}/$track - $title
  default: $albumartist/$album%aunique{}/$track - $title

  9. Configure the audible plugin

    main

    The audible plugin requires specific configuration to manage audiobook metadata and folder structures effectively.

    Key configuration options include:

    • match_chapters: If true, attempts to match files to Audible chapters if the file count matches the chapter count.
    • fetch_art: Whether to retrieve cover art.
    • include_narrator_in_artists: Includes author and narrator in the artist tag.
    • write_description_file: Outputs desc.txt.
    • write_reader_file: Outputs reader.txt.
    • region: The Audible region (e.g., us, uk, ca, de, fr, etc.). Defaults to us.
    • goodreads_apikey: Optional key to search Goodreads for original publication dates.

    Note: It is recommended to disable musicbrainz lookup for audiobooks as it is generally unhelpful for this format.

    plugins: audible edit fromfilename scrub

# Disable musicbrainz for audiobooks
musicbrainz:
  enabled: no

audible:
  match_chapters: true
  fetch_art: true
  include_narrator_in_artists: true
  write_description_file: true
  write_reader_file: true
  region: us
  goodreads_apikey: [APIKEYHERE]

  10. Handle file movement limitations

    main

    When Beets performs a data move (for example, after changing your path configuration in config.yaml), it only moves the audio files and cover art.

    Important: The desc.txt and reader.txt files are not moved automatically because Beets does not associate these files with the album in its database. You must move these files manually to the new location to maintain completeness.

  11. View tags written by beets-audible

    main

    The beets-audible plugin writes specific metadata from Audible to your audio files using various ID3 tags. This ensures compatibility with audiobook players and management software. For .m4b files, specific tags like stik (media type) and shwm (show movement) are used to identify the content as an audiobook.

    | 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 |
| `WOAF` (WWWAUDIOFILE) | Audible Album URL |
| `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 |