Resonite MetaDisc

Res-MD is a music disc format for Resonite. It offers flexibility, metadata support, and advanced features like shuffle playback and mixtape creation. In short, Res-MD delivers the functionality that today's netizens expect of their media, in a convenient virtual package.

Res-MD is also an open specification. You can create your own Res-MD players, editors, and even custom discs, as long as they conform to this specification.

Song Orbs

Song Orbs represent individual music tracks and their associated metadata. A Res-MD disc is, at its core, just a collection of these, and every disc can be modified simply by adding, removing, or rearranging the Song Orbs within.

Structure

The root slot of a Song Orb needs to have a few things:

• An  ObjectRoot
• A  DynamicVariableSpace named SongOrb
• A  Snapper with the keyword SongOrb
• A child slot named Metadata
  • This is where the dynamic variables corresponding to the song's metadata attributes are stored.
  • Implementors SHOULD NOT put any other components or slots here.

Dynamic variables

The following dynamic variables MUST be present:

• _RESMD (string): Magic version identifier. Currently 1;SongOrb
• AudioClip (IAssetProvider<AudioClip>): Bound to a field containing the reference to the track's audio clip asset.
• Duration (double): Bound to the Duration field of an  AudioAssetClipMetadata referencing the audio clip. (Use a  DynamicField for this.)
• _SMFIELDS (string): Semicolon-separated list of metadata attributes present.

_RESMD and AudioClip SHOULD be stored directly on the object root, while _SMFIELDS SHOULD be placed in the Metadata slot.

Additionally, the reference Song Orb implementation defines the following variables, which are used by the integrated player, and may be used:

• IsPlaying (bool): Controls the orb's playback animation.
• IsPausing (bool): Alters the playback animation to indicate a paused state.

If your Song Orb implementation uses string-type dynamic variables not defined here, their names MUST be prefixed with an underscore to prevent collisions with track metadata.

A very important note on asset references

Dynamic variables that hold a reference to assets (i.e. textures or audio clips) MUST NOT use a normal  DynamicReferenceVariable component! This can cause strange, hard-to-reproduce bugs related to asset cleanup, as the variable's backing field is a SyncRef instead of an AssetRef.

Instead, you MUST add a component with a proper AssetRef field, such as  AudioClipAssetMetadata, and then use a  DynamicReference targeting said field.

Metadata

Res-MD track metadata is stored as dynamic variables under the Metadata slot. These variables are always string-type, and are named exactly the same as the metadata attribute.

Metadata attribute names MUST be PascalCase, and MUST NOT contain underscores, spaces, or hyphens (periods are allowed). Also, the name of every attribute in use MUST be stored in _SMFIELDS as a semicolon-delimited list: for example, if the song has Title and Artist attributes, _SMFIELDS should be Title;Artist.

Some attributes might contain multiple values; in this case, each value should be separated by a semicolon.

Also, attributes whose values are empty/null/unspecified/etc. SHOULD NOT be present at all; no variable binding should exist for them.

Standard attributes

The following is a table of all currently standardised Res-MD track attributes. You, of course, can create whatever metadata attributes you wish, but you SHOULD try to standardise them whenever possible, to aid compatibility.

(Note that the "Type" column refers to how the string value should be parsed, not the actual underlying variable type.)

Name	Type	Multi-value	Description
Title	text	No	Name of the track
Artist	text	Yes	Artist(s) of the track
Album	text	No	Name of the album this track belongs to
AlbumArtist	text	Yes	Primary artist(s) that the album was credited to. For compilation albums, use the value Various Artists.
Publisher	text	No	Record label or publisher
Year	number	No	Year of recording/release/etc
Genre	enum/text	Yes	Music genre(s); use  List of ID3v1 genres (w/ Winamp extensions) for guidance
Remix	enum	No	If this is a remix or other derivative work, indicates the type: Remix, Cover, Arrangement, Edit, Other
Remix.OriginalArtist	text	Yes	Artist(s) of the original track, if this is a remix/derivative
Remix.OriginalYear	number	No	Year of the original song's recording/release
Remix.OriginalTitle	text	No	Title of the original track, if this is a remix/derivative
Subtitle	text	No
Arranger	text	Yes
Composer	text	Yes
Conductor	text	Yes
Lyricist	text	Yes
MBID.Recording	uuid	No	The track's MusicBrainz Recording ID
MBID.Release	uuid	No	The album's MusicBrainz Release ID
MBID.Artist	uuid	Yes	MusicBrainz IDs for the track's artist(s)
MBID.AlbumArtist	uuid	Yes	MusicBrainz IDs for the album's release artist(s)
AlbumType	enum	No	Album, Single, EP, Compilation, Live, Mixtape, Other
BPM	number	No
InitialKey	text	No

Integrated player

The Song Orb's integrated player exists solely for the end user. Implementors of Res-MD systems MUST NOT interface with it or assume it exists; reference the AudioClip instead.

Song Orb implementations SHOULD include their own integrated player, but are not strictly required to.

You MUST ensure that all functionality of the Song Orb is disabled when the object root's Active field is set to false. (Notably, context menu entries need their  ContextMenuItemSource's Enabled field driven to false.)

Res-MD Discs

Similar structure to a Song Orb:

• ObjectRoot
• DynamicVariableSpace named ResMD
• Snapper named ResMD
• Child slot named Tracks, where the song orbs go
  • These can (and probably should) be packed, i.e. everything except the data part is removed. However, the player would have to include a template to convert them back into interactable objects as needed.
    • If we had proper cloud spawning this would be so much better
• Child slot named DiscMetadata, whose purpose is not yet known. If you can figure out what this is for, let us know: you could win a FREE ringtone!*
  *While supplies last. Offer contingent on punching the monkey.

Disc-level metadata

Like Song Orbs, there's a _DMFIELDS dynvar that tells us what disc attributes are present.

Some disc attributes can be inferred from a related track attribute. This would (usually) be done by checking if all tracks on the disc have the same value (excluding ones that just don't specify a value at all), and prefilling that in some editor UI.

Name	Type	Description	TrackAttr
Title	text	Disc title, typically the album name	Album
Author	text (multi)	Creator(s) of the disc	AlbumArtist
Type	enum	Album, Single, EP, Compilation, Live, Mixtape, Other	AlbumType
Publisher	text	Record label or publisher	Publisher
Year	number	Year of recording/release/etc	Year
Genre	enum/text (multi)	Music genre(s); use  List of ID3v1 genres (w/ Winamp extensions) for guidance	Genre
MBID.Release	uuid	The album's MusicBrainz Release ID	MBID.Release
MBID.AlbumArtist	uuid (multi)	MusicBrainz IDs for the album's release artist(s)	MBID.AlbumArtist

There is also a dynvar of type IAssetProvider<ITexture2D> called CoverArt. This isn't recorded in _DMFIELDS for various (probably good?) reasons, so you'll have to check for its presence manually. Oh Well!