annotate plugin/api/alsa/README @ 0:da6937383da8

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