pyrekordbox 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

docs/source/installation.md

@@ -1,271 +0,0 @@
-# Installation
-
-Pyrekordbox is available on [PyPI]:
-
-```sh
-$ pip install pyrekordbox
-```
-
-Alternatively, it can be installed via [GitHub]:
-
-```sh
-$ pip install git+https://github.com/dylanljones/pyrekordbox.git@VERSION
-```
-
-where `VERSION` is a branch, tag or release. The project can also be cloned/forked
-and installed via
-
-```sh
-$ pip install .
-```
-
-
-## Installing SQLCipher
-
-Unlocking the new Rekordbox 6 `master.db` database file requires [SQLCipher][sqlcipher].
-Pyrekordbox makes no attempt to download/install SQLCipher, as it is a
-pure Python package - whereas the SQLCipher/sqlcipher3 installation is
-platform-dependent and can not be installed easily via ``pip``.
-
-[sqlcipher3] can either be built with the system [SQLCipher][sqlcipher] or built against
-a statically linked amalgamation of the SQLite3 source code.
-
-### Windows
-
-#### SQLCipher Amalagamation
-
-The easiest method to install SQLCipher on Windows is to build [sqlcipher3]
-against an amalgamation of the SQLite3 source code.
-
-1. **Install [Visual Studio Community Edition][VS]**
-
-   Make sure to select all the GCC options (VC++, C++, etc) in the installation process.
-   The following workloads under ``Desktop & Mobile`` should be sufficient:
-   - Desktop Development with C++
-   - .NET desktop development
-
-
-2. **Install a prebuilt [OpenSSL binary][OpenSSL]**
-
-   Choose the latest Win32/Win64 version. Make sure to download the full version,
-   not the light version.
-
-
-3. **Confirm that the `OPENSSL_CONF` environment variable is set properly in environment variables**
-
-   This should not be root openssl path (ex: `C:/Program Files/openssl-Win64`),
-   but instead should be the path to the config file, for example:
-   - 32-bit: ``C:/Program Files (x86)/openssl-Win32/bin/openssl.cfg``
-   - 64-bit: ``C:/Program Files/openssl-Win64/bin/openssl.cfg``
-
-   ```{note}
-   The library names of OpenSSL have changed in version 1.1.0 (see [this](https://stackoverflow.com/questions/65345077/unable-to-build-sqlcipher3-on-windows) discussion).
-   If you are using a newer version, you can set an environment variable
-   ``OPENSSL_LIBNAME`` to the name of the library, e.g. ``libcrypto.lib``.
-   Alternatively, you can modify the ``setup.py`` script (see step 8 below).
-
-   You might have to restart Windows for the changes to take effect.
-   ```
-
-4. **Copy the openssl folder to the Microsoft Visual Studio 14 VC include directory**
-
-   The openssl folder can be found here:
-   - 32-bit: `C:/Program Files (x86)/OpenSSL-Win32/include/openssl`
-   - 64-bit: `C:/Program Files/OpenSSL-Win64/include/openssl`
-
-   The VC include directory can be found in the
-   Visual Studio 14 installation directory:
-
-   > C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/include
-
-   In newer versions it might aso be in
-
-   > C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/[version]/include
-
-   Confirm the following path exists `.../include/openssl/aes.h`
-
-
-5. **Download / compile the SQLCipher 3 amalgamation files**
-
-   Pre-built SQLCipher amalgamation files can be downloaded from [this repo][amalgamation]:
-   ````shell
-   git clone https://github.com/geekbrother/sqlcipher-amalgamation
-   ````
-   To compile the amalgamation files on your own, follow [this tutorial](http://www.jerryrw.com/howtocompile.php).
-
-
-6. **Clone [sqlcipher3] into any directory**
-
-   ````shell
-   git clone https://github.com/coleifer/sqlcipher3
-   ````
-
-
-7. **Copy amalgamation files to the `sqlcipher3` directory**
-
-   Copy files ``sqlite3.c`` and ``sqlite3.h`` from the amalgamation directory from step 5
-   to the root of the ``sqlcipher3`` directory from step 6.
-   ````shell
-   Copy-Item -Path 'sqlcipher-amalgamation/src/sqlite3.c' -Destination "sqlcipher3/"
-   Copy-Item -Path 'sqlcipher-amalgamation/src/sqlite3.h' -Destination "sqlcipher3/"
-   ````
-
-
-8. **Modify the ``sqlcipher3/setup.py`` script (optional)**
-
-   If building the amalgamation fails and you haven't set the ``OPENSSL_LIBNAME``
-   environment variable in step 3, you have to modify the ``setup.py`` script. Change
-   ````python
-   openssl_libname = os.environ.get('OPENSSL_LIBNAME') or 'libeay32.lib'
-   ````
-   to
-   ````python
-   openssl_libname = os.environ.get('OPENSSL_LIBNAME') or 'libcrypto.lib'
-   ````
-
-
-9. **Build using the amalgamation and install**
-
-    ``cd`` into the ``sqlcipher3`` directory and run
-    ````shell
-    python setup.py build_static build
-    python setup.py install
-    ````
-
-
-You now should have a working ``sqlcipher3`` installation! The directory of the
-cloned ``sqlcipher3`` repo can be deleted after installing the package.
-
-Steps 5-9 can be automated using the CLI of ``pyrekordbox``:
-
-    > python3 -m pyrekordbox install-sqlcipher --help
-    usage: pyrekordbox install-sqlcipher [-h] [-t TMPDIR] [-l CRYPTOLIB] [-q] [-b]
-
-      -t TMPDIR, --tmpdir TMPDIR
-                            Path for storing temporary data (default: '.tmp')
-      -l CRYPTOLIB, --cryptolib CRYPTOLIB
-                            The name of the OpenSSl crypto libary (default: 'libcrypto.lib')
-      -b, --buildonly       Don't install sqlcipher3, only build the amalgamation
-
-
-##### Troubleshooting
-
-- **Microsoft Visual C++ error**
-
-  If you are getting an error like
-  ````shell
-  error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools"``
-  ````
-  and have Visual Studio installed, you might not have all the necessary C/C++ components.
-
-- **LINK error**
-
-  If you are getting an error like
-  ````shell
-  LINK : fatal error LNK1158: cannot run 'rc.exe'
-  ````
-  or
-  ````shell
-  LINK : fatal error LNK1327: failure during running rc.exe
-  ````
-  make sure all the necessary C/C++ components are installed and that you have selected
-  the latest Win 10/11 SDK in the Visual Studio installer. If you are still getting the error,
-  follow the suggestions in this [StackOverflow post](https://stackoverflow.com/questions/14372706/visual-studio-cant-build-due-to-rc-exe).
-
-
-### MacOS
-
-
-#### System SQLCipher
-
-For building [sqlcipher3] against the system SQLCipher installation on MacOS follow these steps:
-
-1) Install [Homebrew](https://brew.sh) if you do not have it on your machine.
-2) Install SQLCipher with `brew install SQLCipher`.
-3) With the python environment you are using to run pyrekordbox active execute the following:
-```shell
-git clone https://github.com/coleifer/sqlcipher3
-cd sqlcipher3
-SQLCIPHER_PATH=$(brew info sqlcipher | awk 'NR==4 {print $1; exit}'); C_INCLUDE_PATH="$SQLCIPHER_PATH"/include LIBRARY_PATH="$SQLCIPHER_PATH"/lib python setup.py build
-SQLCIPHER_PATH=$(brew info sqlcipher | awk 'NR==4 {print $1; exit}'); C_INCLUDE_PATH="$SQLCIPHER_PATH"/include LIBRARY_PATH="$SQLCIPHER_PATH"/lib python setup.py install
-```
-Make sure the `C_INCLUDE` and `LIBRARY_PATH` point to the installed SQLCipher path. It may differ on your machine.
-
-````{note}
-If you are having issues building sqlcipher on M1 Macs you might have to add some symlinks:
-```shell
-ln -s /opt/homebrew/lib/libsqlcipher.a /usr/local/lib/libsqlcipher.a
-ln -s /opt/homebrew/include/sqlcipher /usr/local/include/sqlcipher
-```
-````
-#### SQLCipher Amalagamation
-
-You can also build [sqlcipher3] against an amalgamation on MacOS.
-
-1. **Download / compile the SQLCipher amalgamation files**
-
-   Pre-built SQLCipher amalgamation files can be downloaded from [this repo][amalgamation]:
-   ````shell
-   git clone https://github.com/geekbrother/sqlcipher-amalgamation
-   ````
-   You can also build the amalagamtion files on your own.
-
-
-2. **Clone [sqlcipher3] into any directory**
-
-   ````shell
-   git clone https://github.com/coleifer/sqlcipher3
-   ````
-
-
-3. **Copy amalgamation files to the `sqlcipher3` directory**
-
-   Copy files ``sqlite3.c`` and ``sqlite3.h`` from the amalgamation directory from step 1
-   to the root of the ``sqlcipher3`` directory from step 2.
-   ````shell
-   cp sqlcipher-amalgamation/src/sqlite3.[ch] sqlcipher3/
-   ````
-
-4. **Build using the amalgamation and install**
-
-    ``cd`` into the ``sqlcipher3`` directory and run
-    ````shell
-    python setup.py build_static build
-    python setup.py install
-    ````
-
-The steps above can be automated using the CLI of ``pyrekordbox``
-
-    > python3 -m pyrekordbox install-sqlcipher --help
-    usage: pyrekordbox install-sqlcipher [-h] [-t TMPDIR] [-l CRYPTOLIB] [-q] [-b]
-
-      -t TMPDIR, --tmpdir TMPDIR
-                            Path for storing temporary data (default: '.tmp')
-      -b, --buildonly       Don't install sqlcipher3, only build the amalgamation
-
-
-```{note}
-The `CRYPTOLIB` argument is only used on Windows
-```
-
-
-### Using SQLCipher
-
-After the installation SQLCipher-databases can be unlocked via the `sqlcipher3` package:
-````python
-from sqlcipher3 import dbapi2 as sqlite3
-
-conn = sqlite3.connect('test.db')
-c = conn.cursor()
-c.execute("PRAGMA key='password'")
-````
-
-
-
-[VS]: https://visualstudio.microsoft.com/de/vs/community/
-[OpenSSL]: https://slproweb.com/products/Win32OpenSSL.html
-[sqlcipher3]: https://github.com/coleifer/sqlcipher3
-[amalgamation]: https://github.com/geekbrother/sqlcipher-amalgamation
-[Pypi]: https://pypi.org/project/pyrekordbox/
-[GitHub]: https://github.com/dylanljones/pyrekordbox
-[sqlcipher]: https://www.zetetic.net/sqlcipher/open-source/

