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.