Skip to content
The music playing server for Linux that never stops!
C++ Vue JavaScript Ruby CSS C HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Join the chat at

Musciteer is a music playing server for Linux. It combines your local music files with selected music from streaming services and presents it as one library through a modern web interface. It's designed to run on a small, preferably fanless, pc that is hooked up to your hifi system. I guess you can think of it as an alternative to Volumio or MPD.

NOTE: Currently it only supports flac and spotify


Getting Started

Installation is not as polished as it should be yet. For now head to releases it should contain the information you need to get Musciteer running as service.

There is no integration with any meta data services, at least not yet, so it requires that your local flac files are properly tagged. For album covers you need to tag all your flac files with a front cover or media image. You can use something like Easytag to do this.

For replaygain to work, make sure all your flac files have proper replaygain tags. One way to do this is to use the flac_rg_tagger tool included with Musciteer. It requires the metaflac package in order to run. First run a scan to import your flac files then stop musciteer, run flac_rg_tagger, start musciteer and run a new scan.


A somewhat prioritized list of features / tasks.

  • Configurable through the desktop web interface.
  • FLAC local files
  • Spotify playback
  • Import Spotify albums/tracks from web interface. Not optimal, but will have to do for now.
  • Continuous playback. If nothing is explictly queued, play songs at random from the entire collection. Can be turned on/off from settings.
  • Mobile web application. For android open in browser and choose add to home screen. It is the same web app, but default page is /player. Don't know how it works on iphone.
  • Ubuntu snap package. Not possible currently as snaps cannot access alsa ❗️
  • Debian package for Ubuntu 16.04 and 17.04
  • Browse and queue music from mobile web app. Works best on a tablet, on small screens it is not very usable.
  • Replay gain. Fairly straight forward for FLAC files. Not so for Spotify. See spotify audio features
  • Tagging
  • More advanced Continuous playback. random, more-played, less-played, top-played.
  • Improve Spotify integration
  • Search
  • Remove content on rescan when local flac files are removed
  • Play albums
  • Tidal
  • Playlists
  • Support additional targets, like arm
  • Ubuntu Touch app
  • FLAC file tagging from web interface / Integrate with online music meta data service.
  • MP3 local files
  • Native Android app
  • OGG local files
  • WAV local files
  • Google play
  • Deezer
  • Native IOS app


HTTP Methods URL
GET /api/tracks[?brief=1]
GET, DELETE /api/tracks/:id
GET /api/tracks/:id/sources
GET, DELETE /api/tracks/:id/sources/:name
GET, POST /api/tracks/:id/tags
GET /api/albums
GET, DELETE /api/albums/:id
GET /api/albums/:id/tracks
GET /api/albums/:id/cover
GET /api/artists
GET /api/artists/:id
GET, POST /api/sources/local/directories
POST /api/sources/local/scan
GET, POST /api/sources/spotify/settings
GET /api/player
GET, POST /api/player/ctpb
GET, POST /api/player/output
GET, POST /api/player/replaygain
POST /api/spotify/import

Player control and notifications are done over a websocket.

Client -> Server

{ "event": "play" }
{ "event": "play", "data" : "<track-id>|<album-id>|pl:tag:<tag>" }
{ "event": "stop" }
{ "event": "skip" }
{ "event": "queue", "data" : "<track-id>" }
{ "event": "stream_data_sync", "data" : "<stream-id>" }

Server -> Client

{ "event": "stream_begin", "data" : "<stream-id>" }
{ "event": "stream_end", "data" : "<stream-id>" }
    "event": "stream_progress", "data" : {
        "stream_id" : "<stream-id>",
        "duration"  : Number,
        "length"    : Number
    "event": "queue_update", "data" : {
        "queue_size" : Number,
        "track"      : Object
    "event": "player_state", "data" : {
        "state" : Number
    "event": "source_notification", "data" : {
        "type" : Number,
        "source_name" : String,
        "message" : String
    "event": "stream_data", "data" : {
        "stream_id" : String,
        "track" : Object


Building The Server

To build you will need a spotify application key which is not included in the repository. Register a new application on the spotify developer site and place it in source/player/source_spotify_app_key.cpp

#include <stdint.h>
#include <stdlib.h>

extern "C" const uint8_t g_appkey[] = {
  0x01, 0xB1, 0xA2, 0x29, ...

extern "C" const size_t g_appkey_size = sizeof(g_appkey);

For the spotify web api you will need the client id and client secret in source/spotify_web/id.h

#ifndef __spotify_web__id_h__
#define __spotify_web__id_h__

// ----------------------------------------------------------------------------
namespace spotify_web
  const std::string client_id     = "................................";
  const std::string client_secret = "................................";

// ----------------------------------------------------------------------------

Install needed dependencies

sudo apt install ninja-build libasound2-dev libflac++-dev libkyotocabinet-dev libssl-dev libcrypto++-dev

Get additional dependencies like libspotify and json library.

ninja deps



Building The Web interface

The web interface is a vue webpack application. To build you'll need node and npm.


cd webclient
npm install

The development setup proxies request to /api to http:localhost:8214. To get websocket communication to work change main.js to connect to ws://localhost:8214 then run

npm run dev

To get hot reload working on Linux, you might have to change max_user_watches.

sudo sysctl -w fs.inotify.max_user_watches=16536

Build for production

npm run build

To package the files in dist must be copied to the public folder.


Any kind of feed back is welcome. Feel free to ask me qustions on gitter or open an issue, be it a bug or an idea.

You can’t perform that action at this time.