Track Metadata

The first step is to determine the port on which the player is offering its remote database server. That can be determined by opening a TCP connection to port 12523 on the player and sending it sending a packet with the following content:

The player will send back a two-byte response, containing the high byte of the port number followed by the low byte. So far, the response from a CDJ has always indicated a port number of 1051, but using this query to determine the port to use will protect you against any future changes. The same query can also be sent to a laptop running rekordbox to find the rekordbox database server port, which can also be queried for metadata in the exact same way described below.

To find the metadata associated with a particular track, given its rekordbox ID number, as well as the player and slot from which it was loaded (all of which can be determined from a CDJ status packet received by a virtual CDJ as described in Creating a Virtual CDJ), open a TCP connection to the device from which the track was loaded, using the port that it gave you in response to the DB Server query packet, then send the following four messages. (You can also get metadata for non-rekordbox tracks, even for CD Audio tracks being played in the CD slot, using the variant described in Non-Rekordbox Track Metadata.)

Once you have determined the database port, send it a setup packet with the following content, and the server will send the same five bytes back:

All further messages have a shared structure. They consist of lists of type-tagged fields (a type byte, followed some number of value bytes, although in the case of the variable-size types, the first four bytes are a big-endian integer that specifies the length of the additional value bytes that make up the field). So far, there are four known field types, and it turns out that the packet we just saw is one of them, it represents the number 1 as a 4-byte integer.

The first byte of a field identifies what type of field is coming. The values 0f, 10, and 11 are followed by 1, 2, and 4 byte fixed-length integer fields, while 14 and 26 introduce variable-length fields, a binary blob and a UTF-16 big-endian string respectively.

Messages are introduced by a 4 byte Number field containing a “magic“ value (it is always 872349ae). This is followed by another 4 byte number field that contains a transaction ID (TxID), which starts at 1 and is incremented for each query sent, and all messages sent in response to that query will contain the same transaction ID. This is followed by a 2 byte number field containing the message type, a 1 byte number field (n) containing the number of argument fields present in the message, and a blob field containing a series of bytes which identify the types of each argument field (shown as t₁ through t₁₂ below). This blob is always twelve bytes long, regardless of how few arguments there are (and presumably this means no message ever has more than twelve arguments). Tag bytes past the actual argument count of the message are set to 0.

This header is followed by the fields that make up the message arguments, if any. In other words, the message body consists of arguments identified by the header.

The argument type tags use different values than the field type tags themselves, for some reason, and it is not clear why this redundant information is necessary at all—but that is true a number of places in the protocol as we have seen before and will see again. Here are the known tag values and their meanings:

I am guessing that if we ever see them, a tag of 04 would represent a 1 byte integer, and 05 would represent a 2 byte integer. But so far no such messages have been seen.

Before you can send your first actual query, you need to send a special message which seems to be necessary for establishing the context for queries. It has a type of 0000, a special TxID value of fffffffe, and a single numeric argument, like this:

The value D is, like in the other packets we have seen, a player device number. In this case it is the device that is asking for metadata information. It must be a valid player number between 1 and 4, and that player must actually be present on the network, must not be the same player that you are contacting to request metadata from, and must not be a player that has connected to that player via Link and loaded a track from it. So the safest device number to use is the device number you are using for your virtual CDJ, but since it must be between 1 and 4, you can only do that if there are fewer than four actual CDJs on the network.

The player will respond with a message of type 4000, which is the common “success” response when requested data is available. The response message has two numeric arguments, the first of which is the message type of the request we sent (which was 0000), and the second usually tells you the number of items that are available in response to the query you made, but in this special setup query, it returns its own player number:

To ask for metadata about a particular rekordbox track, send a packet like this:

As described above, TxID should be 1 for the first query packet you send, 2 for the next, and so on.

The first argument of this message requires a little explanation: it is sent as a four-byte number field, but each byte has a separate meaning. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. The second byte is referred to as M, and seems to identify the particular menu location on the CDJ where results are going to be displayed. For this kind of metadata request it always has the value 01.

S_r is the slot in which the track being asked about can be found, and has the same values used in CDJ status packets, as described in the CDJ status packet description. Similarly, T_r identifies the type of track we want information about; for rekordbox tracks this always has the value 01.

This first argument format is used for many different requests about tracks, so it is given the acronym DMST in future discussion.

The second message argument, rekordbox, identifies the local rekordbox database ID of the track being asked about, as found in the CDJ status packet.

As suggested in the above description, track metadata requests are built on the mechanism that is used to request and draw scrollable menus on the CDJs, so the request is essentially interpreted as setting up to draw the “menu” of information that is known about the track. The player responds with a success indicator, saying it is ready to send these “menu items” and reporting how many of them are available:

