Open Crate Codes spec

How DJ software and scripts read and write Open Crate Codes tags. The genre list itself is in occ.toml (and occ.json); this page is the rules around it.

Must, should and may are used in the sense of RFC 2119: must is a requirement, should is a strong recommendation with room for good reasons, may is optional.

1. Scope

An Open Crate Codes tag records two things about a track: its genre, optionally narrowed to a style, and its energy within that genre. Optional labels record yes-or-no facts such as "has a vocal" or "from the 1990s".

• A track has exactly one genre. Pick the floor you'd play it on. If that's still a tie, use the genre the record label or the store filed it under.
• A style is optional. Leave it off when you're not sure: the track still belongs to the genre.
• Energy is optional. A track without one is unrated.

2. Fields

Album is used because every DJ app reads, shows, sorts and filters it, and it travels with the file and with USB exports. That keeps Genre clean for browsing by genre on players.

3. The Album tag

tag     = family " " code [ "." style ] [ " E" level ] " " name
family  = 2 digits         ; 01–89 public, 90–99 private
code    = 3 letters A–Z    ; private: X + 1–3 of A–Z, 0–9
style   = 3 letters A–Z    ; private: as for codes
level   = 1 digit          ; 1–5; unrated has no energy part
name    = display text     ; genre name, then (style name)

As a regular expression:

^(\d{2}) ([A-Z0-9]{2,4})(?:\.([A-Z0-9]{2,4}))?(?: E(\d))? (.+)$

4. Reading

• Trim the Album value and collapse runs of spaces to one, then match it against the expression above. A value that doesn't match isn't a tag: it's a release title. Leave it alone.
• Identify the genre by its code, and the style by code.style. Must ignore the name: it's display text and may be renamed between versions.
• If the family number doesn't match the code's family in your version, still read the tag by its code.
• An unknown code comes from a newer version or from someone's private additions. Must keep the tag as it is. Should show the code, and must not clear or rewrite it without the user asking.
• A deprecated code reads as normal. May suggest its replacement; must not change the file unless the user asks.
• Energy outside 1–5 counts as unrated. Keep the text as it is.
• Labels can be anywhere in Comment, because other tools add text before them. A label is a word that starts with # followed by a label's tag. Match it ignoring case and any punctuation after it, so #Vocal, reads as #vocal. Every other word is someone else's text.

5. Writing

• Must write exactly family code[.style][ En] name, with single spaces and the names of the version you implement.
• Must not write codes you don't know, except private codes the user defined. Must not write deprecated codes for new tags.
• Should write the genre's name, without the style, to the Genre field.
• In Comment, must keep text you didn't write. Write labels first, as #tag words separated by single spaces, followed by the rest. Only add or remove hashtags that are labels from this standard.
• Should keep the release title that Album held before (see Fields).

6. Codes and families

• Genre and style codes are 3 capital letters. Genre codes are unique. Style codes are unique within their genre.
• One style code can sit under several genres when it means the same thing there: MLD is Melodic under Afro House and under Dubstep.
• A style can reuse a genre's code when it means that genre's sound inside another genre, and then it has that genre's name. DNB.HIP is hip-hop drum & bass, named Hip-Hop like the genre HIP.
• Names never contain brackets, so the only brackets in a tag are around the style's name.
• Codes are permanent. A published code keeps its meaning and is never reused. A retired code is marked deprecated, with use naming its replacement, and stays readable.
• Family numbers are permanent. Moving a genre to another family is a major change (see Versions).
• Private range. Codes starting with X and families 90–99 are for anyone's own additions. Public versions never use them. Two people's private codes may collide, so don't expect others to read them.
• Searchable by design. For every code, NN CODE (family number, a space, the code) appears in no other code's tag, and no name contains E followed by a digit. tools/build.py checks both.

7. Energy

Energy ranks a track within its own genre. E5 is the most intense end of that genre, not an absolute level: a Deep House E5 is calmer than a Hard Techno E1, and both are right.

• Rate against the genre's reference tracks first, then against tracks already rated in that genre.
• Most libraries end up with most tracks at E3 and few at E5. That's a result, not a rule.
• Colours are optional. Apps that store a track colour should use these; the names are Rekordbox's colour names.
• Mixed In Key's energy (1–10) measures intensity across all music. It's a different scale: must not be converted to or from this one.

8. Labels

Labels go in the Comment field as hashtags. Tags are lowercase. A track has at most one label from each group.

An edit keeps the genre of the music it edits, and adds #edit. An acapella keeps its genre, and adds #acapella. Neither is a genre of its own.

9. Searching

Smart playlists and searches should include the family number with the code. On its own, a code also finds untagged tracks whose release title contains it, like MIN in "Mind".

Energy on its own (E5) is only safe combined with a genre condition. Codes are capitals, so it doesn't matter whether an app's search ignores case.

10. Working with other tools

Open Crate Codes uses Album, Genre and hashtags in Comment. Other tools write to some of the same fields, so a few settings matter.

Mixed In Key

Mixed In Key measures key, BPM and an energy level from 1 to 10 across all music. That's a different question from this standard's energy, which is judged within a genre. Keep both, and must not convert one into the other.

• In Settings, under Tag Options, write key and energy to Grouping, or in front of the comment. Both leave the labels in place.
• Don't choose "Overwrite the comment": it deletes the labels.

Auto-taggers

• Tools that fill in tags from stores and databases, such as OneTagger or MusicBrainz Picard, can overwrite Album with the release title. Turn off Album writing for tracks that already have a tag.
• The crosswalk in occ.toml (match.discogs, match.musicbrainz, match.everynoise) lets a tool turn the genre it found into a suggested code. A person should confirm it before it's written.

Rekordbox

• Build the searches in section 9 as intelligent playlists on Album.
• My Tag lives only in Rekordbox's own library, not in the file. Use it for personal notes if you like; Open Crate Codes tags go with the file to other apps and computers.
• Rekordbox keeps track colour in its library rather than in the file. Set the energy colours there, or through its XML import: Blue, Aqua, Green, Orange and Red for E1 to E5.

Library managers

Tools that sync a library between DJ apps, such as Lexicon, carry Album over with the rest of a track's details, so tags survive a move from one app to another. Check that any metadata clean-up feature leaves Album alone.

11. Versions

The data files carry a version, numbered as semantic versions. Every change is listed in CHANGELOG.md.

Tags written under any 1.x version read correctly under every later 1.x version.

12. Checklist for app makers

Reading

• Parses Album with the expression in section 3.
• Identifies tags by code and ignores the name.
• Keeps tags with unknown codes as they are.
• Treats an Album that doesn't match as a release title.
• Finds labels anywhere in Comment, ignoring case and trailing punctuation.

Writing

• Writes the exact format, with the names of its version.
• Never writes unknown or deprecated codes for new tags.
• Keeps Comment text it didn't write.
• Keeps the release title Album held before.

Showing

• Explains energy as relative to the genre.
• Shows the family number and code, so users can build the searches in section 9.

13. License

The data files (occ.toml, occ.json) are public domain under CC0 1.0. Use the codes in any product, free or paid, without asking. This spec and the site's text are CC BY 4.0.