TraCoMerger - Manual (Introduction, Workflows, FAQ's, Release Notes)

last Update: August 11, 2017

 


Introduction

What is TraCoMerger ?

Typical Use cases for TraCoMerger

How does TraCoMerger work ?

What is new since TDJ supports iCloud (instead Dropbox) ?

 

Workflows (Use case examples)

Use case 1 - Backup and restore the Traktor DJ (iOS) meta data

Use case 2 - Transfer cue points from Traktor DJ (iOS) to Traktor Pro (PC/Mac)

Use case 3 - Transfer cue points from Traktor Pro (PC/Mac) to Traktor DJ (iOS)

Use case 4 - Using TraCoMerger to transfer musical key tags into TDJ

 

FAQ’s

TraCoMerger System requirements

Is Mac OS X also supported ?

Do I need itunes to sync meta data ?

Do I need the my songs on the TraCoMerger PC ?

Do I need the same songs in both collections (ORIGINAL and IMPORT) ?

Can I import several collections into one new collection?

Where can I find my collection.nml in Traktor Pro (Mac or PC) ?

Where can I find my collection.nml in Traktor DJ (iOS) ?

How to replace the ORIGINAL Traktor Pro collection.nml (Mac or PC) with the new merged collection ?

How to replace the ORIGINAL Traktor DJ collection.nml (iOS) with the new merged collection ?

Is it important to make regular backups of the Traktor collection.nml ?

What is the use case of the File Viewer ?

What is TraCoConverter and how does it work together with TraCoMerger ?

Contact for further questions, ideas, comments

 

Release Notes

 


Introduction

 

What is TraCoMerger ?

TraCoMerger is a “Traktor Collection Merger”, a PC Windows stand alone application to import new or updated meta data into any Traktor song collection. I wrote this application because I missed several features in Traktor DJ and in Traktor Pro:

The TraCoMerger application works for Traktor Pro (PC or Mac) and also for the Traktor DJ (iOS) song collection files. The application itself is a Windows application, but works also with Mac files. All Traktor versions (Traktor Pro and Traktor DJ) store the analyzed meta data of the Traktor song collection in a file named “collection.nml”.

So the idea to solve all listed features were born: TraCoMerger allows you to modify the collection.nml file … which includes grid marker, all 8 hot cue points, musical key values and analyzed bpm. TraCoMerger can transfer information from one collection.nml into another one, it doesn't matter if it is a Traktor Pro or a TDJ (iOS) collection, all possibilities are supported (TPro > TDJ, TDJ > TPro, TPro1 > TPro2, TDJ1 >TDJ2 ..), TraCoMerger always keeps the requested syntax of the original collection file. 

 

Typical Use cases for TraCoMerger

There are several, quite different uses cases. All these use cases are based on one idea: transfer the metadata information from one collection into another collection, Examples:

 

How does TraCoMerger work ?

The application needs 2 files: 1. the collection.nml from your target system (ORIGINAL COLLECTION) and 2. the collection.nml with the information you want to include (IMPORT FILE). Example: if you want to transfer cue points from TPro to TDJ then the TDJ collection is your ORIGINAL. The application will merge both and generate a new merged collection.nml (with file extension "_merged.nml"). Rename the new file "xy_merged.nml" into "collection.nml" and replace your current Traktor collection.nml with it. All meta data will appear in Traktor.

Important to understand the workflow: The new merged collection has exactly the same structure and count of songs as the ORIGINAL COLLECTION, means no song added or removed. This ensures it will always match to you target system.

The new merged collection will contain all songs of ORIGINAL with the meta data information of the IMPORT FILE (hot cues, grid, musical key, bpm). TraCoMerger search for each song in ORIGINAL for the same named song in IMPORT. If the tags TITLE-ARTIST-ALBUM are written exactly same then the application transfers this information. If you have double entries in your library or different songs with same name (with same TITLE-ARTIST-ALBUM) then the first song in IMPORT is used to match.

Don’t worry, TraCoMerger does not write anything into file ORIGINAL collection or IMPORT file. Both files are open as read only. All new information is stored in new merged collection only.

And last detail: TDJ and Traktor Pro sometimes struggle with the special character “ in song titles … don’t ask me why :), so my suggestion is always to avoid this character in song titles at all.

