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

docs/source/tutorial/db6.md

@@ -1,178 +0,0 @@
-# Rekordbox 6 Database
-
-Pyrekordbox uses [SQLALchemy](https://www.sqlalchemy.org/) as ORM-Framework to handle the
-Rekordbox v6 database file (``master.db``). The table declarations can be found in
-``pyrekordbox.db6.tables``.
-
-```{seealso}
-See the {ref}`Rekordbox 6 Database Format <Rekordbox 6 Database Format>` documentation for more information.
-```
-
-Since the Rekordbox v6 database handler automatically finds the ``master.db`` database file
-(see configuration), it can be initialized without any arguments:
-````python
-from pyrekordbox import Rekordbox6Database
-
-db = Rekordbox6Database()
-````
-
-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()
-````
-The key can be found in some other projects (see issue
-[#77](https://github.com/dylanljones/pyrekordbox/issues/77)), for example [here][rb6-key].
-
-
-## Querying the database
-
-A query can be executed on any table by calling the ``query()`` method. The result is
-a SQLAlchemy query object, which can be used to filter and sort the results.
-````python
-from pyrekordbox.db6 import tables
-
-query = db.query(tables.DjmdContent)
-results = query.filter(tables.DjmdContent.Title == "My Song").all()
-````
-
-To simplify querying the database, the ``Rekordbox6Database`` class provides simple
-getters for executing queries on all the tables. The parameters of the getters are
-passed to the ``query.filter_by()`` method. If the query is filtered by a *unique* key
-(e.g. ``ID``), the query will be executed using the ``query.one()`` method, returning the
-table instance directly:
-````python
-# Return specific entry in DjmDContent table
-content = db.get_content(ID=0)
-````
-
-In all other cases the query is returned, allowing to further filter and sort the results:
-````python
-# Query and sort entries in DjmdHistory table
-for history in db.get_history().order_by(tables.DjmdHistory.DateCreated):
-    print(history)
-````
-
-This allows the user to make use of the full power of SQLAlchemy queries.
-
-### Relationships
-
-Some values of table entries are linked to other tables and can not be updated
-directly. For example, the [djmdContent table][djmdContent-table] contains an
-``ArtistID`` column, which links to the [djmdArtist table][djmdArtist-table].
-The table declarations provide relationships to access the linked values.
-The artist of a song can be accessed as follows:
-````python
-content = db.get_content(ID=0)
-artist = content.Artist
-````
-A full list of linked tables can be found in the [](db6-format) documentation.
-
-
-## Updating the database
-
-Many values in the Rekordbox database can be updated by simply changing the corresponding
-attribute of the table instance and calling the ``db.commit()`` method:
-````python
-content = db.get_content().first()
-content.Title = "New title"
-db.commit()
-````
-
-Since some values of table entries are linked to other tables these values can not
-be updated directly. Also, many values depend on other values on the table and have to
-be updated accordingly to ensure consistency of the database, for example the ``TrackNo``
-of songs in playlists.
-
-To simplify updating the database, the ``Rekordbox6Database`` class provides a set of
-high level methods for updating the database. These methods take care of updating all
-linked values and metadata.
-
-### Playlists
-
-A new playlist can be created by calling the ``db.create_playlist()`` method:
-````python
-playlist = db.create_playlist("My Playlist")
-````
-It creates a new [DjmdPlaylist] instance and adds it to the [djmdPlaylist table][djmdPlaylist-table].
-By default, the playlist is inserted as last element of the parent playlist folder.
-Alternatively, the sequence number of the new playlist can be specified:
-````python
-playlist = db.create_playlist("My Playlist", seq=2)
-````
-To add the playlist to a specific playlist folder, the ``parent`` parameter can be used
-to pass a playlist folder instance or ID:
-````python
-folder = db.get_playlist(Name="My Folder").one()  # Query for unique playlist folder
-playlist = db.create_playlist("My Playlist", parent=folder)
-````
-
-Playlist folders can also be created , which are also stored in the [djmdPlaylist table][djmdPlaylist-table].
-The method accepts the same parameters as the ``db.create_playlist()`` method:
-````python
-folder = db.create_playlist_folder("My Folder")
-````
-
-Playlists and playlist folders can also be deleted:
-````python
-playlist = db.get_playlist(Name="My Playlist").one()
-db.delete_playlist(playlist)
-
-folder = db.get_playlist(Name="My Folder").one()
-db.delete_playlist(folder)
-````
-
-```{caution}
-When deleting a playlist or playlist folder, all children are deleted as well.
-Deleting a playlist removes all songs from the playlist before deleting it. Similarly,
-deleting a playlist folder removes all playlists and playlist folders in the folder,
-including all songs in the sub-playlists.
-```
-
-Adding tracks to a playlist is done by calling the ``db.add_to_playlist()`` method.
-It accepts a [DjmdContent] instance or corresponding ID and creates a new entry in
-the [djmdSongPlaylist table][djmdSongPlaylist-table], which stores the contents of playlists:
-````python
-content = db.get_content(ID=0)
-playlist = db.get_playlist(Name="My Playlist").one()
-song = db.add_to_playlist(playlist, content)
-````
-
-To delete a song from a playlist, the [DjmdSongPlaylist] instance or ID has to be passed,
-since a track can be contained in a plalyist more than once:
-````python
-playlist = db.get_playlist(Name="My Playlist").one()
-song = playlist.Songs[0]
-
-db.remove_from_playlist(playlist, song)
-````
-
-```{note}
-More coming soon!
-```
-
-
-
-[db-format]: #db6-format
-[djmdArtist-table]: #djmdArtist
-[DjmdArtist]: pyrekordbox.db6.tables.DjmdArtist
-[djmdContent-table]: #djmdContent
-[DjmdContent]: pyrekordbox.db6.tables.DjmdContent
-[djmdPlaylist-table]: #djmdPlaylist
-[DjmdPlaylist]: pyrekordbox.db6.tables.DjmdPlaylist
-[djmdSongPlaylist-table]: #djmdSongPlaylist
-[DjmdSongPlaylist]: pyrekordbox.db6.tables.DjmdSongPlaylist
-[rb6-key]: https://github.com/mganss/CueGen/blob/19878e6eb3f586dee0eb3eb4f2ce3ef18309de9d/CueGen/Generator.cs#L31

docs/source/tutorial/index.md

@@ -1,20 +0,0 @@
-# Tutorial
-
-```{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"
-```
-
-````{toctree}
----
-maxdepth: 3
----
-
-configuration
-db6
-xml
-anlz
-mysetting
-````

docs/source/tutorial/mysetting.md

@@ -1,124 +0,0 @@
-# My-Settings
-
-
-Rekordbox stores the user settings in ``*SETTING.DAT`` files, which get exported
-to USB devices. These files are located in the ``PIONEER`` directory of a USB drive
-(device exports), but are also present 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.
-
-```{seealso}
-See the {ref}`My-Setting Files Format<My-Setting Files Format>` documentation for more information.
-```
-
-Pyrekordbox includes a file handler for each of the four My-Settings files. To read any of the four files, use
-````python
-from pyrekordbox import read_mysetting_file
-
-file = read_mysetting_file("MYSETTING.DAT")
-````
-
-My-Settings files can also be parsed manually:
-````python
-from pyrekordbox import MySettingFile, MySetting2File, DjmMySettingFile, DevSettingFile
-
-file1 = MySettingFile.parse_file("MYSETTING.DAT")
-file2 = MySetting2File.parse_file("MYSETTING2.DAT")
-file3 = DjmMySettingFile.parse_file("DJMMYSETTING.DAT")
-file4 = DevSettingFile.parse_file("DEVSETTING.DAT")
-````
-
-After parsing a My-Setting file, the settings can be accessed as dictionary:
-````python
->>> file = read_mysetting_file("MYSETTING.DAT")
->>> file["quantize"]
-on
-
->>> file["quantize"] = "off"
-````
-
-To save the updated contents of a My-Settings file, use
-````python
->>> file.save("MYSETTING.DAT")
-````
-
-## MySetting Files
-
-The ``MYSETTING.DAT`` files store the main settings for Pioneers CDJ players.
-
-````python
->>> file = read_mysetting_file("MYSETTING.DAT")
->>> for setting, value in file.items():
-...     print(f"{setting:<25} {value}")
-auto_cue                  on
-auto_cue_level            memory
-disc_slot_illumination    bright
-eject_lock                unlock
-hotcue_autoload           on
-hotcue_color              off
-jog_mode                  vinyl
-jog_ring_brightness       bright
-jog_ring_indicator        on
-language                  english
-lcd_brightness            three
-master_tempo              off
-needle_lock               lock
-on_air_display            on
-phase_meter               type1
-play_mode                 single
-quantize                  on
-quantize_beat_value       one
-slip_flashing             on
-sync                      off
-tempo_range               ten
-time_mode                 remain
-````
-
-
-## MySetting2 Files
-
-The ``MYSETTING2.DAT`` files store additional settings for Pioneers CDJ players.
-
-````python
->>> file = read_mysetting_file("MYSETTING2.DAT")
->>> for setting, value in file.items():
-...     print(f"{setting:<25} {value}")
-vinyl_speed_adjust        touch
-jog_display_mode          auto
-pad_button_brightness     three
-jog_lcd_brightness        three
-waveform_divisions        phrase
-waveform                  waveform
-beat_jump_beat_value      sixteen
-````
-
-
-## DjmMySetting Files
-
-The ``DJMMYSETTING.DAT`` files store the settings for Pioneers DJMD mixers.
-
-````python
->>> file = read_mysetting_file("DJMMYSETTING.DAT")
->>> for setting, value in file.items():
-...     print(f"{setting:<25} {value}")
-channel_fader_curve       linear
-cross_fader_curve         fast_cut
-headphones_pre_eq         post_eq
-headphones_mono_split     stereo
-beat_fx_quantize          on
-mic_low_cut               on
-talk_over_mode            advanced
-talk_over_level           minus_18db
-midi_channel              one
-midi_button_type          toggle
-display_brightness        five
-indicator_brightness      three
-channel_fader_curve_long  exponential
-````
-
-
-## DevSetting Files
-
-The ``DEVSETTING.DAT`` files are not supported.

docs/source/tutorial/xml.md

@@ -1,140 +0,0 @@
-# XML Database
-
-We will use the Rekordbox 6 database from the test data as an example:
-
-```python
-import os
-path = os.path.join(".testdata", "rekordbox 5", "database.xml")
-```
-
-An existing XML database can be parsed by passing the file path to the ``RekordboxXml``
-constructor:
-```python
-from pyrekordbox import RekordboxXml
-xml = RekordboxXml(path)
-print(xml.tostring())
-```
-
-Printing the contents results in the following output:
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<DJ_PLAYLISTS Version="1.0.0">
-    <PRODUCT Name="rekordbox" Version="6.6.2" Company="AlphaTheta"/>
-    <COLLECTION Entries="6">
-        <TRACK TrackID="253529738" Name="Demo Track 1" Artist="Loopmasters" Composer="" Album="" Grouping="" Genre="" Kind="Mp3-Datei " Size="6899624" TotalTime="172" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="128.00" DateAdded="2022-04-09" BitRate="320" SampleRate="44100" Comments="Tracks by www.loopmasters.com" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%201.mp3" Remixer="" Tonality="Fm" Label="Loopmasters" Mix="">
-            <TEMPO Inizio="0.025" Bpm="128.00" Metro="4/4" Battito="1"/>
-        </TRACK>
-        <TRACK TrackID="17109519" Name="Demo Track 2" Artist="Loopmasters" Composer="" Album="" Grouping="" Genre="" Kind="Mp3-Datei " Size="5124342" TotalTime="128" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="120.00" DateAdded="2022-04-09" BitRate="320" SampleRate="44100" Comments="Tracks by www.loopmasters.com" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%202.mp3" Remixer="" Tonality="Fm" Label="Loopmasters" Mix="">
-            <TEMPO Inizio="0.025" Bpm="120.00" Metro="4/4" Battito="1"/>
-            <TEMPO Inizio="48.026" Bpm="120.00" Metro="4/4" Battito="1"/>
-            <TEMPO Inizio="48.525" Bpm="120.00" Metro="4/4" Battito="2"/>
-            <TEMPO Inizio="49.026" Bpm="120.00" Metro="4/4" Battito="3"/>
-            <TEMPO Inizio="49.525" Bpm="120.00" Metro="4/4" Battito="4"/>
-            <TEMPO Inizio="50.026" Bpm="120.00" Metro="4/4" Battito="1"/>
-            <TEMPO Inizio="50.525" Bpm="120.00" Metro="4/4" Battito="2"/>
-            <TEMPO Inizio="51.026" Bpm="120.00" Metro="4/4" Battito="3"/>
-            <TEMPO Inizio="51.525" Bpm="120.00" Metro="4/4" Battito="4"/>
-            <TEMPO Inizio="52.026" Bpm="120.00" Metro="4/4" Battito="1"/>
-        </TRACK>
-        <TRACK TrackID="49557014" Name="HORN" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="2010816" TotalTime="7" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/HORN.wav" Remixer="" Tonality="" Label="" Mix=""/>
-        <TRACK TrackID="209873516" Name="NOISE" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1382226" TotalTime="5" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/NOISE.wav" Remixer="" Tonality="" Label="" Mix=""/>
-        <TRACK TrackID="55231398" Name="SINEWAVE" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1515258" TotalTime="5" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/SINEWAVE.wav" Remixer="" Tonality="" Label="" Mix=""/>
-        <TRACK TrackID="92396897" Name="SIREN" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1941204" TotalTime="7" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/SIREN.wav" Remixer="" Tonality="" Label="" Mix=""/>
-    </COLLECTION>
-    <PLAYLISTS>
-        <NODE Type="0" Name="ROOT" Count="1">
-            <NODE Name="Trial playlist - Cloud Library Sync" Type="1" KeyType="0" Entries="0"/>
-        </NODE>
-    </PLAYLISTS>
-</DJ_PLAYLISTS>
-```
-
-## Tracks
-
-Individual tracks in the collection can be fetched by supplying an index
-````
->>> xml.get_track(0)
-<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
-````
-or the `TrackID`:
-````
->>> xml.get_track(TrackID=253529738)
-<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
-````
-
-All items in the collection can be fetched via
-````
->>> tracks = xml.get_tracks()
->>> tracks[0]
-<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
-````
-
-The XML attributes of a `Track` element are accessable as an attribute of the ``Track``
-object or via a dict-interface:
-````python
->>> track = xml.get_track(0)
->>> track.Name
-Demo Track 1
-
->>> track["Name"]
-Demo Track 1
-````
-
-Each track can contain a ``Tempo`` or ``PositionMark`` element. The ``Tempo`` element
-stores the beat grid information:
-````python
->>> track = xml.get_track(0)
->>> tempo = track.tempos[0]
->>> tempo.Bpm
-128.0
-````
-
-and the ``PositionMark`` element stores the cue points of a track (not included in the XML example above):
-````python
->>> track = xml.get_track(0)
->>> mark = track.marks[0]
->>> mark.Type
-cue
-
->>> mark.Start
-0.0
-
->>> mark.Num
--1
-````
-
-```{seealso}
-See the {ref}`XML Database Format<XML Database Format>` documentation for a list of valid
-attributes. All XML attributes start with a capital letter.
-```
-
-
-## Playlists
-
-Playlists or playlist folders can be accessed by supplying the path:
-````python
-folder = xml.get_playlist("Folder")
-paylist = xml.get_playlist("Folder", "Sub Playlist")
-````
-Content in a playlist is stored as a key, which can either be the ``TrackID`` or the
-``Location`` (file path):
-````python
->>> playlist.key_type
-TrackID
-````
-
-The keys can be retrieved by calling
-````python
-keys = playlist.get_tracks()
-````
-
-A new track can be added to a playlist by specifying the corresponding key:
-````python
-playlist.add_track(track_key)
-````
-
-A new sub-folder or -playlist can be added by supplying the name:
-````python
-folder.add_playlist("Playlist")
-folder.add_playlist_folder("Folder")
-````