Chris@0: libdssialsacompat 1.0.8a
Chris@0: ========================
Chris@0: libdssialsacompat is simply an extraction from and repackaging of
Chris@0: the code from alsa-lib 1.0.8, necessary to support DSSI on non-ALSA
Chris@0: systems.  It is copyright (c)2005 under the GNU Lesser General
Chris@0: Public License, version 2.1 or later.  See the enclosed file COPYING
Chris@0: for details.
Chris@0: 
Chris@0: More information on DSSI can be found at:
Chris@0: 
Chris@0:   http://dssi.sourceforge.net/
Chris@0: 
Chris@0: Introduction
Chris@0: ============
Chris@0: The DSSI specification makes use of the ALSA snd_seq_event_t
Chris@0: structure for passing MIDI events.  This has the advantage of making
Chris@0: it immediately familiar to developers familiar with ALSA, but the
Chris@0: disadvantage of making porting DSSI applications and plugins to
Chris@0: systems that lack ALSA more difficult.
Chris@0: 
Chris@0: libdssialsacompat is intended to provide the snd_seq_event_t
Chris@0: declarations and handling code necessary to compile and use DSSI on
Chris@0: non-ALSA systems.  It aims to allows compiling DSSI code with as
Chris@0: little change as possible, while not presenting itself in such a way
Chris@0: as to fool other autoconf-enabled code into thinking a system has
Chris@0: ALSA.
Chris@0: 
Chris@0: libdssialsacompat is simply an extraction of the relevant
Chris@0: snd_seq_event_t declarations, and raw MIDI stream to snd_seq_event_t
Chris@0: encoder code, from alsa-lib version 1.0.8, packaged into a
Chris@0: convenient library.
Chris@0: 
Chris@0: This library does NOT provide any sort of emulation of the ALSA
Chris@0: audio, MIDI, or sequencer devices.  The only part of ALSA that is
Chris@0: required by the DSSI specification is the snd_seq_event_t definition
Chris@0: and handling, and that is all libdssialsacompat is intended to
Chris@0: replace.  Other ALSA code should be ported to native facilities.
Chris@0: 
Chris@0: Installation
Chris@0: ============
Chris@0: libdssialsacompat uses GNU autoconf and automake, so installation can
Chris@0: be a simple as `./configure && make && make install'.  See the
Chris@0: enclosed file INSTALL for more information.
Chris@0: 
Chris@0: The library itself is installed to <prefix>/lib; for example, on Mac
Chris@0: OS X, the following files are installed:
Chris@0: 
Chris@0:     <prefix>/lib/libdssialsacompat.0.0.0.dylib
Chris@0:     <prefix>/lib/libdssialsacompat.0.dylib
Chris@0:     <prefix>/lib/libdssialsacompat.a
Chris@0:     <prefix>/lib/libdssialsacompat.dylib
Chris@0:     <prefix>/lib/libdssialsacompat.la
Chris@0: 
Chris@0: The header files are installed to <prefix>/include/dssi/alsa:
Chris@0: 
Chris@0:     <prefix>/include/dssi/alsa/asoundef.h
Chris@0:     <prefix>/include/dssi/alsa/asoundlib.h
Chris@0:     <prefix>/include/dssi/alsa/seq.h
Chris@0:     <prefix>/include/dssi/alsa/seq_event.h
Chris@0:     <prefix>/include/dssi/alsa/seq_midi_event.h
Chris@0:     <prefix>/include/dssi/alsa/sound/asequencer.h
Chris@0: 
Chris@0: Note that they are NOT installed to <prefix>/include/alsa, which
Chris@0: could make them visible to non-libdssialsacompat-aware autoconf
Chris@0: configure scripts, possibly fooling them into thinking the full ALSA
Chris@0: was available.
Chris@0: 
Chris@0: Finally, a pkgconfig configuration file is installed:
Chris@0: 
Chris@0:     <prefix>/lib/pkgconfig/libdssialsacompat.pc
Chris@0: 
Chris@0: Use
Chris@0: ===
Chris@0: At its most basic, compiling with gcc and libdssialsacompat consists
Chris@0: of adding '-I<prefix>/include/dssi -L<prefix>/lib -ldssialsacompat'
Chris@0: to your gcc command line.  Note that the '-I' directive will cause
Chris@0: code like to following:
Chris@0: 
Chris@0:     #include <alsa/asoundlib.h>
Chris@0:     #include <alsa/seq_event.h>
Chris@0: 
Chris@0: to find the libdssialsacompat header files, even though they are not
Chris@0: installed in the usual location for ALSA headers.
Chris@0: 
Chris@0: libdssialsacompat is easiest to use with autoconf/automake/pkgconfig-
Chris@0: enabled code.  In which case, editing the configure.in or configure.ac
Chris@0: file and changing:
Chris@0: 
Chris@0:     PKG_CHECK_MODULES(ALSA, alsa)
Chris@0: 
Chris@0: to:
Chris@0: 
Chris@0:     PKG_CHECK_MODULES(ALSA, alsa, , [PKG_CHECK_MODULES(ALSA, libdssialsacompat)])
Chris@0: 
Chris@0: then doing 'autoreconf', may be all that is needed to get the
Chris@0: snd_seq_event_t-using code to compile cleanly.  Of course, if the
Chris@0: code uses other ALSA features, libdssialsacompat won't help with
Chris@0: them....
Chris@0: 
Chris@0: DSSI Installation
Chris@0: =================
Chris@0: Installation of DSSI itself (at least as recently as 2005/4/6 CVS)
Chris@0: must be done by hand, which goes something like this (assuming
Chris@0: you're running OS X 10.3 and want to install to /usr/local):
Chris@0: 
Chris@0: $ tar xpzf dssi-0.9.tar.gz
Chris@0: $ cd dssi-0.9
Chris@0: $ sudo mkdir -p /usr/local/include
Chris@0: $ sudo cp dssi/dssi.h /usr/local/include/
Chris@0: $ sed s:.PREFIX.:/usr/local: dssi.pc >dssi.pc.new
Chris@0: $ sudo mkdir -p /usr/local/lib/pkgconfig
Chris@0: $ sudo mv dssi.pc.new /usr/local/lib/pkgconfig/dssi.pc
Chris@0: 
Chris@0: (You may stop here if you're not interested in the example plugins.)
Chris@0: 
Chris@0: $ cd examples
Chris@0: $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
Chris@0: $ export PKG_CONFIG_PATH
Chris@0: $ make dssi_osc_send
Chris@0: $ sudo cp -p dssi_osc_send /usr/local/bin
Chris@0: $ gcc -Wall -fno-common -O2 `pkg-config libdssialsacompat dssi --cflags` \
Chris@0:     trivial_synth.c -c -o trivial_synth.o
Chris@0: $ gcc -Wall -fno-common -O2 -c -o message_buffer.o \
Chris@0:     ../message_buffer/message_buffer.c
Chris@0: $ gcc -bundle -flat_namespace -undefined suppress -o trivial_synth.so \
Chris@0:     trivial_synth.o message_buffer.o \
Chris@0:     `pkg-config libdssialsacompat dssi --libs`
Chris@0: $ sudo mkdir -p /usr/local/lib/dssi
Chris@0: $ sudo cp -p trivial_synth.so /usr/local/lib/dssi
Chris@0: 
Chris@0: Building the rest of the DSSI distribution's plugins is left as an
Chris@0: exercise to the reader.  Note that (as of 2005/4/6) jack-dssi-host
Chris@0: will not build without patching since it uses the ALSA sequencer.
Chris@0: 
Chris@0: What Works (Or Doesn't)
Chris@0: =======================
Chris@0: libdssialsacompat 1.0.8a was tested on Mac OS X 10.3.8, using the
Chris@0: Apple Developer Tools, Gentoo-installed versions of pkgconfig and
Chris@0: liblo 0.18, hand-installed GTK+ 1.2 and LADSPA SDK, and JackOSX
Chris@0: 0.6.1.  Under this configuration, the following are known to work:
Chris@0: 
Chris@0: - ghostess (from the 20050411 release, which includes a clumsy but
Chris@0:     working CoreMIDI driver.)  ghostess can be found at:
Chris@0: 
Chris@0:     http://home.jps.net/~musound/
Chris@0: 
Chris@0: - trivial_synth.so (DSSI 0.9 release)
Chris@0: 
Chris@0: - fluidsynth-dssi.so and FluidSynth-DSSI_gtk (DSSI 0.9 release,
Chris@0:     using a statically compiled libfluidsynth 1.0.3)
Chris@0: 
Chris@0: - Xsynth-DSSI (CVS as of 2005/4/11)
Chris@0: 
Chris@0: - hexter (CVS as of 2005/4/11, note that sys-ex patch editing isn't
Chris@0:     supported on non-ALSA systems)
Chris@0: 
Chris@0: The following problems are known to exist:
Chris@0: 
Chris@0: - less_trivial_synth.so (DSSI 0.9) plays at the wrong pitch on
Chris@0:     big-endian systems due the little-endian assumption of the
Chris@0:     typedef union fixp in less_trivial_synth.c (line 69).  Otherwise
Chris@0:     works fine.
Chris@0: 
Chris@0: - I have not tested any of the DSSI 0.9 Qt GUIs, or
Chris@0:     trivial_sampler.so.
Chris@0: 
Chris@0: - jack-dssi-host (DSSI 0.9) works as an OSC-driven host if you
Chris@0:     comment out all the ALSA seqeuncer code.
Chris@0: