Document '-r' switch and switch README to proper markdown.
[aseqjoy.git] / README
1 aseqjoy - a simple joystick to ALSA MIDI sequencer converter
2 ============================================================
3
4 Copyright 2003-2016 by Alexander K├Ânig - alex@lisas.de
5
6 License: GNU General Public License Version 2 or (at your option) any later 
7 version - for details please refer to the file [COPYING](./COPYING) included 
8 with the aseqjoy source code.
9
10 What it does: Each axis of the joystick device is mapped to a specific MIDI 
11 controller. Moving the joystick along an axis will cause aseqjoy to emit
12 MIDI controller messages via ALSA's sequencer API. The value of the controller
13 message represents the joystick's position along the axis (eg 'left' -> 0, 
14 'middle' -> 63, 'right' -> 127). Note that you can run aseqjoy with the '-r'
15 commandline switch to use fine MIDI control change messages instead (with 14
16 bit resolution).
17
18 aseqjoy uses the ALSA sequencer API to emit the MIDI events. Therefor it
19 creates and output port named after joystick used. You can then use for example
20 aconnect (from alsa-utils), QjackCtl or Robert Ham's alsa-patch-bay to connect
21 an aseqjoy instance to an input port of your choice. 
22
23 Requirements
24 ------------
25
26 * Current Linux system with joystick input drivers and ALSA sound system 
27   properly configured.
28
29 Links
30 -----
31
32 * [aseqjoy homepage](https://terminatorx.org/addons/)
33 * [ALSA homepage](http://www.alsa-project.org)
34 * [Joystick utils](http://atrey.karlin.mff.cuni.cz/~vojtech/joystick/)
35 * [QjackCtl](http://qjackctl.sourceforge.net/)
36 * [ALSA-patch-bay](http://pkl.net/~node/alsa-patch-bay.html)
37
38 Howto
39 -----
40
41 In some cases the joystick may not utilize the full range of available 
42 controller values - in this case you should use "jscal" from the joystick
43 package (most distributions feature this package) to calibrate your joystick 
44 before running aseqjoy. Note: Analog PC joysticks are no high-precision 
45 devices - so even after calibrating the device you might not always be able
46 to reach "0" or "127" controller values - depending on the joystick you
47 use.
48
49 Start aseqjoy - if you have a working joystick (Nr. 0 - use the -d switch to
50 select other joysticks) aseqjoy will detect that and map each axis of that 
51 joystick to a controller from 10 on upwards:
52
53 * Axis -> Controller 
54 * 0 -> 10
55 * 1 -> 11
56 * 2 -> 12
57
58 From now on aseqjoy emits events over the "Joystick0" output port. To make use
59 of these events in another application use for example the alsa-patch-bay
60 to connect that output port to another application's input sequencer port
61 (for example the "terminatorX" input port for terminatorX). After you've bound
62 the controllers to certain controls you should see how moving the joystick
63 affects the corresponding control.
64
65 Have Fun,
66 Alex