Skip to content

API Reference

Everything the CLI does is available from Python. The public surface is the three functions in rekordbox_edit.api and the Pydantic models in rekordbox_edit.models that describe their inputs and outputs.

from pyrekordbox import Rekordbox6Database
from rekordbox_edit.api import search
from rekordbox_edit.models import SearchRequest

db = Rekordbox6Database()
response = search(db, SearchRequest(artist=["Daft Punk"], format=["flac"], match_all=True))
for track in response.tracks:
    print(track.ID, track.Title)

--print json on any CLI command emits exactly these response envelopes, so the models below also document the JSON you get when scripting.

Functions

rekordbox_edit.api.search

Search API for rekordbox-edit.

logger module-attribute 

logger = getLogger(__name__)

search 

search(
    db: Rekordbox6Database, args: SearchRequest
) -> SearchResponse

rekordbox_edit.api.edit

Edit API for rekordbox-edit.

logger module-attribute 

logger = getLogger(__name__)

FIELD_COLUMNS module-attribute 

FIELD_COLUMNS: dict[str, str] = {'Title': 'Title'}

edit 

edit(
    db: Rekordbox6Database,
    args: EditRequest,
    *,
    dry_run: bool = False,
) -> EditResponse

Apply a metadata edit across tracks matching the filter args.

With dry_run=True, returns the planned edits without any DB writes. With dry_run=False (default), commits the changes.

rekordbox_edit.api.convert

Convert API for rekordbox-edit.

logger module-attribute 

logger = getLogger(__name__)

TARGET_BIT_DEPTH module-attribute 

TARGET_BIT_DEPTH = 16

TARGET_SAMPLE_RATE module-attribute 

TARGET_SAMPLE_RATE = 44100

convert 

convert(
    db: Rekordbox6Database,
    args: ConvertRequest,
    *,
    dry_run: bool = False,
) -> ConvertResponse

Convert audio files to a target format and update the Rekordbox database.

With dry_run=True, returns the planned conversions without any ffmpeg or DB writes. With dry_run=False (default), commits the changes.

The rollback block protects only pre-commit work; once a database commit lands, the transaction is honoured even if the delete-originals loop or response re-query later fails.

Models

The models form three layers: the FilterArgs base that every command shares, the per-command requests and responses, and the lower-level domain types those req/resp models are built from.

rekordbox_edit.models.FilterArgs

Bases: BaseModel

Track-selection criteria shared by all commands.

track_id class-attribute instance-attribute 

track_id: list[str] = []

track_ids class-attribute instance-attribute 

track_ids: list[str] = []

title class-attribute instance-attribute 

title: list[str] = []

exact_title class-attribute instance-attribute 

exact_title: list[str] = []

playlist class-attribute instance-attribute 

playlist: list[str] = []

exact_playlist class-attribute instance-attribute 

exact_playlist: list[str] = []

artist class-attribute instance-attribute 

artist: list[str] = []

exact_artist class-attribute instance-attribute 

exact_artist: list[str] = []

album class-attribute instance-attribute 

album: list[str] = []

exact_album class-attribute instance-attribute 

exact_album: list[str] = []

path class-attribute instance-attribute 

path: list[str] = []

exact_path class-attribute instance-attribute 

exact_path: list[str] = []

format class-attribute instance-attribute 

format: list[str] = []

first class-attribute instance-attribute 

first: int | None = Field(default=None, gt=0)

last class-attribute instance-attribute 

last: int | None = Field(default=None, gt=0)

match_all class-attribute instance-attribute 

match_all: bool = False

rekordbox_edit.models.SearchRequest

Bases: FilterArgs

Inputs for search(): the shared track filters, with no search-specific fields.

rekordbox_edit.models.SearchResponse

Bases: BaseModel

tracks instance-attribute 
tracks: list[Track]

Edit

rekordbox_edit.models.EditRequest

Bases: FilterArgs

Inputs for edit(): the shared track filters plus the field to change and its new value.

field instance-attribute 
field: str
replace_value instance-attribute 
replace_value: str
match_pattern class-attribute instance-attribute 
match_pattern: str | None = None
multi class-attribute instance-attribute 
multi: bool = False

rekordbox_edit.models.EditResponse

Bases: BaseModel

tracks instance-attribute 
tracks: list[Track]
result instance-attribute 
result: EditResult

rekordbox_edit.models.EditResult

Bases: BaseModel

Result payload for edit(). edits aligns 1:1 with response.tracks.

