pyrekordbox 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

docs/source/formats/xml.md

@@ -0,0 +1,376 @@
+# XML Database Format
+
+The Rekordbox XML format is well documented by Pioneer in [^footnote-1] and [^footnote-2].
+
+The first entry of the XML file should be displayed as follows:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+```
+
+```{warning}
+In order to save playlists and their information to Rekordbox, all rows from the
+second row and beyond must follow a format which rekordbox supports.
+```
+
+## General structure
+
+The general structure of the Rekordbox XML file is as follows:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<DJ_PLAYLISTS Version="1.0.0">
+        <PRODUCT Name="rekordbox" Version="5.4.3" Company="Pioneer DJ"/>
+        <COLLECTION Entries="1234">
+                <TRACK TrackID="1" Name="NOISE" Artist="" Composer="" Album="" Grouping=""
+                           Genre="" Kind="WAV File" Size="1382226" TotalTime="5" DiscNumber="0"
+                           TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2017-09-07"
+                           BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0"
+                           Location="file://localhost/C:/Users/user/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/NOISE.wav"
+                           Remixer="" Tonality="" Label="" Mix=""/>
+                <TRACK TrackID="2" Name="SINEWAVE" Artist="" Composer="" Album="" Grouping=""
+                           Genre="" Kind="WAV File" Size="1515258" TotalTime="5" DiscNumber="0"
+                           TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2017-09-07"
+                           BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0"
+                           Location="file://localhost/C:/Users/user/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/SINEWAVE.wav"
+                           Remixer="" Tonality="" Label="" Mix="">
+                        <TEMPO Inizio="0.232" Bpm="172.00" Metro="4/4" Battito="1"/>
+                        <POSITION_MARK Name="" Type="0" Start="0.232" Num="-1"/>
+                        ...
+                </TRACK>
+                ...
+        </COLLECTION>
+        <PLAYLISTS>
+                <NODE Type="0" Name="ROOT" Count="11">
+                        <NODE Name="Favourites" Type="1" KeyType="0" Entries="56">
+                                <TRACK Key="1"/>
+                                <TRACK Key="2"/>
+                                ...
+                        </NODE>
+                </NODE>
+                ...
+        </PLAYLISTS>
+</DJ_PLAYLISTS>
+```
+
+## Supported Elements and Attributes
+
+```{eval-rst}
+.. list-table:: Supported Rekordbox XML elements and attributes
+   :widths: 1 1 1 1
+   :header-rows: 1
+
+   * - Element
+     - Description
+     - Type
+     - Notes
+   * - **DJ_PLAYLIST**
+     -
+     -
+     -
+   * - *Version*
+     - Version of XML format
+     - utf-8
+     - The latest version is 1.0.0
+   * - **PRODUCT**
+     -
+     -
+     -
+   * - *Name*
+     - Name of product
+     - utf-8
+     - This name will be displayed in each application software.
+   * - *Version*
+     - Version of application
+     - utf-8
+     -
+   * - *Company*
+     - Name of company
+     - utf-8
+     -
+   * - **COLLECTION**
+     -
+     -
+     -
+   * - *Entries*
+     - Number of TRACK in COLLECTION
+     - sint32
+     -
+   * - **TRACK**
+     -
+     -
+     - "Location" is essential for each track
+   * - *TrackID*
+     - Identification of track
+     - utf-8
+     -
+   * - *Name*
+     - Name of track
+     - utf-8
+     -
+   * - *Artist*
+     - Name of artist
+     - utf-8
+     -
+   * - *Composer*
+     - Name of composer (or producer)
+     - utf-8
+     -
+   * - *Album*
+     - Name of album
+     - utf-8
+     -
+   * - *Grouping*
+     - Name of group
+     - utf-8
+     -
+   * - *Genre*
+     - Name of genre
+     - utf-8
+     -
+   * - *Kind*
+     - Type of audio file
+     - utf-8
+     -
+   * - *Size*
+     - Size of audio file
+     - sint64
+     - Unit: Octet
+   * - *TotalTime*
+     - Duration of track
+     - float64
+     - Unit: Second (without decimal numbers)
+   * - *DiscNumber*
+     - Number of the disc of the album
+     - sint32
+     -
+   * - *TrackNumber*
+     - Number of the track of the album
+     - sint32
+     -
+   * - *Year*
+     - Year of release
+     - sint32
+     -
+   * - *AverageBpm*
+     - Value of average BPM
+     - float64
+     - Unit: Second (with decimal numbers)
+   * - *DateModified*
+     - Date of last modification
+     - utf-8
+     - Format: yyyy-mm-dd; ex.: 2010-08-21
+   * - *DateAdded*
+     - Date of addition
+     - utf-8
+     - Format: yyyy-mm-dd; ex.: 2010-08-21
+   * - *BitRate*
+     - Encoding bit rate
+     - sint32
+     - Unit: Kbps
+   * - *SampleRate*
+     - Frequency of sampling
+     - float64
+     - Unit: Hertz
+   * - *Comments*
+     - Comments
+     - utf-8
+     -
+   * - *PlayCount*
+     - Play count of the track
+     - sint32
+     -
+   * - *LastPlayed*
+     - Date of last playing
+     - utf-8
+     - Format: yyyy-mm-dd; ex.: 2010-08-21
+   * - *Rating*
+     - Rating of the track
+     - sint32
+     - 0="0", 1="51", 2="102", 3="153", 4="204", 5="255"
+   * - *Location*
+     - Location of the file
+     - utf-8 (URI)
+     - includes the file name
+   * - *Remixer*
+     - Name of remixer
+     - utf-8
+     -
+   * - *Tonality*
+     - Tonality (Kind of musical key)
+     - utf-8
+     -
+   * - *Label*
+     - Name of record label
+     - utf-8
+     -
+   * - *Mix*
+     - Name of mix
+     - utf-8
+     -
+   * - *Colour*
+     - Colour for track grouping
+     - utf-8
+     - RGB format (3 bytes)
+   * - **TEMPO**
+     -
+     -
+     - BeatGrid; More than two "TEMPO" can exist for each track
+   * - *Inizio*
+     - Start position of BeatGrid
+     - float64
+     - Unit: Second (with decimal numbers)
+   * - *Bpm*
+     - Value of BPM
+     - float64
+     - Unit: Second (with decimal numbers)
+   * - *Metro*
+     - Kind of musical meter
+     - utf-8
+     - ex. 3/4, 4/4, 7/8 ...
+   * - *Battito*
+     - Beat number in the bar
+     - sint32
+     - If "Metro" is 4/4, the value should be 1, 2, 3 or 4
+   * - **POSITION_MARK**
+     -
+     -
+     - More than two "POSITION MARK" can exist for each track
+   * - *Name*
+     - Name of position mark
+     - utf-8
+     -
+   * - *Type*
+     - Type of position mark
+     - sint32
+     - Cue="0", Fade-In="1", Fade-Out="2", Load="3", Loop="4"
+   * - *Start*
+     - Start position of position mark
+     - float64
+     - Unit: Second (with decimal numbers)
+   * - *End*
+     - End position of position mark
+     - float64
+     - Unit: Second (with decimal numbers)
+   * - *Num*
+     - Number of the position mark
+     - sint32
+     - Hot Cue: A="0", B="1", C="2"; Memory Cue: "-1"
+
+```
+
+Playlists are a bit more complex since they are nested:
+
+```{eval-rst}
+.. list-table:: Supported Rekordbox XML playlist elements and attributes
+   :widths: 1 1 1 1
+   :header-rows: 1
+
+   * - Element
+     - Description
+     - Type
+     - Notes
+   * - **NODE**
+     -
+     -
+     -
+   * - *Type*
+     - Type of NODE
+     - sint32
+     - "0" (FOLDER)
+   * - *Name*
+     - Name of NODE
+     - utf-8
+     - ("ROOT")
+   * - *Count*
+     - Number of items in the NODE
+     - sint32
+     -
+   * - **NODE**
+     -
+     -
+     -
+   * - *Type*
+     - Type of NODE
+     - sint32
+     - "0" (FOLDER)
+   * - *Name*
+     - Name of NODE
+     - utf-8
+     - ("ROOT")
+   * - (if "Type" == "1")
+     -
+     -
+     - Node is a PLAYLIST
+   * - *Entries*
+     - Number of TRACK in PLAYLIST
+     - sint32
+     -
+   * - *KeyType*
+     - Kind of identification
+     - sint32
+     - "0" (Track ID) or "1"(Location)
+   * - **TRACK**
+     -
+     -
+     -
+   * - *Key*
+     - Identification of track
+     - sint32/utf-8
+     -
+   * - (if "Type" == "0")
+     -
+     -
+     - Node is a FOLDER
+   * - *Count*
+     - Number of items in the NODE
+     - sint32
+     -
+
+```
+
+Rekordbox track colors:
+
+```{eval-rst}
+.. list-table:: Rekordbox group colors
+   :widths: 1 1 1
+   :header-rows: 1
+
+   * - Name
+     - Hex
+     - RGB
+   * - Rose
+     - 0xFF007F
+     - 255, 0, 127
+   * - Red
+     - 0xFF0000
+     - 255, 0, 0
+   * - Orange
+     - 0xFFA500
+     - 255, 165, 0
+   * - Lemon
+     - 0xFFFF00
+     - 255, 255, 0
+   * - Green
+     - 0x00FF00
+     - 0, 255, 0
+   * - Turquoise
+     - 0x25FDE9
+     - 37, 253, 233
+   * - Blue
+     - 0x0000FF
+     - 0, 0, 255
+   * - Violet
+     - 0x660099
+     - 102, 0, 153
+
+```
+
+## References
+
+[^footnote-1]: Rekordbox for developers.
+    <https://rekordbox.com/en/support/developer/>
+
+[^footnote-2]: Rekordbox XML format
+    <https://cdn.rekordbox.com/files/20200410160904/xml_format_list.pdf>

