IMDS Overview (V1.3.2)

The Promise

IMDS (IPFS music distribution and storage) is a fully decentralized method of storing and distributing music. Nobody owns it and nobody has any more control over the storage and distribution of music than anyone else. IMDS allows anyone to host music, create a music player application, access the music, etc. IMDS does not provide listening analytics or streaming revenue, but services build on top of IMDS could implement these features on their own. IMDS aims to serve as a single yet decentralized backbone for online music distribution.

Functionality Overview

IMDS is built entirely on top of IPFS. It stores music files directly on the IPFS network and metadata as JSON objects which are also stored directly on the IPFS network as plain text. An album for example, will simply be a JSON object with metadata and a list of tracks which are also JSON objects with references to actual audio files, artwork, etc.

Data Storage

Audio Files

Audio files can be stored as MP3, WAV, M4A, or any other audio file format. There is no standard format defined by IMDS, but in order to ensure compatibility, it is advisable to store them as MP3 or WAV files.

Tracks

Tracks are stored as JSON objects which contain their metadata and reference their assets.
Here is the format of a track object (note: colored text refers to information specific to a track):

{
	"contentType": "track",
	"imdsVersion": "1.1",
	"date": "date the track was released",
	"version": "version of track",
	"versionDate": "date this version of the track was released",
	"title": "track title",
	"displayName": "artist names - track title (extra information)",
	"musicalKey": "key of track",
	"bpm": tempo of track,
	"description": "description of track",
	"notes": "other details about track",
	"artists": [
		{
			"name":"name of artist #1",
			"role":"role of artist #1",
			"ensDomainName": "ens domain"
		},
		{
			"name":"name of artist #2",
			"role":"role of artist #2",
			"ensDomainName": "ens domain"
		}
	],
	"audioFiles": [
		{
			"name":"name of version",
			"format":"file format",
			"cid":"ipfs cid"
		}
	],
	"artwork": [
		{
			"width":width in px if applicable,
			"height":height in px if applicable,
			"format":"file format",
			"cid":"ipfs cid"
		}
	],
	"assets":"ipfs cid",
	"extraData": {any JSON object}
}

Overview of properties:

contentType: for tracks, this must be "track"
imdsVersion: this refers to the version of IMDS this content item is formatted in. This should be written as you see the version at the top of this document without the "V". This shouldn't change the structure of the content, but is important just in case there are breaking changes in the future
date: the date the first version of this content item was released. This should be in the following format: YYYY-MM-DD
version: this refers to the version of the specific content item. This should be formatted as a series of integers separated by periods. For example: "1.1.1". This is important since IPFS CIDs will only refer to one specific JSON file. This allows the creator to update their works. NOTE: adding a newer version of a content item will not get rid of older versions.
versionDate: this refers to the date this specific version was released. This should be in the following format: YYYY-MM-DD
title: the title of the track
displayName: the entire track name if displayed on one line. The artist can choose how to format this however he/she pleases
musicalKey: the key the track is in. There is no standard format for this data so multiple keys are allowed and can be written in any format. Fore example, "E♭m", "Ebm", "E flat minor" and "2A" are all acceptable.
bpm: the tempo of the track in beats per minute. This is strictly a number
description: a description of the track.
notes: a notes about the track.
artists: a list of artists as JSON objects with the following properties:
- name: the name of the artist
- role: the role(s) of the artist. For example: "primary artist", "producer", "featured artist", "original artist", etc.
- ensDomainName: an ens domain name that references this artist's IMDS object. Track objects cannot referece artist objects if that artist object contains the track itself due to the content-addressing nature of IPFS. This reference allows that upwards referencing.
audioFiles: a list of audio files of the SAME TRACK (multiple audio files are used to store variations of mastering and audio format) as JSON objects with the following properties:
- name: the name of the version. For example: "main", "streaming", "loud master", "radio master", "lossless", "compressed", etc. Note: music streaming applications should look for "main" as the default audio file. Having multiple "main" files is advisable if they have different file formats. this can ensure compatibility across players
- format: the format of the audio file. For example: "mp3", "wav", "flaac", etc.
- cid: the actual cid for the audio file on the IPFS network
artwork: a list of image files of the SAME ARTWORK (multiple files can be used to ensure compatibility with players) as JSON objects with the following properties:
- width: the width in pixels of the file if applicable. Note: vector images should not require this.
- height: the height in pixels of the file if applicable. Note: vector images should not require this.
- format: the format of the image file. For example: "png", "jpeg", "svg", etc.
- cid: the actual cid for the image file on the IPFS network
assets: This should refer to an IPFS cid (usually a folder) containing additional data or files for the track. For example, stems, videos, DJ edits, extra artwork, etc.
extraData: a JSON object with no specification. This can be used for any purpose. Some purposes might be: links to websites where the song is hosted, metadata for use by a specific player, etc.

Collections

Collections are lists of mixed content and can be used for playlists, albums, discographies, etc. Collections can hold other collections and can therefor be used for defining artist discographies, personal music collections or anything else. (note: colored text refers to information specific to a collection):