Summary of the TraCoMerger workflow: TraCoMerger merge two collection.nml files and create a new one with all updated information. This merged file can be used to replace files without (or older) metadata. It’s not any online sync mechanism (as it was supported between older NI Traktor Pro versions with TDJ.

TraCoMerger can not substitute the still missed automated meta data sync between Traktor Pro and TDJ connectivity, but keep in mind: this is not the only use case, the manual process via TraCoMerger has the advantage that you can combine whatever collections, and at any certain time you need. It’s under your control and independent from any itunes, iOS installations, any song libraries or different laptop systems – TraCoMerger is a flexible meta data transfer tool, not a sync tool. 

 

What is new since TDJ supports iCloud (instead Dropbox) ?

The Dropbox access from TDJ ended at June 28th 2017. After this date it was not longer possible to store or share any TDJ metadata. So NI offered a new TDJ version (1.6.8) which uses the Apple iCloud for meta data sharing, a successor for the older Drop box using versions.

From my own experience the TDJ Cloud workflow works quite well. It is similar to Dropbox workflow in past, but some details changed, the restore into TDJ changed completely. So you need the current TraCoMerger, 1.5 is the first one which supports all iCloud related features

Pros and Cons (TDJ iCloud compared to TDJ Dropbox connectivity in past):

Pros:

(+) works well, easier to use (no longer any setting in TDJ options needed), no Dropbox needed + the restore of a new merged collection (from TraCoMerger) is much easier + the whole TraCoMerger workflow works well (also the transfer to/from Traktor Pro)

Cons:

(-) The TDJ 1.6.8 is an iPad version only, currently not possible to install on iPhone. As long as NI does not change this, you can not share any meta data between iPads and iPhone. It worked in the past (with Dropbox), but does not work with iCloud. And of course my TraCoMerger can not be used as NI does not create any external collection.nml. So let’s cross our finger that NI will offer a TDJ iPhone version with iCloud support soon.

(-) 2nd problem: In the past you could replace an existing collection.nml with an older backup (maybe some guys remember my ‘hack’ with the Dropbox folder rename). So a backup/restore workflow was possible. TDJ checks the timestamp and user of each meta data change in collection.nml, so an older backup will be rejected. Good news: the new TraCoMerger updates timestamp & user, so a restore via TraCoMerger works well, even easier then in past.

(-) to my own surprise: I excepted that meanwhile a de-install and new re-install of a TDJ version would load older meta data automatically from iCloud .. but it does NOT !. So be careful, with a reinstall of TDJ, you will still lose all meta data (same as in past with Dropbox.). So I still recommend to make a backup of your iCloud collection regularly, so you can use TraCoMerger to recover the data.

In summary:

  


Workflows (Use case examples)

 

Use case 1 - Backup and restore the Traktor DJ (iOS) meta data

The Backup Workflow is the easier part, search for the TDJ collection.nml.gz file and store it at a safe place. See FAQ: “Where can I find my collection.nml in Traktor DJ (iOS) ?”

Restore workflow:

This workflow has completely changed since TDJ 1.6.8, when Dropbox got replaced from iCloud.

Bad news:

It is NOT longer possible to restore older meta date with a older backup file. If you ever test to replace the iCloud collection with your backup you may notice that TDJ is ignoring the file, because the older backup contains older data then the iCloud data. More details see FAQ: “What is new since TDJ supports iCloud (instead Dropbox) ?”

Good news:

Using TraCoMerger it is still possible to restore any meta data from older backup files. So the only difference to earlier restore workflow (with Dropbox): TraCoMerger seems mandatory meanwhile, because you ‘must’ create a new merged collection from of your earlier backup file, before you replace on iCloud.

Workflow:

 

Use case 2 - Transfer cue points from Traktor DJ (iOS) to Traktor Pro (PC/Mac)

The maybe most important use case for most user is the meta data transfer between Traktor Pro and TDJ. Background: NI disabled this native feature in Traktor Pro in versions later 2.6.6. TraCoMerger allows you now to transfer the meta data via collection.nml update, works for all versions of Traktor Pro or TDJ.

Workflow:

1) Ensure your tracks are completely analyzed in Traktor Pro (your target system):
In Traktor Pro: select the songs in Track Collection (or select whole Track Collection), choose mouse context menu Analyze (Async). Of course only for the songs with missed or old cue points, because Analyze will redefine bpm and erase all cues. Wait until Analyze process is done.