docs/source/index.md

@@ -0,0 +1,105 @@
+<!--
+pyrekordbox documentation master file, created by
+sphinx-quickstart on Thu Apr  7 15:06:50 2022.
+-->
+
+# Pyrekordbox documentation
+
+[![Tests][tests-badge]][tests-link]
+[![Codecov][codecov-badge]][codecov-link]
+[![Version][pypi-badge]][pypi-link]
+[![Python][python-badge+]][pypi-link]
+[![Platform][platform-badge]][pypi-link]
+[![license: MIT][license-badge]][license-link]
+[![style: black][black-badge]][black-link]
+
+```{admonition} Disclaimer
+This project is not affiliated with Pioneer Corp. or its related companies
+in any way or form and has been written independently! Pyrekordbox is licensed
+under the [MIT license][license-link].
+The maintainers of the project are not liable for any damages to your Rekordbox library.
+```
+
+Pyrekordbox is a Python package for interacting with the library and export data of
+Pioneer's Rekordbox DJ Software. It currently supports
+
+- Rekordbox 6 `master.db` database
+- Rekordbox XML database
+- Analysis files (ANLZ)
+- My-Settings files
+
+Tested Rekordbox versions: `5.8.6 | 6.5.3 | 6.7.7`
+
+```{warning}
+This project is still under development and might contain bugs or
+have breaking API changes in the future.
+```
+
+## Contents
+
+```{toctree}
+---
+maxdepth: 2
+caption: User Guide
+---
+
+quickstart
+installation
+tutorial/index
+api
+```
+
+```{toctree}
+---
+maxdepth: 2
+caption: File formats
+---
+
+formats/db6
+formats/xml
+formats/anlz
+formats/mysetting
+```
+
+```{toctree}
+---
+maxdepth: 1
+caption: Development
+---
+
+development/contributing
+development/changes
+```
+
+```{toctree}
+---
+hidden:
+caption: Project Links
+---
+
+GitHub <https://github.com/dylanljones/pyrekordbox>
+PyPI <https://pypi.org/project/pyrekordbox/>
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`search`
+
+
+[tests-badge]: https://img.shields.io/github/actions/workflow/status/dylanljones/pyrekordbox/tests.yml?branch=master&label=tests&logo=github&style=flat
+[codecov-badge]: https://codecov.io/gh/dylanljones/pyrekordbox/branch/master/graph/badge.svg?token=5Z2KVGL7N3
+[python-badge]: https://img.shields.io/pypi/pyversions/pyrekordbox?style=flat
+[python-badge+]: https://img.shields.io/badge/python-3.7+-blue.svg
+[platform-badge]: https://img.shields.io/badge/platform-win%20%7C%20osx-blue?style=flat
+[pypi-badge]: https://img.shields.io/pypi/v/pyrekordbox?style=flat
+[license-badge]: https://img.shields.io/pypi/l/pyrekordbox?color=lightgrey
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000?style=flat
+
+[pypi-link]: https://pypi.org/project/pyrekordbox/
+[license-link]: https://github.com/dylanljones/pyrekordbox/blob/master/LICENSE
+[tests-link]: https://github.com/dylanljones/pyrekordbox/actions/workflows/tests.yml
+[black-link]: https://github.com/psf/black
+[codecov-link]: https://app.codecov.io/gh/dylanljones/pyrekordbox/tree/master
+
+[issue]: https://github.com/dylanljones/pyrekordbox/issues/64

docs/source/installation.md

@@ -0,0 +1,3 @@
+```{include} ../../INSTALLATION.md
+
+```

docs/source/quickstart.md

@@ -0,0 +1,185 @@
+# Quick-Start
+
+
+Pyrekordbox can be installed via:
+````shell
+$ pip install pyrekordbox
+````
+
+See the {doc}`Installation</installation>` section for more details.
+
+```{attention}
+Please make sure to back up your Rekordbox collection before making
+any changes with pyrekordbox or developing/testing new features.
+
+The backup dialog can be found under "File" > "Library" > "Backup Library"
+```
+
+
+## Configuration
+
+Pyrekordbox looks for installed Rekordbox versions and sets up the configuration
+automatically. The configuration can be checked by calling:
+````python
+from pyrekordbox import show_config
+
+show_config()
+````
+If for some reason the configuration fails the values can be updated by providing the
+paths to the directory where Pioneer applications are installed (`pioneer_install_dir`)
+and to the directory where Pioneer stores the application data  (`pioneer_app_dir`)
+````python
+from pyrekordbox.config import update_config
+
+update_config("<pioneer_install_dir>", "<pioneer_app_dir>")
+````
+Alternatively the two paths can be specified in a configuration file under the section
+`rekordbox`. Supported configuration files are pyproject.toml, setup.cfg, pyrekordbox.toml,
+pyrekordbox.cfg and pyrekordbox.yaml.
+
+
+## Rekordbox 6 database
+
+Rekordbox 6 now uses a SQLite database for storing the collection content.
+Unfortunatly, the new `master.db` SQLite database is encrypted using
+[SQLCipher][sqlcipher], which means it can't be used without the encryption key.
+However, since your data is stored and used locally, the key must be present on the
+machine running Rekordbox.
+
+Pyrekordbox can unlock the new Rekordbox `master.db` SQLite database and provides
+an easy interface for accessing the data stored in it:
+
+````python
+from pyrekordbox import Rekordbox6Database
+
+db = Rekordbox6Database()
+
+for content in db.get_content():
+    print(content.Title, content.Artist.Name)
+
+playlist = db.get_playlist()[0]
+for song in playlist.Songs:
+    content = song.Content
+    print(content.Title, content.Artist.Name)
+````
+Fields in the Rekordbox database that are stored without linking to other tables
+can be changed via the corresponding property of the object:
+````python
+content = db.get_content()[0]
+content.Title = "New Title"
+````
+Some fields are stored as references to other tables, for example the artist of a track.
+Check the [documentation](#db6-format) of the corresponding object for more information.
+So far only a few tables support adding or deleting entries:
+- ``DjmdPlaylist``: Playlists/Playlist Folders
+- ``DjmdSongPlaylist``: Songs in a playlist
+
+````{important}
+Starting from Rekordbox version ``6.6.5`` Pioneer obfuscated the ``app.asar`` file
+contents, breaking the key extraction (see [this discussion](https://github.com/dylanljones/pyrekordbox/discussions/97) for more details).
+If you are using a later version of Rekorbox and have no cached key from a previous
+version, the database can not be unlocked automatically.
+The command line interface of ``pyrekordbox`` provides a command for downloading
+the key from known sources and writing it to the cache file:
+```shell
+python -m pyrekordbox download-key
+```
+Once the key is cached the database can be opened without providing the key.
+The key can also be provided manually:
+```python
+db = Rekordbox6Database(key="<insert key here>")
+```
+````
+
+
+## Rekordbox XML
+
+The Rekordbox XML database is used for importing (and exporting) Rekordbox collections
+including track metadata and playlists. They can also be used to share playlists
+between two databases.
+
+Pyrekordbox can read and write Rekordbox XML databases.
+
+````python
+from pyrekordbox.xml import RekordboxXml
+
+xml = RekordboxXml("database.xml")
+
+track = xml.get_track(0)    # Get track by index (or TrackID)
+track_id = track.TrackID    # Access via attribute
+name = track["Name"]        # or dictionary syntax
+
+path = "/path/to/file.mp3"
+track = xml.add_track(path) # Add new track
+track["Name"] = "Title"     # Add attributes to new track
+track["TrackID"] = 10       # Types are handled automatically
+
+# Get playlist (folder) by path
+pl = xml.get_playlist("Folder", "Sub Playlist")
+keys = pl.get_tracks()  # Get keys of tracks in playlist
+ktype = pl.key_type     # Key can either be TrackID or Location
+
+# Add tracks and sub-playlists (folders)
+pl.add_track(track.TrackID)
+pl.add_playlist("Sub Sub Playlist")
+````
+
+## Rekordbox ANLZ files
+
+Rekordbox stores analysis information of the tracks in the collection in specific files,
+which also get exported to decives used by Pioneer professional DJ equipment. The files
+have names like `ANLZ0000` and come with the extensions `.DAT`, `.EXT` or `.2EX`.
+They include waveforms, beat grids (information about the precise time at which
+each beat occurs), time indices to allow efficient seeking to specific positions
+inside variable bit-rate audio streams, and lists of memory cues and loop points.
+
+Pyrekordbox can parse all three analysis files, although not all the information of
+the tracks can be extracted yet.
+
+````python
+from pyrekordbox.anlz import AnlzFile
+
+anlz = AnlzFile.parse_file("ANLZ0000.DAT")
+beat_grid = anlz.get("beat_grid")
+path_tags = anlz.getall_tags("path")
+````
+
+Changing and creating the Rekordbox analysis files is planned as well, but for that the
+full structure of the analysis files has to be understood.
+
+
+```{note}
+Some ANLZ tags are still unsupported:
+  - PCOB
+  - PCO2
+  - PSSI
+  - PWV6
+  - PWV7
+  - PWVC
+```
+
+
+## Rekordbox My-Settings
+
+Rekordbox stores the user settings in `*SETTING.DAT` files, which get exported to USB
+devices. These files are either in the `PIONEER`directory of a USB drive
+(device exports), but are also present for on local installations of Rekordbox 6.
+The setting files store the settings found on the "DJ System" > "My Settings" page of
+the Rekordbox preferences. These include language, LCD brightness, tempo fader range,
+crossfader curve and other settings for Pioneer professional DJ equipment.
+
+Pyrekordbox supports both parsing and writing My-Setting files.
+
+````python
+from pyrekordbox.mysettings import read_mysetting_file
+
+mysett = read_mysetting_file("MYSETTINGS.DAT")
+sync = mysett.get("sync")
+quant = mysett.get("quantize")
+````
+
+```{note}
+The `DEVSETTING.DAT` file is still not supported
+```
+
+[sqlcipher]: https://www.zetetic.net/sqlcipher/open-source/

docs/source/requirements.txt

@@ -0,0 +1,7 @@
+sphinx==7.2.3
+sphinx_copybutton==0.5.2
+numpydoc==1.5.0
+furo==2023.09.10
+myst-parser==2.0.0
+docutils==0.19
+matplotlib

docs/source/tutorial/anlz.md

@@ -0,0 +1,7 @@
+# Analysis Files
+
+Coming soon!
+
+```{seealso}
+See the {ref}`Analysis Files Format<Analysis Files Format>` documentation for more information.
+```