back

canary

a music streaming server/client

canary is a package of a music streaming server and its companion iOS client that run upon DAAP. Employing DAAP for streaming and mDNS/DNS-SD for service advertisement let canary work perfectly with iTunes.

running canary and iTunes

This document explains the server. See the files in the client directory for the client.

The server supports, among other things:

  • iTunes as a client,
  • rescan of songs based on a schedule,
    • it cleverly does nothing unless files or directories change
  • authorization via a password,
  • delievery of mp3/ogg files if your client can play them and
  • multiple paths to contain your songs

but does not support yet:

  • adding or editing smart playlists and
  • what I don't know yet but you do
    • please let me know about them!

The initial scan of songs is fairly fast thanks to high performance of the music-metadata module; 7 mins with 4,500+ songs on my Gentoo machine with Intel Atom D525, 4GB RAM and a 5400-rpm HDD. Once the database has been built, rescanning is even faster; 30 secs on the same condition. The server remembers the mtime, modification time of files and reads only added or modified files.

Prerequisites

canary can run with avahi or dns-sd, or launch its own instance of mDNS/DNS-SD service implemented in pure JavaScript (node-mdns-js) when you have neither installed.

Having more than one instance of mDNS/DNS-SD service on the same machine confuses the service to prevent it from properly working.

The value for mdns in server.conf (see below) chooses a service for mDNS publication.

  • avahi: avahi-publish-service is probed to execute;
  • dns-sd: dns-sd is probed to execute;
  • mdns-js: mdns-js is launched without probing the two above;
  • auto: canary tries to execute either of avahi-publish-service or dns-sd, and launches mdns-js on failure. This is the default behavior;
  • off: no service advertisement activated.

If your system have avahi or dns-sd, please make sure that avahi-publish-service or dns-sd is accessible not specifying a path from the location canary runs.

Whenever avahi or dns-sd fails to start, mdns-js is selected as a fallback.

If you are not able to get the service advertisement to work with any of these options, please let me know to help you.

Configuration

Two configuration files need to be provided for the server, one for its database and the other for the server itself.

The server configuration, config/server.json looks like:

{
    "name":     "canary music",
    "port":     3689,
    "runAs": {
        "uid": "userid",
        "gid": "groupid"
    },
    "password": "password",
    "scan": {
        "path":  [ "/path/to/mp3/files" ],
        "cycle": [ "17:00:00" ],
        "utc":   false
    },
    "mdns":  "auto",
    "debug": false
}
  • the name of the server will be published and broadcast via Avahi. If your client knows DNS-SD, it will appear on it;
  • the server will run on port; it must be set to the default port 3689 for iTunes to work with the server;
  • runAs, if specified, makes the server drop privileges by changing its uid and gid to the given ones, which is useful when the server initially runs as root, for example, by an init.d script. If not specified, running the server as root will be warned;
  • if password is a non-empty string, the server requires a client to send the password on every request. This, for example, forces iTunes ask a password on its initial connection to the server;
  • scan specifies the schedule for rescanning files:
    • path is an array of directories of music files to serve;
    • cycle and utc: clear what these mean from their names but you can refer to ontime for how to specify the rescanning schedule. canary-server accepts other options for ontime except single that is always set to true;
  • mdns selects a service for mDNS advertisement. Possible values are auto, avahi, dns-sd, mdns-js and off. See Prerequisites section above;
  • debug controls the server's log level. Setting this to true makes the server verbose.

config/db.json contains:

{
    "host":          "localhost",
    "port":          27017,
    "db":            "canary",
    "user":          "user",
    "password":      "password",
    "reconnectTime": 2
}

The options from host to password inclusive specify basic information for DB connection. If no authentication is required, user and password can be omitted.

reconnectTime specifies a time interval in seconds for which the server waits before trying to reconnect when disconnected from the DB.

How to run

As other node.js programs, you can run canary-server with

node server.js -c config/

where the -c option (or --config) specifies a configuration directory the server will use.

Clients tested

The following DAAP clients have been tested with canary-server. If your favorite client is not on the list or does not work with the server, please open a new issue to describe the problem concisely.

Help needed

canary-server is implemented in a very short time. It already works well but needs many improvements that include, but not limited to:

  • support for other DBs, especially MySQL and sqlite; MongoDB is getting popular but there are still many who don't have or are not familiar with it;
  • testing for files with various and sometimes weird meta data; metadata of my files are normalized so not enough samples to push the server's metadata handling.

How to install

Refer to INSTALL.md for an installation guide.

Repository

canary uses git as its repository to publish on github. You can browse the repository through the web, or clone it as follows:

git clone https://github.com/mycoboco/canary.git

If you want to contribute to the project, simply fork it and send me pull requests.

Recent commits are:

and more.

Issue tracker

canary employed github for its issue tracker. If you'd like to file a bug or ask a question, do not hesitate to post a new issue; a self-describing title or a short text to deliver your idea would be enough. Even if issues I have posted are all written in English, nothing keeps you from posting in Korean.

Open issues are:

License

LICENSE.md describes the license imposed on users of canary.