Skip to main content

Utilities to read and write Traktor NML files

Project description

Traktor NML utils

Python package

This module contains utilities to parse and modify Native Instruments Traktor NML files.
Both Traktor 2.x and Traktor 3.x NML files are supported.

It can parse collection NML files ($TRAKTOR_DIR/collection.nml) and history NML files ($TRAKTOR_DIR/History/history_$DATE.nml).

All NML attributes are readable and writable using auto-generated dataclasses (see traktor_nml_utils/models).
This allows a typesafe way to work with NML files, fully supporting IDE autocompletion:

alt text

While reading should work in 99% cases, writing NML files hasn't been tested thoroughly enough yet, so always keep a copy of your NML files.


Because traktor-nml-utils uses dataclasses, you need at least Python 3.7.x.

traktor-nml-utils is tested with Traktor 3.3.0, though it should be able to parse Traktor 2.x NML files as well. Feel free to provide files that cause problems on parsing.


pip install traktor-nml-utils


Get artist, title and rating of all collection entries

from traktor_nml_utils import TraktorCollection
from pathlib import Path

collection = TraktorCollection(path=Path('collection.nml'))

for entry in collection.nml.entry:
    print(entry.artist, entry.title,

Get cuepoint start

entry = collection.nml.entry[0]

for cue_v2 in entry.cue_v2:

Find entry

artist = "Yotto"
title = "Another Riff For The Good Times (Extended Mix)"

entry = [
    entry for entry in collection.nml.entry 
    if entry.artist == artist
    and entry.title == title

Add cuepoint

from traktor_nml_utils.models.collection import CueV2Type
from traktor_nml_utils.utils import duration_str_to_milliseconds

my_cue = CueV2Type(

# Write XML file

Run tests

Run tests within Docker container:

make docker-build docker-test

Create virtualenv and run tests:

make virtualenv-create virtualenv-test

To test if parsing your own collection/history files with traktor-nml-utils works, pass your Traktor directory to pytest:

pytest --nml-dir="~/traktor3/" tests/

How does it work?

NML file to XSD schema

Since there is no official XSD available to parse Traktor NML files, an XSD was generated both for history and collection files using Apache XMLBeans.

See them in xml_to_xsd/collection.xsd and xml_to_xsd/history.xsd.

You can regenerate the XSD by putting your own collection.nml and history.nml overwriting the existing ones in ./xml_to_xsd/ and run:

make xml-to-xsd

XSD to Python dataclasses

Using the generated XSD files, Python dataclasses can be generated with xsdata. To update these, run:

make xsd-to-python


Help wanted!

Since the XSD-schema was created from my own Traktor files, the schema might not fit for all collection and history files. In case you have any problems parsing NML files, please report an issue and attach the problematic NML file so I can update the schema.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for traktor-nml-utils, version 3.1.0
Filename, size File type Python version Upload date Hashes
Filename, size traktor-nml-utils-3.1.0.tar.gz (21.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page