2) Now search for both collection.nml files from Traktor Pro and TDJ:
See FAQ: "Where can I find my collection.nml in Traktor Pro (Mac or PC) ?" and
See FAQ: "Where can I find my collection.nml in Traktor DJ (iOS) ?".
Copy the Traktor Pro file ‘collection.nml’ (from your PC/Mac) and the Traktor DJ collection.nml (included in the compressed collection.nml.gz !) to any folder on the PC with TraCoMerger, best is to rename for not mixing up, e.g. “collection_TPro.nml” and “collection_TDJ.nml”.

3) Start TraCoMerger and select:
ORIGINAL collection = “collection_TPro.nml”
IMPORT file = “collection_TDJ.nml”
Press button ‘Create NEW Collection’. A new collection with extension _merged.nml is created.
An additional created .log file shows you what TraCoMerger did in detail (useful if any warnings appeared during merging process).

4) Replace original collection.nml of Traktor Pro with the new created merged collection:
See FAQ: “How to replace the ORIGINAL Traktor DJ collection.nml (iOS) with the new merged collection ?”

5) Start Traktor Pro, you should find all TDJ meta data (grid, bpm, musical keys, 8 hot cue points) in Traktor Pro.
Done :) 

 

Use case 3 - Transfer cue points from Traktor Pro (PC/Mac) to Traktor DJ (iOS)

The maybe most important use case for most user is the meta data transfer between Traktor Pro and TDJ. Background: NI disabled this native feature in Traktor Pro in versions later 2.6.6. TraCoMerger allows you now to transfer the meta data via collection.nml update, works for all versions of Traktor Pro or TDJ.

Workflow:

1) Ensure your tracks are completely analyzed in Traktor DJ (your target system):
Open TDJ first and ensure there is no message visible like ‘“…xy songs of xy analyzed …” (song browser, message below the cross fader).
Wait until Analyze process is done.

2) Now search the Traktor Pro collection, see FAQ: "Where can I find my collection.nml in Traktor Pro (Mac or PC) ?"

3) the next steps are lightly different to the use case from TDJ to Traktor Pro. Simple reason: TDJ is mirroring all data continuously to iCloud (Traktor Pro does not), and we must ensure that your merged collection from TraCoMerger have latest date.
So you must create a new merged collection which is newer than the current iCloud collection !

ORIGINAL collection = current TDJ collection on iCloud
IMPORT file = Traktor Pro collection from step 2 
Now (!) launch TraCoMerger and create a new merged collection
Please follow exactly this workflow: “How to replace the ORIGINAL Traktor DJ collection.nml (iOS) with the new merged collection ?”

 

Use case 4 - Using TraCoMerger to transfer musical key tags into TDJ

Why ? - Traktor Pro users can modify their musical keys, ether manually or in batch e.g. with MixedInKey (MIK). The TDJ (Traktor DJ on iOS) users have a problem. Even if the mp3 would have the right (or MIK) value, itunes will not transfer this information into iOS song library. So TDJ is detecting itself, building always own keys. Solution: overwrite the TDJ values of the TDJ collection with 'better' (e.g.MIK) keys, using TraCoMerger to 'merge 'MIK' into TDJ'.

How ? - There are several way to do this. In each case you need an IMPORT FILE with the right keys. Either from a collection.nml with the right keys already (earlier backup) or creating an own collection manually with the right keys. 

Scenario 1 - You have already an older collection.nml with the right keys of your songs):

Quite easy: use the current collection as ORIGINAL COLLECTION, open the older collection (with the right keys) as an IMPORT FILE. The new merged collection will contain all songs of the ORIGINAL COLLECTION with the updated musical keys from your older collection. Done.

Scenario 2 - Your songs have the correct musical key in the mp3 tag attributes, but you don’t have any collection.nml with the correct keys yet:

This is the more complex scenario. How to create a file with the right keys ?.  What we need is a way to export all musical key tags from the mp3 songs, then create a file in Traktor collection.nml syntax which we can use a IMPORT FILE in TraCoMerger. Here’s the 3 step workflow for scenario 2:

1) Make sure your mp3 songs have the right musical keys in the original mp3 attribute tag. Use e.g. MixedInkey or the freeware e.g. Keyfinder to update the original mp3 tag. Don’t use the comment field tag, use the native musical key tag INITIALKEY.