docs/source/key.md

@@ -1,103 +0,0 @@
-# Database key
-
-If the automatic key extraction fails 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.
-if you obtained the key from another source, you can also pass it to the database handler
-````python
-db = Rekordbox6Database(key="<insert key here>")
-````
-or write it to the cache file manually:
-````python
-from pyrekordbox.config import write_db6_key_cache
-
-write_db6_key_cache("<insert key here>")  # call once
-db = Rekordbox6Database()
-````
-
-## Alternative methods
-
-The key can be extracted manually from the users machine. After the key is obtained
-it can be writen to the cache file as described above.
-The method varies depending on the operating system.
-
-### Windows
-
-On Windows, the key can be extracted from the Rekordbox executable using a debugger:
-
-1. Download [x64dbg] and run it.
-
-2. Options -> Preferences. Make sure "Entry Breakpoint" is set in the Events tab.
-
-3. File -> Open... `rekordbox.exe` (the main application executable)
-
-4. Look at the status bar. It should have a yellow "Paused" icon followed by some status text.
-   Right now it should say "System breakpoint reached!"
-
-5. Hit F9 or press the Run button in the top bar. The status text should change to
-   "INT3 breakpoint 'entry breakpoint' at <rekordbox.EntryPoint>".
-
-6. Click in the disassembly window, then press Ctrl+G to open the Go To Expression box,
-   and search for `sqlite3_key_v2` and press OK. This should jump you to the code for
-   that function, which typically starts with `mov dword ptr ss:[rsp+xx], r9d` or similar.
-
-7. Without clicking anywhere on the disassembly window, press F2 to toggle breakpoint.
-   The top instruction's address should turn red.
-
-8. Hit F9 or press the Run button in the top bar. The status text will start changing
-   a bunch, while the program starts up. Wait until the status bar goes back to "Paused"
-   in yellow. If the status text says something like "First chance exception on..."
-   press F9 again.
-
-9. The status bar should go to "Paused" in yellow again, this time with status text
-   that says "INT3 breakpoint at <sqlite3.sqlite3_key_v2>". This means our breakpoint
-   has been hit.
-
-10. Click the register panel (top right, where RAX, RBX, RCX, etc. are listed) so
-   it updates. Right click the red address next to R8, and click "Follow in dump".
-
-11. The dump at the bottom left will move to that address. Right click the dump panel
-   and select Text -> ASCII at the bottom. You should now see the key as a string.
-   You can drag-select it, then right click to copy selected line.
-
-12. Go to Debug -> Close to close the process, then close x64dbg.
-
-
-```{figure} /_static/images/x64dbg_rb_key.png
-:align: center
-:scale: 60
-```
-
-
-### MacOS
-
-On MacOS, the key can be extracted using the [RekordLocksmith] tool:
-
-1. Install LLDB:
-   - LLDB can be installed with Xcode on macOS via the App Store or xcode-cli-commands.
-   - Ensure LLDB is accessible from the terminal by running `lldb` in the terminal.
-
-2. Disable SIP:
-   - Restart your Mac and hold down `Command-R` as it boots to enter Recovery Mode.
-   - Open the Terminal from the Utilities menu.
-   - Type `csrutil disable` and press Enter.
-   - Restart your Mac.
-
-3. Download RekordLocksmith:
-   - Clone or download the [RekordLocksmith] repository from GitHub.
-
-4. Run RekordLocksmith:
-   - Use the terminal to navigate to the folder containing `rekordlocksmith.py`.
-   - Run the script:
-     ````shell
-     python3 rekordlocksmith.py /Applications/rekordbox\ 6/rekordbox.app/Contents/MacOS/rekordbox
-     ````
-     The tool will output the database key to the terminal and save it to a file named `rekordbox_db_pass.txt` in the current directory.
-
-
-[x64dbg]: https://x64dbg.com/
-[RekordLocksmith]: https://github.com/Bide-UK/rekordlocksmith#rekordlocksmith