We’ve seen this type of “data available” response already in the query context setup response, but this one is a more typical example. As usual, TxID matches the value we sent in our request, and the first argument, with value 2002, reflects the type field of our request. The second argument reports that there are 11 (0b) entries of track metadata available to be retrieved for the track we asked about, and that the player is ready to send them to us.

If there was no track with ID rekordbox in that media slot, the second argument would have the value ffffffff to let us know. If we messed up something else about the request, we will get a response with a type other than 4000. See Experimenting with Metadata for instructions on how to explore these variations on your own.

But assuming everything went well, we can get the player to send us all eleven of those metadata entries by telling it to render all of the current menu, using a “render menu” request with type 3000 like this:

As always, the value of TxID should be one higher than the one you sent in your setup packet, while the values of D, S_r, and T_r should be identical to what you sent in it.

The request has six numeric arguments. At this point it is worth talking a bit more about the byte after D in the first argument. This seems to specify the location of the menu being drawn, with the value 1 meaning the main menu on the left-hand half of the CDJ display, while 2 means the submenu (for example the info popup when it is open) which overlays the right-hand half of the display. We don’t yet know exactly what, if any, difference there is between the response details when 2 is used instead of 1 here. And special data requests use different values: for example, the track waveform summary, which is drawn in a strip along the entire bottom of the display, is requested with a menu location number of 8 in this second byte.

As described above, T_r has the value 1 for rekordbox tracks.

The second argument, offset, specifies which menu entry is the first one you want to see, and the third argument, limit, specifies how many should be sent. In this case, since there are only 11 entries, we can request them all at once, so we will set offset to 0 and limit to 11. But for large playlists, for example, you need to request batches of entries that are smaller than the total available, or the player will be unable to send them to you. We have not found what the exact limit is, but getting 64 at a time seems to work on Nexus 2 players.

We don’t know the purpose of the fourth argument, but sending a value of 0 works. The fifth argument, total, seems to usually contain the total number of items reported in the intial menu response, but sending a second copy of limit here works too; it may not matter much. And the sixth and final argument also has an unknown purpose, but 0 works.

So, for our metadata request, the packet we want to send in order to get all the metadata will have the specific values shown here:

This causes the player to send us 13 messages: The 11 metadata items we requested are sent (with type 4101, second figure below), but they are preceded by a menu header message (with type 4001, first figure below), and followed by a menu footer message (with type 4201, third figure below). This wrapping happens with all “render menu” requests, and the menu footer is an easy way to know you are done, although you can also count the messages.

The menu item responses all have the same structure, and use all twelve message argument slots, containing ten numbers and two strings, although they generally don’t have meaningful values in all of the slots. They have the general structure shown here, and the arguments are listed in the Table below:

The menu footer message has a type of 4201 and no arguments, so it has a header only, and is always made up of the exact same sequence of bytes (apart from the TxID).

As noted above, the seventh argument in a menu item response identifies the type of the item. The meanings we have identified so far are:

As noted above, track metadata responses use many of these types. Others are used in different kinds of menus and queries.

As discussed in the introduction to this section, you can get metadata for non-rekordbox tracks as well (although they don’t have beat grids, waveforms, or album art available). All you need to do is use a slight variant of the metadata request message, using the value 2202 (instead of 2002) for the message type, and a value of T_r that is appropriate for the kind of track you are asking about (02 for non-rekordbox tracks loaded from media slots, and 05 for CD audio tracks playing in the CD slot, which has a S_r value of 01). After the initial query setup message, the other message types are the same as in the above discussion, but you will continue using the S_r and T_r values appropriate for the slot and media type you are asking about.

Since these tracks don’t have rekordbox IDs, you will need to use the rekordbox value reported in CDJ status packets in order to find out the values used to request the metadata for tracks loaded from solid state media; CD tracks are requested using the simple track number as the rekordbox value.

To request the artwork image associated with a track, send a message with type 2003 containing the artwork ID that was specified in the track title item (as described in Item 1: Title), like this:

As usual, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. Finally, artwork identifies the specific artwork image you are requesting, as it was specified in the track medatata response. As with other graphical requests, the value after D, which identifies the location of the menu for which data is being loaded, is 8.

The response will be a message with type 4002, containing four arguments. The first argument echoes back our request type, which was 2003. The second always seems to be 0. The third contains the length of the image in bytes, which seems redundant, because that is also conveyed in the fourth argument itself, a blob containing the actual bytes of the image data, as shown below. However, if there is no image data, this value will be 0, and the blob field will be completely omitted from the response, so you must not try to read it!

