Rekordbox Plugin Guide

Difficulty: Intermediate | Time: 20-30 minutes (first time), 5 minutes (subsequent imports)

Import DJ mixes from Rekordbox with automatic tracklisting, MP3 encoding, and markdown generation.

Overview

The Rekordbox plugin:

• Imports WAV audio + CUE tracklist from Rekordbox
• Encodes to high-quality 320kbps MP3
• Parses CUE files for automatic tracklisting
• Generates markdown with frontmatter
• Optionally adds to iTunes library
• Optionally archives original files

Prerequisites

# Install encoding tools
brew install lame ffmpeg

Quick Start

# First import - configure interactively
astrolock import rekordbox

The wizard will:

1. Let you choose an audio collection
2. Ask for configuration settings
3. Save to .astrolock/rekordbox.json for future use
4. Process your mix and create all files

Next imports are faster - just press Enter to accept saved defaults!

Configuration File

Configuration is stored in .astrolock/rekordbox.json (not in init.json).

Basic Configuration

{
  "mixes": {
    "enabled": true,
    "IMPORT_FOLDER": "~/Rekordbox/Recordings",
    "ASSETS_FOLDER": "public/audio/content/mixes",
    "SOURCE_FOLDER": "src/content/mixes",
    "POST_TITLE_PREFIX": "My Podcast",
    "POST_TAGS": "mix, techno, house",
    "TAG_GENRE": "Electronic",
    "TAG_ARTIST": "DJ Name",
    "TAG_ALBUM": "Mix Series",
    "TAG_GROUPING": "DJ Mix"
  }
}

With Defaults (Multiple Collections)

Use "defaults" to share settings across collections:

{
  "defaults": {
    "IMPORT_FOLDER": "~/Rekordbox/Recordings",
    "TAG_ARTIST": "DJ Name",
    "TAG_GROUPING": "DJ Mix",
    "LIBRARY_FOLDER": "~/Music",
    "LIBRARY_ADD_FOLDER": "~/Automatically Add to Music.localized"
  },
  "mixes": {
    "enabled": true,
    "ASSETS_FOLDER": "public/audio/content/mixes",
    "SOURCE_FOLDER": "src/content/mixes",
    "POST_TITLE_PREFIX": "Techno Sessions",
    "TAG_ALBUM": "Techno Sessions",
    "TAG_GENRE": "Techno"
  },
  "podcasts": {
    "enabled": true,
    "ASSETS_FOLDER": "public/audio/content/podcasts",
    "SOURCE_FOLDER": "src/content/podcasts",
    "POST_TITLE_PREFIX": "My Podcast",
    "TAG_ALBUM": "My Podcast",
    "TAG_GENRE": "Podcast"
  }
}

Configuration Fields

Required Fields

Field	Description	Example
enabled	Enable/disable plugin	true
IMPORT_FOLDER	Source folder for WAV/CUE files	~/Rekordbox/Recordings
ASSETS_FOLDER	Output folder for MP3 files	public/audio/content/mixes
SOURCE_FOLDER	Output folder for markdown	src/content/mixes

Optional Metadata Fields

Field	Description	Example
POST_TITLE_PREFIX	Prefix for titles	"RpHP Sessions"
POST_TAGS	Default tags (comma-separated)	"mix, techno, house"
TAG_GENRE	Genre tag	"Electronic"
POST_INTRO	Introduction text	"A recorded session..."
POST_LEADER	Section header	"Tracklist"
TAG_ARTIST	MP3 artist tag	"Your DJ Name"
TAG_ALBUM	MP3 album tag	"Mix Series"
TAG_GROUPING	MP3 grouping	"DJ Mix"

Optional Archive/Library Fields

Field	Description	Example
LIBRARY_FOLDER	iTunes library folder	~/Music
LIBRARY_ADD_FOLDER	iTunes auto-add folder	~/Automatically Add to Music.localized
ARCHIVE_WAV_FOLDER	Archive original WAV files	~/Archive/WAV
ARCHIVE_MP3_FOLDER	Archive encoded MP3 files	~/Archive/MP3

The Import Process

First Import

astrolock import rekordbox

You’ll be prompted for:

1. Collection - Which audio collection to import to
2. Import folder - Where Rekordbox saves recordings
3. Title prefix - e.g., “RpHP Sessions”, “My Podcast”
4. Tags - Comma-separated keywords
5. Genre - Music genre
6. Intro/description - About the mix
7. Artist & album - Your DJ name and series

Subsequent Imports

The CLI loads saved settings and shows them as defaults:

Title prefix (e.g., "RpHP Sessions") [My Podcast]: ⏎
Tags (comma-separated) [mix, techno, house]: ⏎
Genre [Electronic]: ⏎

Just press Enter to accept defaults, or type new values to override.

What Gets Created