2) You need a text file (using later as IMPORT FILE) which lists all songs including the correct musical key. The data enties must follow the NI Traktor syntax:  <ENTRY TITLE="…" [ARTIST="…"] [ALBUM TITLE="…"] MUSICAL_KEY VALUE="xy" </ENTRY>

Background to syntax: Each line starts with <ENTRY and ends with </ENTRY>, the music title is mandatory, artist and album optional (only needed if different songs have same title).  The musical key xy can be any of 5 options. TraCoMerger is quite flexible and translates all of this option to the right Traktor notation. Example for “xy” for C# major (C sharp): “C#” (musical sharp notation) or “Db” (musical flat notation) or “3B” (Camelot system) or “8d” (open notation) or “1” or “01” for Traktor Pro and Traktor DJ notation. All accepted.

How to create such a text file ?. Answer: You need any mp3 editor which allows creating flexible report exports. Easiest to use is the freeware mp3 editor ‘Mp3tag’ , because TraCoMerger (new since ver. 1.4) includes already a report macro for Mp3tag .Install instruction (once befor you can start): Copy the file ‘Export musical keys (Mp3tag macro).mte’ into your Mp3tag directory (usually in folder: ‘C:\Users\..\AppData\Roaming\Mp3tag\export’).

Open Mp3tag , load your songs, mark all songs (Ctrl-A), choose context menu (mouse right click) and click on ‘Export’. Select the new macro ‘Export musical keys (Mp3tag macro)’. Start export. A new file ‘musical_keys.nml’ will be created. This file contains the musical keys of all songs, following the Traktor Collection syntax.

3) Similar to scenario 1: Open TraCoMerger and use the current collection as ORIGINAL COLLECTION and the file ‘musical_keys.nml’ as IMPORT FILE. The new merged collection will contain all songs of the ORIGINAL COLLECTION with the updated musical keys. Done

Do you see ? .. even the workflow is somehow complex, it allows you to transfer e.g. MixedInKey musical keys into TDJ (Traktor Pro not needed at all). I did it once with my whole collection (using Scenario 2), since this day I enjoy the great song recommendation in TDJ with the much better MIK keys. And in future (e.g. after TDJ reinstall) i can use the simple Scenario 1, as my backup containts the MIK value now already.

Recap Workflow Summary: MIK write native mp3 tags > Create a mp3tag IMPORT file > TraCoMerger merges keys into TDJ collection > replace TDJ collection on iCloud 

 


FAQ’s

 

TraCoMerger System requirements

TraCoMerger runs on Microsoft Windows 7 (or later), 32 or 64 Bit. Also a parallel Windows 7 Installation on Mac should work.

Microsoft .NET 4.0 Framework (4.0 or higher) is always needed. Actual Windows versions include .NET 4.0 already, no addition installation necessary. If you start TraCoMerger and an application error or .NET warning occurs, then update your Windows with .NET first. Use any of the official MS Update links, e.g.: Microsoft .NET Framework 4 (Web Installer)

Windows XP is not longer supported from MS, but works also with TraCoMerger, IF latest XP update packages (including actual .NET 4.0) were installed before the MS Windows XP support ended.

TraCoMerger is a portable direct run application. To start double click the .exe itself, no install necessary. So it’s possible to run the application from any PC or direct from an USB stick or hard disc. Let me know if you have any problems with the direct run application, if necessary I also could build a Setup.exe in addition. 

 

Is Mac OS X also supported ?

TraCoMerger itself is a native Windows application, so will not run on a Mac OS X. But TraCoMerger running on any PC Windows can merge collection.nml files also from Traktor Pro on Mac.

If you have a Mac only, no PC … maybe ask a friend to run the application on his PC. Quite easy as TraCoMerger is a direct run application. Launch the application on any Windows PC with .NET 4.0 directly from USB stick. 

You don’t need any itunes or your mp3 song on the TraCoMerger PC. Only the 2 collection files (from TDJ on iOS or from Traktor Pro on Mac or PC). 

 

Do I need itunes to sync meta data ?

No, you don’t need itunes at all on the PC to create a new collection. You need only the TraCoMerger application itself (.exe), optionally the help file and the two collection files: 1. the collection.nml from your target system (ORIGINAL COLLECTION) with old or missed cue’s and 2. the collection.nml with the updated meta data information (IMPORT FILE). 

  

