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.

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

The server supports, among other things:

but does not support yet:

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.


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.

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.


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

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:

running canary

How to install

This package does not provide an automated way to build or install the server except using npm because canary-server is intended to runs on top of node.js. If you have node.js in your system,

npm install --legacy-bundling canary

brings the latest version of canary-server and installs it with its all depending packages.

_The --legacy-bundling option is necessary when using npm3 because, without it, dependent modules will be installed at the same nesting level as canary into node_modules._


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

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:


Copyright (C) 2015 by Jun Woong.

This package is a music streaming server and its companion iOS client that run upon DAAP.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Questions or suggestions?

I'd be glad to hear your opinion. Do not hesitate to contact me via email (woong.jun at