beets-beatport4 1.2.0

Plugin for beets (http://beets.io) to replace stock beatport plugin which is not yet compatible with Beatport API v4.

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.

[!WARNING] This method stores your Beatport credentials unencrypted in the config file. If that is a concern, use Method 2 instead.

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

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

[!TIP]

• If you specify only one dimension, the other is set to the same value (1:1 aspect ratio).
• If you omit both dimensions, the original full-size art is downloaded.
• If you specify both dimensions, they are used in the dynamic URI, but Beatport typically returns images in 1:1 aspect ratio using the smaller dimension.

---

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.

[!NOTE] Enabling this triggers an additional API call per matched singleton track to retrieve release data. This may slow down singleton imports.

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

Value	Result for a track with genre Trance (Main Floor) and sub-genre Hard Trance
sub (default)	Hard Trance — the sub-genre, falling back to the main genre when the track has no sub-genre
main	Trance (Main Floor) — always the main genre
both	Trance (Main Floor), Hard Trance — both, main genre first

[!NOTE] Not every Beatport track has a sub-genre — for those, all three settings produce just the main genre.

---

Configuration Reference

Option	Type	Default	Description
art	bool	no	Enable album art fetching and embedding
art_overwrite	bool	no	Overwrite existing art if already present
art_width	int	(none)	Target image width in pixels (0 or omit to disable resizing)
art_height	int	(none)	Target image height in pixels (0 or omit to disable resizing)
genres	sub | main | both	sub	Which Beatport genre fields go into beets' genres: sub-genre (falling back to genre), main genre, or both
singletons_with_album_metadata.enabled	bool	no	Fetch release data for singleton imports
singletons_with_album_metadata.year	bool	yes	Populate release date fields
singletons_with_album_metadata.album	bool	yes	Populate album name
singletons_with_album_metadata.label	bool	yes	Populate record label
singletons_with_album_metadata.catalognum	bool	yes	Populate catalog number
singletons_with_album_metadata.albumartist	bool	yes	Populate album artist
singletons_with_album_metadata.track_number	bool	yes	Populate track number within the release
username	string	(none)	Your Beatport username (for auto-authorization)
password	string	(none)	Your Beatport password (for auto-authorization)
client_id	string	(auto)	Beatport API client ID (scraped automatically from docs)

Full example with all defaults:

beatport4:
    art: no
    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.