pyrekordbox.rbxml#

Rekordbox XML database file handler.

exception pyrekordbox.rbxml.XmlElementNotInitializedError(name)[source]#

Bases: Exception

Raised when an XML element is not initialized.

exception pyrekordbox.rbxml.RootNodeNotInitializedError[source]#

Bases: Exception

Raised when the root paylist node is not initialized.

exception pyrekordbox.rbxml.XmlDuplicateError(key_type, key)[source]#

Bases: Exception

Raised when a track already exists in the XML database.

exception pyrekordbox.rbxml.XmlAttributeKeyError(cls, key, attributes)[source]#: Bases: Exception

pyrekordbox.rbxml.encode_path(path)[source]#

Encodes a file path as URI string.

Parameters:

pathstr or Path: The file path to encode.

Returns:

urlstr: The encoded file path as URI string.

Examples

>>> s = r"C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3"  # noqa: W605
>>> encode_path(s)
file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%201.mp3

pyrekordbox.rbxml.decode_path(url)[source]#

Decodes an as URI string encoded file path.

Parameters:

urlstr: The encoded file path to decode.

Returns:

pathstr: The decoded file path.

Examples

>>> s = r"file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%201.mp3"
>>> decode_path(s)
C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3  # noqa: W605

class pyrekordbox.rbxml.AbstractElement(element=None, *args, **kwargs)[source]#

Bases: Mapping

Abstract base class for Rekordbox XML elements.

Implements attribute getters and setters for an XML element

TAG#

Name of the XML element

Type:: str

ATTRIBS#

List of all attribute keys of the XML element

Type:: list[str]

GETTERS = {}#

Dictionary of attribute getter conversion methods.

See also

AbstractElement.get

Type:: dict[str, Callable]

SETTERS = {}#

Dictionary of attribute setter conversion methods.

See also

AbstractElement.set

Type:: dict[str, Callable]

get(key, default=None)[source]#

Returns the value of an attribute of the XML element.

The type of the attribute value is converted if a conversion method is specified in the GETTERS class attribute. If no conversion method is found the value is returned unconverted as the default type str.

Parameters:

keystr: The key of the attribute.
defaultAny, optional: The default value returned if the attribute does not exist.

Returns:

valueAny: The value of the atttribute. The type of the attribute is converted acccording to the data of the field.

Raises:

XmlAttributeKeyError:: Raised if key is not a valid attribute key.

set(key, value)[source]#

Sets the value of an attribute of the XML element.

The type of the given value is converted before updating the attribute if a conversion method is specified in the SETTERS class attribute. If no conversion method is found the value updated set as given.

Parameters:

keystr: The key of the attribute.
valueAny: The value for updating the attribute. The type conversion is handled automatically.

Raises:

XmlAttributeKeyError:: Raised if key is not a valid attribute key.

class pyrekordbox.rbxml.Tempo(parent=None, Inizio=0.0, Bpm=0.0, Metro='4/4', Battito=1, element=None)[source]#

Bases: AbstractElement

Tempo element representing the beat grid of a track.

Attributes:

Iniziofloat: The start position of the beat grid item.
Bpmfloat: The BPM value of the beat grid item.
Metrostr: The kind of musical meter, for example ‘4/4’. The default is ‘4/4’.
Battitoint: The beat number in the bar. If metro is ‘4/4’, the value can be 1, 2, 3 or 4.

TAG = 'TEMPO'#

Name of the XML element

Type:: str

ATTRIBS = ['Inizio', 'Bpm', 'Metro', 'Battito']#

List of all attribute keys of the XML element

Type:: list[str]

GETTERS = {'Battito': <class 'int'>, 'Bpm': <class 'float'>, 'Inizio': <class 'float'>}#

Dictionary of attribute getter conversion methods.

See also

AbstractElement.get

Type:: dict[str, Callable]

class pyrekordbox.rbxml.PositionMark(parent=None, Name='', Type='cue', Start=0.0, End=None, Num=-1, element=None)[source]#

Bases: AbstractElement

Position element for storing position markers like cue points of a track.

Attributes:

Namestr: The name of the position mark.
Typestr: The type of position mark. Can be ‘cue’, ‘fadein’, ‘fadeout’, ‘load’ or ‘loop’.
Startfloat: Start position of the position mark in seconds.
Endfloat, optionl: End position of the position mark in seconds.
Numint, optional: Charakter for identification of the position mark (for hot cues). For memory cues this is always -1.

TAG = 'POSITION_MARK'#

Name of the XML element

Type:: str

ATTRIBS = ['Name', 'Type', 'Start', 'End', 'Num']#

List of all attribute keys of the XML element

Type:: list[str]

