beets-beatport4

Beatport API v4 plugin for beets

A drop-in replacement for the stock beets beatport plugin, updated for Beatport API v4.

As Beatport killed their API v3, the stock beatport plugin no longer works. It is also currently not possible to request API access the "normal" way (using your client credentials or an API token generated by Beatport), so this plugin uses a workaround: the public API client ID from the Beatport docs frontend.

For more info, see this issue. A pull request has also been opened in the official beets repository — if it gets merged, this plugin may be retired.

Table of Contents

• Installation
• Authorization
  • Method 1: Username and password
  • Method 2: Copy token from the browser
• Album Art
  • Image size
• Singleton Album Metadata
• Genres
• Configuration Reference
• Debug Logging & Sensitive Data

Installation

# if beets was installed with pip:
pip install beets-beatport4

# or, if beets was installed with pipx:
pipx inject beets beets-beatport4

Then add beatport4 to the plugins list in your beets config file.

Beatport Authorization

There are two ways to acquire a user access token for the Beatport v4 API.

Method 1: Username and password

This method is fully automatic and relies on storing your Beatport username and password in your beets config file. It authorizes via the authorization_code grant type using the client_id provided by Beatport for their swagger-ui frontend. By default, the client_id is scraped automatically from that URL. Alternatively, you can set it manually via plugin configuration.

Steps:

1. Add beatport4 to your beets/config.yaml plugins list.
2. Add the following configuration and fill in your credentials:

beatport4:
    username: <YOUR_BEATPORT_USERNAME>
    password: <YOUR_BEATPORT_PASSWORD>

Method 2: Copy token from the browser

Use this method if you don't want to store credentials in the config file, or if something goes wrong during username/password authorization. This is also the fallback method when invalid credentials are provided.

Steps:

1. Add beatport4 to your beets/config.yaml plugins list.
2. When the first import with the plugin enabled happens, you will be prompted to paste the access token JSON.
3. Visit https://api.beatport.com/v4/docs/.
4. Open the Network tab in your browser and start capturing traffic.
5. Log in with your Beatport account.
6. Search for the request to https://api.beatport.com/v4/auth/o/token/.
7. Copy the response (the whole JSON structure).
8. Paste it into the terminal (or save it to a beatport_token.json file next to your beets/config.yaml — check the path with beet config --paths).
9. If the token expires, you will be prompted again to repeat the above steps.

Fetching and Embedding Album Art

This plugin has its own art fetching and embedding, independent of the fetchart and embedart plugins. It uses the beets.art module shipped with the core library. It handles both albums and singletons, but only works when the chosen candidate source is Beatport.

Under the hood, it uses the image URL for the track's release exposed by the Beatport API.

Enable this feature via configuration (disabled by default):

beatport4:
    art: yes

By default, existing art will not be overwritten. To force overwriting:

beatport4:
    art: yes
    art_overwrite: yes

Embedding vs. saving a cover file

By default the image is embedded into the audio files. With art_mode you can instead (or additionally) save it as the album's cover art file, like the stock fetchart plugin does:

beatport4:
    art: yes
    art_mode: file  # embed | file | both

Image size

Original Beatport images can be large, but thanks to Beatport's dynamic image URIs you can request a pre-resized image, saving bandwidth and local processing.

beatport4:
    art: yes
    art_width: 250   # omit or set to 0 to disable
    art_height: 250  # omit or set to 0 to disable

Singleton Album Metadata

When importing singletons (individual tracks), the original Beatport plugin does not populate album-level fields such as year, album name, label, catalog number, album artist, or track number. This plugin can optionally fetch the full release data from Beatport and fill these fields.

Enable the feature via configuration (disabled by default). Individual fields can be toggled off — all default to yes when the feature is enabled:

beatport4:
    singletons_with_album_metadata:
        enabled: yes
        year: yes          # release date (year, month, day)
        album: yes         # album name
        label: yes         # record label
        catalognum: yes    # catalog number
        albumartist: yes   # album artist
        track_number: yes  # track number within the release

Genres

Beatport tracks always carry a main genre (e.g. Trance (Main Floor)) and, for some genres, a more specific sub-genre (e.g. Hard Trance). The genres option controls which of them the plugin passes to beets' multi-value genres field:

beatport4:
    genres: sub   # one of: sub (default), main, both

Configuration Reference

Full example with all defaults:

beatport4:
    art: no
    art_mode: embed
    art_overwrite: no
    art_width: 0
    art_height: 0
    genres: sub
    singletons_with_album_metadata:
        enabled: no
        year: yes
        album: yes
        label: yes
        catalognum: yes
        albumartist: yes
        track_number: yes
    username:
    password:
    client_id:  # optional, scraped automatically from Beatport docs

Debug Logging & Sensitive Data

When running beets with verbose logging (beet -vv), the plugin automatically redacts sensitive information — usernames, emails, authorization codes, and access tokens — replacing them with <REDACTED>. This makes it safe to paste -vv output into bug reports.

If you need the full unredacted output for local debugging, set the BEATPORT4_DEBUG_DISABLE_REDACTION environment variable:

Linux / macOS:

BEATPORT4_DEBUG_DISABLE_REDACTION=1 beet -vv import /path/to/music

Windows (PowerShell):

$env:BEATPORT4_DEBUG_DISABLE_REDACTION = "1"
beet -vv import C:\path\to\music

Windows (cmd):

set BEATPORT4_DEBUG_DISABLE_REDACTION=1
beet -vv import C:\path\to\music

Apart from the above, the plugin works the same way as the stock one — refer to the official documentation for general usage.