traktor-metadata

Read and write Native Instruments Traktor DJ metadata from audio files.

Features

• Parse Traktor's proprietary binary metadata from MP3 files
• Extract BPM, key, cue points, loops, artwork, and more
• Serialize metadata back to binary format
• Full TypeScript support
• Works in Node.js and browser

Installation

npm install traktor-metadata

Usage

Extract from file (Node.js)

import { extractFromFile } from 'traktor-metadata'

const metadata = await extractFromFile('track.mp3')

console.log(metadata.title)      // "Track Name"
console.log(metadata.artist)     // "Artist Name"
console.log(metadata.bpm)        // 128.5
console.log(metadata.key)        // "Am"
console.log(metadata.cuePoints)  // [{ name: "Drop", start: 60000, ... }]

Extract from buffer

import { extractFromBuffer } from 'traktor-metadata'

const buffer = await fs.promises.readFile('track.mp3')
const metadata = await extractFromBuffer(new Uint8Array(buffer))

Parse raw Traktor binary data

import { parse } from 'traktor-metadata'

// If you already have the PRIV frame data
const metadata = parse(traktorBinaryData)

Serialize metadata

import { serialize } from 'traktor-metadata'

const metadata = {
  title: 'My Track',
  artist: 'Artist Name',
  bpm: 128,
  key: 'Am',
  cuePoints: [
    { name: 'Drop', index: 0, type: 0, start: 60000, length: 0, repeats: 0, hotcue: 1 }
  ]
}

const binary = serialize(metadata)
// Write binary to PRIV frame in ID3 tag

API

Types

interface TraktorMetadata {
  // Track info
  title?: string
  artist?: string
  album?: string
  genre?: string
  label?: string
  producer?: string
  remixer?: string
  comment?: string

  // Analysis
  bpm?: number
  bpmPrecise?: number
  key?: string
  keyNumeric?: number

  // Stats
  trackNumber?: number
  playCount?: number
  ranking?: number
  lengthMs?: number
  bitrate?: number

  // Dates
  fileModified?: Date
  releaseDate?: Date
  lastPlayed?: Date
  importDate?: Date

  // Complex data
  cuePoints?: CuePoint[]
  artwork?: Artwork

  // Validation
  checksumValid?: boolean
  formatVersion?: number
}

interface CuePoint {
  name: string
  index: number
  type: CuePointType
  start: number      // milliseconds
  length: number     // milliseconds (for loops)
  repeats: number    // -1 = infinite
  hotcue: number     // 1-8, or 0 if not a hot cue
}

enum CuePointType {
  Cue = 0,
  FadeIn = 1,
  FadeOut = 2,
  Load = 3,
  Grid = 4,
  Loop = 5,
}

interface Artwork {
  width: number
  height: number
  data: Uint8ClampedArray  // RGBA pixels
}

Functions

| Function | Description | |----------|-------------| | extractFromFile(path) | Extract metadata from an audio file (Node.js) | | extractFromBuffer(buffer) | Extract metadata from a buffer | | parse(buffer) | Parse raw Traktor binary data | | serialize(metadata) | Serialize metadata to binary format | | calculateChecksum(buffer) | Calculate Traktor checksum |

Demo

Try the interactive demo to parse Traktor metadata in your browser.

How it works

Traktor stores DJ-specific metadata in the PRIV frame of ID3v2 tags. This library:

1. Extracts the PRIV frame from the audio file
2. Parses the proprietary binary format (element tree structure)
3. Decodes all field types (strings, floats, dates, cue points, artwork)
4. Validates the checksum

For writing, the process is reversed: metadata is serialized to the binary format with proper checksums.

License

MIT