GETTERS = {'End': <class 'float'>, 'Num': <class 'int'>, 'Start': <class 'float'>, 'Type': <bound method Mapping.get of bidict({'0': 'cue', '1': 'fadein', '2': 'fadeout', '3': 'load', '4': 'loop'})>}#

Dictionary of attribute getter conversion methods.

See also

AbstractElement.get

Type:: dict[str, Callable]

SETTERS = {'Type': <bound method Mapping.get of bidict({'cue': '0', 'fadein': '1', 'fadeout': '2', 'load': '3', 'loop': '4'})>}#

Dictionary of attribute setter conversion methods.

See also

AbstractElement.set

Type:: dict[str, Callable]

class pyrekordbox.rbxml.Track(parent=None, Location='', element=None, **kwargs)[source]#

Bases: AbstractElement

Track element for storing the metadata of a track.

Raises:

XmlAttributeKeyError:: Raised if initialized with invalid key in attributes.

Attributes:

TrackIDint: Identification of the track.
Name: str: The name of the track.
Artiststr: The name of the artist.
Composerstr: The name of the composer (or producer).
Albumstr: The name of the album.
Groupingstr: The name of the grouping.
Genrestr: The name of the genre.
Kindstr: The kind of the audio file, for example ‘WAV File’ or ‘MP3 File’.
Sizeint: The size of the audio file.
TotalTimeint: The duration of the track in seconds.
DiscNumberint: The number of the disc of the album.
TrackNumberint: The Number of the track of the album.
Yearint: The year of release.
AverageBpmfloat: The average BPM of the track.
DateModifiedstr: The date of last modification in the format ‘yyyy-mm-dd’.
DateAddedstr: The date of addition modification in the format ‘yyyy-mm-dd’.
BitRateint: The encoding bit rate.
SampleRatefloat: The frequency of sampling.
Commentsstr: The comments of the track.
PlayCountint: The play count of the track.
LastPlayedstr: The date of last playing in the format ‘yyyy-mm-dd’.
Ratingint: The rating of the track using the mapping 0=0, 1=51, 2=102, 3=153, 4=204, 5=255.
Locationstr: The location of the file encoded as URI string. This value is essential for each track.
Remixerstr: The name of the remixer.
Tonalitystr: The tonality or kind of musical key.
Labelstr: The name of the record label.
Mixstr: The name of the mix.
Colourstr: The color for track grouping in RGB format.
temposlist: The Tempo elements of the track.
markslist: The PositionMark elements of the track.

TAG = 'TRACK'#

Name of the XML element

Type:: str

ATTRIBS = ['TrackID', 'Name', 'Artist', 'Composer', 'Album', 'Grouping', 'Genre', 'Kind', 'Size', 'TotalTime', 'DiscNumber', 'TrackNumber', 'Year', 'AverageBpm', 'DateModified', 'DateAdded', 'BitRate', 'SampleRate', 'Comments', 'PlayCount', 'LastPlayed', 'Rating', 'Location', 'Remixer', 'Tonality', 'Label', 'Mix', 'Colour']#

List of all attribute keys of the XML element

Type:: list[str]

GETTERS = {'AverageBpm': <class 'float'>, 'BitRate': <class 'int'>, 'DiscNumber': <class 'int'>, 'Location': <function decode_path>, 'PlayCount': <class 'int'>, 'Rating': <bound method Mapping.get of bidict({'0': 0, '51': 1, '102': 2, '153': 3, '204': 4, '255': 5})>, 'SampleRate': <class 'float'>, 'Size': <class 'int'>, 'TotalTime': <class 'int'>, 'TrackID': <class 'int'>, 'TrackNumber': <class 'int'>, 'Year': <class 'int'>}#

Dictionary of attribute getter conversion methods.

See also

AbstractElement.get

Type:: dict[str, Callable]

SETTERS = {'Location': <function encode_path>, 'Rating': <bound method Mapping.get of bidict({0: '0', 1: '51', 2: '102', 3: '153', 4: '204', 5: '255'})>}#

Dictionary of attribute setter conversion methods.

See also

AbstractElement.set

Type:: dict[str, Callable]

add_tempo(Inizio, Bpm, Metro, Battito)[source]#

Adds a new Tempo XML element to the track element.

Parameters:

Iniziofloat: The start position of the beat grid item.
Bpmfloat: The BPM value of the beat grid item.
Metrostr, optional: The kind of musical meter, for example ‘4/4’. The default is ‘4/4’.
Battitoint: The beat number in the bar. If metro is ‘4/4’, the value can be 1, 2, 3 or 4.

Returns:

tempoTempo: The newly created tempo XML element.

See also

Tempo: Beat grid XML element handler

