WavePin Overview (V0.1)

WavePin (formerly known as IMDS) 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. WavePin allows anyone to host music, create a music player application, access the music, etc. WavePin does not provide listening analytics or streaming revenue, but services build on top of WavePin could implement these features on their own. WavePin aims to serve as a single yet decentralized backbone for online music distribution.

WavePin 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.

Audio files must be stored as WAV files. The highest quality possible is recommended. Encoding to smaller or lossy formats should be left up to applications and users. WavePin should be seen as the source of truth only.

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):

Overview of properties:

• contentType: for tracks, this must be "track"
• wavepinVersion: this refers to the version of wavepin 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
  • wavepinArtistUrl: a url that returns a string (and only a string) that is the CID of this artist's discography on wavepin (a wavepin artist object)
  • role: the role(s) of the artist. For example: "primary artist", "producer", "featured artist", "original artist", etc.
• recording: the main recording of the track. This object has two properties:
  
  • filename: the name of the audio file if it is downloaded or shared
  • cid: the actual cid for the PCM audio file on the IPFS network
• alternateRecordings: 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
• alternateLinks: a list of links to THIS track on other stores or streaming services:
  
  • name: the name of the service or store. For example, SoundCloud, Spotify, BandCamp
  • url: the url to the track on the service named in the name field
• artwork: a JSON object representing the track's artwork 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
• 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 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):

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
  • wavepinArtistUrl: a url that returns a string (and only a string) that is the CID of this artist's discography on wavepin (a wavepin artist object)
  • role: the role(s) of the artist. For example: "primary artist", "producer", "featured artist", "original artist", etc.
• items: a list of IPFS cids referring to the objects within the collection. Note: these cids do NOT refer to audio files.
• artwork: a JSON object representing the collection artwork 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
• extraData: a JSON object with no specification. This can be used for any purpose.

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.

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 JSON object representing the artist's profile image 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
• extraData: a JSON object with no specification. This can be used for any purpose.

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

This specification was written by Luke Branson
May 2023