{
	"contentType": "collection",
	"imdsVersion": "1.1",
	"collectionType": "type of collection"
	"date": "date the collection was released",
	"version": "version of collection",
	"versionDate": "date this version of the collection was released",
	"title": "collection title",
	"description": "description of collection",
	"notes": "other details about collection",
	"artists": [
		{
			"name":"name of artist #1",
			"role":"role of artist #1",
			"ensDomainName": "ens domain"
		},
		{
			"name":"name of artist #2",
			"role":"role of artist #2",
			"ensDomainName": "ens domain"
		}
	],
	"items": [
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid"
	],
	"artwork": [
		{
			"width":width in px if applicable,
			"height":height in px if applicable,
			"format":"file format",
			"cid":"ipfs cid"
		}
	],
	"assets":"ipfs cid",
	"extraData": {any JSON object}
}

Overview of properties:

contentType: for collections, this must be "collection"
imdsVersion: this refers to the version of IMDS this content item is formatted in. This should be written as you see the version at the top of this document without the "V". This shouldn't change the structure of the content, but is important just in case there are breaking changes in the future
collectionType: the kind of collection this content type defines. Example values could be "playlist", "album", "collective", "discography", etc.
date: the date the first version of this content item was released. This should be in the following format: YYYY-MM-DD
version: this refers to the version of the specific content item. This should be formatted as a series of integers separated by periods. For example: "1.1.1". This is important since IPFS CIDs will only refer to one specific JSON file. This allows the creator to update their works. NOTE: adding a newer version of a content item will not get rid of older versions.
versionDate: this refers to the date this specific version was released. This should be in the following format: YYYY-MM-DD
title: the title of the collection
description: a description of the collection.
notes: notes about the collection.
artists: a list of artists as JSON objects with the following properties:
- name: the name of the artist
- role: the role(s) of the artist. For example: "primary artist", "producer", "featured artist", "original artist", etc.
- ensDomainName: an ens domain name that references this artist's IMDS object. Track objects cannot referece artist objects if that artist object contains the track itself due to the content-addressing nature of IPFS. This reference allows that upwards referencing.
items: a list of IPFS cids referring to the objects within the collection. Note: these cids do NOT refer to audio files.
artwork: a list of image files of the SAME ARTWORK (multiple files can be used to ensure compatibility with players) as JSON objects with the following properties:
- width: the width in pixels of the file if applicable. Note: vector images should not require this.
- height: the height in pixels of the file if applicable. Note: vector images should not require this.
- format: the format of the image file. For example: "png", "jpeg", "svg", etc.
- cid: the actual cid for the image file on the IPFS network
assets: This should refer to an IPFS cid (usually a folder) containing additional data or files for the collection. For example, videos, extra artwork, etc.
extraData: a JSON object with no specification. This can be used for any purpose.

Artists

The artist data type is used to describe an artist. Typically an artist should register a domain and have the domain point to an artist object which can in turn point to all of that artist's music on IMDS.

{
	"contentType": "artist",
	"imdsVersion": "1.1",
	"version": "version of artist data",
	"versionDate": "date this version of the artist data was released",
	"name": "artist name",
	"bio": "artist bio",
	"notes": "other details about the artist",
	"works": [
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid",
		"ipfs cid"
	],
	"profileImage": [
		{
			"width":width in px if applicable,
			"height":height in px if applicable,
			"format":"file format",
			"cid":"ipfs cid"
		}
	],
	"assets":"ipfs cid",
	"extraData": {any JSON object}
}

Overview of properties:

contentType: for artists, this must be "artist"
imdsVersion: this refers to the version of IMDS this content item is formatted in. This should be written as you see the version at the top of this document without the "V". This shouldn't change the structure of the content, but is important just in case there are breaking changes in the future
version: this refers to this specific version of the artist data. This should be formatted as a series of integers separated by periods. For example: "1.1.1". This is important since IPFS CIDs will only refer to one specific JSON file. This allows the creator to update their works. NOTE: adding a newer version of a content item will not get rid of older versions.
versionDate: this refers to the date this specific version was released. This should be in the following format: YYYY-MM-DD
name: the name of the artist
bio: a bio/description of the artist.
notes: notes about the artist.
works: a list of IPFS cids referring to the objects within the collection. Note: these cids do NOT refer to audio files.
profileImage: a list of image files of the SAME ARTWORK (multiple files can be used to ensure compatibility with players) as JSON objects with the following properties:
- width: the width in pixels of the file if applicable. Note: vector images should not require this.
- height: the height in pixels of the file if applicable. Note: vector images should not require this.
- format: the format of the image file. For example: "png", "jpeg", "svg", etc.
- cid: the actual cid for the image file on the IPFS network
assets: This should refer to an IPFS cid (usually a folder) containing additional data or files for the artist. For example, branding materials, videos, etc.
extraData: a JSON object with no specification. This can be used for any purpose.

Other notes regarding data storage

Music players and other applications that intend to read music from IPFS under the IMDS should be able to handle any property missing

About

This specification was written by Luke Branson
May 2023