Hackathon Gunther Daemon
=========================

HGD is a music system suitable for hackathons, internet cafes, LAN
parties etc. Music is played on one set of speakers and clients queue up
media from their own machines over the network. Because we use MPlayer to play
media, you can send anything MPlayer understands, including video.

HGD was inspired by the LPD hack -- a music system used at OpenBSD
hackathons. We plan to implement similar functionality and extend it.

Current features
----------------

 * Network listener daemon.
 * Player daemon (uses mplayer).
 * Command line client with the ability queue and vote-off tracks.
 * Works on Linux and OpenBSD.

Prerequisites
-------------

To build, you will need:

 * Linux or OpenBSD (possibly others, not tested)
 * Make (either GNU or BSD)
 * GCC or Clang
 * SQLite3 libs and headers (if building servers).
 * OpenSSL libs and headers.
 * LibBSD (linux only) libs and headers.
 * Mplayer (for the server)
 * autoconf (git checkouts only)

And optionally:

 * LibConfig, if you want config file support.
 * TagLib, if you want media tag support in the server.
 * Python-{2.6,2.7}, if you want the scripting backend.

On ubuntu (and debian?) you can do something like:

sudo apt-get install libbsd0 libbsd-dev mplayer python2.7 python2.7-dev	\
	libtagc0 libtagc0-dev libconfig8 libconfig8-dev libsqlite3-0	\
	libsqlite3-dev libssl-dev libssl0.9.8

Building
--------

 1) If you checked out from git, first run:
    ./autogen.sh

 2) Configure the build:
    ./configure

    If you don't want to pollute /usr/local, pass a --prefix=/some/path
    argument.

    Examine the output and install anything missing. Don't forget linux
    packages headers and libraries separately.

 3) Build the components you need:

    * To build everything, type 'make'.
    * To build only the client type 'make client'.
    * To build only the server components 'make server'.

 4) Install:

    * To install everything, type 'make install'.
    * To install in a custom path, type 'make prefix=/home/gunther install'.
    * Other useful install targets are 'install-server', 'install-client'
      and 'install-docs'.

NOTES:

HGD will happily run out of it's build directory.

On MacOS X, you may have to jump through hoops. Others have succeeded using
macports for libconfig and sqlite3 dependencies. You may need to set the
include path and library path to /opt/include and /opt/lib respectively (good
luck).

Quickstart for the Lazy
-----------------------

This is how to configure a HGD server an client:

If you upgraded from a previous version of HGD, i would recommend
removing your state directory and starting afresh, as the database
structure does change from time to time.

If you need a custom state path (ie. not /var/hgd), you can either pass -d to
all server components (make sure they are the same of course), or make a hgd.rc
config file (see the FILES sections in manual pages).

Now you should make user accounts:

 % hgd-admin user-add <username>

You will be asked to type a password twice. Do this for all users.

Then you can run the hgd daemons:

 % hgd-netd
 % hgd-play

Then you can queue tracks:
 % hgdc q <some media file>

Each command has a manual page for detailed usage instructions. Also,
each command has a '-h' option for quick help. 

If you do not want to show the video of media files, 'unset DISPLAY'
before running hgd-playd.

For information on SSL (TLSv1) crypto, see the manual page for
hgd-netd(1).

Please note that SSL support in HGD is only partially implemented at
this time. You may use it for encrypting traffic, but not for server
identity.

History
-------

 * 0.1   - basic functionality.
 * 0.2   - SSL crypto support and user authentication.
 * 0.3   - Config file support.
 * 0.4   - Autoconf, taglib, Python scripting.
 * 0.4.1 - Properly daemonise, log to syslog, honor SIGHUP.

Roadmap
-------

https://github.com/vext01/hgd/issues/milestones

Bugs
----

Inevitable. Please report bugs on github:
https://github.com/vext01/hgd/issues/

Thanks
------

We thank the following people:

 * Yhg1s on #python on freenode for code reviews on Python C API code.

Feedback / Questions
--------------------

Go to #hgd on freenode. If you liked and use hgd, please buy us a beer.