add_mark(Name='', Type='cue', Start=0.0, End=None, Num=-1)[source]#

Adds a new PositionMark XML element to the track element.

Parameters:

Namestr: The name of the position mark.
Typestr: The type of position mark. Can be ‘cue’, ‘fadein’, ‘fadeout’, ‘load’ or ‘loop’.
Startfloat: Start position of the position mark in seconds.
Endfloat or None, optionl: End position of the position mark in seconds.
Numint, optional: Charakter for identification of the position mark (for hot cues). For memory cues this is always -1.

Returns:

position_markPositionMark: The newly created position mark XML element.

See also

PositionMark: Position mark XML element handler

class pyrekordbox.rbxml.Node(parent=None, element=None, **attribs)[source]#

Bases: object

Node element used for representing playlist folders and playlists.

A node configured as playlist folder can store other nodes as well as tracks, a node configured as playlist can only store tracks. The tracks in playlists are stored via a key depending on the key type of the playlist. The key type can either be the ID of the track in the XML database (‘TrackID’) or the file path of the track (‘Location’).

TAG = 'NODE'#

Name of the XML element

Type:: str

FOLDER = 0#

PLAYLIST = 1#

classmethod folder(parent, name)[source]#

Initializes a playlist folder node XML element.

Parameters:

parentNode: The parent node XML element of the new playlist folder node.
namestr: The name of the playlist folder node.

classmethod playlist(parent, name, keytype='TrackID')[source]#

Initializes a playlist node XML element.

Parameters:

parentxml.Element: The parent node XML element of the new playlist node.
namestr: The name of the playlist node.
keytypestr, optional: The key type used by the playlist node. Can be ‘TrackID’ or ‘Location’ (file path of the track).

property parent#

The parent of the node.

Type:: xml.Element

property name#

The name of the node.

Type:: str

property type#

The type of the node (0=folder or 1=playlist).

Type:: int

property count#

The number of attributes of the XML element.

Type:: int

property entries#

The number of entries of the node.

Type:: int

property key_type#

The type of key used by the playlist node.

Type:: str

property is_folder#

True if the node is a playlist folder, false if otherwise.

Type:: bool

property is_playlist#

True if the node is a playlist, false if otherwise.

Type:: bool

get_node(i)[source]#

Returns the i-th sub-Node of the current node.

Parameters:

iint: Index of sub-Node

Returns:

subnodeNode

get_playlist(name)[source]#

Returns the sub-Node with the given name.

Parameters:

namestr: Name of the sub-Node

Returns:

subnodeNode

get_playlists()[source]#

Returns all sub-nodes that are playlists.

Returns:

playlistslist[Node]: The playlist nodes in the current node.

add_playlist_folder(name)[source]#

Add a new playlist folder as child to this node.

Parameters:

namestr: The name of the new playlist folder.

Returns:

folder_nodeNode: The newly created playlist folder node.

Raises:

ValueError:: Raised if called on a playlist node.

add_playlist(name, keytype='TrackID')[source]#

Add a new playlist as child to this node.

Parameters:

namestr: The name of the new playlist.
keytype{‘TrackID’, ‘Location’} str: The type of key the playlist uses to store the tracks. Can either be ‘TrackID’ or ‘Location’.

Returns:

playlist_nodeNode: The newly created playlist node.

Raises:

ValueError:: Raised if called on a playlist node.

remove_playlist(name)[source]#

Removes a playlist from the playlist folder node.

Parameters:

namestr: The name of the playlist to remove.

add_track(key)[source]#

Adds a new track to the playlist node.

Parameters:

keyint or str: The key of the track to add, depending on the type of the playlist node.

Returns:

elxml.SubElement: The newly created playlist track element.

remove_track(key)[source]#

Removes a track from the playlist node.

Parameters:

keyint or str: The key of the track to remove, depending on the type attribute of the playlist node.

get_tracks()[source]#

Returns the keys of all tracks contained in the playlist node.

Returns:

keyslist: The keys of the tracks in the playlist. The format depends on the type attribute of the playlist node.

get_track(key)[source]#: Returns the formatted key of the track.

treestr(indent=4, lvl=0)[source]#

returns a formatted string of the node tree strucutre.

Parameters:

indentint, optional: Number of spaces used for indenting.
lvlint, optional: Internal parameter for recursion, don’t use!

Returns:

sstr: The formatted tree string.

class pyrekordbox.rbxml.RekordboxXml(path=None, name=None, version=None, company=None)[source]#

Bases: object

Rekordbox XML database object.

The XML database contains the tracks and playlists in the Rekordbox collection. By importing the database, new tracks and items can be added to the Rekordbox collection.

