/
README
224 lines (170 loc) · 7.4 KB
/
README
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
221
222
223
224
################################################################################
The MusA (Musical Analyser) application aims to draw an image
illustrating played tones, their timbres, etc.
in the given audio stream (file, microphone, ...),
see Overview section for details.
Copyright (C) 2016--2017 Lukáš Ondráček <ondracek.lukas@gmail.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3
as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
################################################################################
Overview
--------
The application opens an audio file
or reads data from an input device (e.g. microphone).
It draws spectrum of the sound
as two dimensional image (with time and frequency axes).
Frequency axis uses logarithmic (tone) scale to preserve constant distances
between neighbouring semitones.
The scale consists of lines of three types, in descending brightness:
* C tones,
* other tones without flats/sharps (white keys on piano),
* tones with flats/sharps (black keys on piano).
By default, spectrum contains all harmonics of played tones
(fundamental frequency and overtones).
Overtones can be partially filtered out,
but this feature is currently under development
and it may not work as expected.
The application uses Helmholtz pitch notation (..., C1, C, c, c1, c2, ...),
instead of scientific pitch notation (..., C1, C2, C3, C4, C5, ...);
concert pitch is thus denoted by a1.
In addition, German key notation is used
replacing sharp by -is suffix and flat by -es suffix
(c, cis/des, d, dis/es, e, f, fis/ges, g, gis/hes, h);
for clarity, B tone name is not used at all.
Dependencies and compilation
----------------------------
Run-time dependencies: OpenGL, Freeglut 3.0, ffmpeg, PortAudio
(pulseaudio-alsa plug-in may be needed on Linux with PulseAudio).
Additional compile-time dependencies: Perl5, GNU make.
To compile the application on Linux just use 'make' command
after satisfying the dependencies.
To cross-compile it on Linux for Windows use 'make arch=win32'.
Command-line arguments
----------------------
musa -h | -? ...prints help
musa -r ...prints this README
musa -c ...prints COPYING
musa [OPTIONS] [ FILENAME | -d[FREQUENCY] ]
...runs the application opening given file
or input device (with specified frequency or not).
OPTIONS are
--OPTION ...activates boolean OPTION
--noOPTION ...deactivates boolean OPTION
--OPTION=VALUE ...sets non-boolean OPTION to VALUE
You can find the list of options below.
Keyboard control
----------------
The application is controlled by keyboard only.
You can use integrated command line
(all commands starts with : character)
or directly several mapped keys,
some of them may be preceded by a numerical argument N (defaults to 1).
: ...open the command line
j / k ...decrease/increase lowest shown tone by N semitones
J / K ...decrease/increase lowest shown tone by N octaves
u / i ...decrease/increase highest shown tone by N semitones
U / I ...decrease/increase highest shown tone by N octaves
g / t ...decrease/increase gain by N dB
G ...toggle dynamic gain
v / b ...decrease/increase signal to noise ratio by N dB
o ...open file
O ...open input device
space ...play/pause
h / l ...seek backward/forward by N seconds
left / right ...seek backward/forward by 5 seconds
down / up ...seek backward/forward by 1 minute
q ...quit the application
The following mapping will be changed in future versions:
w ...toggle overtone filtering
z / a ...decrease/increase overtoneThreshold by 10*N %
x / s ...decrease/increase overtoneRatio by 10*N %
c / d ...decrease/increase overtoneAddition by 10*N %
Application commands
--------------------
:set
...print values of all options
:set OPTION?
...print value of OPTION
:set OPTION
...print value of non-boolean OPTION
...activate boolean OPTION
:set noOPTION
...deactivate boolean OPTION
:set OPTION=VALUE
...set value of non-boolean OPTION (VALUE is without unit)
:open PATH / :o PATH
...open given audio file
:opendevice [FREQUENCY]
...open input device, possibly with the specified sample rate
:close / :c
...close currently open source without closing the application
:quit / :q
...quit the application
:pause
...pauses playback
:play
...resumes playback
:seekto SECONDS
...seeks to the given position in a file
:seek SECONDS
...seeks relatively to current position (negative argument to seek backwards)
Options
-------
a1freq / a1 (real number, Hz)
...frequency of a1, usually 440 Hz
highesttone / ht (real number, Hz)
...highest shown frequency
lowesttone / lt (real number, Hz)
...lowest shown frequency
rate / rt (real number, Hz)
...number of columns/rows drawn per second
gain / g (real number, dB)
...amplification of the drawn amplitudes;
taken into account only if dynamicgain is not set
dynamicgain / dg (boolean)
...highest amplitude in a column/row is constant (highest)
signaltonoise / stn (real number, dB)
...signal to noise ratio, lower amplitudes are considered to be zero
showgrid / sg (boolean)
...show tone scale
showcursor / sc (boolean)
...show cursor indicating position of the player
cursorposition / cursorpos / cp (real number, %)
...position of the cursor in the screen
(0% -- only unplayed sound is visible, 100% -- only played sound is visible)
forcecursorposition / forcecursorpos / fcp (boolean)
...keep cursor its position even if there is not enough data before/after it
reversedirection / rd (boolean)
...reverse direction of time axis (it points left/up instead of right/down)
swapaxes / sa (boolean)
...swap time and tone axes (time axis points up/down instead of left/right)
The following options will be changed in future versions:
filterovertones / fo (boolean)
...activate overtone filtering
overtoneblur / ob (real number, px)
...how smoothly should be overtones recognized (w.r.t. near frequencies)
overtonethreshold / ot (real number, %)
...minimal ratio of average of harmonics of an overtone to average of all overtones
to consider the overtone as individual tone
overtoneratio / or (real number, %)
...maximal ratio of average of considered overtones to fundamental tone,
(too silent fundamental tone cannot has arbitrary loud overtones)
overtoneaddition / oa (real number, %)
...fundamental tone amplitude can be increased by percents of its overtones
See also
--------
VERSION for current version of the application,
COPYING for full text of GNU General Public Licence version 3.
Other information and recent versions can be found on my web page
http://ondracek-lukas.hys.cz/musa
and/or on github repository
http://github.com/ondracek-lukas/musa .
If you want to support the development of this application,
you can send a donation to my PayPal account <ondracek.lukas@gmail.com>.