To experiment with this, start up dysentery in a Clojure REPL and connect to a player as described in Experimenting with Metadata, then evaluate an expression like:

Replace the arguments with the var holding your player connection, the proper S_r number for the media slot holding the art, and the artwork ID of the album art, and dysentery will open a window like this showing the image:

The CDJs do not send any timing information other than beat numbers during playback, which has made it difficult to offer absolute timecode information. The discovery of beat grid requests provides a clean answer to the problem. The beat grid for a track is a list of every beat which occurs in the track, along with the point in time at which that beat would occur if the track were played at its standard (100%) tempo. Armed with this table, it is possible to translate any beat packet into an absolute position within the track, and, combined with the tempo information, to generate timecode signals allowing other software (such as video resources) to sync tightly with DJ playback.

To request the beat grid of a track, send a message with type 2204 containing the rekordbox ID of the track:

As usual, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. Finally, rekordbox identifies the specific beat grid you are requesting, as found in a CDJ status packet or playlist response. As with graphical requests, the value after 𝐷, which identifies the location of the menu for which data is being loaded, is 8.

The response will be a message with type 4602, containing four arguments. The first argument echoes back our request type, which was 2204. The second always seems to be 0. The third contains the length of the beat grid in bytes, which seems redundant, because that is also conveyed in the fourth argument itself, which is a blob containing the actual bytes of the beat grid, as shown below. However, if there is no beat grid available, this value will be 0, and the blob field will be completely omitted from the response, so you must not try to read it!

The beat grid itself is spread through the value returned as argument 4, consisting of a series of sixteen-byte entries with the following structure:

Each entry begins with a two-byte little-endian^[2] integer holding the beat-within-bar number (labeled B_b in the CDJ status packet diagram) of the beat, which is always 1, 2, 3, or 4. This is followed by a two-byte little-endian tempo value, which records the track tempo at the point where this beat occurs, in beats per minute multiplied by 100 (to allow a precision of BPM). Finally, there is a four-byte little-endian time value, which specifies the time at which this beat would occur, in milliseconds, when playing the track at its normal speed.

In other words, the B_b value of the first beat in the track is found at bytes 0x14-15 of argument 4, its tempo at bytes 16-17, and the time at which that beat occurs at bytes 18–1b. Subsequent beats are found at 0x10-byte intervals, so the second B_b value is found at bytes 24-25, its tempo at bytes 26-27, its time at bytes 28-2b, and so on.

The purpose of the other bytes within the beat grid is so far undetermined. It looks like there may be some sort of monotonically increasing value following the beat millisecond value, but what it means, and why it sometimes skips values, is mysterious.

Waveform data for tracks can be requested, both the preview, which is 400 pixels long, and the detailed waveform, which uses 150 pixels per second of track content. There is also an even tinier 100 pixel preview, which is used by older players such as the pre-Nexus CDJ 900, returned as the final 100 bytes of the preview response.

Thanks to some wonderful analysis by @jan2000 we now know how to request and interpret the higher resolution and color waveforms supported by the nxs2 series of players.

Both the enhanced waveform preview and enhanced detail are requested using variations on the same request type, which asks for specific content from the ANLZ0000.EXT file created by rekordbox. The Crate Digger project which has its own analysis document, is focused on obtaining and interpreting these files.

To request the enhanced waveform preview of a track, send a message with type 2c04 containing the rekordbox ID of the track, the tag type identifier PWV4 and the file extension identifier EXT encoded as four-byte numbers, holding the ASCII in big-endian (backwards) order:

As usual, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. For some reason the value after D, which identifies the location of the menu for which data is being loaded, is 1 in this case, rather than the 8 we would expect to see for a graphical data request. rekordbox identifies the specific track whose analysis you are requesting, as found in a CDJ status packet or playlist response, and the final two numeric arguments specify that you are interested in the PWV4 tag (which holds the enhanced waveform preview) from the track’s EXT extended analysis file.

The response will be a message with type 4f02, containing five arguments. The first argument echoes back our request type, which was 2c04. The second always seems to be 0. The third contains the length of the requested tag (holding the enhanced waveform preview) in bytes. If this value is 0, the fourth argument will be omitted from the response. When present, the fourth argument is a blob containing the actual bytes of the enhanced waveform preview, as shown below. The fifth argument has an unknown purpose and so far seems to always have the value 0.

The extended preview data begins at byte 34 and is 7,200 (decimal) bytes long, representing 1,200 columns of waveform preview information.