Do I need the my songs on the TraCoMerger PC ?

No, you also don’t need any songs on the PC to run the application. You need only the TraCoMerger application itself and the two collection files. This makes it quite easy to create the NEW collection also on separate Windows PC, also if one or both collection files are from any Mac or iOS device. Mac user can use any Windows PC of a friend, to merge their Mac or iOS collection files, as no songs or itunes is needed to on the TraCoMerger Windows PC. 

 

Do I need the same songs in both collections (ORIGINAL and IMPORT) ?

No, the benefit using this application is exactly, that the files must NOT match in counts of songs.

Understanding this workflow allows you to extract information from several backups into you current ORIGINAL backup.  

 

Can I import several collections into one new collection?

Yes of course. Merge your original collection with any IMPORT collection. Use the new merged collection as a new Original file and import the next one. Repeat as often you need.

I use this use case quite often, because I have collections of parts of my song library, or related to playlists or song collection backups from different days, also from different laptops or itunes libraries. You can import all, one after the other.

Easiest use case is of course to have one backup with all songs and final meta data, always using this as import file, independent which sub-collection you have currently loaded into iOS song library. Store (backup) a complete once, use this always for replace, that’s the way I do.

Again: All use cases above work, because TraCoMerger always restores/import meta data only for the songs which are currently in your Original collection. 

 

Where can I find my collection.nml in Traktor Pro (Mac or PC) ?

The file collection.nml is stored in the Traktor Pro main directory, typical path (or similar):

PC Windows 7: C: \Users \xy.. \Documents \Native Instruments \Traktor xy.

Mac OS X: Macintosh HD /Library /Application Support /Native Instruments /Traktor xy. 

 

Where can I find my collection.nml in Traktor DJ (iOS) ?

This has changed with TDJ 1.6.8, as TDJ is using iCloud now (instead Dropbox):

Open iCloud and you will find the TDJ collection, two ways how you can access iCloud:

Now open iCloud and search for the ‘iCloud Drive’, open drive .. you will find ‘Traktor DJ’. Open this folder, you will find the file ‘collection.nml.gz’. This is the compressed (gz-zipped) collection.nml. Save it on a safe place on PC/Mac. Open (unzip) on your local PC/Mac with double click .. inside is your ‘collection.nml’ – this .nml file (not the nml.gz file) is needed for TraCoMerger. 

 

How to replace the ORIGINAL Traktor Pro collection.nml (Mac or PC) with the new merged collection ?

Close Traktor Pro application first. Then copy the new collection into the folder of the original Traktor Pro collection.nml. Your new collection must be named ‘collection.nml’. I recommend to make a backup of the original file first before overwrite (or rename the original e.g. to collection_orig.nml, so you can always restore the original status if needed). When you reopen Traktor Pro all new meta data should appear and are available now. 

 

How to replace the ORIGINAL Traktor DJ collection.nml (iOS) with the new merged collection ?

Since NI supports iCloud in TDJ it is much easier then before with Dropbox. Some user may remember the workaround with ‘renaming’ of Dropbox folder, this is not longer needed. Keep the new simple 6 steps approach below.

Be aware, all songs have to be analyzed in TDJ before you even start to use TraCoMerger.

  1. Open TDJ and stay there, do not play any songs (alternative: close TDJ and wait 1 min)
  2. Open iCloud via PC/Mac: https://www.icloud.com .. and download collection.nml.gz:
    see FAQ: “Where can I find my collection.nml in Traktor DJ (iOS) ?”
  3. NOW create a new merged collection via TraCoMerger, create a ‘compressed .gz’ file
  4. Rename the created ‘collection_merged.nml.gz into collection.nml.gz
  5. Erase the current collection.nml.gz on iCloud .. and upload your new .gz file instead
  6. Wait about 20 sec … watch TDJ deck view … all meta data are imported .. done;)

In summary: It is easier then before with Dropbox, no folder renaming needed, even nice to see TDJ open when the new metadata appear in real-time, looks somehow magic. Btw: you can also keep TDJ closed at all, after re-launch the new meta data are imported.

Some details, be aware:

  

Is it important to make regular backups of the Traktor collection.nml ?

