Introduction
This document is meant to serve as a technical reference to Roon's metadata model.
Roon models your metadata in an object graph. This means that there are a set of objects--such as albums, tracks, performers, performances, compositions, labels, roles, periods, forms, and so on. Each object has attributes of their own, and links to other objects.
Most software designed for managing music files does not work anything like this. Generally, they represent music by treating each track as a set of key-value pairs, and building a set of views on top of that data. For example, the album view in iTunes is essentially a view of tracks that has been "grouped" by the values of the artist and album tags. The "spreadsheet" model for looking at tracks is frequently seen with this approach. Each of the "keys" represents a possible column, and columns support sorting and filtering.
A lot of people who come to Roon are confused as to why features commonly found in other software are missing. Oftentimes it is because those features fall naturally out of the "other" model, but not are not as natural a fit in ours.
This document should help explain some of the important details, and should enable us to have better conversations with some of our more serious, interested users about this topic in the future.
If you have feedback for this document, or ideas about how it might be expanded, head over to our
community site and let us know.
Disclaimer
Metadata Modeling at Roon is an ongoing research effort. This document will not always be perfectly up to date or perfectly complete. Things change over time and these details are not set in stone.
A Thought Experiment: What does it mean to be an Album?
Think about Miles Davis's Kind of Blue for a second. What is it?
On earth, it's not really just one album. It's a level up from that--an entity that causes many releases of Kind of Blue to spring forth--releases that share something in common--the bulk of the musical material--but vary in other attributes.
In your library, it's a set of tracks--physical files in a folder on one of your storage devices--that comprise one copy of one of those releases.
This duality is vexing, and it's not limited to albums. The "On Earth" view is amorphous and sometimes subjective, but dramatically more expressive. The "In Your Library" view is very concrete, but ultimately very limited in what it can do and where it can go.
Ultimately, Roon is striking a balance between both perspectives--a global perspective motivated by considering what these things mean "on earth", and a local perspective, which focuses on how they manifest "in your library".
Object Identity
Before we can discuss the objects that inhabit Roon's Metadata Model, we need to have a handle on what they are, and how they're identified.
Objects with global identity
There is only one Ludwig Van Beethoven. And only one Symphony No. 9 in his catalog.
These entities have a single name, and a single representation. There is no such thing as the name of Symphony No. 9 on one album, as opposed to another--there is a global notion of Symphony No. 9 with a unique identity and metadata associated with it.
He, and his compositions, have the same identity regardless of what media he might have a relationship with in your library.
These objects live firmly with in the global perspective described above.
Objects with local identity
Tracks, Albums, and Performances fall into this category. Their identity is directly backed by files within your library.
If you have two copies of Kind of Blue, even if they are the same files, with the same name, and the same file tags, Roon assigns a separate identity to each one.
You can see evidence of this all over the place: they have separate album pages. You can tag and favorite them separately. When their tracks appear in playlists, or your play history, they are clearly referring to either one set of files or the other.
This is where it gets sticky: These albums (and tracks, and performances) may also have a global identity.
This dual identity is what allows information from your files to be blended with data from our cloud services. It's why Kind of Blue has a full credit listing, an original release date, and a review. It's also how we know that there's a version of Kind of Blue available via your TIDAL subscription--your album and the TIDAL album share a sense of identity in a global sense, even though they refer to different media.
Objects that are purely identified by name.
Genres, Labels, Places, Periods, Forms, Credit Roles, and Countries fall into this category.
For the most part, these objects are simple. All of them are immutable with the exception of genres. They behave as if they have global identity, but with an additional constraint: that it's not possible to have two with the same name.
Schema
This is a representation of each object's attributes, roughly filtered to exclude data that Roon doesn't use, data that is derived from other properties, and data that is "boring".
It's meant to give you an idea of where information lives within Roon's data model and where that data comes from.
The "Data Source" column gives insight into where the data comes from.
Roon - Roon's metadata service
File - Tags from your media file
Edit - Metadata edits performed in Roon
The "ands" and "ors" in that column are significant--they tell you whether data is being chosen from one of the sources, or blended across multiple sources. When blending happens, it is usually not a simple union--there is a merging algorithm that tries to make good choices to produce a clean result.
Album
Field
| Type
| Data Source
| Notes
|
|---|
Title
| text
| File or Roon or Edit
|
|
Album Artist
| text
| File or Roon or Edit
|
|
Type
| enum
| Roon or Edit
| Main, Single, Other, Unknown, Extended Play, Soundtrack
|
Main Performers
| links
| File or Roon or Edit
|
|
Rating
| 0-5stars
| Roon or Profile
|
|
Cover Art
| image
| Roon or File or Edit
|
|
Genres
| links
| File and/or Roon and/or Edit
| See notes about genres below
|
Labels
| links
| File or Roon or Edit
|
Is Favorite?
| boolean
| Profile
|
|
Is Banned?
| boolean
| Profile
|
|
Original Release Date
| date
| File or Roon or Edit
|
Release Date
| date
| File or Roon or Edit
|
Recording Start Date
| date
| Roon or Edit
|
Recording End Date
| date
| Roon or Edit
|
Is Live?
| boolean
| Roon or Edit
|
Is Compilation?
| boolean
| Roon or Edit
|
Is Bootleg?
| boolean
| Roon or Edit
|
Version
| text
| File or Edit
|
Country
| text
| File or Roon or Edit
|
Credits
| credits
| File and/or Roon and/or Edit
| See the section on credits below.
|
Product Code
| text
| File or Roon or Edit
| ISRC, UPC, ASIN, etc
|
Catalog Number
| text
| File or Roon or Edit
| The music Label's catalog number
|
Review
| text
| Roon
|
Track
Field
| Type
| Data Source
| Notes
|
|---|
Title
| text
| File or Roon or Edit
|
|
Album
| link
| File or Edit
|
Credits
| credits
| File and/or Roon and/or Edit
| Note that this includes things that other software handle directly like "track artist" and "composer"
|
Is Pick?
| boolean
| Roon and/or Edit
|
Track Number
| number
| File and/or Edit
|
Media Number
| number
| File and/or Edit
| sometimes referred to as "disc number"
|
Is Hidden?
| boolean
| Edit
|
Is Corrupt?
| boolean
| File
|
Is Live?
| boolean
| Roon or Edit
|
Import Date
| boolean
| File or Edit
|
Part Name
| text
| File or Roon
|
Performance
| link
| Roon
|
Is Favorite?
| boolean
| Profile
|
|
Is Banned?
| boolean
| Profile
|
|
Play History
| plays
| Profile
|
Format
| format
| File
| file type, bits per sample, sample rate, channel layout, bitrate, etc.
|
Duration
| number
| File
|
Start Date
| date
| Roon
|
End Date
| date
| Roon
|
Location
| text
| Roon
|
In Roon-the-product, users are confronted with artists, composers, performers, and production personnel. In the data model, a single entity represents all four. We call this entity a "Performer" for mostly historical reasons.
Field
| Type
| Data Source
| Notes
|
|---|
Name
| text
| File or Roon or Edit
|
|
Type
| enum
| Roon or Edit
| Individual or Group
|
Biography
| text
| Roon
| Biography for this person or group, focusing on their work as a performer
|
Composer Biography
| text
| Roon
| Biography for this person, focusing on their work as a composer
|
Birth Place
| link
| Roon or Edit
|
|
Death Place
| link
| Roon or Edit
|
|
Birth Date
| date
| Roon or Edit
|
|
Death Date
| date
| Roon or Edit
|
|
Country
| link
| Roon or Edit
|
|
Related Performers
| links
| Roon
| MemberOf, Members, Conducted, Conductors, Founded, Founders, AlsoPerformedAs, SimilarTo, ComposerSimilarTo, Influenced, Followed, CollaboratorWith, IsAssociatedWith, StudiedWith, Relative Of, Sibling Of, Child Of, Parent Of, Grandparent Of, Grandchild Of, Married To
|
Periods
| links
| Roon
|
Genres
| links
| File and/or Roon and/or Edit
|
Related URLs
| urls
| Roon
| Web links related to this performer
|
Is Favorite?
| boolean
| Profile
|
|
Is Banned?
| boolean
| Profile
|
|
Image
| image
| Roon or Edit
|
Last-First Sort Key
| text
| Roon or Edit
|
Is Classical Composer?
| boolean
| Roon or Edit
|
Composition
Field
| Type
| Data Source
| Notes
|
|---|
Title
| text
| File or Roon or Edit
|
|
Composers
| links
| Roon or Edit
|
Period
| link
| Roon or Edit
|
Composition Start Date
| date
| Roon or Edit
|
Composition End Date
| date
| Roon or Edit
|
Description
| text
| Roon
|
Instrumentation
| text
| Roon
|
Form
| text
| Roon or Edit
|
Is Favorite?
| boolean
| Profile
|
|
Is Banned?
| boolean
| Profile
|
|
Catalog Numbers
| custom
| Roon
| Each catalog number has a system (e.g. "K" or "BWV") and a piece of text representing the number within that system.
|
Nominal Duration
| duration
| Roon
|
Parts
| custom
| Roon
| This represents how this work breaks down into parts on earth, but not necessarily how it breaks down into parts on any particular album.
|
Performances are simply a link between a composition and one or more tracks on the same album.
Field
| Type
| Data Source
| Notes
|
|---|
Composition
| link
| Roon
|
Credits
A Credit consists of three components:
There are six categories:
Main Performer
Performer
Ensemble
Composer
Conductor
Production
This categorization is fundamental to how Roon deals with credits. Virtually all of the business and display logic related to credits is looking at the category when making its decisions.
Roon merges credits data from multiple sources on a category-by-category basis. Meaning, it's possible to see a track that gets its Composer credits from your file tags, but its Conductor credits from Roon's metadata service, but the merge algorithm never uses multiple sources to populate a category.
Genres
Genres in Roon are a complex topic that is already well documented elsewhere. Instead of getting into the nitty gritty here, check out
Genres.
Performance/Composition data actually come from two data sources: one is Roon's data service in the cloud, and the other is an algorithm that is executed locally on unidentified albums. This algorithm attempts to "Munge" the data--looking for patterns and synthesizing performance and composition objects that represent the content in your library.
This is a complex machine, and one that is constantly being improved, both with "expert" knowledge of composers and their catalogs, and by improving the algorithm itself.