diff --git a/docs/source/formats/itunes.md b/docs/source/formats/itunes.md new file mode 100644 index 0000000..9b67823 --- /dev/null +++ b/docs/source/formats/itunes.md @@ -0,0 +1,354 @@ +# Itunes XML Format + +The Itunes XML format is used by Apple's Itunes software to store information about tracks, playlists, and other data. +The format is based on XML and is human-readable. The format is used by Rekordbox to import playlists from Itunes. + +````{note} +Not all features of the Itunes XML format are supported, +only the elements and attributes used by Rekordbox. +```` + + +The first lines of the XML file should be displayed as follows: + +```xml + + +``` + +## General structure + +The general structure of the Rekordbox XML file is as follows: + +```xml + + + + + Major Version1 + Minor Version1 + Application Version12.11.3.17 + Date2024-01-07T03:30:56 + Features5 + Show Content Ratings + Library Persistent IDE116CD8C3BA8AC5D + Tracks + + 1 + + Track ID1 + Persistent ID746809D638F42895 + Locationfile://localhost/C:/Users/user/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/NOISE.wav + NameNOISE + + + Playlists + + + Master + Playlist ID1 + Playlist Persistent IDEF98A43F1B09E435 + All Items + Visible + NameLibrary + Playlist Items + + + Track ID1 + + + + + Playlist ID1 + Playlist Persistent IDB323CD428E351B3C + NameTest Playlist + All Items + Playlist Items + + + Track ID1 + + + + + Music Folderfile://localhost/C:/Users/user/Music/iTunes/iTunes%20Media + + +``` + +Attributes are stored as key-value pairs in a dictionary with the type as the XML tag +of the value item, for example: +```xml +NameNOISE +Play Count1 +``` + +One exception are boolean types, where the value is stored as the XML tag: +```xml +Compilation +Clean +``` + + +## Supported Elements and Attributes + +### Tracks + + +```{eval-rst} +.. list-table:: Supported Track elements + :widths: 1 1 1 1 + :header-rows: 1 + + * - Element + - Type + - Description + - Notes + * - Track ID + - integer + - Track ID + - required + * - Persistent ID + - string + - Persistent ID + - required + * - Location + - string + - File location + - encoded as utf-8 (URI), required + * - Album + - string + - Album name + - + * - Album Artist + - string + - Album artist name + - + * - Artist + - string + - Artist name + - + * - Artwork Count + - integer + - Number of artworks + - + * - BPM + - integer + - Beats per minute + - + * - Bit Rate + - integer + - Bit rate in kbps + - + * - Clean + - bool + - Is the track clean + - + * - Comments + - string + - Comments + - + * - Compilation + - bool + - Is the track a compilation + - + * - Composer + - string + - Composer name + - + * - Date Added + - date + - Date added + - + * - Date Modified + - date + - Date modified + - + * - Disc Count + - integer + - Number of discs + - + * - Disc Number + - integer + - Disc number + - + * - File Folder Count + - integer + - Number of file folders + - + * - Genre + - string + - Genre name + - + * - Grouping + - string + - Grouping name + - + * - Has Video + - bool + - Does the track have a video + - + * - Kind + - string + - File type + - + * - Library Folder Count + - integer + - Number of library folders + - + * - Loved + - bool + - Is the track loved + - + * - Name + - string + - Track title + - + * - Part Of Gapless Album + - bool + - Is the track part of a gapless album + - + * - Play Count + - integer + - Play count + - + * - Play Date + - date + - Play date + - + * - Play Date UTC + - date + - Play date UTC + - + * - Purchased + - bool + - Is the track purchased + - + * - Release Date + - date + - Release date + - + * - Sample Rate + - integer + - Sample rate in Hz + - + * - Size + - integer + - File size in bytes + - + * - Skip Count + - integer + - Skip count + - + * - Skip Date + - date + - Skip date + - + * - Sort Album + - string + - Sort album name + - + * - Sort Album Artist + - string + - Sort album artist name + - + * - Sort Artist + - string + - Sort artist name + - + * - Sort Composer + - string + - Sort composer name + - + * - Sort Name + - string + - Sort track title + - + * - Total Time + - integer + - Total time in milliseconds + - + * - Track Count + - integer + - Number of tracks + - + * - Track Number + - integer + - Track number + - + * - Track Type + - string + - Track type + - + * - Volume Adjustment + - integer + - Volume adjustment in dB + - + * - Work + - string + - Label name + - + * - Year + - integer + - Year + - +``` + +### Playlists + +```{note} +The Master playlist is the main playlist of the library and contains *all* tracks. +``` + +Playlists are stored in the `Playlists` array. +Each playlist is a dictionary with some information and the `Playlist Items` array, +which contains the tracks of the playlist as a list of dictionaries with the `Track ID` of the track. + +```xml +Playlist Items + + + Track ID1 + + +``` + +Playlists can have the following attributes: +```{eval-rst} +.. list-table:: Supported Playlist elements + :widths: 1 1 1 1 + :header-rows: 1 + + * - Element + - Type + - Description + - Notes + * - Playlist ID + - integer + - Playlist ID + - required + * - Playlist Persistent ID + - string + - Persistent ID + - required + * - Parent Persistent ID + - string + - Persistent ID of parent + - required + * - All Items + - array + - Plalyist contains + - + * - All Items + - bool + - ? + - usually true + * - Name + - string + - Playlist name + - +``` + +The Master playlist additionally has a ``Visible`` attribute, which is set to ``false``. + +There are more playlist attributes, but they are not relevant for Rekordbox. diff --git a/docs/source/index.md b/docs/source/index.md index 3e53447..77f7927 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -57,6 +57,7 @@ caption: File formats formats/db6 formats/xml +formats/itunes formats/anlz formats/mysetting ``` diff --git a/docs/source/tutorial/index.md b/docs/source/tutorial/index.md index 6149eda..5ad3933 100644 --- a/docs/source/tutorial/index.md +++ b/docs/source/tutorial/index.md @@ -17,4 +17,5 @@ db6 xml anlz mysetting +itunes ```` diff --git a/docs/source/tutorial/itunes.md b/docs/source/tutorial/itunes.md new file mode 100644 index 0000000..9f41bb9 --- /dev/null +++ b/docs/source/tutorial/itunes.md @@ -0,0 +1,7 @@ +# Itunes XML Database + +Coming soon! + +```{seealso} +See the {ref}`Itunes XML Format` documentation for more information. +```