Universal DJ USB

A tool for converting playlists present in Rekordbox-ready USB drives to various formats including Traktor NML, M3U, and M3U8.

Features

• Parse Rekordbox USB drives: Automatically detect and parse Rekordbox database files (.pdb)
• Multiple output formats: Convert to Traktor NML, M3U, or M3U8 playlists
• Cross-platform: Works on Windows, macOS, and Linux
• Preserve metadata: Keep track information, BPM, Key
• Flexible paths: Support for both relative and absolute file paths
• Playlist filtering: Convert specific playlists or all playlists at once
• GUI: Graphical user interface for easy interaction
• CLI interface: Easy-to-use command-line interface with rich output

Installation (users)

There are two flavors for this tool: GUI app or CLI, both are portable 1-file executables. I try to keep feature parity on both.

1. Download the latest release from the Releases page. Pick your OS and architecture.
2. Run the executable (GUI) or follow the CLI instructions.
3. Be (somehow) free from vendor lock 👌

Usage (opinionated)

I recommend you save the playlists in a folder inside your USB drive so that you take them with you!

Because of OS reasons, paths might differ when using this tool in macOS vs Windows, so it's also wise to keep this (portable) app in your USB drive in case you need to quickly re-generate your playlists and start playing!

This is not the case for NML! Traktor playlists generated in macOS will work in Windows and vice versa :D

My usual workflow would be:

1. Sync rekordbox playlists to USB drive.
2. Open the Universal DJ USB app.
3. Convert the ones I might use at the afters later to a folder in the same USB. 🤣
4. Profit!

Detailed Usage

GUI Usage

1. Launch the application. Refresh USB drives.
2. Select the USB drive containing the Rekordbox playlists (will be detected automatically).
3. Choose the desired output folder and format(s) and any specific playlists to convert.
4. Click "Convert" and wait for the process to complete.
5. Find created playlist in the specified output folder.

CLI Usage

# Basic help and version
udj --help
udj --version

# List available playlists on a USB drive
udj list-playlists /path/to/usb/drive

# Convert all playlists to Traktor NML format
udj convert /path/to/usb/drive

# Convert specific playlists to M3U format
udj convert /path/to/usb/drive -p "My Playlist" -p "Another Playlist" -f m3u

# Convert to all formats
udj convert /path/to/usb/drive -f all -o ./output

Commands

detect

Detect and validate Rekordbox data on a USB drive.

udj detect /path/to/usb/drive

list-playlists

List all available playlists on the USB drive.

udj list-playlists /path/to/usb/drive

convert

Convert playlists to specified format(s).

udj convert [OPTIONS] USB_PATH

Options:
  -o, --output PATH           Output directory for playlist files
  -p, --playlist TEXT         Specific playlist names to convert (multiple allowed)
  -f, --format [nml|m3u|m3u8|all]  Output format (default: nml)
  --relative-paths/--absolute-paths  Use relative or absolute file paths (default: relative)

info

Get detailed information about a specific playlist.

udj info /path/to/usb/drive "Playlist Name"

Examples

# Convert all playlists to Traktor NML format
udj convert /Volumes/USB_DRIVE -f nml -o ~/TraktorPlaylists

# Convert specific playlists to M3U8 format
udj convert /Volumes/USB_DRIVE -p "House Music" -p "Techno Sets" -f m3u8

# Get information about a playlist
udj info /Volumes/USB_DRIVE "My Weekend Mix"

File Structure

The tool expects a standard Rekordbox USB drive structure:

USB Drive/
├── PIONEER/
│   └── rekordbox/
│       └── export.pdb          # Main database file
└── Contents/                      # Your music files
    ├── <Artist>
    │   ├── <Album>
    │   │   ├── track1.mp3
    │   │   ├── track2.mp3
    │   │   └── ...
    │   └── ...
    └── ...

Output Formats

Traktor NML (.nml)

• Native Traktor playlist format
• Includes (full) metadata, Key, and BPM information

M3U (.m3u)

• Basic playlist format supported by most DJ software and media players
• Includes track duration and basic metadata

M3U8 (.m3u8)

• Extended M3U format with UTF-8 encoding
• Includes additional metadata like album, year, genre, and BPM (maybe not)
• Better cross-software compatibility (except Traktor)

Development

Note

I have developed this with heavy use of AI agent (Claude Sonnet 4). I acknowledge the limitations and potential inaccuracies that may arise from this, but on the way I've learned a lot on how to use it wisely. I'd rather say I was the architect that told the builder what to do and closely supervised the process. All testing and validation has been done manually, as well as the engineering approaches taken were decided by me.

Setting up for Development

# Clone the repository
git clone https://github.com/juanmartin/universal-dj-usb.git
cd universal-dj-usb

# Setup python version
pyenv local 3.11.13

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting and formatting
uv run black src/
uv run isort src/
uv run flake8 src/

Running Tests

uv run pytest
uv run pytest --cov=src/universal_dj_usb

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Motivation

Many times I have found myself in the situation in which someone wants to play using my equipment (Traktor) and they have a rekordbox-ready USB drive, so they would not have their playlists displayed in Traktor, only the Contents/ folder impossible to play with. It even happens to me, as I usually only carry a rekordbox-ready USB to play with CDJs. But at friends' houses, some have Traktor or other systems.

With this, you can easily convert your playlists on the fly, avoiding having duplicated audio files and just referencing them from existing rekordbox playlists. So you only sync once with rekordbox, then this translates that to other compatible playlists formats.

How?

This tool works by parsing the Rekordbox database file (export.pdb) and extracting the necessary information to create compatible playlists for other DJ software. Files are untouched. Rekordbox puts audio files in a specific folder structure, so this tool can easily locate them based on the metadata extracted from the database.

Acknowledgments

• This project uses Kaitai Struct definitions for parsing Rekordbox PDB files
• Thanks to the guys at Deep-Symmetry for reverse engineering the Rekordbox format. Check out their crate-digger. I found about this from using Mixxx DJ software and seeing it could parse playlists from a rekordbox-ready USB. This would not be possible without their work.
• Built with Python, Click, Rich, and lxml

Troubleshooting

Common Issues

1. "No Rekordbox database found"

   • Ensure your USB drive contains a proper Rekordbox export
   • Check that the PIONEER/rekordbox/export.pdb file exists

2. "Failed to parse database"

   • The PDB file might be corrupted or from an unsupported Rekordbox version
   • Try exporting again from Rekordbox

3. File paths not working

   • Use the --relative-paths option for better cross-platform compatibility
   • Ensure your music files are in the expected location on the USB drive

Getting Help

• Open an issue on GitHub with detailed information about your problem
• Include the USB drive structure and any error messages
• Specify your operating system and Python version