sonido

A private audio streaming service.

SUPER-WARNING

This software does not work as-is. It is a work in progress. First working version will be tagged as v0.1.0 when it's ready.

WARNING

This is a work in progress so consider nothing to be stable. The API will be considered stable at v1.0.0.

Also, treat this README as a guide for the future as most of this stuff is a lie right now (there is no HTTPS support for the API yet), but I'll get there.

Why?

I wanted to stream my music from the cloud for free without compromising my privacy. No solution in the market provides this until now.

Installation

Supported OSes: Linux Ubuntu 14

1. SSH into your server.
2. Install node.js with nvm, which includes npm
   • Execute either wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.13.0/install.sh | bash or curl https://raw.githubusercontent.com/creationix/nvm/v0.13.0/install.sh | bash in the terminal.
   • nvm install 0.11
   • nvm use 0.11
3. npm install -g sonido-cli
4. sonido setup

Configuration

Configuration Wizard: <!--- This is what the user will see during the configuration ->

Welcome to sonido!

These questions will help me get you setup right away.

First, I will need to create an account for you. What's your email?

Now we need to setup a password. It is recommended that you use a password manager. So what will the password be?

Cool! You will use this email and password to log into your sonido server from now on.

Add audio files with sonido add [path].

The server is up and running and your host is HOST.

Enjoy your music!

Documentation:

Configuration should check for mediainfo, and install it if missing.

Configurable stuff:

• Username
• Password

API

All API access is over HTTPS, and accessed through yourdomain.com/api/v1/. All data is sent and recieved as JSON.

Songs

A song resource has the following object structure. Missing properties will have null values.

{
  "id": Number,
  "title": String,
  "artist": String,
  "album": String,
  "genre": String,
  "audio": Stream Data (Blob?)
}

GET /songs?title&artist&album&genre&audio

The URL parameters are used for filtering. If no parameters are provided, the response will be an Array of all song objects with the audio property set to null.

Parameter values:

title - String, defaults to null

artist - String, defaults to null

album - String, defaults to null

genre - String, defaults to null

audio - Boolean, defaults to false

Examples:

A request to /api/v1/songs?title=Untouchable&artist=Childish%20Gambino will return songs whose title is the string "Untouchable", and artist is "Childish Gambino", but will not include the audio file.

A request to /api/v1/songs?audio=true will return all song objects and their respective audio files.

GET /song/:id?audio

Returns a single song object. Includes the audio data if the audio parameter is true.

Parameters:

audio - Boolean, defaults to false.

POST /song

PUT /song/:id

PATCH /song/:id

DELETE /song/:id

Authentication

The authentication scheme used is JSON Web Tokens (JWT).

Each token will expire after a period of inactivity. This period defaults to never.

POST /authentication

Parameters:

username - String password - String

Returns a JSON Web Token if credentials are valid.

DELETE /authentication

Adding Files

$ sonido add [path] will create a soft symlink to [path].

The symlinks will be stored in ~/.sonido/data, and will be used to stream data to the client.

Behaviour

This command only creates symlinks for individual files. If the source path points to a directory it will recursively read every file and create symlinks.

Roadmap

v0.1.0

• Authentication (email, password) NOT SECURE!
• Stream audio files
• Add audio and (some) metadata by watching directories for changes.

Future

• Encrypt passwords, use TLS
• Tests for previous release
• Upload songs
• Edit metadata
• Shuffle
• Search (by title, artist, work, genre)
• Playlists
• Music recommendations? (Recommend a new song based on your previous music recommendations and latest music listened to)
• Download? (Verify legal issues with this...)
• Configurable token expiration time
• Multiple accounts
• Account permissions to access certain audio files only
• Serve variable bitrate depending on connection strength
• Encrypt all data

Keeping shit simple

Only accept .flac or .mp3 sound files.

Require as fewer metadata fields as possible: Name, Author, Work (album), Genre. All optional except Name.

Stack

• Koajs server (Node.js)
• SQLite database

Libraries

• mediainfo