README

XMMS2 client library for GNU guile
----------------------------------

This is  a native implementation  of the control  protocol for the  XMMS2 audio
playback server application. The library  is written in Scheme and specifically
targets the GNU Guile implementation of the language.

The  actual command  set for  the protocol  is generated  from XMMS2's  ipc.xml
definition file. The code in ‘scheme/constants’ and in ‘scheme/ipc’ is directly
generated from said definition.


Quickstart
----------

% make ipc XMMS2_IPC_XML="$HOME"/src/xmms2/src/ipc.xml
% make compile
% ./tools/guile-in-here ./examples/cli play

(This assumes you followed the “Examples” section below.)


Documentation
-------------

The ‘doc’ subdirectory  contains all documentation for the  project, except for
this  README. The  main documentation  consists of  two documents:  One is  the
library's reference manual. Much of the  reference manual is generated from the
Scheme source code  using the documentation strings attached to  the symbols of
the public APIs of the different  modules, using some of GNU Guile's introspec-
tion features.

The  second document,  is a  set notes  about the  protocol that  XMMS2 servers
speak, as implemented by the library. These were taken during development. They
are neither complete nor does the document  claim to be any sort of an authori-
tative source of information about the protocol. And it was never proof-read by
anyone  who knows  the protocol,  so bugs  are likely.  Hence the  subtitle “An
Unreliable Hacker’s Guide”.

Building the documentation requires ‘pandoc’ to be installed on the build host,
along with its dependencies to generate ‘html’, ‘roff’ (manual pages) and ‘pdf’
(think “LaTeX”) documents. Calling ‘make doc’ from the project's root directory
will then build the two main documents in those three formats.


Dependencies
------------

The library requires the use of an XMMS2 snapshot (0.8DrO_o-947-g3bd868a at the
time of writing), as well as GNU  Guile 2.0. The documentation inside the ‘doc’
sub-directory is generated from markdown  sources to their target formats using
pandoc. Generating  PDF versions  of the documentation  will require  a working
LaTeX installation.

Moreover, running  the test-suite  requires the ‘scm-test-tap’  as well  as the
‘test-dispatch’ packages from:

    https://github.com/ft/scm-test-tap
    https://github.com/ft/test-dispatch


Installation
------------

% make ipc XMMS2_IPC_XML="$HOME"/src/xmms2/src/ipc.xml
% make doc
% make compile
% make test
(…and as root…)
# ./install


Examples
--------

The ‘examples’ sub-directory  contains a couple of programs  using the library,
that were and are written as experiments  to test the library against an actual
XMMS2 server.

Because they  are mainly used during  development, they do not  necessarily use
the most elegant solution to a  given problem, but rather something that worked
at the time. This may improve in the future.

Also note,  that because of  their development-aiding purpose, the  examples do
not connect the  default XMMS2 server socket,  but instead use a  version of it
that  is piped  through socat.  In order  to get  such a  socat session  up and
running, use the following command in a separate terminal:

  % socat -t100 -x -v \
      UNIX-LISTEN:/tmp/xmms-ipc-"$USER".socat,mode=700,reuseaddr \
      fork \
      UNIX-CONNECT:/tmp/xmms-ipc-"$USER"

Note that piping through socat significantly impacts performance.