Dcent Beats Backend

Backend to the Dcent Beats app.

Install

npm i dcent-beats-backend

API

const dbBackend = new DcentBeatsBackend(corestore, swarmManager, opts)

Create a new backend.

corestore is a Corestore instance.

swarmManager is a Swarm Manager instance.

Neither the corestore nor the swarmManager are managed by the backend, so they need to be closed separately (after the backend closed).

opts include:

• msGcDelay (advanced) how long to wait before garbage collecting a hyperdrive

await dbBackend.ready()

Open the backend and start swarming.

await dbBackend.close()

Close the backend, cleanup and stop swarming.

Song Modifiers

const record = await dbBackend.createBeats(blob)

Create a new dcent beats instance and adds it to the library.

blob is a blob of bytes containing an mp3 file.

Returns the corresponding library record.

const record = await dbBackend.createBeatsFromPath(filePath)

Creates a new song from the mp3 file at filePath.

Returns the corresponding library record.

Playlist Modifiers

const record = await dbBackend.createPlaylist(title, songs, opts?

Creates a new playlist and adds it to the library.

title is the playlist title.

songs is a list with entries of form

{
  driveKey, // drive where the song lives
  location, // location of the song in the drive
  driveVersion // drive version when the song was created
}

opts include:

• cover: cover image of format { data, metadata }. data is the raw bytes of a jpeg file. metadata should be { format: 'image/jpeg'} (no other formats are supported at the moment).
• description: textual description of the playlist

const record = await dbBackend.createPlaylistFromPath(dirPath, title, opts?)

Like dbBackend.createPlaylist(...), but populating songs with all the mp3 files in dirPath instead of passing in a list of existing songs.

Note: also creates new songs for each mp3 file.

const playlist = await dbBackend.previewPlaylist(dirPath)

Helper function to show what a playlist created by dbBackend.createPlaylistFromPath(...) will look like without actually creating it.

Returns { metadatas, invalidFiles }.

metadatas is a list of parsed metadatas of all songs which would be included in the playlist (in order).

invalidFiles is a list of { location, error } objects of mp3 files that could not be parsed (usually because they do not contain the required song metadata).

Song accessors

Songs are identified by their songId = { driveKey, location, version }.

driveKey is the key of the drive (in buffer, hex or z32 format).

location is the location of the song's directory in the drive.

version is the hyperdrive version at which the song was created.

All these methods will hang until the hyperdrive is loaded at the specified version. They might hang forever if neither you nor any peer have that version available.

const strean = dbBackend.streamSong(songId)

Retruns a read stream of the song's mp3 file.

const cover = dbBackend.getSongCover(songId)

Returns an object with the cover image corresponding to this song, or null.

See DcentBeats.getSongCover() for the object format.

const metadata = dbBackend.getSongMetadata(songId)

Returns the metadata of the song.

See DcentBeats.getSongMetadata() for the object format.

const stream = dbBackend.streamSongMetadatas(songs, opts)

Returns a read stream of [index, metadata] tuples, 1 for each song passed in. index indicates the position in the original songs list. metadata is a Dcent Beats metadata object.

This method can quickly load large batches of metadatas (like for a playlist) because it does not yield the metadatas in order and aggressively prefetches entries.

songs is an iterable of songId objects.

opts include:

• windowSize = 100: max amount of metadatas to prefetch
• eagerOpen = true: whether to start prefetching immediately (set false to wait until the stream is being consumed)

const stream = dbBackend.streamSongCovers(songs, opts)

Returns a read stream of [index, cover] tuples, 1 for each song passed in. index indicates the position in the original songs list. cover is a Dcent Beats cover object.

This method can quickly load large batches of covers (like for a playlist) because it does not yield the covers in order and aggressively prefetches entries.

songs is an iterable of songId objects.

opts include:

• windowSize = 10: max amount of covers to prefetch
• eagerOpen = true: whether to start prefetching immediately (set false to wait until the stream is being consumed)

Playlist accessors

Playlists are identified by their playlistId = { driveKey, location, version }.

driveKey is the key of the drive (in buffer, hex or z32 format).

location is the location of the playlist's directory in the drive.

version is the hyperdrive version at which the playlist was created.

All these methods will hang until the hyperdrive is loaded at the specified version. They might hang forever if neither you nor any peer have that version available.

const playlist = await dbBackend.getPlaylist(playlistId)

Returns the playlist, which is an object of form

songs: [songId1, songId2, ...], // The songs (in order)
title: // str: the title
cover, // the playlist cover object (or null). Has the same structure as the [song cover object](https://gitlab.com/HDegroote/dcent-beats#const-cover--await-dbeatsgetcover)
description // str: description of the playlist (or null)

const entries = await dbBackend.getPlaylistSongs(playlistId)

Like dbBackend.getPlaylist(...) but only returns the songs`.

const description = await dbBackend.getPlaylistDescription (playlistId)

Like dbBackend.getPlaylist(...) but only returns the description`.

Library

The library stores data about the songs and playlists a user knows about (both their own and those from others they have encountered).

New entries are added under the hood when new playlists or songs are first loaded, so the library API consistst mostly of accessor methods.

Library Song Record Structure:

const songRecord = {
  major, // int: song major version when the record was created
  minor, // int: song minor version when the record was created
  driveKey, // buffer: key of the drive where the song lives
  artist, // str: song artist
  title, // str: song title
  location, // str: location in the drive where the song lives
  favourite, // boolean: true if the song was favourited
  isOwn, // boolean: true if we own the drive where the song lives
  driveVersion // int: drive version after this song was created
}

Library Playlist Record Structure:

{
  major, // int: playlist major version when the record was created
  minor, // playlist minor version when the record was created
  driveKey, // buffer: key of the drive where the playlist lives
  title, // str: playlist title
  location, // str: location in the drive where the playlist lives
  favourite, // boolean: true if the playlist was favourited
  isOwn, // boolean: true if we own the drive where the playlist lives
  driveVersion // int: drive version after this playlist was created
  uid // buffer: 32-byte hash of the driveKey and the location
}

const strean = dbBackend.streamLibrarySongs()

Returns a stream of all song records in the library.

const strean = dbBackend.streamLibraryPlaylists()

Returns a stream of all playlist records in the library.

const strean = dbBackend.streamLibraryFavourites()

Returns a stream of all favourited playlists in the library.

const overview = await dbBackend.announceOnBlindPeers(blindPeerKeys)

Adds all drives referenced by the library's playlists to the specified blind peers. This includes the drives where the playlists live, as well as the drives of all the songs they contain.

Assumes your dht public key is trusted by the blind peers.

Returns the overview of all blind-peering requests as a list (one per added core).

const record = await dbBackend.favouritePlaylist(playlistId, favourite = true)

Mark a playlist as favourite. Returns the updated library record.

Set favourite = false to unmark the playlist as favourite.

const playlist = await dbBackend.getRandomPlaylist(libraryKey, version)

Returns a random playlist from the library at key libraryKey with the given version (or null if the library contains no playlists).

Will hang until the library is loaded (can hang forever if it is not available locally and no peers have it).

const txt = await dbBackend.getDriveFile(key, path, version)

Returns the text at path from the hyperdrive with the specified key checked out at version (assumes the file is a text file).

Will hang until the drive is loaded (can hang forever if it is not available locally and no peers have it).