rekordbox-key-tool 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arnvid Karstad
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.4
2
+ Name: rekordbox-key-tool
3
+ Version: 1.1.0
4
+ Summary: Convert MIK-exported keys to Camelot notation in rekordbox.xml
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/squelch303
7
+ Project-URL: Repository, https://github.com/squelch303/rekordbox-key-tool
8
+ Project-URL: Issues, https://github.com/squelch303/rekordbox-key-tool/issues
9
+ Keywords: rekordbox,mixed-in-key,camelot,harmonic-mixing,dj
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Multimedia :: Sound/Audio
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: license-file
19
+
20
+ # rekordbox-key-tool
21
+
22
+ [![CI](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml)
23
+
24
+ Converts track keys in a `rekordbox.xml` library file from standard musical notation
25
+ (as exported by Mixed In Key / MIK) to Camelot Wheel notation used by rekordbox.
26
+
27
+ <!-- TODO: demo GIF from the Reel 01 recording → docs/demo.gif -->
28
+
29
+ ## The problem
30
+
31
+ When Mixed In Key analyzes your tracks and writes key data back to rekordbox,
32
+ it sometimes writes keys in standard notation (`Am`, `C`, `F#m`) rather than
33
+ the Camelot wheel format that rekordbox uses natively (`8A`, `8B`, `2B`).
34
+ This tool fixes that — in bulk, across your whole library.
35
+
36
+ ## Quick start — no coding needed
37
+
38
+ 1. **Download** the latest version for your computer from
39
+ [Releases](https://github.com/squelch303/rekordbox-key-tool/releases/latest):
40
+ - Windows: `rekordbox-key-tool-windows.exe`
41
+ - macOS (Apple Silicon): `rekordbox-key-tool-macos-arm64.zip`
42
+ 2. **Export your library** from rekordbox: **File → Export Collection in xml format**.
43
+ 3. **Convert it**
44
+ - Windows: drag `rekordbox.xml` onto `rekordbox-key-tool-windows.exe`.
45
+ - macOS: unzip, then in Terminal run `./rekordbox-key-tool ~/path/to/rekordbox.xml`.
46
+
47
+ You get `rekordbox_fixed.xml` next to the original. The original is never touched.
48
+ 4. **Import `rekordbox_fixed.xml` back into rekordbox** (see [Importing](#importing-into-rekordbox)).
49
+
50
+ > The downloads aren't code-signed yet. Windows SmartScreen may say *"Windows protected your PC"*:
51
+ > click **More info → Run anyway**. On macOS, if it's blocked, right-click → **Open**, or run
52
+ > `xattr -d com.apple.quarantine rekordbox-key-tool` once.
53
+
54
+ ## With Python
55
+
56
+ Requires Python 3.9+. No dependencies outside the standard library.
57
+
58
+ ```bash
59
+ # Run straight from PyPI with uv, no install step
60
+ uvx rekordbox-key-tool rekordbox.xml
61
+
62
+ # Or install it
63
+ pip install rekordbox-key-tool
64
+ ```
65
+
66
+ ## Usage
67
+
68
+ ```bash
69
+ # Just the file: writes rekordbox_fixed.xml, original untouched
70
+ rekordbox-key-tool rekordbox.xml
71
+
72
+ # Preview changes without modifying anything
73
+ rekordbox-key-tool --input rekordbox.xml --dry-run
74
+
75
+ # Show every track that changes
76
+ rekordbox-key-tool --input rekordbox.xml --dry-run --verbose
77
+
78
+ # Convert and write to a named file
79
+ rekordbox-key-tool --input rekordbox.xml --output rekordbox_fixed.xml
80
+
81
+ # Convert in place (backs up to rekordbox.xml.bak first; an existing backup is never overwritten)
82
+ rekordbox-key-tool --input rekordbox.xml --inplace
83
+ ```
84
+
85
+ ## Recognised key formats
86
+
87
+ | Format | Examples | Result |
88
+ |--------|----------|--------|
89
+ | Standard / MIK | `Am`, `F#m`, `Bbm`, `C`, `Eb` | `8A`, `11A`, `3A`, `8B`, `5B` |
90
+ | Long form | `F# minor`, `Ab Major`, `A min`, `C maj` | `11A`, `4B`, `8A`, `8B` |
91
+ | Unicode accidentals | `A♭m`, `F♯` | `1A`, `2B` |
92
+ | Camelot, odd casing / zero-padded | `8a`, `08A` | `8A` |
93
+ | Open Key (Traktor, Beatport) | `1m`, `1d`, `6m` | `8A`, `8B`, `1A` |
94
+ | Combined | `Am/8A`, `8A - Am` | `8A` |
95
+
96
+ Keys already in Camelot are left as they are. Anything not recognised is left unchanged
97
+ and listed at the end of the run. Please report those as an
98
+ [issue](https://github.com/squelch303/rekordbox-key-tool/issues).
99
+
100
+ ## Where is rekordbox.xml?
101
+
102
+ Export it from rekordbox: **File → Export Collection in xml format**
103
+
104
+ Default locations:
105
+ - Windows: `C:\Users\<user>\Documents\Pioneer\rekordbox\rekordbox.xml`
106
+ - macOS: `~/Library/Pioneer/rekordbox/rekordbox.xml`
107
+
108
+ ## Importing into rekordbox
109
+
110
+ Back up your rekordbox library first (**File → Library → Backup Library**).
111
+
112
+ 1. **Preferences → Advanced → Database → rekordbox xml → Imported Library**: choose `rekordbox_fixed.xml`.
113
+ 2. Make sure **rekordbox xml** is ticked under **Preferences → View → Layout**, so it shows in the tree view.
114
+ 3. In the tree view, open **rekordbox xml**, right-click **All Tracks** → **Import to Collection**.
115
+
116
+ ## Key format mapping
117
+
118
+ | Standard (MIK) | Camelot |
119
+ |----------------|---------|
120
+ | Ab minor / G# minor | 1A |
121
+ | B major | 1B |
122
+ | Eb minor / D# minor | 2A |
123
+ | F# major / Gb major | 2B |
124
+ | Bb minor / A# minor | 3A |
125
+ | Db major / C# major | 3B |
126
+ | F minor | 4A |
127
+ | Ab major / G# major | 4B |
128
+ | C minor | 5A |
129
+ | Eb major / D# major | 5B |
130
+ | G minor | 6A |
131
+ | Bb major / A# major | 6B |
132
+ | D minor | 7A |
133
+ | F major | 7B |
134
+ | A minor | 8A |
135
+ | C major | 8B |
136
+ | E minor | 9A |
137
+ | G major | 9B |
138
+ | B minor | 10A |
139
+ | D major | 10B |
140
+ | F# minor / Gb minor | 11A |
141
+ | A major | 11B |
142
+ | C# minor / Db minor | 12A |
143
+ | E major | 12B |
144
+
145
+ ## Development
146
+
147
+ ```bash
148
+ python -m unittest discover -s tests -v
149
+ ```
150
+
151
+ Releases are built by GitHub Actions when a `v*` tag is pushed: Windows .exe, macOS binary,
152
+ PyPI package and the GitHub Release page.
153
+
154
+ ## License
155
+
156
+ MIT — see [LICENSE](LICENSE).
157
+
158
+ ---
159
+
160
+ Part of [squelch303](https://github.com/squelch303)
@@ -0,0 +1,141 @@
1
+ # rekordbox-key-tool
2
+
3
+ [![CI](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml)
4
+
5
+ Converts track keys in a `rekordbox.xml` library file from standard musical notation
6
+ (as exported by Mixed In Key / MIK) to Camelot Wheel notation used by rekordbox.
7
+
8
+ <!-- TODO: demo GIF from the Reel 01 recording → docs/demo.gif -->
9
+
10
+ ## The problem
11
+
12
+ When Mixed In Key analyzes your tracks and writes key data back to rekordbox,
13
+ it sometimes writes keys in standard notation (`Am`, `C`, `F#m`) rather than
14
+ the Camelot wheel format that rekordbox uses natively (`8A`, `8B`, `2B`).
15
+ This tool fixes that — in bulk, across your whole library.
16
+
17
+ ## Quick start — no coding needed
18
+
19
+ 1. **Download** the latest version for your computer from
20
+ [Releases](https://github.com/squelch303/rekordbox-key-tool/releases/latest):
21
+ - Windows: `rekordbox-key-tool-windows.exe`
22
+ - macOS (Apple Silicon): `rekordbox-key-tool-macos-arm64.zip`
23
+ 2. **Export your library** from rekordbox: **File → Export Collection in xml format**.
24
+ 3. **Convert it**
25
+ - Windows: drag `rekordbox.xml` onto `rekordbox-key-tool-windows.exe`.
26
+ - macOS: unzip, then in Terminal run `./rekordbox-key-tool ~/path/to/rekordbox.xml`.
27
+
28
+ You get `rekordbox_fixed.xml` next to the original. The original is never touched.
29
+ 4. **Import `rekordbox_fixed.xml` back into rekordbox** (see [Importing](#importing-into-rekordbox)).
30
+
31
+ > The downloads aren't code-signed yet. Windows SmartScreen may say *"Windows protected your PC"*:
32
+ > click **More info → Run anyway**. On macOS, if it's blocked, right-click → **Open**, or run
33
+ > `xattr -d com.apple.quarantine rekordbox-key-tool` once.
34
+
35
+ ## With Python
36
+
37
+ Requires Python 3.9+. No dependencies outside the standard library.
38
+
39
+ ```bash
40
+ # Run straight from PyPI with uv, no install step
41
+ uvx rekordbox-key-tool rekordbox.xml
42
+
43
+ # Or install it
44
+ pip install rekordbox-key-tool
45
+ ```
46
+
47
+ ## Usage
48
+
49
+ ```bash
50
+ # Just the file: writes rekordbox_fixed.xml, original untouched
51
+ rekordbox-key-tool rekordbox.xml
52
+
53
+ # Preview changes without modifying anything
54
+ rekordbox-key-tool --input rekordbox.xml --dry-run
55
+
56
+ # Show every track that changes
57
+ rekordbox-key-tool --input rekordbox.xml --dry-run --verbose
58
+
59
+ # Convert and write to a named file
60
+ rekordbox-key-tool --input rekordbox.xml --output rekordbox_fixed.xml
61
+
62
+ # Convert in place (backs up to rekordbox.xml.bak first; an existing backup is never overwritten)
63
+ rekordbox-key-tool --input rekordbox.xml --inplace
64
+ ```
65
+
66
+ ## Recognised key formats
67
+
68
+ | Format | Examples | Result |
69
+ |--------|----------|--------|
70
+ | Standard / MIK | `Am`, `F#m`, `Bbm`, `C`, `Eb` | `8A`, `11A`, `3A`, `8B`, `5B` |
71
+ | Long form | `F# minor`, `Ab Major`, `A min`, `C maj` | `11A`, `4B`, `8A`, `8B` |
72
+ | Unicode accidentals | `A♭m`, `F♯` | `1A`, `2B` |
73
+ | Camelot, odd casing / zero-padded | `8a`, `08A` | `8A` |
74
+ | Open Key (Traktor, Beatport) | `1m`, `1d`, `6m` | `8A`, `8B`, `1A` |
75
+ | Combined | `Am/8A`, `8A - Am` | `8A` |
76
+
77
+ Keys already in Camelot are left as they are. Anything not recognised is left unchanged
78
+ and listed at the end of the run. Please report those as an
79
+ [issue](https://github.com/squelch303/rekordbox-key-tool/issues).
80
+
81
+ ## Where is rekordbox.xml?
82
+
83
+ Export it from rekordbox: **File → Export Collection in xml format**
84
+
85
+ Default locations:
86
+ - Windows: `C:\Users\<user>\Documents\Pioneer\rekordbox\rekordbox.xml`
87
+ - macOS: `~/Library/Pioneer/rekordbox/rekordbox.xml`
88
+
89
+ ## Importing into rekordbox
90
+
91
+ Back up your rekordbox library first (**File → Library → Backup Library**).
92
+
93
+ 1. **Preferences → Advanced → Database → rekordbox xml → Imported Library**: choose `rekordbox_fixed.xml`.
94
+ 2. Make sure **rekordbox xml** is ticked under **Preferences → View → Layout**, so it shows in the tree view.
95
+ 3. In the tree view, open **rekordbox xml**, right-click **All Tracks** → **Import to Collection**.
96
+
97
+ ## Key format mapping
98
+
99
+ | Standard (MIK) | Camelot |
100
+ |----------------|---------|
101
+ | Ab minor / G# minor | 1A |
102
+ | B major | 1B |
103
+ | Eb minor / D# minor | 2A |
104
+ | F# major / Gb major | 2B |
105
+ | Bb minor / A# minor | 3A |
106
+ | Db major / C# major | 3B |
107
+ | F minor | 4A |
108
+ | Ab major / G# major | 4B |
109
+ | C minor | 5A |
110
+ | Eb major / D# major | 5B |
111
+ | G minor | 6A |
112
+ | Bb major / A# major | 6B |
113
+ | D minor | 7A |
114
+ | F major | 7B |
115
+ | A minor | 8A |
116
+ | C major | 8B |
117
+ | E minor | 9A |
118
+ | G major | 9B |
119
+ | B minor | 10A |
120
+ | D major | 10B |
121
+ | F# minor / Gb minor | 11A |
122
+ | A major | 11B |
123
+ | C# minor / Db minor | 12A |
124
+ | E major | 12B |
125
+
126
+ ## Development
127
+
128
+ ```bash
129
+ python -m unittest discover -s tests -v
130
+ ```
131
+
132
+ Releases are built by GitHub Actions when a `v*` tag is pushed: Windows .exe, macOS binary,
133
+ PyPI package and the GitHub Release page.
134
+
135
+ ## License
136
+
137
+ MIT — see [LICENSE](LICENSE).
138
+
139
+ ---
140
+
141
+ Part of [squelch303](https://github.com/squelch303)
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "rekordbox-key-tool"
7
+ dynamic = ["version"]
8
+ description = "Convert MIK-exported keys to Camelot notation in rekordbox.xml"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.9"
12
+ dependencies = []
13
+ keywords = ["rekordbox", "mixed-in-key", "camelot", "harmonic-mixing", "dj"]
14
+ classifiers = [
15
+ "Environment :: Console",
16
+ "Intended Audience :: End Users/Desktop",
17
+ "Operating System :: OS Independent",
18
+ "Programming Language :: Python :: 3",
19
+ "Topic :: Multimedia :: Sound/Audio",
20
+ ]
21
+
22
+ [project.scripts]
23
+ rekordbox-key-tool = "rekordbox_key_tool:main"
24
+
25
+ [tool.setuptools]
26
+ py-modules = ["rekordbox_key_tool"]
27
+
28
+ [tool.setuptools.dynamic]
29
+ version = { attr = "rekordbox_key_tool.__version__" }
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/squelch303"
33
+ Repository = "https://github.com/squelch303/rekordbox-key-tool"
34
+ Issues = "https://github.com/squelch303/rekordbox-key-tool/issues"
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.4
2
+ Name: rekordbox-key-tool
3
+ Version: 1.1.0
4
+ Summary: Convert MIK-exported keys to Camelot notation in rekordbox.xml
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/squelch303
7
+ Project-URL: Repository, https://github.com/squelch303/rekordbox-key-tool
8
+ Project-URL: Issues, https://github.com/squelch303/rekordbox-key-tool/issues
9
+ Keywords: rekordbox,mixed-in-key,camelot,harmonic-mixing,dj
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Multimedia :: Sound/Audio
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: license-file
19
+
20
+ # rekordbox-key-tool
21
+
22
+ [![CI](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/squelch303/rekordbox-key-tool/actions/workflows/ci.yml)
23
+
24
+ Converts track keys in a `rekordbox.xml` library file from standard musical notation
25
+ (as exported by Mixed In Key / MIK) to Camelot Wheel notation used by rekordbox.
26
+
27
+ <!-- TODO: demo GIF from the Reel 01 recording → docs/demo.gif -->
28
+
29
+ ## The problem
30
+
31
+ When Mixed In Key analyzes your tracks and writes key data back to rekordbox,
32
+ it sometimes writes keys in standard notation (`Am`, `C`, `F#m`) rather than
33
+ the Camelot wheel format that rekordbox uses natively (`8A`, `8B`, `2B`).
34
+ This tool fixes that — in bulk, across your whole library.
35
+
36
+ ## Quick start — no coding needed
37
+
38
+ 1. **Download** the latest version for your computer from
39
+ [Releases](https://github.com/squelch303/rekordbox-key-tool/releases/latest):
40
+ - Windows: `rekordbox-key-tool-windows.exe`
41
+ - macOS (Apple Silicon): `rekordbox-key-tool-macos-arm64.zip`
42
+ 2. **Export your library** from rekordbox: **File → Export Collection in xml format**.
43
+ 3. **Convert it**
44
+ - Windows: drag `rekordbox.xml` onto `rekordbox-key-tool-windows.exe`.
45
+ - macOS: unzip, then in Terminal run `./rekordbox-key-tool ~/path/to/rekordbox.xml`.
46
+
47
+ You get `rekordbox_fixed.xml` next to the original. The original is never touched.
48
+ 4. **Import `rekordbox_fixed.xml` back into rekordbox** (see [Importing](#importing-into-rekordbox)).
49
+
50
+ > The downloads aren't code-signed yet. Windows SmartScreen may say *"Windows protected your PC"*:
51
+ > click **More info → Run anyway**. On macOS, if it's blocked, right-click → **Open**, or run
52
+ > `xattr -d com.apple.quarantine rekordbox-key-tool` once.
53
+
54
+ ## With Python
55
+
56
+ Requires Python 3.9+. No dependencies outside the standard library.
57
+
58
+ ```bash
59
+ # Run straight from PyPI with uv, no install step
60
+ uvx rekordbox-key-tool rekordbox.xml
61
+
62
+ # Or install it
63
+ pip install rekordbox-key-tool
64
+ ```
65
+
66
+ ## Usage
67
+
68
+ ```bash
69
+ # Just the file: writes rekordbox_fixed.xml, original untouched
70
+ rekordbox-key-tool rekordbox.xml
71
+
72
+ # Preview changes without modifying anything
73
+ rekordbox-key-tool --input rekordbox.xml --dry-run
74
+
75
+ # Show every track that changes
76
+ rekordbox-key-tool --input rekordbox.xml --dry-run --verbose
77
+
78
+ # Convert and write to a named file
79
+ rekordbox-key-tool --input rekordbox.xml --output rekordbox_fixed.xml
80
+
81
+ # Convert in place (backs up to rekordbox.xml.bak first; an existing backup is never overwritten)
82
+ rekordbox-key-tool --input rekordbox.xml --inplace
83
+ ```
84
+
85
+ ## Recognised key formats
86
+
87
+ | Format | Examples | Result |
88
+ |--------|----------|--------|
89
+ | Standard / MIK | `Am`, `F#m`, `Bbm`, `C`, `Eb` | `8A`, `11A`, `3A`, `8B`, `5B` |
90
+ | Long form | `F# minor`, `Ab Major`, `A min`, `C maj` | `11A`, `4B`, `8A`, `8B` |
91
+ | Unicode accidentals | `A♭m`, `F♯` | `1A`, `2B` |
92
+ | Camelot, odd casing / zero-padded | `8a`, `08A` | `8A` |
93
+ | Open Key (Traktor, Beatport) | `1m`, `1d`, `6m` | `8A`, `8B`, `1A` |
94
+ | Combined | `Am/8A`, `8A - Am` | `8A` |
95
+
96
+ Keys already in Camelot are left as they are. Anything not recognised is left unchanged
97
+ and listed at the end of the run. Please report those as an
98
+ [issue](https://github.com/squelch303/rekordbox-key-tool/issues).
99
+
100
+ ## Where is rekordbox.xml?
101
+
102
+ Export it from rekordbox: **File → Export Collection in xml format**
103
+
104
+ Default locations:
105
+ - Windows: `C:\Users\<user>\Documents\Pioneer\rekordbox\rekordbox.xml`
106
+ - macOS: `~/Library/Pioneer/rekordbox/rekordbox.xml`
107
+
108
+ ## Importing into rekordbox
109
+
110
+ Back up your rekordbox library first (**File → Library → Backup Library**).
111
+
112
+ 1. **Preferences → Advanced → Database → rekordbox xml → Imported Library**: choose `rekordbox_fixed.xml`.
113
+ 2. Make sure **rekordbox xml** is ticked under **Preferences → View → Layout**, so it shows in the tree view.
114
+ 3. In the tree view, open **rekordbox xml**, right-click **All Tracks** → **Import to Collection**.
115
+
116
+ ## Key format mapping
117
+
118
+ | Standard (MIK) | Camelot |
119
+ |----------------|---------|
120
+ | Ab minor / G# minor | 1A |
121
+ | B major | 1B |
122
+ | Eb minor / D# minor | 2A |
123
+ | F# major / Gb major | 2B |
124
+ | Bb minor / A# minor | 3A |
125
+ | Db major / C# major | 3B |
126
+ | F minor | 4A |
127
+ | Ab major / G# major | 4B |
128
+ | C minor | 5A |
129
+ | Eb major / D# major | 5B |
130
+ | G minor | 6A |
131
+ | Bb major / A# major | 6B |
132
+ | D minor | 7A |
133
+ | F major | 7B |
134
+ | A minor | 8A |
135
+ | C major | 8B |
136
+ | E minor | 9A |
137
+ | G major | 9B |
138
+ | B minor | 10A |
139
+ | D major | 10B |
140
+ | F# minor / Gb minor | 11A |
141
+ | A major | 11B |
142
+ | C# minor / Db minor | 12A |
143
+ | E major | 12B |
144
+
145
+ ## Development
146
+
147
+ ```bash
148
+ python -m unittest discover -s tests -v
149
+ ```
150
+
151
+ Releases are built by GitHub Actions when a `v*` tag is pushed: Windows .exe, macOS binary,
152
+ PyPI package and the GitHub Release page.
153
+
154
+ ## License
155
+
156
+ MIT — see [LICENSE](LICENSE).
157
+
158
+ ---
159
+
160
+ Part of [squelch303](https://github.com/squelch303)
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ rekordbox_key_tool.py
5
+ rekordbox_key_tool.egg-info/PKG-INFO
6
+ rekordbox_key_tool.egg-info/SOURCES.txt
7
+ rekordbox_key_tool.egg-info/dependency_links.txt
8
+ rekordbox_key_tool.egg-info/entry_points.txt
9
+ rekordbox_key_tool.egg-info/top_level.txt
10
+ tests/test_rekordbox_key_tool.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ rekordbox-key-tool = rekordbox_key_tool:main
@@ -0,0 +1 @@
1
+ rekordbox_key_tool
@@ -0,0 +1,276 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ rekordbox-key-tool
4
+ Converts track keys in rekordbox.xml from standard/MIK notation to Camelot Wheel.
5
+
6
+ Usage:
7
+ python rekordbox_key_tool.py rekordbox.xml # writes rekordbox_fixed.xml
8
+ python rekordbox_key_tool.py --input rekordbox.xml --dry-run
9
+ python rekordbox_key_tool.py --input rekordbox.xml --output rekordbox_fixed.xml
10
+ python rekordbox_key_tool.py --input rekordbox.xml --inplace
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import re
17
+ import shutil
18
+ import sys
19
+ import xml.etree.ElementTree as ET
20
+ from datetime import datetime
21
+ from pathlib import Path
22
+
23
+ __version__ = "1.1.0"
24
+
25
+ # ---------------------------------------------------------------------------
26
+ # Key mapping: standard / MIK notation -> Camelot Wheel
27
+ # ---------------------------------------------------------------------------
28
+
29
+ # Standard notation (normalised: lower case, no spaces, "m" = minor) -> Camelot
30
+ KEY_MAP = {
31
+ # --- Minor keys (A) ---
32
+ "abm": "1A", "g#m": "1A",
33
+ "ebm": "2A", "d#m": "2A",
34
+ "bbm": "3A", "a#m": "3A",
35
+ "fm": "4A",
36
+ "cm": "5A",
37
+ "gm": "6A",
38
+ "dm": "7A",
39
+ "am": "8A",
40
+ "em": "9A",
41
+ "bm": "10A",
42
+ "f#m": "11A", "gbm": "11A",
43
+ "c#m": "12A", "dbm": "12A",
44
+
45
+ # --- Major keys (B) ---
46
+ "b": "1B",
47
+ "f#": "2B", "gb": "2B",
48
+ "db": "3B", "c#": "3B",
49
+ "ab": "4B", "g#": "4B",
50
+ "eb": "5B", "d#": "5B",
51
+ "bb": "6B", "a#": "6B",
52
+ "f": "7B",
53
+ "c": "8B",
54
+ "g": "9B",
55
+ "d": "10B",
56
+ "a": "11B",
57
+ "e": "12B",
58
+ }
59
+
60
+ # Camelot values we recognise as already correct — skip these
61
+ CAMELOT_VALUES = {f"{n}{s}" for n in range(1, 13) for s in ("A", "B")}
62
+
63
+ CAMELOT_RE = re.compile(r"^0?([1-9]|1[0-2])([ab])$") # 8a, 08A
64
+ OPEN_KEY_RE = re.compile(r"^0?([1-9]|1[0-2])([md])$") # Open Key: 1m = Am = 8A, 1d = C = 8B
65
+ SEPARATORS_RE = re.compile(r"\s*[/|,]\s*|\s+-\s+") # "Am/8A", "8A - Am"
66
+
67
+
68
+ def normalise_key(raw: str) -> str:
69
+ """Normalise a raw key string: 'F# Minor' -> 'f#m', 'A♭ maj' -> 'ab'."""
70
+ key = raw.strip().lower().replace("♭", "b").replace("♯", "#").replace(" ", "")
71
+ for long, short in (("minor", "m"), ("min", "m"), ("major", ""), ("maj", "")):
72
+ key = key.replace(long, short)
73
+ return key
74
+
75
+
76
+ def to_camelot(raw: str) -> str | None:
77
+ """Convert a single key token to Camelot, or None if not recognised."""
78
+ key = normalise_key(raw)
79
+ m = CAMELOT_RE.match(key)
80
+ if m:
81
+ return f"{int(m.group(1))}{m.group(2).upper()}"
82
+ m = OPEN_KEY_RE.match(key)
83
+ if m:
84
+ number = (int(m.group(1)) + 6) % 12 + 1
85
+ return f"{number}{'A' if m.group(2) == 'm' else 'B'}"
86
+ return KEY_MAP.get(key)
87
+
88
+
89
+ def convert_key(raw: str) -> tuple[str | None, str]:
90
+ """
91
+ Convert a raw key string to Camelot notation.
92
+
93
+ Returns (camelot_value, status) where status is one of:
94
+ 'converted' – successfully mapped
95
+ 'already' – already in Camelot format
96
+ 'unknown' – not recognised, left unchanged
97
+ 'empty' – no key set
98
+ """
99
+ if not raw or not raw.strip():
100
+ return None, "empty"
101
+
102
+ if raw in CAMELOT_VALUES:
103
+ return raw, "already"
104
+
105
+ camelot = to_camelot(raw)
106
+ if camelot is None:
107
+ # Combined formats like "Am/8A" or "8A - Am": every recognised part must agree
108
+ results = {to_camelot(part) for part in SEPARATORS_RE.split(raw.strip()) if part}
109
+ results.discard(None)
110
+ if len(results) == 1:
111
+ camelot = results.pop()
112
+
113
+ if camelot:
114
+ return camelot, "converted"
115
+ return None, "unknown"
116
+
117
+
118
+ # ---------------------------------------------------------------------------
119
+ # XML processing
120
+ # ---------------------------------------------------------------------------
121
+
122
+ def process_xml(input_path: Path, output_path: Path, dry_run: bool, verbose: bool) -> dict:
123
+ """Parse rekordbox.xml, convert keys, write output. Returns stats."""
124
+ tree = ET.parse(input_path)
125
+ root = tree.getroot()
126
+
127
+ stats = {"converted": 0, "already": 0, "unknown": 0, "empty": 0, "total": 0}
128
+ unknown_keys = set()
129
+
130
+ collection = root.find("COLLECTION")
131
+ if collection is None:
132
+ print("Error: no <COLLECTION> element found in XML.", file=sys.stderr)
133
+ sys.exit(1)
134
+
135
+ for track in collection:
136
+ name = track.get("Name", "<unknown>")
137
+ artist = track.get("Artist", "")
138
+ raw_key = track.get("Tonality", "")
139
+
140
+ camelot, status = convert_key(raw_key)
141
+ stats[status] += 1
142
+ stats["total"] += 1
143
+
144
+ if status == "converted":
145
+ if verbose:
146
+ print(f" ✓ {artist} – {name}: {raw_key!r} → {camelot}")
147
+ if not dry_run:
148
+ track.set("Tonality", camelot)
149
+
150
+ elif status == "unknown" and raw_key:
151
+ unknown_keys.add(raw_key)
152
+ if verbose:
153
+ print(f" ? {artist} – {name}: {raw_key!r} (unrecognised)")
154
+
155
+ if not dry_run:
156
+ # Preserve the XML declaration and encoding
157
+ tree.write(output_path, encoding="utf-8", xml_declaration=True)
158
+
159
+ if unknown_keys:
160
+ print(f"\n⚠ Unrecognised key values (not converted): {sorted(unknown_keys)}")
161
+ print(" Please report these at https://github.com/squelch303/rekordbox-key-tool/issues")
162
+
163
+ return stats
164
+
165
+
166
+ # ---------------------------------------------------------------------------
167
+ # CLI
168
+ # ---------------------------------------------------------------------------
169
+
170
+ def backup_path(input_path: Path) -> Path:
171
+ """rekordbox.xml -> rekordbox.xml.bak; never overwrite an existing backup."""
172
+ backup = input_path.with_name(input_path.name + ".bak")
173
+ if backup.exists():
174
+ stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
175
+ backup = input_path.with_name(f"{input_path.name}.{stamp}.bak")
176
+ return backup
177
+
178
+
179
+ def main():
180
+ # Output contains ✓ → ⚠ — force UTF-8 so Windows doesn't crash when stdout is piped/redirected
181
+ for stream in (sys.stdout, sys.stderr):
182
+ if hasattr(stream, "reconfigure"):
183
+ stream.reconfigure(encoding="utf-8", errors="replace")
184
+
185
+ parser = argparse.ArgumentParser(
186
+ description="Convert rekordbox.xml track keys from MIK/standard notation to Camelot Wheel.",
187
+ epilog="Just a file and no options (or dragging rekordbox.xml onto the program) "
188
+ "writes <name>_fixed.xml next to it and leaves the original untouched.",
189
+ )
190
+ parser.add_argument("xml", nargs="?", help="Path to rekordbox.xml (same as --input)")
191
+ parser.add_argument("--input", "-i", default=None, help="Path to rekordbox.xml")
192
+ parser.add_argument("--output", "-o", default=None, help="Output file (default: print stats only)")
193
+ parser.add_argument("--inplace", "-I", action="store_true",
194
+ help="Modify input file in place (creates rekordbox.xml.bak first)")
195
+ parser.add_argument("--dry-run", "-n", action="store_true",
196
+ help="Show what would change without writing anything")
197
+ parser.add_argument("--verbose", "-v", action="store_true",
198
+ help="Print every conversion")
199
+ parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
200
+ args = parser.parse_args()
201
+
202
+ # Drop mode: only a file was given (e.g. rekordbox.xml dragged onto the .exe)
203
+ drop_mode = bool(args.xml) and not (args.input or args.output or args.inplace or args.dry_run)
204
+ # A frozen .exe started by double-click or drag-and-drop closes its window at once — keep it open
205
+ pause = getattr(sys, "frozen", False) and (drop_mode or len(sys.argv) == 1)
206
+
207
+ try:
208
+ run(parser, args, drop_mode)
209
+ finally:
210
+ if pause:
211
+ try:
212
+ input("\nPress Enter to close...")
213
+ except EOFError:
214
+ pass
215
+
216
+
217
+ def run(parser: argparse.ArgumentParser, args: argparse.Namespace, drop_mode: bool) -> None:
218
+ if args.xml and args.input:
219
+ parser.error("give the input file once: either as an argument or with --input")
220
+ if not (args.xml or args.input):
221
+ if getattr(sys, "frozen", False):
222
+ print("Drag your rekordbox.xml onto this program to convert it.")
223
+ print("rekordbox: File > Export Collection in xml format")
224
+ return
225
+ parser.error("no input file given (rekordbox-key-tool rekordbox.xml, or --input)")
226
+
227
+ input_path = Path(args.xml or args.input)
228
+ if not input_path.exists():
229
+ print(f"Error: {input_path} not found.", file=sys.stderr)
230
+ sys.exit(1)
231
+
232
+ if args.inplace and args.output:
233
+ parser.error("use either --output or --inplace, not both")
234
+
235
+ # Resolve output path
236
+ if args.inplace:
237
+ output_path = input_path
238
+ elif args.output:
239
+ output_path = Path(args.output)
240
+ if output_path.resolve() == input_path.resolve():
241
+ parser.error("--output is the same file as --input; use --inplace to overwrite (a backup is made)")
242
+ elif drop_mode:
243
+ output_path = input_path.with_name(f"{input_path.stem}_fixed{input_path.suffix}")
244
+ else:
245
+ output_path = None # stats only
246
+
247
+ dry_run = args.dry_run or output_path is None
248
+
249
+ if dry_run:
250
+ print("Dry run — no files will be written.\n")
251
+ elif args.inplace:
252
+ backup = backup_path(input_path)
253
+ shutil.copy2(input_path, backup)
254
+ print(f"Backup created: {backup}")
255
+
256
+ try:
257
+ stats = process_xml(input_path, output_path, dry_run=dry_run, verbose=args.verbose)
258
+ except ET.ParseError as e:
259
+ print(f"Error: {input_path} is not a valid XML file ({e}).", file=sys.stderr)
260
+ sys.exit(1)
261
+
262
+ # Summary
263
+ print(f"\nDone. Processed {stats['total']} tracks:")
264
+ print(f" {stats['converted']:4d} converted to Camelot")
265
+ print(f" {stats['already']:4d} already in Camelot format")
266
+ print(f" {stats['unknown']:4d} unrecognised (left unchanged)")
267
+ print(f" {stats['empty']:4d} no key set")
268
+
269
+ if not dry_run and output_path:
270
+ print(f"\nWritten to: {output_path}")
271
+ if drop_mode:
272
+ print("Import it in rekordbox to update your keys (see README).")
273
+
274
+
275
+ if __name__ == "__main__":
276
+ main()
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,159 @@
1
+ """Tests for rekordbox-key-tool. Standard library only: python -m unittest"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shutil
6
+ import subprocess
7
+ import sys
8
+ import tempfile
9
+ import unittest
10
+ import xml.etree.ElementTree as ET
11
+ from pathlib import Path
12
+
13
+ ROOT = Path(__file__).resolve().parent.parent
14
+ sys.path.insert(0, str(ROOT))
15
+
16
+ import rekordbox_key_tool as tool # noqa: E402
17
+
18
+ EXAMPLE = ROOT / "test_data" / "example.xml"
19
+ SCRIPT = ROOT / "rekordbox_key_tool.py"
20
+
21
+
22
+ def run_cli(*args: str) -> subprocess.CompletedProcess:
23
+ return subprocess.run(
24
+ [sys.executable, str(SCRIPT), *args],
25
+ capture_output=True, text=True, encoding="utf-8",
26
+ )
27
+
28
+
29
+ def tonalities(path: Path) -> dict[str, str]:
30
+ root = ET.parse(path).getroot()
31
+ return {t.get("Name"): t.get("Tonality") for t in root.find("COLLECTION")}
32
+
33
+
34
+ class ConvertKeyTests(unittest.TestCase):
35
+ def check(self, raw: str, expected: str | None, status: str):
36
+ self.assertEqual(tool.convert_key(raw), (expected, status), raw)
37
+
38
+ def test_full_wheel_standard_notation(self):
39
+ wheel = {
40
+ "Abm": "1A", "B": "1B", "Ebm": "2A", "F#": "2B", "Bbm": "3A", "Db": "3B",
41
+ "Fm": "4A", "Ab": "4B", "Cm": "5A", "Eb": "5B", "Gm": "6A", "Bb": "6B",
42
+ "Dm": "7A", "F": "7B", "Am": "8A", "C": "8B", "Em": "9A", "G": "9B",
43
+ "Bm": "10A", "D": "10B", "F#m": "11A", "A": "11B", "C#m": "12A", "E": "12B",
44
+ }
45
+ for raw, camelot in wheel.items():
46
+ self.check(raw, camelot, "converted")
47
+
48
+ def test_enharmonics(self):
49
+ self.check("G#m", "1A", "converted")
50
+ self.check("Gb", "2B", "converted")
51
+ self.check("A#m", "3A", "converted")
52
+ self.check("Dbm", "12A", "converted")
53
+
54
+ def test_long_and_unicode_forms(self):
55
+ self.check("F# minor", "11A", "converted")
56
+ self.check("Ab Major", "4B", "converted")
57
+ self.check("A min", "8A", "converted")
58
+ self.check("C maj", "8B", "converted")
59
+ self.check("A♭m", "1A", "converted")
60
+ self.check("F♯", "2B", "converted")
61
+ self.check(" Am ", "8A", "converted")
62
+
63
+ def test_camelot(self):
64
+ self.check("8A", "8A", "already")
65
+ self.check("12B", "12B", "already")
66
+ self.check("8a", "8A", "converted")
67
+ self.check("08A", "8A", "converted")
68
+ self.check("13A", None, "unknown")
69
+
70
+ def test_open_key(self):
71
+ self.check("1m", "8A", "converted")
72
+ self.check("1d", "8B", "converted")
73
+ self.check("6m", "1A", "converted")
74
+ self.check("12m", "7A", "converted")
75
+ self.check("12d", "7B", "converted")
76
+
77
+ def test_combined_formats(self):
78
+ self.check("Am/8A", "8A", "converted")
79
+ self.check("8A - Am", "8A", "converted")
80
+ self.check("Am | 8A", "8A", "converted")
81
+ self.check("Am/9A", None, "unknown") # parts disagree: leave it alone
82
+
83
+ def test_empty_and_unknown(self):
84
+ self.check("", None, "empty")
85
+ self.check(" ", None, "empty")
86
+ self.check("H", None, "unknown")
87
+ self.check("xyz", None, "unknown")
88
+
89
+
90
+ class CliTests(unittest.TestCase):
91
+ def setUp(self):
92
+ self.tmp = Path(tempfile.mkdtemp())
93
+ self.xml = self.tmp / "rekordbox.xml"
94
+ shutil.copy(EXAMPLE, self.xml)
95
+
96
+ def tearDown(self):
97
+ shutil.rmtree(self.tmp)
98
+
99
+ def test_dry_run_writes_nothing(self):
100
+ before = self.xml.read_bytes()
101
+ result = run_cli("--input", str(self.xml), "--dry-run", "-v")
102
+ self.assertEqual(result.returncode, 0, result.stderr)
103
+ self.assertIn("4 converted to Camelot", result.stdout)
104
+ self.assertEqual(self.xml.read_bytes(), before)
105
+ self.assertEqual(sorted(p.name for p in self.tmp.iterdir()), ["rekordbox.xml"])
106
+
107
+ def test_output_file(self):
108
+ out = self.tmp / "fixed.xml"
109
+ result = run_cli("--input", str(self.xml), "--output", str(out))
110
+ self.assertEqual(result.returncode, 0, result.stderr)
111
+ self.assertEqual(tonalities(out), {
112
+ "Already Camelot": "8A", "Standard Minor": "8A", "Standard Major": "8B",
113
+ "MIK Long Form": "11A", "Flat Notation": "3A", "No Key": "",
114
+ })
115
+
116
+ def test_drop_mode_writes_fixed_copy(self):
117
+ before = self.xml.read_bytes()
118
+ result = run_cli(str(self.xml))
119
+ self.assertEqual(result.returncode, 0, result.stderr)
120
+ self.assertEqual(self.xml.read_bytes(), before)
121
+ self.assertEqual(tonalities(self.tmp / "rekordbox_fixed.xml")["Standard Minor"], "8A")
122
+
123
+ def test_inplace_makes_backup_and_never_overwrites_it(self):
124
+ original = self.xml.read_bytes()
125
+ self.assertEqual(run_cli("--input", str(self.xml), "--inplace").returncode, 0)
126
+ self.assertEqual((self.tmp / "rekordbox.xml.bak").read_bytes(), original)
127
+ self.assertEqual(tonalities(self.xml)["Standard Minor"], "8A")
128
+
129
+ self.assertEqual(run_cli("--input", str(self.xml), "--inplace").returncode, 0)
130
+ self.assertEqual((self.tmp / "rekordbox.xml.bak").read_bytes(), original)
131
+ self.assertEqual(len(list(self.tmp.glob("rekordbox.xml.*.bak"))), 1)
132
+
133
+ def test_inplace_dry_run_makes_no_backup(self):
134
+ self.assertEqual(run_cli("--input", str(self.xml), "--inplace", "--dry-run").returncode, 0)
135
+ self.assertFalse((self.tmp / "rekordbox.xml.bak").exists())
136
+
137
+ def test_output_same_as_input_is_refused(self):
138
+ result = run_cli("--input", str(self.xml), "--output", str(self.xml))
139
+ self.assertNotEqual(result.returncode, 0)
140
+ self.assertIn("--inplace", result.stderr)
141
+
142
+ def test_output_and_inplace_is_refused(self):
143
+ result = run_cli("--input", str(self.xml), "--output", str(self.tmp / "x.xml"), "--inplace")
144
+ self.assertNotEqual(result.returncode, 0)
145
+
146
+ def test_invalid_xml_gives_clean_error(self):
147
+ self.xml.write_text("not xml", encoding="utf-8")
148
+ result = run_cli("--input", str(self.xml), "--dry-run")
149
+ self.assertEqual(result.returncode, 1)
150
+ self.assertIn("not a valid XML file", result.stderr)
151
+ self.assertNotIn("Traceback", result.stderr)
152
+
153
+ def test_version(self):
154
+ result = run_cli("--version")
155
+ self.assertIn(tool.__version__, result.stdout)
156
+
157
+
158
+ if __name__ == "__main__":
159
+ unittest.main()