docs/source/quickstart.md

@@ -1,189 +0,0 @@
-# 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
-- ``DjmdAlbum``: Albums
-- ``DjmdArtist``: Artists
-- ``DjmdGenre``: Genres
-- ``DjmdLabel``: Labels
-
-````{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.rbxml 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

@@ -1,7 +0,0 @@
-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

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

docs/source/tutorial/configuration.md

@@ -1,66 +0,0 @@
-# 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()
-````
-
-which, for example, will print
-````
-Pioneer:
-   app_dir =      C:\Users\user\AppData\Roaming\Pioneer
-   install_dir =  C:\Program Files\Pioneer
-Rekordbox 5:
-   app_dir =      C:\Users\user\AppData\Roaming\Pioneer\rekordbox
-   db_dir =       C:\Users\user\AppData\Roaming\Pioneer\rekordbox
-   db_path =      C:\Users\user\AppData\Roaming\Pioneer\rekordbox\datafile.edb
-   install_dir =  C:\Program Files\Pioneer\rekordbox 5.8.6
-   version =      5.8.6
-Rekordbox 6:
-   app_dir =      C:\Users\user\AppData\Roaming\Pioneer\rekordbox6
-   db_dir =       C:\Users\user\AppData\Roaming\Pioneer\rekordbox
-   db_path =      C:\Users\user\AppData\Roaming\Pioneer\rekordbox\master.db
-   dp =           FJ9s0iA+hiPZg...
-   install_dir =  C:\Program Files\Pioneer\rekordbox 6.5.3
-   version =      6.5.3
-````
-
-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)
-````
-
-## Configuration files
-Alternatively the two paths can be specified in a configuration file under the section
-`rekordbox`. Supported configuration files are pyproject.toml, setup.cfg, rekordbox.toml,
-rekordbox.cfg and rekordbox.yml.
-
-**pyproject.toml** / **pyrekordbox.toml**
-`````toml
-[rekordbox]
-pioneer-install-dir = "C:/Program Files/Pioneer"
-pioneer-app-dir = "C:/Users/user/AppData/Roaming/Pioneer"
-`````
-
-
-**setup.cfg** / **pyrekordbox.cfg**
-`````ini
-[rekordbox]
-pioneer-install-dir = C:/Program Files/Pioneer
-pioneer-app-dir = C:/Users/user/AppData/Roaming/Pioneer
-`````
-
-
-**pyrekordbox.yml**
-````yaml
-rekordbox:
-  pioneer-install-dir: C:/Program Files/Pioneer
-  pioneer-app-dir: C:/Users/user/AppData/Roaming/Pioneer
-````