| 1 |
libdssialsacompat 1.0.8a |
| 2 |
======================== |
| 3 |
libdssialsacompat is simply an extraction from and repackaging of |
| 4 |
the code from alsa-lib 1.0.8, necessary to support DSSI on non-ALSA |
| 5 |
systems. It is copyright (c)2005 under the GNU Lesser General |
| 6 |
Public License, version 2.1 or later. See the enclosed file COPYING |
| 7 |
for details. |
| 8 |
|
| 9 |
More information on DSSI can be found at: |
| 10 |
|
| 11 |
http://dssi.sourceforge.net/ |
| 12 |
|
| 13 |
Introduction |
| 14 |
============ |
| 15 |
The DSSI specification makes use of the ALSA snd_seq_event_t |
| 16 |
structure for passing MIDI events. This has the advantage of making |
| 17 |
it immediately familiar to developers familiar with ALSA, but the |
| 18 |
disadvantage of making porting DSSI applications and plugins to |
| 19 |
systems that lack ALSA more difficult. |
| 20 |
|
| 21 |
libdssialsacompat is intended to provide the snd_seq_event_t |
| 22 |
declarations and handling code necessary to compile and use DSSI on |
| 23 |
non-ALSA systems. It aims to allows compiling DSSI code with as |
| 24 |
little change as possible, while not presenting itself in such a way |
| 25 |
as to fool other autoconf-enabled code into thinking a system has |
| 26 |
ALSA. |
| 27 |
|
| 28 |
libdssialsacompat is simply an extraction of the relevant |
| 29 |
snd_seq_event_t declarations, and raw MIDI stream to snd_seq_event_t |
| 30 |
encoder code, from alsa-lib version 1.0.8, packaged into a |
| 31 |
convenient library. |
| 32 |
|
| 33 |
This library does NOT provide any sort of emulation of the ALSA |
| 34 |
audio, MIDI, or sequencer devices. The only part of ALSA that is |
| 35 |
required by the DSSI specification is the snd_seq_event_t definition |
| 36 |
and handling, and that is all libdssialsacompat is intended to |
| 37 |
replace. Other ALSA code should be ported to native facilities. |
| 38 |
|
| 39 |
Installation |
| 40 |
============ |
| 41 |
libdssialsacompat uses GNU autoconf and automake, so installation can |
| 42 |
be a simple as `./configure && make && make install'. See the |
| 43 |
enclosed file INSTALL for more information. |
| 44 |
|
| 45 |
The library itself is installed to <prefix>/lib; for example, on Mac |
| 46 |
OS X, the following files are installed: |
| 47 |
|
| 48 |
<prefix>/lib/libdssialsacompat.0.0.0.dylib |
| 49 |
<prefix>/lib/libdssialsacompat.0.dylib |
| 50 |
<prefix>/lib/libdssialsacompat.a |
| 51 |
<prefix>/lib/libdssialsacompat.dylib |
| 52 |
<prefix>/lib/libdssialsacompat.la |
| 53 |
|
| 54 |
The header files are installed to <prefix>/include/dssi/alsa: |
| 55 |
|
| 56 |
<prefix>/include/dssi/alsa/asoundef.h |
| 57 |
<prefix>/include/dssi/alsa/asoundlib.h |
| 58 |
<prefix>/include/dssi/alsa/seq.h |
| 59 |
<prefix>/include/dssi/alsa/seq_event.h |
| 60 |
<prefix>/include/dssi/alsa/seq_midi_event.h |
| 61 |
<prefix>/include/dssi/alsa/sound/asequencer.h |
| 62 |
|
| 63 |
Note that they are NOT installed to <prefix>/include/alsa, which |
| 64 |
could make them visible to non-libdssialsacompat-aware autoconf |
| 65 |
configure scripts, possibly fooling them into thinking the full ALSA |
| 66 |
was available. |
| 67 |
|
| 68 |
Finally, a pkgconfig configuration file is installed: |
| 69 |
|
| 70 |
<prefix>/lib/pkgconfig/libdssialsacompat.pc |
| 71 |
|
| 72 |
Use |
| 73 |
=== |
| 74 |
At its most basic, compiling with gcc and libdssialsacompat consists |
| 75 |
of adding '-I<prefix>/include/dssi -L<prefix>/lib -ldssialsacompat' |
| 76 |
to your gcc command line. Note that the '-I' directive will cause |
| 77 |
code like to following: |
| 78 |
|
| 79 |
#include <alsa/asoundlib.h> |
| 80 |
#include <alsa/seq_event.h> |
| 81 |
|
| 82 |
to find the libdssialsacompat header files, even though they are not |
| 83 |
installed in the usual location for ALSA headers. |
| 84 |
|
| 85 |
libdssialsacompat is easiest to use with autoconf/automake/pkgconfig- |
| 86 |
enabled code. In which case, editing the configure.in or configure.ac |
| 87 |
file and changing: |
| 88 |
|
| 89 |
PKG_CHECK_MODULES(ALSA, alsa) |
| 90 |
|
| 91 |
to: |
| 92 |
|
| 93 |
PKG_CHECK_MODULES(ALSA, alsa, , [PKG_CHECK_MODULES(ALSA, libdssialsacompat)]) |
| 94 |
|
| 95 |
then doing 'autoreconf', may be all that is needed to get the |
| 96 |
snd_seq_event_t-using code to compile cleanly. Of course, if the |
| 97 |
code uses other ALSA features, libdssialsacompat won't help with |
| 98 |
them.... |
| 99 |
|
| 100 |
DSSI Installation |
| 101 |
================= |
| 102 |
Installation of DSSI itself (at least as recently as 2005/4/6 CVS) |
| 103 |
must be done by hand, which goes something like this (assuming |
| 104 |
you're running OS X 10.3 and want to install to /usr/local): |
| 105 |
|
| 106 |
$ tar xpzf dssi-0.9.tar.gz |
| 107 |
$ cd dssi-0.9 |
| 108 |
$ sudo mkdir -p /usr/local/include |
| 109 |
$ sudo cp dssi/dssi.h /usr/local/include/ |
| 110 |
$ sed s:.PREFIX.:/usr/local: dssi.pc >dssi.pc.new |
| 111 |
$ sudo mkdir -p /usr/local/lib/pkgconfig |
| 112 |
$ sudo mv dssi.pc.new /usr/local/lib/pkgconfig/dssi.pc |
| 113 |
|
| 114 |
(You may stop here if you're not interested in the example plugins.) |
| 115 |
|
| 116 |
$ cd examples |
| 117 |
$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig |
| 118 |
$ export PKG_CONFIG_PATH |
| 119 |
$ make dssi_osc_send |
| 120 |
$ sudo cp -p dssi_osc_send /usr/local/bin |
| 121 |
$ gcc -Wall -fno-common -O2 `pkg-config libdssialsacompat dssi --cflags` \ |
| 122 |
trivial_synth.c -c -o trivial_synth.o |
| 123 |
$ gcc -Wall -fno-common -O2 -c -o message_buffer.o \ |
| 124 |
../message_buffer/message_buffer.c |
| 125 |
$ gcc -bundle -flat_namespace -undefined suppress -o trivial_synth.so \ |
| 126 |
trivial_synth.o message_buffer.o \ |
| 127 |
`pkg-config libdssialsacompat dssi --libs` |
| 128 |
$ sudo mkdir -p /usr/local/lib/dssi |
| 129 |
$ sudo cp -p trivial_synth.so /usr/local/lib/dssi |
| 130 |
|
| 131 |
Building the rest of the DSSI distribution's plugins is left as an |
| 132 |
exercise to the reader. Note that (as of 2005/4/6) jack-dssi-host |
| 133 |
will not build without patching since it uses the ALSA sequencer. |
| 134 |
|
| 135 |
What Works (Or Doesn't) |
| 136 |
======================= |
| 137 |
libdssialsacompat 1.0.8a was tested on Mac OS X 10.3.8, using the |
| 138 |
Apple Developer Tools, Gentoo-installed versions of pkgconfig and |
| 139 |
liblo 0.18, hand-installed GTK+ 1.2 and LADSPA SDK, and JackOSX |
| 140 |
0.6.1. Under this configuration, the following are known to work: |
| 141 |
|
| 142 |
- ghostess (from the 20050411 release, which includes a clumsy but |
| 143 |
working CoreMIDI driver.) ghostess can be found at: |
| 144 |
|
| 145 |
http://home.jps.net/~musound/ |
| 146 |
|
| 147 |
- trivial_synth.so (DSSI 0.9 release) |
| 148 |
|
| 149 |
- fluidsynth-dssi.so and FluidSynth-DSSI_gtk (DSSI 0.9 release, |
| 150 |
using a statically compiled libfluidsynth 1.0.3) |
| 151 |
|
| 152 |
- Xsynth-DSSI (CVS as of 2005/4/11) |
| 153 |
|
| 154 |
- hexter (CVS as of 2005/4/11, note that sys-ex patch editing isn't |
| 155 |
supported on non-ALSA systems) |
| 156 |
|
| 157 |
The following problems are known to exist: |
| 158 |
|
| 159 |
- less_trivial_synth.so (DSSI 0.9) plays at the wrong pitch on |
| 160 |
big-endian systems due the little-endian assumption of the |
| 161 |
typedef union fixp in less_trivial_synth.c (line 69). Otherwise |
| 162 |
works fine. |
| 163 |
|
| 164 |
- I have not tested any of the DSSI 0.9 Qt GUIs, or |
| 165 |
trivial_sampler.so. |
| 166 |
|
| 167 |
- jack-dssi-host (DSSI 0.9) works as an OSC-driven host if you |
| 168 |
comment out all the ALSA seqeuncer code. |
| 169 |
|