field instance-attribute 
field: str
edits instance-attribute 
edits: list[EditOp]
skipped instance-attribute 
skipped: list[SkippedTrack]

Convert

rekordbox_edit.models.ConvertRequest

Bases: FilterArgs

Inputs for convert(): the shared track filters plus output format and original-file handling.

format_out class-attribute instance-attribute 
format_out: str = 'aiff'
delete_originals class-attribute instance-attribute 
delete_originals: DeleteOriginalsMode = 'lossless'

When to delete original files after conversion: "all" always deletes them, "none" never deletes them, and "lossless" (the default) deletes them only when the conversion loses no audio information. Down-sampling to the conversion target counts as lossy, as does MP3 output.

overwrite class-attribute instance-attribute 
overwrite: bool = False

rekordbox_edit.models.ConvertResponse

Bases: BaseModel

tracks instance-attribute 
tracks: list[Track]
result instance-attribute 
result: ConvertResult

rekordbox_edit.models.ConvertResult

Bases: BaseModel

Result payload for convert(). converted aligns 1:1 with response.tracks.

format_out instance-attribute 
format_out: str
converted instance-attribute 
converted: list[ConvertOp]
deleted instance-attribute 
deleted: int
skipped instance-attribute 
skipped: list[SkippedTrack]

Miscellaneous

rekordbox_edit.models.Track

Bases: BaseModel

A Rekordbox track. Field names mirror the DjmdContent table's column names, except where additional derived fields have been added for convenience. What's defined here are just the fields RBE cares about, but all database columns and their raw are silently included in each Track instance, and are included in --print json.

AlbumName class-attribute instance-attribute 
AlbumName: str | None = None
Analysed class-attribute instance-attribute 
Analysed: int | None = None
AnalysisUpdated class-attribute instance-attribute 
AnalysisUpdated: str | None = None
ArtistName class-attribute instance-attribute 
ArtistName: str | None = None
BitDepth class-attribute instance-attribute 
BitDepth: int | None = None
BitRate class-attribute instance-attribute 
BitRate: int | None = None
Commnt class-attribute instance-attribute 
Commnt: str | None = None
DateCreated class-attribute instance-attribute 
DateCreated: str | None = None
FileNameL instance-attribute 
FileNameL: str
FileNameS class-attribute instance-attribute 
FileNameS: str | None = None
FileType class-attribute instance-attribute 
FileType: int | None = None
FolderPath instance-attribute 
FolderPath: str
ID instance-attribute 
ID: str
Length class-attribute instance-attribute 
Length: int | None = None
Rating class-attribute instance-attribute 
Rating: int | None = None
ReleaseDate class-attribute instance-attribute 
ReleaseDate: str | None = None
ReleaseYear class-attribute instance-attribute 
ReleaseYear: int | None = None
SampleRate class-attribute instance-attribute 
SampleRate: int | None = None
Tag class-attribute instance-attribute 
Tag: str | None = None
Title class-attribute instance-attribute 
Title: str | None = None
TrackNo class-attribute instance-attribute 
TrackNo: int | None = None

rekordbox_edit.models.EditOp

Bases: BaseModel

A planned or performed edit: track ID + the value it would / did become.

id instance-attribute 
id: str
new_value instance-attribute 
new_value: str

rekordbox_edit.models.ConvertOp

Bases: BaseModel

A planned or performed conversion: track ID, source/output paths, and the file type, bit depth, and sample rate on each side. Source audio fields mirror the database record; output fields reflect the conversion target, with the sample rate clamped to the source so a conversion never up-samples.

id instance-attribute 
id: str
source_path instance-attribute 
source_path: str
output_path instance-attribute 
output_path: str
source_file_type class-attribute instance-attribute 
source_file_type: str | None = None
source_bit_depth class-attribute instance-attribute 
source_bit_depth: int | None = None
source_sample_rate class-attribute instance-attribute 
source_sample_rate: int | None = None
output_file_type class-attribute instance-attribute 
output_file_type: str | None = None
output_bit_depth class-attribute instance-attribute 
output_bit_depth: int | None = None
output_sample_rate class-attribute instance-attribute 
output_sample_rate: int | None = None

rekordbox_edit.models.SkippedTrack

Bases: BaseModel

A track the command declined to operate on. e.g. A result in a convert command that is already the target format.

id instance-attribute 
id: str
reason instance-attribute 
reason: SkipReason

rekordbox_edit.models.SkipReason module-attribute 

SkipReason: TypeAlias = Literal[
    "no_change",
    "already_target_format",
    "output_file_exists",
]