-
Notifications
You must be signed in to change notification settings - Fork 331
/
Audio.shtml
220 lines (176 loc) · 8.69 KB
/
Audio.shtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">
<title>JMRI: Audio</title><!-- Style -->
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="/css/default.css"
media="screen">
<link rel="stylesheet" type="text/css" href="/css/print.css"
media="print">
<link rel="icon" href="/images/jmri.ico" type="image/png">
<link rel="home" title="Home" href="/"><!-- /Style -->
</head>
<body>
<!--#include virtual="/Header" -->
<div id="mBody">
<!--#include virtual="Sidebar" -->
<div id="mainContent">
<h1>JMRI: Audio Documentation</h1>JMRI Audio objects hold
information about sounds that can be played-back by the
computer.
<h2>The Audio Table</h2>The <a href=
"../../package/jmri/jmrit/beantable/AudioTable.shtml">Audio
Table</a> lets you see what Audio objects have been defined,
and what information they currently contain.<br>
<a href=
"../../package/jmri/jmrit/beantable/AudioTable.jpg"><img src=
"../../package/jmri/jmrit/beantable/AudioTable.jpg" height=
"178" width="420"></a>
<h4>Audio Table controls</h4>
<p>Below the Audio Table are two buttons, named "Add
Source..." and "Add Buffer..." to <a href=
"../../package/jmri/jmrit/beantable/AudioAddEdit.shtml">create
new Audio objects</a>.</p>
<h2>Audio Objects</h2>The JMRI audio framework consists of
three distinct types of object:
<ul>
<li>Audio Listeners</li>
<li>Audio Buffers</li>
<li>Audio Sources</li>
</ul>
<h4>Audio Listener</h4>The Audio Listener defines where the
person hearing the sounds is located.
<p><a href="images/EditAudioListener.png"><img src=
"images/EditAudioListener.png" height="187" width=
"122"></a></p>
<p>The defined listener position is then used to calculate
the actual pan and gain of each audio source when played
back.</p>
<p>The orientation settings define the co-ordinate system in
use. The default values transpose to:</p>
<ul>
<li>x - left-to-right (-ve to +ve)</li>
<li>y - front-to-back (-ve to +ve)</li>
<li>z - down-to-up (-ve to +ve)</li>
</ul>With the default position, 'y' values would be positive,
measured from the front-edge of the layout and 'x' values to
be negative to the left of the layout centre-line and
positive to the right of the layout centre-line. Positive 'z'
values would be measured from layout level upwards.
<p>Unless modified by changing 'Meters per unit', all
distance and velocity units are measured in real-world
meters.</p>
<p>Only one Audio Listener can exist, and it is already
present in the Audio Table where it may be configured by
clicking its <b>Edit</b> button.</p>
<h4>Audio Buffers</h4>An Audio Buffer holds the actual sound
sample data.
<p><a href="images/AddEditAudioBuffer.png"><img src=
"images/AddEditAudioBuffer.png" height="93" width=
"176"></a></p>
<p>To load an Audio Buffer with sound data, click the
'Browse...' button and select the appropriate '.wav'
file.</p>
<p>One Audio Buffer object can be used by many Audio
Sources.</p>
<h4>Audio Sources</h4>An Audio Source controls the playback
of sound sample data and controls the position.
<p><a href="images/AddEditAudioSource.png"><img src=
"images/AddEditAudioSource.png" height="241" width=
"123"></a></p>
<p>To actually play a sound, an Audio Source must be linked
to an existing Audio Buffer - choose one from the drop-down
list. Buffers are allowed to be shared between Audio Sources,
in which case they will be played back independently.</p>
<p>As with the Audio Listener, an Audio Source should be
positioned in 3d-space. If required to 'move' whilst playing,
set the velocity in x, y and z directions. This will move the
position of the Audio Source in the direction and speed
specified by the velocity vector at the defined rate while
the Audio Source is playing.</p>
<p><em>Example:</em> An 'x' value of 2 will move the Audio
Source 2 units (meters) per second towards the right whilst
playing.</p>
<p><em>Note:</em> The Audio Source position is only relevant
when bound to a mono buffer - those holding multi-channel
sounds (i.e. stereo) will not be affected by changes in
position and played as-is.</p>
<p>If it is necessary to turn-down the volume of a specific
Audio Source, this can be achieved by changing the 'Gain'
setting. Similarly, the pitch can be modified by changing the
'Pitch' parameter.</p>
<p>Normal behavior is for the volume of an Audio Source to be
altered by the distance from the Audio Listener. This
behavior can be modified by altering the Reference Distance
and Maximum Distance settings. The Reference Distance
determines the distance at which the volume will start to
decrease - at distances smaller than the reference distance,
the volume of the Audio Source will be as defined by the gain
setting. The Maximum Distance determines the distance at
which the volume is zero. Roll-off Factor determines the
rate-of-change of the gain with respect to distance - larger
values denote a faster rate-of-change.</p>
<p>Finally, the fade-in and fade-out times of the Audio
Source can be defined - these are specified in milli-seconds.
Fading-in and out of an Audio Source is achieved by using the
fadeIn and fadeOut methods of the Audio Source; play, stop
and pause methods do not utilize fade times.</p>
<p>Unless modified by changing the 'Meters per unit'
parameter of the Audio Listener, all distance and velocity
units are measured in real-world meters.</p>
<h3>Using Audio Objects with Logix</h3>A Logix can be defined
to control audio objects. Currently, it is possible to play,
pause, stop, rewind, fade-in and fade-out audio sources.
<h3>Using Audio Objects with Scripts</h3>You can directly
manipulate Audio Objects with scripts. There's an <a href=
"http://jmri.org/jython/AudioExample.py">example script</a>
in the distribution, along with documentation for the
<a href="http://jmri.org/JavaDoc/doc/jmri/jmrit/audio/AudioBuffer.html">
AudioBuffer</a>, <a href=
"http://jmri.org/JavaDoc/doc/jmri/jmrit/audio/AudioSource.html">
AudioSource</a> and <a href=
"http://jmri.org/JavaDoc/doc/jmri/jmrit/audio/AudioListener.html">
AudioListener</a> classes that control the audio processing.
<h2>Playing Audio</h2>The JMRI audio framework makes use of
either of the following audio libraries:
<ul>
<li><a href=
"http://www.oracle.com/technetwork/java/index-139508.html">JavaSound</a>
- for basic audio functions (limited to stereo)<br>
JavaSound is normally available with a Sun Microsystems
Java Runtime Environment; other vendors, such as OpenJDK,
do not include JavaSound.</li>
<li><a href="http://www.openal.org/">OpenAL</a> - for
full-featured audio functions (including support for up-to
7.1 surround)<br>
OpenAL may already be included with your operating
system:</li>
</ul>
<h4>Mac OS X</h4>Those versions of Mac OS X that are suitable
for JMRI already have a suitable version of OpenAL installed.
<h4>MS Windows</h4>By default, OpenAL will require installing
on your system. Certain sound cards, notably those
manufactured by Creative Labs and NVidia, will normally
already come with suitable OpenAL drivers. If OpenAL is not
installed, <a href="http://www.openal.org/downloads/">it
should be downloaded</a> from OpenAL.org and then installed
on your system.
<h4>Linux</h4>Depending on the provider of your Linux
distribution, OpenAL might already be included in the default
package. If not, the 'libopenal-dev' package should be
installed using the package manager on your system. For
Debian-based distributions, this will typically be achieved
by the command:
<pre>
$ sudo apt-get install libopenal-dev
</pre>
<p>For Ubuntu, the 'Universe' repository should be enabled.
</p><!--#include virtual="/Footer" -->
</div><!-- closes #mainContent-->
</div><!-- closes #mBody-->
</body>
</html>