Markdown File

src/content/mixes/2024-01-15-my-mix.md:

---
title: "My Podcast 2024-01-15"
date: 2024-01-15T00:00:00.000Z
categories:
  - audio
tags:
  - mixes
  - techno
genres:
  - Electronic
---

## Introduction

A recorded ad-hoc session of freshly discovered tunes, new and old.

1. Artist Name - Track Title (00:00)
2. Another Artist - Another Track (05:30)
3. Third Artist - Third Track (12:15)
   ...

Audio File

public/audio/content/mixes/2024-01-15-my-mix.mp3

• 320kbps high-quality MP3
• ID3 tags with artist, album, genre

Optional Archives

If configured:

• ~/Archive/WAV/DJ Name/Mix Series/original.wav
• ~/Archive/MP3/DJ Name/Mix Series/encoded.mp3

Advanced Usage

iTunes Integration

To automatically add mixes to iTunes/Music:

{
  "LIBRARY_ADD_FOLDER": "/Users/username/Music/Music/Media.localized/Automatically Add to Music.localized"
}

The MP3 will be copied to this folder after encoding.

Archiving Originals

To save originals to external drive:

{
  "ARCHIVE_WAV_FOLDER": "/Volumes/Backup/Archive/WAV",
  "ARCHIVE_MP3_FOLDER": "/Volumes/Backup/Archive/MP3"
}

Files are organized as {ARTIST}/{ALBUM}/{filename}.

Skip Archives/Library

Leave fields empty or omit them:

{
  "LIBRARY_ADD_FOLDER": null,
  "ARCHIVE_WAV_FOLDER": null,
  "ARCHIVE_MP3_FOLDER": null
}

Troubleshooting

No WAV files found

Check:

1. IMPORT_FOLDER path is correct
2. WAV files exist in that folder
3. Path is absolute (not relative)
4. Tilde (~) is properly expanded

Fix: Update in .astrolock/rekordbox.json:

{
  "IMPORT_FOLDER": "/Users/yourusername/Rekordbox/Recordings"
}

Missing tracklist

Cause: No CUE file or CUE file not readable

Check: CUE file exists with same name as WAV:

my-mix.wav
my-mix.cue  ← Must have same base name

lame: command not found

brew install lame ffmpeg

Encoding takes too long

Expected: A 60-minute mix takes 2-5 minutes to encode at 320kbps quality.

Can’t read saved configuration

Check:

# Validate JSON syntax
jq '.' .astrolock/rekordbox.json

# Install jq if missing
brew install jq

Workflow Examples

Weekly Podcast Series

{
  "podcasts": {
    "enabled": true,
    "POST_TITLE_PREFIX": "The Weekly Mix",
    "POST_TAGS": "podcast, weekly, electronic",
    "TAG_GENRE": "Podcast",
    "TAG_ARTIST": "DJ Name",
    "TAG_ALBUM": "The Weekly Mix"
  }
}

Generates consistent titles: “The Weekly Mix #42”, “The Weekly Mix #43”, etc.

Multiple Mix Series

{
  "defaults": {
    "IMPORT_FOLDER": "~/Rekordbox/Recordings",
    "TAG_ARTIST": "DJ Name"
  },
  "techno-sessions": {
    "enabled": true,
    "POST_TITLE_PREFIX": "Techno Sessions",
    "TAG_GENRE": "Techno",
    "TAG_ALBUM": "Techno Sessions"
  },
  "house-vibes": {
    "enabled": true,
    "POST_TITLE_PREFIX": "House Vibes",
    "TAG_GENRE": "House",
    "TAG_ALBUM": "House Vibes"
  }
}

Best Practices

1. Naming: Use consistent naming for WAV exports:

   2024-01-15-session-name.wav
   2024-01-15-session-name.cue

2. Batch Import: Export multiple mixes, then run imports in one session (saved defaults make it fast)

3. Review Before Publishing: Content is created with draft: false by default - edit before building

4. Backup Strategy:

   • Commit .astrolock/rekordbox.json to git
   • Commit generated markdown to git
   • Archive WAV files to external drive
   • Exclude public/audio/ from git (large files)

Command-Line Usage

# Via CLI (recommended)
astrolock import rekordbox

# Via Makefile
cd /path/to/project
make -f /path/to/astrolock-template/Makefile rekordbox.import COLLECTION=mixes

# Via Node.js (advanced)
node plugins/rekordbox/rekordboxImport.js /path/to/project mixes

Next Steps

1. Configure: Edit .astrolock/rekordbox.json
2. Export: Record and export from Rekordbox
3. Import: Run astrolock import rekordbox
4. Review: astrolock list mixes
5. Build: astrolock build
6. Deploy: astrolock deploy

---

See Also:

• Import Command Reference
• Collections Guide
• Content Management