Metadata Model

Metadata Model

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

Performer

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.

Performance

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:
  • A link to a performer
  • The role that they are being credited as
  • The category of that role
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 Munging

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.
    • Related Articles

    • Metadata updates

      Roon updates the metadata in your collection periodically, and analyzes your audio files on import, but you can always force Roon to do it again. This can be done using either the Album Editor or the Track Editor. For example, in the Album Editor, in ...
    • FAQ: Roon is displaying incorrect track titles

      Roon is displaying incorrect track titles - how do I fix this? If Roon is displaying incorrect song titles, it usually means there's an error in our cloud metadata database. Assuming the album is identified and you're confident that the "file tags" ...
    • FAQ: How do I make bulk edits to Track metadata?

      You may find that some of your ripped CDs (or even newly downloaded files!) have bad metadata. This bad metadata is causing Roon to display erroneous or redundant information. It is possible to correct the metadata in the track files themselves, ...
    • Editing and Grooming Your Collection

      Even prior to our launch in May '15, it was clear Roon needed to do much more to meet the needs of users who want to exert control over how metadata is displayed and experienced in the app. At launch, Roon was focused on the user who wants their ...
    • Starting with Roon Server

      What is Roon Server? Roon Server is media server software that runs on a powerful computer, NAS, or turnkey appliance (like Nucleus or ROCK), located on the network within your home. (For more information on how it fits in with Control and Output ...
    Visit the Roon Community!
    Need help? Thousands of Roon subscribers and audio enthusiasts are chatting over on our community site right now, join them! You don't even need a Roon subscription to sign up.