If you spend much time in gridding or cueing your song collection .. YES !. Personally I strongly recommend to backup this file quite often. In particular if you are using Traktor DJ on iOS. Do it better today then tomorrow. :)

The reason is quite simple: there are many reasons which could result in lost of all cues. Examples: any iOS update in background can force this lost, also TDJ updates can cause this. Also updates in the iOS music mediathek, or crashes on iOS or itunes at all. All this events can force the lost of all cue points. Be aware, any iOS backup procedure via cloud or itunes does NOT include your TDJ song collection with your cue points.

Also the new iCloud support in TDJ (since version 1.6.8) does not protect your data!. In case you remove and reinstall the TDJ app, TDJ will start a new analyze process and reset all meta data, so any earlier grid or hotcues get lost .. even more worse: the iCloud file will be overwritten with this new empty collection file. This feels like a bug for me, i would expect that iCloud is also used for keeping the meta data, but it seems like that NI is using iCloud only for sync between iPads, the most important use case (keeping meta data forever) is still not solved from NI.

In summary: There are many reasons why meta data can get lost, my "Take away":

Best idea is if you keep your collection always as backup. Traktor Pro user find the collection.nml in the Traktor directories, TDJ user can find the collection.nml.gz in iCloud. Personally I always save my backups to a save place, before I change anything in my iOS music mediathek or update iOS or the TDJ app. So i recommend: Whenever you have created some work in Traktor (gridding. hot cue definitions etc. ..), make a backup our Traktor collection.nml or your TDJ collection.nml.gz. So you can replace or merge with TraCoMerger any time you need. 

 

What is the use case of the File Viewer ?

The File viewer is not needed for the merging workflow, but if you ever want look inside a nml file, then try this viewer. The ‘split’ view option makes it quite easy to understand the Traktor structure. The ‘split view mode’ separate the songs and tags, and the search field on top allows to an easy searching. I needed such view quite often, so included this tool into TraCoMerger.

Open menu ‘View Files’ to open the integrated File Viewer. You can view the ORIGINAL COLLECTION, the IMPORT FILE, and the NEW MERGED COLLECTION. Each file can be viewed with original content, the ‘split view’ mode add line breaks between the songs and tags, this is the most comfortable way to browse through the .nml files. The text search in the file viewer allows you to search for certain tags or songs.

The LOG File views more detail after about the process during creating new files. The LOG File collects the found songs and all tags which were updated in the new collection. 

 

What is TraCoConverter and how does it work together with TraCoMerger ?

TraCoConverter is another PC Windows stand alone application, also developed by myself. TraCoConverter can convert all meta data of your song collection (bpm., grid, cue points etc.) into new file formats. Supported file formats: TXT, CSV and a pre-formatted XLS Excel spreadsheet. This allows you to visualize your hot cue definitions of all songs. 

NEW in TraCoConverter (since version 2.0): Create database format of the iOS DJ app 'DJ Player Pro' (DJPP). This allows you to transfer all metadata from the Traktor world into DJPP iOS app.

Both application (TraCoMerger and TraCoConverter) support the Traktor Pro and Traktor DJ collection.nml files.

The software architecture of TraCoMerger and TraCoConverter are quite similar, based on the same code base. Both application work perfectly together.

I always use TraCoConverter together with TraCoMerger. When I create any new collection files with TraCoMerger I always use TraCoConverter in addition to compare the content via Excel spread sheets before and after the merging process.

You can download both applications (TraCoConverter and TraCoMerger) in the NI TDJ community forum: http://www.native-instruments.com/forum/forums/traktor-dj-for-iphone-and-ipad.327/   

 

Contact for further questions, ideas, comments

All questions, ideas or suggestions for further updates are always welcome. Contact me (KALO) on the NI community forum: http://www.native-instruments.com/forum/forums/traktor-dj-for-iphone-and-ipad.327/

If you have any detailed question or technical problem, then send me a PM (private message): open my avatar in the forum and ‘Start a Conversation’.

 


Release Notes

 

Version 1.5 (August 11, 2017)

Version 1.4 (August 16, 2016)

Version 1.3 (July 12, 2015)

Version 1.2 (June 28, 2015)

Version 1.01 (June 18, 2015)

Version 1.0 (June 16, 2015)

 


Hope you enjoy TraCoMerger :)

KALO