0.3.13 • Public • Published

Musiphone [alpha] npm version Build status

Musiphone is a decentralized music player based on the museria project.

There is an article here with an explanation.

import { Node } from 'musiphone';
try {
  const node = new Node({
    port: 4000,
    hostname: 'localhost',
    musicStorageAddress: ''
  await node.init();
catch(err) {
import { Client } from 'musiphone';
try {
  const client = new Client({
    address: 'localhost:4000'
  await client.init();    
  const title = 'Playlist title';
  const songs = [
    'Onycs - Eden',
    'Onycs - Shine',
    'Onycs - Timeless'      

  // Add the playlist
  const response = await client.addPlaylist(title, songs);

  // Get the playlist
  const playlist = await client.getPlaylist(response.hash);
catch(err) {

Browser client

You can also use the client in a browser. Look at the description of the spreadable library. In window you have window.ClientMusiphone instead of window.ClientSpreadable. The prepared file name is musiphone.client.js.

How to use it via the command line

Look at the description of the spreadable library. You only need to change everywhere spreadable word to musiphone.

How it works

There are two sides to work with. On the server side the library allows you to create a decentralized network for storing music playlists based on the metastocle data storage. When you run the node, it is required to specify what kind of music storage clients will connect to, using musicStorageAddress option. It can be a node address of any network that uses the museria library. When you add a playlist to the database, it gets a unique hash that you can use to get it later. On the client side it is a player where we manage all that stuff: creating playlists, sharing them with your friends, listening to music and so on. Currently, the player can be used in the browser and android smartphones.

Browser player

To use browser version of the player you only need to find and open any available musiphone node address. It will look like a regular website. You can use the player version based on the global music storage.

Android player

You can get prepared apk/aab files from ./dist/android. To build an android application by yourself, you have to install all the necessary dependencies and compile the application via cordova. All the necessary scripts you can find in the project ./package.json. The only option to pass for building is an API address. It is necessary for the application to know where to connect for working. You can specify MUSIPHONE_API_ADDRESS environment variable. If you don't pass it, the user will have to set it up in the app. The value can be any musiphone node address in your network:

MUSIPHONE_API_ADDRESS= npm run make-mobile.

or several addresses separated by comma:

MUSIPHONE_API_ADDRESS=, npm run run-mobile-device.

or the path to a js/json file:

MUSIPHONE_API_ADDRESS=./faces.json npm run make-mobile-prod.

You can build it directly to your phone with run-mobile-device. To get an apk/aab file for installation use make-mobile for the debug version or make-mobile-prod for production ready one. The debug version you can install on the phone, but can't distribute to the markets. The production version is unsigned. To use it somewhere you have to sign it at first.

Playlist links

There are two types of links:

  • Static links. They are stored in a decentralized database. Each playlist has a unique hash depending on its content and title. It creates a link in the player that you can share. This link is active as long as it is stored in the database. If there are more links than the space in the network, the old links will be gradually deleted. These links look like: http://node-address/musiphone/someHash

  • Dynamic links. These are wrappers to some external links that return a valid m3u file. This file must contain song titles in the #EXTINF. These links look like: http://node-address/musiphone/external:someHash

What are the limitations

The maximum size of a playlist is 100 kb, by default. You can change it using the playlist.maxSize option.

What are the requirements

Look at the metastocle requirements.

Node configuration

When you create an instance of the node you can pass options below. Only specific options of this library are described here, without considering the options of the parent classes.

  • {object} [server] - section that responds for server settings.

  • {string|number} [server.staticMaxAge] - maximum age for static files.

  • {object} [playlist] - section that responds for playlist settings.

  • {number|string} [playlist.maxSize="100kb"] - maximum playlist size.

  • {number|string} [playlist.collection] - playlist collection settings.

Client interface

async Client.prototype.getStorageAddress() - get the music storage address.

  • {object} [options] - addition options
  • {number} [options.timeout] - addition timeout

async Client.prototype.addPlaylist() - add the playlist to the network.

  • {string} title - playlist title
  • {string[]} content - array with song titles to save
  • {object} [options] - addition options
  • {number} [options.timeout] - addition timeout

async Client.prototype.getPlaylist() - get the playlist.

  • {string} hash - playlist hash
  • {object} [options] - getting options
  • {number} [options.timeout] - getting timeout

Exporting playlists

If necessary, you have the opportunity to export playlists from one server to another. There are two options:

  • Copy all project files to the second server. It is convenient and works at the current moment, because the node is able to reconfigure all information to a new address. But there is no guarantee that this will work in the future.

  • Use the song export feature: run node.exportPlaylists() method or via the command line as musiphone -a exportPlaylists -n


If you face a bug or have an idea how to improve the library, create an issue on github. In order to fix something or add new code yourself, fork the library, make changes and create a pull request to the master branch. Don't forget about tests in this case. Also you can join the project on github.

Package Sidebar


npm i musiphone

Weekly Downloads






Unpacked Size

13.4 MB

Total Files


Last publish


  • ortex