root/trunk/libffado/README

Revision 961, 10.3 kB (checked in by jwoithe, 16 years ago)

Nitpick: officially MOTU is all capitals.
Make all sections of readme fall within 80 columns.
Minor grammatical corrections.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 FFADO v2.x
2 ==========
3
4 The FFADO project aims to provide a free driver implemenation for FireWire
5 (IEEE1394, iLink) based (semi-) professional audio interfaces. The focus of
6 the project are on audio/music production rather than consumer audio. This
7 means that, although we intend to supported all features at some point,
8 consumer features are considered less important. The most obvious example of
9 a consumer feature is AC3/DTS passthrough support, which is unsupported at
10 the moment.
11
12 This package provides the libffado shared library that provides a unified
13 programming interface to configure and use all supported devices. Currently
14 this library is used by the 'firewire' backends of the jack audio connection
15 kit sound server (jackaudio.org). This backend provides audio and midi support,
16 and is available both in jackd and it's multiprocessor variant jackdmp.
17 (note: At the moment there is no support for ALSA nor for pulseaudio.)
18
19 Access to the device internal configuration (e,g, internal mixer) is exposed
20 using the ffado-dbus-server daemon. This daemon exposes the configurable
21 parameters of all detected devices through DBUS. The ffadomixer application in
22 support/mixer presents a GUI to control these parameters (only for officially
23 supported devices).
24
25 Features
26 --------
27 * 24-bit audio input/output (unlimited number of channels)
28 * supports for all samplerates a device supports
29 * MIDI input/output (unlimited number of channels)
30 * Support for S/PDIF and ADAT/SMUX I/O
31 * Internal mixer and device control support for all officially supported
32   devices (NOTE: no support for internal DSP)
33 * Support for device aggregation (limited to devices on the same bus)
34
35 Device Support
36 --------------
37
38 The devices officially supported are:
39 * ESI Quatafire 610
40 * Terratec Producer Phase 88
41 * Focusrite Saffire (original/white)
42 * Focusrite Saffire PRO10
43 * Focusrite Saffire PRO26
44 * ECHO AudioFire2
45 * Mackie Onyx Mixer FireWire expansion
46
47 The 'officially supported' label is only given to devices that fullfil the
48 following:
49 * at least one of the developers has the device
50 * the vendor provides development support (access to information)
51 * the device works
52
53 Through reverse-engineering the following devices will also work:
54 * MOTU traveller
55 * MOTU 828mkII
56 Note: the support for these devices is based on a significant reverse
57 engineering effort. This means that the developers had no support from the
58 device vendor, and this of course limits the extent to which problems can
59 be solved. You have been warned. Please do not buy devices for which support
60 is based upon reverse engineering, nor from vendors that are Linux-hostile
61 (e.g. MOTU). Value the support that some vendors provide and buy their
62 stuff. Check ffado.org for details. It can't be said enough: currently it is
63 extremely unwise to buy a MOTU device if you intend to use Linux.
64
65 The driver is written to provide generic support for all devices it might be
66 able to handle. This means that most devices based on the BridgeCo BeBoB or
67 the ECHO FireWorks platform will work, at least to a certain extent.
68
69 Devices that have been reported to (partially) work with the generic support:
70 * Presonus FireBox
71 * Presonus FirePod / FP10
72 * Focusrite Saffire LE
73 * ECHO AudioFire8
74 * ECHO AudioFire12
75
76 Usupported devices:
77 * Presonus FireStation
78 * Presonus FireStudio (all variants)
79 * TC Konnekt (all variants)
80 * Alesis devices
81 * Metric Halo devices
82 * RME Firewire devices
83
84 We constantly try to persuade vendors to help us extend our device support.
85
86 Dependencies
87 ------------
88
89 To build libffado you need several libraries. For all libraries a
90 version is provided which is a 'known good' version.  The first few
91 libraries it seems it is not necessary that the version must
92 match. The chances that it works also with an older versions are good:
93
94 alsa        (>= 1.0.0)
95 libxml++2   (>= 2.13.0)
96
97 These libraries here should be at least the version listed:
98
99 libraw1394  (>= 1.3.0),  http://www.linux1394.org
100 libiec61883 (>= 1.1.0),  http://www.linux1394.org
101 libavc1394  (>= 0.5.3),  http://sourceforge.net/projects/libavc1394
102 dbus-1      (>= 1.0),    http://dbus.freedesktop.org
103
104 Currently only the jackd audio server is supported.
105
106 jackd (>= 0.107.6), http://jackaudio.org
107
108 Optionally, but recommended is that you install qjackctl:
109
110 qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl
111
112 How to build
113 ------------
114
115 Building the code is straight forward if PKG_CONFIG_PATH, LD_LIBRARY_PATH
116 and INCLUDE_PATH is correctly set up.
117
118 E.g on my system I have installed libraw1394, libiec61883 and libavc1394
119 under /usr/local:
120
121 $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
122 $ export LD_LIBRARY_PATH=/usr/local/lib
123
124 If you want to build the release version you can do following:
125
126 $ scons
127 $ scons install
128
129 If you want some debug information (because something seems not
130 to work correctly) you can try to do following:
131
132 $ scons DEBUG=yes
133 $ scons install
134
135 NOTE: In order to build jackd with ffado support, you have
136 to install libffado before you build jackd. The backend to use in jackd is
137 firewire.
138
139 DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
140 if it is not on by default. If device support for a specific device
141 is not turned on by default by the developers, it means that it is not
142 ready yet. Most of the time it is placeholder code for future devices.
143
144 Running jackd
145 -------------
146
147 The easiest way to run this is using qjackctl. There are only minor
148 differences with the other backends, however you should change some
149 of the default values:
150 - The 'interface' field should contain only a number. This number is
151   the port number of the IEEE1394 host controller the audio device
152   is connected to. For most people this will be '0', but if you have
153   multiple controllers, you have to change this number.
154 - The 'Input channels' and 'Output channels' fields indicate if the
155   backend should provide capture and/or playback channels. If you set
156   these to 0, no channels are created. In order to enable capture and/or
157   playback, you have to set them to a nonzero value.
158 - It is recommended to change the 'periods/buffer' field to 3, especially
159   if you use low period sizes (=< 128)
160 - It is recommended to raise the RT priority to 70.
161
162 In order to get it running from the command line, you need to provide some
163 arguments to jackd.
164
165 Run
166
167 $ jackd -d firewire --help
168
169 to see the backend options. You can easily figure out how to set them using
170 the remarks given above (for qjackctl).
171
172 For the other aspects of jackd usage, consult the jackd documentation.
173
174 Here is a sample session (without realtime support enabled):
175
176 [wagi@halo ~]$ jackd -d firewire
177 jackd 0.102.9
178 Copyright 2001-2005 Paul Davis and others.
179 jackd comes with ABSOLUTELY NO WARRANTY
180 This is free software, and you are welcome to redistribute it
181 under certain conditions; see the file COPYING for details
182
183 JACK compiled with System V SHM support.
184 loading driver ..
185 Freebob using Firewire port 0, node -1
186 libiec61883 warning: Established connection on channel 0.
187 You may need to manually set the channel on the receiving node.
188 libiec61883 warning: Established connection on channel 1.
189 You may need to manually set the channel on the transmitting node.
190
191 (Note: you can safely ignore the libiec61883 warnings, they are normal.)
192
193 In case of problems
194 -------------------
195
196 Under the tests directory there is a test program. You should first
197 try to run this.
198
199 If you don't have installed libffado then you can adapt your
200 LD_LIBRARY_PATH environment variable to
201
202 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../src/.libs
203
204 Then you can try running the program without having to install it.
205
206 With the release version you see something like this:
207
208 wagi@cruxam:~/src/libffado/tests$ ./test-ffado discover
209 verbose level = 0
210 Using ffado library version: libffado 0.9.0
211
212   port = 2, devices_on_bus = 1
213   get info for device = 0, node = 1
214 Direction:              0 (capture)
215
216 Connection Info
217 ===============
218
219 Number of connections:  1
220
221   Connection  0
222   -------------
223     [ 0] Id:         0
224     [ 0] Port:       2
225     [ 0] Node:       1
226     [ 0] Plug:       0
227     [ 0] Dimension:  7
228     [ 0] Samplerate: 44100
229     [ 0] IsoChannel: -1
230     [ 0] IsMaster:   0
231     [ 0] Number of stream infos: 8
232
233     StreamId  Position Location Format Type DPort Name
234     --------------------------------------------------
235     [ 0]:[ 0] 0x01     0x01     0x06   0x02 0x00  MicIn 1+2 left
236     [ 0]:[ 1] 0x04     0x02     0x06   0x02 0x00  MicIn 1+2 right
237     [ 0]:[ 2] 0x02     0x01     0x06   0x03 0x00  LineIn 1+2 left
238     [ 0]:[ 3] 0x05     0x02     0x06   0x03 0x00  LineIn 1+2 right
239     [ 0]:[ 4] 0x00     0x01     0x06   0x04 0x00  SpdifIn 1 left
240     [ 0]:[ 5] 0x03     0x02     0x06   0x04 0x00  SpdifIn 1 right
241     [ 0]:[ 6] 0x06     0x01     0x0d   0x0a 0x00  MidiIn2
242     [ 0]:[ 7] 0x06     0x02     0x0d   0x0a 0x00  MidiIn2
243
244
245 Direction:              1 (playback)
246
247 Connection Info
248 ===============
249
250 Number of connections:  1
251
252   Connection  0
253   -------------
254     [ 0] Id:         0
255     [ 0] Port:       2
256     [ 0] Node:       1
257     [ 0] Plug:       0
258     [ 0] Dimension:  11
259     [ 0] Samplerate: 44100
260     [ 0] IsoChannel: -1
261     [ 0] IsMaster:   0
262     [ 0] Number of stream infos: 12
263
264     StreamId  Position Location Format Type DPort Name
265     --------------------------------------------------
266     [ 0]:[ 0] 0x01     0x01     0x06   0x03 0x00  MultiChannel 7.1 Front left
267     [ 0]:[ 1] 0x06     0x02     0x06   0x03 0x00  MultiChannel 7.1 Front right
268     [ 0]:[ 2] 0x02     0x03     0x06   0x03 0x00  MultiChannel 7.1 Center
269     [ 0]:[ 3] 0x07     0x04     0x06   0x03 0x00  MultiChannel 7.1 Subwoofer
270     [ 0]:[ 4] 0x03     0x05     0x06   0x03 0x00  MultiChannel 7.1 Rear left
271     [ 0]:[ 5] 0x08     0x06     0x06   0x03 0x00  MultiChannel 7.1 Rear right
272     [ 0]:[ 6] 0x04     0x07     0x06   0x03 0x00  MultiChannel 7.1 Surround left
273     [ 0]:[ 7] 0x09     0x08     0x06   0x03 0x00  MultiChannel 7.1 Surround right
274     [ 0]:[ 8] 0x00     0x01     0x06   0x04 0x00  SpdifOut 1 left
275     [ 0]:[ 9] 0x05     0x02     0x06   0x04 0x00  SpdifOut 1 right
276     [ 0]:[10] 0x0a     0x01     0x0d   0x0a 0x00  MidiOut2
277     [ 0]:[11] 0x0a     0x02     0x0d   0x0a 0x00  MidiOut2
278
279
280 If you don't get this, check if you have multiple host controllers, and
281 use the -p parameter to specify them. If you get any error messages, the
282 best way to help us figure out what the problem might be is to build the
283 debug version (scons ENABLE_DEBUG=1). You can then rerun the test
284 application (with -v5) and send us its output.
285
Note: See TracBrowser for help on using the browser.