# 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](https://community.roonlabs.com) 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. 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 <span style='display: inline-block; width:140px'>Field</span> | <span style='display: inline-block; width:80px'>Type</span>|<span style='display: inline-block; width:180px'>Data Source</span>|<span style='display: inline-block;'>Notes</span> :-----------------|:--------|:-------------------|:--------- Title|text|File or Roon or Edit| Album Artist|text|File or Roon or Edit| Type|enum|File or 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 <span style='display: inline-block; width:140px'>Field</span> | <span style='display: inline-block; width:80px'>Type</span>|<span style='display: inline-block; width:160px'>Data Source</span>|<span style='display: inline-block; width=1800px'>Notes</span> :-----------------|:--------|:-----------|:--------- 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. <span style='display: inline-block; width:140px'>Field</span> | <span style='display: inline-block; width:80px'>Type</span>|<span style='display: inline-block; width:160px'>Data Source</span>|<span style='display: inline-block; width:200px'>Notes</span> :-----------------|:--------|:-----------|:--------- 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 <span style='display: inline-block; width:140px'>Field</span> | <span style='display: inline-block; width:80px'>Type</span>|<span style='display: inline-block; width:160px'>Data Source</span>|<span style='display: inline-block;'>Notes</span> :-----------------|:--------|:-----------|:--------- 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. <span style='display: inline-block; width:140px'>Field</span> | <span style='display: inline-block; width:80px'>Type</span>|<span style='display: inline-block; width:160px'>Data Source</span>|<span style='display: inline-block;'>Notes</span> :-----------------|:--------|:-----------|:--------- 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. You can find a full list of credit roles and how they map onto categories [[!here|Credit_Roles]]. 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.
Page last changed Thu Jun 08 2017