If a file path is passed to the constructor of the RekordboxXml object, the file is opened and parsed. Otherwise, an empty file is created with the given arguments. Creating an importable XML file requires a product name, xml database version and company name.

Examples

Open Rekordbox XML file

>>> file = RekordboxXml(Path(".testdata", "rekordbox 6", "database.xml"))

Create new XML file

>>> file = RekordboxXml()

Attributes:

pathstr, optional: The file path to

ROOT_TAG = 'DJ_PLAYLISTS'#

PRDT_TAG = 'PRODUCT'#

PLST_TAG = 'PLAYLISTS'#

COLL_TAG = 'COLLECTION'#

property frmt_version#

The version of the Rekordbox XML format.

Type:: str

property product_name#

The product name that will be displayed in the software.

Type:: str

property product_version#

The product version.

Type:: str

property product_company#

The company name.

Type:: str

property num_tracks#

The number of tracks in the collection.

Type:: int

property root_playlist_folder#

The node of the root playlist folder containing all other nodes.

Type:: Node

get_tracks()[source]#

Returns the tracks in the collection of the XML file.

Returns:

trackslist of Track: A list of the track objects in the collection.

get_track(index=None, TrackID=None, Location=None)[source]#

Get a track in the collection of the XML file.

Parameters:

indexint, optional: If index is given, the track with this index in the collection is returned.
TrackIDint or str, optional: If TrackID is given, the track with this ID in the collection is returned.
Locationstr, optional: If Location is given, the track with this file path in the collection is returned.

Returns:

trackTrack: The XML track element.

Raises:

ValueError:: Raised if neither the index of the track id is specified.

Examples

Get track by index

>>> file = RekordboxXml("database.xml")
>>> track = file.get_track(0)

or by TrackID

>>> track = file.get_track(TrackID=1)

get_track_ids()[source]#

Returns the TrackID of all tracks in the collection of the XML file.

Returns:

idslist of int: The ID’s of all tracks.

get_playlist(*names)[source]#

Returns a playlist or playlist folder with the given path.

Parameters:

*namesstr: Names in the path. If no names are given the root playlist folder is returned.

Returns:

nodeNode: The playlist or playlist folder node.

Examples

>>> file = RekordboxXml("database.xml")
>>> playlist = file.get_playlist("Folder", "Sub Playlist")

add_track(location, **kwargs)[source]#

Add a new track element to the Rekordbox XML collection.

Parameters:

locationstr or Path: The file path of the track.
kwargs: Keyword arguments which are used to fill the track attributes. If no argument for TrackID is given the ID is auto-incremented.

Returns:

trackTrack: The newly created XML track element.

Raises:

ValueError:: Raised if the database already contains a track with the track-id or file path.

Examples

>>> file = RekordboxXml("database.xml")
>>> _ = file.add_track("path/to/track.wav")

remove_track(track)[source]#

Remove a track element from the Rekordbox XML collection.

Parameters:

trackTrack: The XML track element to remove.

Examples

>>> file = RekordboxXml("database.xml")
>>> t = file.get_track(0)
>>> file.remove_track(t)

add_playlist_folder(name)[source]#

Add a new top-level playlist folder to the XML collection.

Parameters:

namestr: The name of the new playlist folder.

Returns:

folder_nodeNode: The newly created playlist folder node.

See also

Node.add_playlist_folder

Examples

>>> file = RekordboxXml("database.xml")
>>> file.add_playlist_folder("New Folder")

add_playlist(name, keytype='TrackID')[source]#

Adds a new top-level playlist to the XML collection.

Parameters:

namestr: The name of the new playlist.
keytype{‘TrackID’, ‘Location’} str: The type of key the playlist uses to store the tracks. Can either be ‘TrackID’ or ‘Location’.

Returns:

playlist_nodeNode: The newly created playlist node.

See also

Node.add_playlist

Examples

Create playlist using the track ID as keys

>>> file = RekordboxXml("database.xml")
>>> file.add_playlist("New Playlist", keytype="TrackID")

Create playlist using the file paths as keys

>>> file.add_playlist("New Playlist 2", keytype="Location")

tostring(indent=None, encoding='utf-8')[source]#

Returns the contents of the XML file as a string.

Parameters:

indentstr, optional: The indentation used for formatting the XML file. The default is ‘t’.
encodingstr, optional: The encoding used for the XML file. The default is ‘utf-8’.

Returns:

sstr: The contents of the XML file

save(path='', indent=None, encoding='utf-8')[source]#

Saves the contents to an XML file.

Parameters:

pathstr or Path, optional: The path for saving the XML file. The default is the original file.
indentstr, optional: The indentation used for formatting the XML file. The default is ‘t’.
encodingstr, optional: The encoding used for the XML file. The default is ‘utf-8’.