The color waveform preview entries are the most complex of any of the waveform tags. See the discussion on Github for how the analysis was performed. @jan2000 created an audio file containing a 10 second sine wave sweep from 20 Hz to 20 kHz, and analyzed that in rekordbox. The results looked like this:

As a summary, the top six stripes plot the values of each six channels of waveform preview information. The first byte of data is the first column of the top stripe, the next byte is the first column of the second stripe, and so on, until we reach the seventh byte, which is the second column of the first stripe.

We are not sure what the top two stripes represent, but they do seem to have an effect on the blue version of the waveform preview, so they somehow encode “whiteness”. The next stripe, corresponding to byte 2 of each column, indicates how much sound energy is present in the bottom half of the frequency range (it drops around 10 KHz). The stripe corresponding to byte 3 reflects how much sound energy is present in the bottom third of the frequency range, byte 4 reflects how much sound energy is in the middle of the frequency range, and byte 5 tracks the sound energy in the top of the frequency range.

The stripe labeled “color” reflect’s @jan2000’s algorithm for combining bytes 3, 4, and 5 into a color preview, and the bottom stripe is his approach for deriving the blue preview from that and the other two stripes.

The calculations used by Beat Link to build its own color previews can be found in the segmentColor and segmentHeight methods of the WaveformPreview class, and the way they are used to draw the actual graphical representation can be found in the updateWaveform method of the WaveformPreviewComponent class. These produce attractive results, but it is certainly possible that refinements can be found in the future.

As mentioned, requesting the detailed color waveform is a simple variant of the request used to obtain the preview. The same request type is used, and the only difference is that the tag type requested to obtain the scrollable detail view is PWV5. The full request is shown here:

As usual, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. For some reason the value after D, which identifies the location of the menu for which data is being loaded, is 1 in this case, rather than the 8 we would expect to see for a graphical data request. rekordbox identifies the specific track whose analysis you are requesting, as found in a CDJ status packet or playlist response, and the final two numeric arguments specify that you are interested in the PWV5 tag (which holds the enhanced waveform detail) from the track’s EXT extended analysis file.

The response will be a message with type 4f02, containing five arguments. The first argument echoes back our request type, which was 2c04. The second always seems to be 0. The third contains the length of the requested tag (holding the enhanced waveform detail) in bytes. If this value is 0, the fourth argument will be omitted from the response. When present, the fourth argument is a blob containing the actual bytes of the enhanced waveform segments, as shown below. The fifth argument has an unknown purpose and so far seems to always have the value 0.

The extended waveform detail data begins at byte 34 and has a variable length, but a vastly simpler structure than the waveform preview. Every pair of bytes represents one segment of the waveform, and there are 150 (decimal) segments per second of audio. (These seem to correspond to “half frames” following the seconds in the player display.) Each pair of bytes encodes the height of the waveform at that segment as a five bit value, along with three bits each of red, green, and blue intensity, arranged as shown below:

The locations of the cue points and loops stored in a track can be obtained with a request like this:

As always, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. The value after D, which identifies the location of the menu for which data is being loaded, is 8 which is what we expect for a graphical or data request. rekordbox is the datbase ID of the specific track whose cue points you are requesting, as found in a CDJ status packet or playlist response.

The response will be a message with type 4702, containing nine arguments. The first argument echoes back our request type, which was 2104. The second always seems to be 0. The third contains the length of the blob containing cue and loop points in bytes, which seems redundant, because that is also conveyed in the fourth argument itself, which is a blob containing the actual bytes of the cue and loop points, as shown below. However, if there are no cue or loop points, this value will be 0, and the following blob field will be completely omitted from the response, so you must not try to read it!

The fifth argument is a number with uncertain purpose. It always seems to have the value 0x24, which may be telling us the size of each cue/loop point entry in argument 4 (they do seem to each take up 24 bytes, as shown below). The sixth argument, shown as num_hot, seems to contain the number of hot cue entries found in argument 4, and the seventh, num_cue seems to contain the number of ordinary memory point cues. The eighth argument is a number containing the length of the second binary field which follows it. We don’t know the meaning of the final, binary, argument.

As described above, the first binary field in the cue point response is divided up in to 24-byte entries, each of which potentially holds a cue or loop point. They are not in any particular order, with respect to the time at which they occur in the track. They each have the structure shown below:

The first byte, F_l, has the value 01 if this entry specifies a loop, or 00 otherwise. The second byte, F_c, has the value 01 if this entry contains a cue point, and 00 otherwise. Entries with loops have the value 01 in both of these bytes, because loops also act as cue points. If both values are 00, the entry is ignored (it is probably a leftover cue point that was deleted by the DJ). The third byte, labeled H, is 00 for ordinary cue points, but has a non-zero value if this entry defines a hot cue. Hot cues A through C are represented by the values 01, 02, and 03.

The actual location of the cue and loop points are in the values cue and loop. These are both 4-byte integers, and like beat grid positions, but unlike essentially every other number in the protocol, they are sent in little-endian byte order. For non-looping cue points, only cue has a meaning, and it identifies the position of the cue point in the track, in second units. For loops, cue identifies the start of the loop, and loop identifies the end of the loop, again in second units.

For tracks that have been exported since the introduction of the nxs2 series of players, rekordbox includes a richer set of information about cue points and loops. In addition to the information described in Requesting Cue Points and Loops, you can learn about any custom colors a DJ has assigned to their hot cues, as well as optional text comments describing hot cues, memory points, and loops. And while older players only supported hot cues A through C, this new format returns more.

Enhanced information about the cue points and loops stored in a track can be obtained with a request like this:

As always, TxID should be incremented each time you send a query, and will be used to identify the response messages. D should have the same value you used in your initial query context setup packet, identifying the device that is asking the question. S_r and T_r are the slot in which the track being asked about can be found and its track type; each has the same values used in CDJ status packets. The value after D, which identifies the location of the menu for which data is being loaded, is 8 which is what we expect for a graphical or data request. rekordbox is the datbase ID of the specific track whose extended cue information you are requesting, as found in a CDJ status packet or playlist response.

The response will be a message with type 4e02, containing five arguments. The first argument echoes back our request type, which was 2b04. The second always seems to be 0. The third contains the length of the blob containing cue and loop points in bytes, which seems redundant, because that is also conveyed in the fourth argument itself, which is a blob containing the actual bytes of the cue and loop points, as shown below. However, if there are no cue or loop points, this value will be 0, and the following blob field will be completely omitted from the response, so you must not try to read it!

The fifth argument reports the number of cue point entries found in the blob. Because each extended cue entry can include a comment string, they have variable lengths, so each entry needs to be examined in order to figure out where it ends, and therefore the next one begins. The extended entry structure is shown below:^[3]

The first four bytes, length, hold the length of the current entry, and so can be used to find the start of the next entry. Like other numbers in cue point responses (and unlike most numbers in the protocol), this is sent in little-endian byte order. The fourth byte, labeled H, is 00 for ordinary cue points, but has a non-zero value if this entry defines a hot cue. Hot cues A through H are represented by the values 01 through 08.

F_l, at byte 06 has the value 01 if this entry specifies a memory point and 02 if it is a loop. If both H and F_l are 00, the entry should be ignored (it is probably a leftover cue point that was deleted by the DJ).

The actual location of the cue and loop points are in the values cue at bytes 0c-0f and loop at bytes 10-13. These are both 4-byte integers, and as noted above, they are sent in a little-endian byte order. For non-looping cue points, only cue has a meaning, and it identifies the position of the cue point in the track, in second units. For loops, cue identifies the start of the loop, and loop identifies the end of the loop, again in second units.

c_id at byte 22 is used only for ordinary memory points and loops. If it has a non-zero value, it identifies a row in the color table that specifies the color the user assigned to the memory point or loop. Hot cues have their own color information later in the entry.

len_c at byte 48 is a two-byte, little-endian integer that contains the length of the comment. If it is zero, there is no comment. Otherwise, comment will follow len_c, taking up that many bytes, as a string (in UTF-16 encoding with a trailing 0000 character). So if len_c isn’t zero, it will be an even number with minimum value four, representing a comment that is one character long.

Four bytes past the end of comment (in other words, starting len_c + 4e past the start of the entry) there are four one-byte values containing hot cue color information. 𝑐 appears to be a code identifying the color with which rekordbox displays the cue, by looking it up in a table. There have been sixteen codes identified, and their corresponding RGB colors can be found by looking at the findRecordboxColor static method in the Beat Link library’s CueList class. The next three bytes, r, g, and b, make up an RGB color specification which is similar, but not identical, to the color that rekordbox displays. We believe these are the values used to illuminate the RGB LEDs in a player that has loaded the hot cue. When no color is associated with the hot cue, all four of these bytes have the value 00.

We do not know what, if anything, is sent in the remaining bytes of the the entry, so they are shown as blank in the byte field diagram above.

Starting with rekordbox version 6, when DJs export tracks on which they have performed phrase analyisis, that information is exported into the .EXT file as a PSSI tag. (Pioneer Song Structure Information?) This data can be obtained using an analysis tag request, specifyign PSSI (1230197584) for the tag type and, as usual, EXT for the file extension: