-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.html
1032 lines (1022 loc) · 48.7 KB
/
README.html
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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SoundTouch library README</title>
<meta http-equiv="Content-Language" content="en-us">
<meta name="author" content="Olli Parviainen">
<meta name="description" content="Readme file for SoundTouch audio processing library">
<style>
body {
font-family: Arial, Helvetica;
}
</style>
</head>
<body class="normal">
<hr>
<h1>SoundTouch audio processing library v2.4.0</h1>
<p class="normal">SoundTouch library Copyright © Olli Parviainen 2001-2025</p>
<hr>
<h2>1. Introduction </h2>
<p>SoundTouch is an open-source audio processing library that allows
changing the sound tempo, pitch and playback rate parameters
independently from each other, i.e.:</p>
<ul>
<li> Sound tempo can be increased or decreased while maintaining the
original pitch</li>
<li> Sound pitch can be increased or decreased while maintaining the
original tempo</li>
<li> Change playback rate that affects both tempo and pitch at the
same time</li>
<li> Choose any combination of tempo/pitch/rate</li>
</ul>
<h3>1.1 Contact information </h3>
<p>Author email: oparviai 'at' iki.fi </p>
<p>SoundTouch WWW page: <a href="http://soundtouch.surina.net">http://soundtouch.surina.net</a></p>
<p>SoundTouch git repository: <a
href="https://codeberg.org/soundtouch/soundtouch.git">https://codeberg.org/soundtouch/soundtouch.git</a></p>
<hr>
<h2>2. Compiling SoundTouch</h2>
<p>Before compiling, notice that you can choose the sample data format if it's
desirable to use 16bit integer sample data instead of floating point samples. See
section "sample data format" for more information.</p>
<p>Also notice that SoundTouch can use OpenMP instructions for parallel
computation to accelerate the runtime processing speed in multi-core systems,
however, these improvements need to be separately enabled before compiling. See
OpenMP notes in Chapter 3 below.</p>
<h3>2.1. Building in Microsoft Windows</h3>
<p>Project files for Microsoft Visual C++ are supplied with the source
code package. Go to Microsoft WWW page to download
<a href="http://www.visualstudio.com/en-US/products/visual-studio-express-vs">
Microsoft Visual Studio Express version for free</a>.
</p>
<p>To build the binaries with Visual C++ compiler, either run
"make-win.bat" script, or open the appropriate project files in source
code directories with Visual Studio. The final executable will appear
under the "SoundTouch\bin" directory. If using the Visual Studio IDE
instead of the make-win.bat script, directories bin and lib may need to
be created manually to the SoundTouch package root for the final
executables. The make-win.bat script creates these directories
automatically. </p>
<p><strong>C# example</strong>: The source code package includes also a C# example
application for Windows that shows how to invoke SoundTouch.dll
dynamic-load library for processing mp3 audio.
<p><strong>OpenMP NOTE</strong>: If activating the OpenMP parallel computing in
the compilation, the target program will require additional vcomp dll library to
properly run. In Visual C++ 9.0 these libraries can be found in the following
folders.</p>
<ul>
<li>x86 32bit: C:\Program Files (x86)\Microsoft Visual Studio
9.0\VC\redist\x86\Microsoft.VC90.OPENMP\vcomp90.dll</li>
<li>x64 64bit: C:\Program Files (x86)\Microsoft Visual Studio
9.0\VC\redist\amd64\Microsoft.VC90.OPENMP\vcomp90.dll</li>
</ul>
<p>In other VC++ versions the required library will be expectedly found in similar
"redist" location.</p>
<p>Notice that as minor demonstration of a "dll hell" phenomenon both the 32-bit
and 64-bit version of vcomp90.dll have the same filename but different contents,
thus choose the proper version to allow the program to start.</p>
<h3>2.2. Building in Gnu platforms</h3>
<p>The SoundTouch library compiles in practically any platform
supporting GNU compiler (GCC) tools.
<h4>2.2.1 Compiling with autotools</h4>
<p>To install build prerequisites for 'autotools' tool chain (for Ubuntu/Debian. Use dnf/yum/etc in other distros):</p>
<pre> sudo apt install -y automake autoconf libtool build-essential</pre>
<p>To build and install the binaries, run the following commands in
/soundtouch directory:</p>
<table border="0" cellpadding="0" cellspacing="4">
<tbody>
<tr>
<td style="vertical-align: top;">
<pre>./bootstrap -</pre>
</td>
<td style="vertical-align: top;">Creates "configure" file with
local autoconf/automake toolset.<br>
</td>
</tr>
<tr valign="top">
<td>
<pre>./configure -</pre>
</td>
<td>
<p>Configures the SoundTouch package for the local environment.
Notice that "configure" file is not available before running the
"./bootstrap" command as above.<br>
</p>
</td>
</tr>
<tr valign="top">
<td>
<pre>make -</pre>
</td>
<td>
<p>Builds the SoundTouch library & SoundStretch utility. You can
optionally add "-j" switch after "make" to speed up the compilation in
multi-core systems.</p>
</td>
</tr>
<tr valign="top">
<td>
<pre>make install -</pre>
</td>
<td>
<p>Installs the SoundTouch & BPM libraries to <b>/usr/local/lib</b>
and SoundStretch utility to <b>/usr/local/bin</b>. Please notice that
'root' privileges may be required to install the binaries to the
destination locations.</p>
</td>
</tr>
</tbody>
</table>
<b>Compiling portable Shared Library / DLL version</b>
<p> The GNU autotools compilation automatically builds an additional dynamic-link version
of SoundTouch library that features position-independent code and "C"-style API that is
more suitable for calling the SoundTouch routines from other programming languages.</p>
<p>This dynamic-link library is built under source/SoundTouchDLL directory, whose
subdirectories also comtain simple example apps that use the dynamic-link library.
</p>
<h4><b>2.2.2 Compiling with cmake</b></h4>
<p>'cmake' build scripts are provided as an alternative to the autotools toolchain.</p>
<p>To install cmake build prerequisites (for Ubuntu/Debian. Use dnf/yum/etc in other distros):</p>
<pre> sudo apt install -y libtool build-essential cmake</pre>
<p>To build:</p>
<pre>
cmake .
make -j
make install</pre>
<p>To list available build options:</p>
<pre>
cmake -LH</pre>
<p>To compile the additional portable Shared Library / DLL version with the native C-language API:</p>
<pre>
cmake . -DSOUNDTOUCH_DLL=ON
make -j
make install</pre>
<h3>2.3. Building in Android</h3>
<p>Android compilation instructions are within the
source code package, see file "<b>source/Android-lib/README-SoundTouch-Android.html</b>"
in the source code package. </p>
<p>The Android compilation automatically builds separate .so library binaries
for ARM, X86 and MIPS processor architectures. For optimal device support,
include all these .so library binaries into the Android .apk application
package, so the target Android device can automatically choose the proper
library binary version to use.</p>
<p>The <strong>source/Android-lib</strong> folder includes also an Android
example application that processes WAV audio files using SoundTouch library in
Android devices.</p>
<h3>2.4. Building in Mac</h3>
<p>Install autoconf tool as instructed in <a
href="http://macappstore.org/autoconf/">http://macappstore.org/autoconf/</a>, or alternatively the 'cmake' toolchain.</p>
<p>Then, build as described above in section "Building in Gnu platforms".</p>
<hr>
<h2>3. About implementation & Usage tips <h3>3.1. Supported sample data formats</h3>
<p>The sample data format can be chosen between 16bit signed integer
and 32bit floating point values.</p>
</p> The default sample type is 32bit floating point format,
which also provides better sound quality than integer format because
integer algorithms need to scale already intermediate calculation results to
avoid integer overflows. These early integer scalings can slightly degrade
output quality.</p>
<p> In Windows environment, the sample data format is chosen in file
"STTypes.h" by choosing one of the following defines:</p>
<ul>
<li> <span style="font-weight: bold;">#define
SOUNDTOUCH_INTEGER_SAMPLES</span> for 16bit signed integer</li>
<li> <span style="font-weight: bold;">#define </span><span style="font-weight: bold;">SOUNDTOUCH_</span><span
style="font-weight: bold;">FLOAT_SAMPLES</span> for 32bit floating
point</li>
</ul>
<p> In GNU environment, the floating sample format is used by default,
but integer sample format can be chosen by giving the following switch
to the configure script: </p>
<blockquote>
<pre>./configure --enable-integer-samples</pre>
</blockquote>
<p>The sample data can have either single (mono) or double (stereo)
audio channel. Stereo data is interleaved so that every other data
value is for left channel and every second for right channel. Notice
that while it'd be possible in theory to process stereo sound as two
separate mono channels, this isn't recommended because processing the
channels separately would result in losing the phase coherency between
the channels, which consequently would ruin the stereo effect.</p>
<p>Sample rates between 8000-48000Hz are supported.</p>
<h3>3.2. Processing latency</h3>
<p>The processing and latency constraints of the SoundTouch library are:</p>
<ul>
<li> Input/output processing latency for the SoundTouch processor is
around 100 ms. This is when time-stretching is used. If the rate
transposing effect alone is used, the latency requirement is much
shorter, see section 'About algorithms'.</li>
<li> Processing CD-quality sound (16bit stereo sound with 44100H
sample rate) in real-time or faster is possible starting from
processors equivalent to Intel Pentium 133Mh or better, if using the
"quick" processing algorithm. If not using the "quick" mode or if
floating point sample data are being used, several times more CPU power
is typically required.</li>
</ul>
<h3>3.3. About algorithms</h3>
<p>SoundTouch provides three seemingly independent effects: tempo,
pitch and playback rate control. These three controls are implemented
as combination of two primary effects, <em>sample rate transposing</em>
and <em>time-stretching</em>.</p>
<p><em>Sample rate transposing</em> affects both the audio stream
duration and pitch. It's implemented simply by converting the original
audio sample stream to the desired duration by interpolating from
the original audio samples. In SoundTouch, linear interpolation with
anti-alias filtering is used. Theoretically a higher-order
interpolation provide better result than 1st order linear
interpolation, but in audio application linear interpolation together
with anti-alias filtering performs subjectively about as well as
higher-order filtering would.</p>
<p><em>Time-stretching </em>means changing the audio stream duration
without affecting it's pitch. SoundTouch uses WSOLA-like
time-stretching routines that operate in the time domain. Compared to
sample rate transposing, time-stretching is a much heavier operation
and also requires a longer processing "window" of sound samples used by
the processing algorithm, thus increasing the algorithm input/output
latency. Typical i/o latency for the SoundTouch time-stretch algorithm
is around 100 ms.</p>
<p>Sample rate transposing and time-stretching are then used together
to produce the tempo, pitch and rate controls:</p>
<ul>
<li> <strong>'Tempo'</strong> control is implemented purely by
time-stretching.</li>
<li> <strong>'Rate</strong>' control is implemented purely by sample
rate transposing.</li>
<li> <strong>'Pitch</strong>' control is implemented as a
combination of time-stretching and sample rate transposing. For
example, to increase pitch the audio stream is first time-stretched to
longer duration (without affecting pitch) and then transposed back to
original duration by sample rate transposing, which simultaneously
reduces duration and increases pitch. The result is original duration
but increased pitch.</li>
</ul>
<h3>3.4 Tuning the algorithm parameters</h3>
<p>The time-stretch algorithm has few parameters that can be tuned to
optimize sound quality for certain application. The current default
parameters have been chosen by iterative if-then analysis (read: "trial
and error") to obtain best subjective sound quality in pop/rock music
processing, but in applications processing different kind of sound the
default parameter set may result into a sub-optimal result.</p>
<p>The time-stretch algorithm default parameter values are set by the
following #defines in file "TDStretch.h":</p>
<blockquote>
<pre>#define DEFAULT_SEQUENCE_MS AUTOMATIC<br>#define DEFAULT_SEEKWINDOW_MS AUTOMATIC<br>#define DEFAULT_OVERLAP_MS 8</pre>
</blockquote>
<p>These parameters affect to the time-stretch algorithm as follows:</p>
<ul>
<li> <strong>DEFAULT_SEQUENCE_MS</strong>: This is the default
length of a single processing sequence in milliseconds which determines
the how the original sound is chopped in the time-stretch algorithm.
Larger values mean fewer sequences are used in processing. In principle
a larger value sounds better when slowing down the tempo, but worse
when increasing the tempo and vice versa.<br>
<br>
By default, this setting value is calculated automatically according to
tempo value.<br>
</li>
<li> <strong>DEFAULT_SEEKWINDOW_MS</strong>: The seeking window
default length in milliseconds is for the algorithm that seeks the best
possible overlapping location. This determines from how wide a sample
"window" the algorithm can use to find an optimal mixing location when
the sound sequences are to be linked back together.<br>
<br>
The bigger this window setting is, the higher the possibility to find a
better mixing position becomes, but at the same time large values may
cause a "drifting" sound artifact because neighboring sequences can be
chosen at more uneven intervals. If there's a disturbing artifact that
sounds as if a constant frequency was drifting around, try reducing
this setting.<br>
<br>
By default, this setting value is calculated automatically according to
tempo value.<br>
</li>
<li> <strong>DEFAULT_OVERLAP_MS</strong>: Overlap length in
milliseconds. When the sound sequences are mixed back together to form
again a continuous sound stream, this parameter defines how much the
ends of the consecutive sequences will overlap with each other.<br>
<br>
This shouldn't be that critical parameter. If you reduce the
DEFAULT_SEQUENCE_MS setting by a large amount, you might wish to try a
smaller value on this.
</li>
</ul>
<p>Notice that these parameters can also be set during execution time
with functions "<strong>TDStretch::setParameters()</strong>" and "<strong>SoundTouch::setSetting()</strong>".</p>
<p>The table below summaries how the parameters can be adjusted for
different applications:</p>
<table border="1">
<tbody>
<tr>
<td valign="top"><strong>Parameter name</strong></td>
<td valign="top"><strong>Default value magnitude</strong></td>
<td valign="top"><strong>Larger value affects...</strong></td>
<td valign="top"><strong>Smaller value affects...</strong></td>
<td valign="top"><strong>Effect to CPU burden</strong></td>
</tr>
<tr>
<td valign="top">
<pre>SEQUENCE_MS</pre>
</td>
<td valign="top">Default value is relatively large, chosen for
slowing down music tempo</td>
<td valign="top">Larger value is usually better for slowing down
tempo. Growing the value decelerates the "echoing" artifact when
slowing down the tempo.</td>
<td valign="top">Smaller value might be better for speeding up
tempo. Reducing the value accelerates the "echoing" artifact when
slowing down the tempo </td>
<td valign="top">Increasing the parameter value reduces
computation burden</td>
</tr>
<tr>
<td valign="top">
<pre>SEEKWINDOW_MS</pre>
</td>
<td valign="top">Default value is relatively large, chosen for
slowing down music tempo</td>
<td valign="top">Larger value eases finding a good mixing
position, but may cause a "drifting" artifact</td>
<td valign="top">Smaller reduce possibility to find a good mixing
position, but reduce the "drifting" artifact.</td>
<td valign="top">Increasing the parameter value increases
computation burden</td>
</tr>
<tr>
<td valign="top">
<pre>OVERLAP_MS</pre>
</td>
<td valign="top">Default value is relatively large, chosen to
suit with above parameters.</td>
<td valign="top"></td>
<td valign="top">If you reduce the "sequence ms" setting, you
might wish to try a smaller value.</td>
<td valign="top">Increasing the parameter value increases
computation burden</td>
</tr>
</tbody>
</table>
<h3>3.5 Performance Optimizations </h3>
<p><strong>Integer vs floating point:</strong></p>
<p>Floating point sample type is generally recommended because it provides
better sound quality.</p>
<p>However, execution speed difference between integer and floating point processing
depends on the CPU architecture. As rule of thumb,
<ul>
<li>in 32-bit x86 floating point and integer are roughly equally fast</li>
<li>in 64-bit x86/x64 floating point can be significantly faster than integer
version, because MMX integer optimizations are not available in the x64 architecture.
That depends on the compiler however, so that gcc can autovectorize integer routines
to work equally fast as floating point, where as Visual C++ (2017) does not
perform equally well and produces integer code that runs some 3x slower than
SSE-optimized floating poing code.
</li>
<li>in ARMv7 integer routines are twice as fast as floating point. Their
relative difference is roughly the same both with and without NEON; NEON
vfpu can however bring 2.4x speed improvement.
</li>
<li>in other platforms: try out if the execution time performance makes a
big difference</li>
</ul>
</p>
<p><strong>General optimizations:</strong></p>
<p>The time-stretch routine has a 'quick' mode that substantially
speeds up the algorithm but may slightly compromise the sound quality.
This mode is activated by calling SoundTouch::setSetting()
function with parameter id of SETTING_USE_QUICKSEEK and value
"1", i.e. </p>
<blockquote>
<p>setSetting(SETTING_USE_QUICKSEEK, 1);</p>
</blockquote>
<p><strong>CPU-specific optimizations:</strong></p>
<p>Intel x86 specific SIMD optimizations are implemented using compiler
intrinsics, providing about a 3x processing speedup for x86 compatible
processors vs. non-SIMD implementation:</p>
<ul>
<li> MMX optimized routines are used in 32-bit x86 build when 16bit integer
sample type is used</li>
<li> SSE optimized routines are used in 32- and 64-bit x86 CPUs when 32bit
floating point sample type is used</li>
</ul>
<p>The algorithms are tuned to utilize autovectorization efficiently
also in other CPU architectures, for example ARM cpus see approx 2.4x processing
speedup when NEON SIMD support is present.
</p>
<h3>3.5 OpenMP parallel computation</h3>
<p>SoundTouch 1.9 onwards support running the algorithms parallel in several CPU
cores. Based on benchmark the experienced multi-core processing speed-up gain
ranges between +30% (on a high-spec dual-core x86 Windows PC) to 215% (on a moderately low-spec
quad-core ARM of Raspberry Pi2). </p>
<p>See an external blog article with more detailed discussion about the
<a href="http://www.softwarecoven.com/parallel-computing-in-embedded-mobile-devices/">
SoundTouch OpenMP optimization</a>.
</p>
<p>The parallel computing support is implemented using OpenMP spec 3.0
instructions. These instructions are supported by Visual C++ 2008 and later, and
GCC v4.2 and later. Compilers that do not supporting OpenMP will ignore these
optimizations and routines will still work properly. Possible warnings about
unknown #pragmas are related to OpenMP support and can be safely ignored.</p>
<p>The OpenMP improvements are disabled by default, and need to be enabled by
developer during compile-time. Reason for this is that parallel processing adds
moderate runtime overhead in managing the multi-threading, so it may not be
necessary nor desirable in all applications. For example real-time processing
that is not constrained by CPU power will not benefit of speed-up provided by
the parallel processing, in the contrary it may increase power consumption due
to the increased overhead.</p>
<p>However, applications that run on low-spec multi-core CPUs and may otherwise
have possibly constrained performance will benefit of the OpenMP improvements.
This include for example multi-core embedded devices.</p>
<p>OpenMP parallel computation can be enabled before compiling SoundTouch
library as follows:</p>
<ul>
<li><strong>Visual Studio</strong>: Open properties for the <strong>SoundTouch
</strong>sub-project, browse to <strong>C/C++</strong> and <strong>Language
</strong>settings. Set
there "<strong>OpenMP support</strong>" to "<strong>Yes</strong>". Alternatively add
<strong>/openmp</strong> switch to command-line
parameters
</li>
<li><strong>GNU</strong>: Run the configure script with "<strong>./configure
--enable-openmp</strong>" switch, then run make as usually</li>
<li><strong>Android</strong>: Add "<strong>-fopenmp</strong>" switches to compiler & linker
options, see README-SoundTouch-Android.html in the source code package for
more detailed instructions.</li>
</ul>
<hr>
<h2><a name="SoundStretch"></a>4. SoundStretch audio processing utility
</h2>
<p>SoundStretch audio processing utility<br>
Copyright (c) Olli Parviainen 2002-2024</p>
<p>SoundStretch is a simple command-line application that can change
tempo, pitch and playback rates of WAV sound files. This program is
intended primarily to demonstrate how the "SoundTouch" library can be
used to process sound in your own program, but it can as well be used
for processing sound files.</p>
<h3>4.1. SoundStretch Usage Instructions</h3>
<p>SoundStretch Usage syntax:</p>
<blockquote>
<pre>soundstretch infilename outfilename [switches]</pre>
</blockquote>
<p>Where: </p>
<table width="100%" border="0" cellpadding="2">
<tbody>
<tr>
<td valign="top">
<pre>"infilename"</pre>
</td>
<td valign="top">Name of the input sound data file (in .WAV audio
file format). Give "stdin" as filename to use standard input pipe. </td>
</tr>
<tr>
<td valign="top">
<pre>"outfilename"</pre>
</td>
<td valign="top">Name of the output sound file where the
resulting sound is saved (in .WAV audio file format). This parameter
may be omitted if you don't want to save the output (e.g. when
only calculating BPM rate with '-bpm' switch). Give "stdout" as
filename to use standard output pipe.</td>
</tr>
<tr>
<td valign="top">
<pre>[switches]</pre>
</td>
<td valign="top">Are one or more control switches.</td>
</tr>
</tbody>
</table>
<p>Available control switches are:</p>
<table width="100%" border="0" cellpadding="2">
<tbody>
<tr>
<td valign="top">
<pre>-tempo=n </pre>
</td>
<td valign="top">Change the sound tempo by n percents (n = -95.0
.. +5000.0 %) </td>
</tr>
<tr>
<td valign="top">
<pre>-pitch=n</pre>
</td>
<td valign="top">Change the sound pitch by n semitones (n = -60.0
.. + 60.0 semitones) </td>
</tr>
<tr>
<td valign="top">
<pre>-rate=n</pre>
</td>
<td valign="top">Change the sound playback rate by n percents (n
= -95.0 .. +5000.0 %) </td>
</tr>
<tr>
<td valign="top">
<pre>-bpm=n</pre>
</td>
<td valign="top">Detect the Beats-Per-Minute (BPM) rate of the
sound and adjust the tempo to meet 'n' BPMs. When this switch is
applied, the "-tempo" switch is ignored. If "=n" is omitted, i.e.
switch "-bpm" is used alone, then the BPM rate is estimated and
displayed, but tempo not adjusted according to the BPM value. </td>
</tr>
<tr>
<td valign="top">
<pre>-quick</pre>
</td>
<td valign="top">Use quicker tempo change algorithm. Gains speed
but loses sound quality. </td>
</tr>
<tr>
<td valign="top">
<pre>-naa</pre>
</td>
<td valign="top">Don't use anti-alias filtering in sample rate
transposing. Gains speed but loses sound quality. </td>
</tr>
<tr>
<td valign="top">
<pre>-license</pre>
</td>
<td valign="top">Displays the program license text (LGPL)</td>
</tr>
</tbody>
</table>
<p>Notes:</p>
<ul>
<li> To use standard input/output pipes for processing, give "stdin"
and "stdout" as input/output filenames correspondingly. The standard
input/output pipes will still carry the audio data in .wav audio file
format.</li>
<li> The numerical switches allow both integer (e.g. "-tempo=123")
and decimal (e.g. "-tempo=123.45") numbers.</li>
<li> The "-naa" and/or "-quick" switches can be used to reduce CPU
usage while compromising some sound quality</li>
<li> The BPM detection algorithm works by detecting repeating bass or
drum patterns at low frequencies of <250Hz. A lower-than-expected
BPM figure may be reported for music with uneven or complex bass
patterns.</li>
</ul>
<h3>4.2. SoundStretch usage examples </h3>
<p><strong>Example 1</strong></p>
<p>The following command increases tempo of the sound file
"originalfile.wav" by 12.5% and stores result to file
"destinationfile.wav":</p>
<blockquote>
<pre>soundstretch originalfile.wav destinationfile.wav -tempo=12.5</pre>
</blockquote>
<p><strong>Example 2</strong></p>
<p>The following command decreases the sound pitch (key) of the sound
file "orig.wav" by two semitones and stores the result to file
"dest.wav":</p>
<blockquote>
<pre>soundstretch orig.wav dest.wav -pitch=-2</pre>
</blockquote>
<p><strong>Example 3</strong></p>
<p>The following command processes the file "orig.wav" by decreasing
the sound tempo by 25.3% and increasing the sound pitch (key) by 1.5
semitones. Resulting .wav audio data is directed to standard output
pipe:</p>
<blockquote>
<pre>soundstretch orig.wav stdout -tempo=-25.3 -pitch=1.5</pre>
</blockquote>
<p><strong>Example 4</strong></p>
<p>The following command detects the BPM rate of the file "orig.wav"
and adjusts the tempo to match 100 beats per minute. Result is stored
to file "dest.wav":</p>
<blockquote>
<pre>soundstretch orig.wav dest.wav -bpm=100</pre>
</blockquote>
<p><strong>Example 5</strong></p>
<p>The following command reads .wav sound data from standard input pipe
and estimates the BPM rate:</p>
<blockquote>
<pre>soundstretch stdin -bpm</pre>
</blockquote>
<p><strong>Example 6</strong></p>
<p>The following command tunes song from original 440Hz tuning to 432Hz tuning:
this corresponds to lowering the pitch by -0.318 semitones:</p>
<blockquote>
<pre>soundstretch original.wav output.wav -pitch=-0.318</pre>
</blockquote>
<hr>
<a name="changehistory"><h2>5. Change History</h2></a>
<h3>5.1. SoundTouch library Change History </h3>
<p><b>2.4.0:</b></p>
<ul class="current">
<li>Set CMake minimum version to 3.5 to avoid deprecation warning</li>
<li>Increase max nr. of channels from 16 to 32</li>
<li>Don't use `pow()` when using integer precision samples</li>
<li>Replace `-Ofast` that's being deprecated in some compilers, by `-O3 -ffast-math`</li>
</ul>
<p><b>2.3.3:</b></p>
<ul>
<li>Fixing compiler warnings, maintenance fixes to make/build files for various systems
</li>
</ul>
<p><b>2.3.2:</b></p>
<ul>
<li>Improve autotools makefiles to build the `SoundTouchDLL` dynamic-link link library with
C-style API. This library variation is easier to import and use from other programming
languages than the default C++ library.
</li>
</ul>
<p><b>2.3.1:</b></p>
<ul>
<li>Adjusted cmake build settings and header files that cmake installs</li>
</ul>
<p><b>2.3.0:</b></p>
<ul>
<li>Disable setting "SOUNDTOUCH_ALLOW_NONEXACT_SIMD_OPTIMIZATION" by default. The original
purpose of this setting was to avoid performance penalty due to unaligned SIMD memory
accesses in old CPUs, but that is not any more issue in concurrent CPU SIMD implementations
and having this setting enabled can cause slight compromise in result quality.
</li>
<li>Bugfix: soundtouch.clear() to really clear whole processing pipeline state. Earlier
individual variables were left uncleared, which caused slightly different result if
the same audio stream were processed again after calling clear().
</li>
<li>Bugfix: TDstretch to align initial offset position to be in middle of correlation search
window. This ensures that with zero tempo change the output will be same as input.
</li>
<li>Bugfix: Fix a bug in TDstrectch with too small initial skipFract value that occurred
with certain processing parameter settings: Replace assert with assignment that
corrects the situation.
</li>
<li>Remove OpenMP "_init_threading" workaround from Android build as it's not needed with concurrent
Android SDKs any more.</li>
</ul>
<p><b>2.2:</b></p>
<ul>
<li>Improved source codes so that compiler can autovectorize them more effectively.
This brings remarkable improvement e.g. ARM cpus equipped with NEON vfpu: Bencmarked
2.4x improvement in execution speed in ARMv7l vs the previous SoundTouch version
for both integer and floating point sample types.
</li>
<li>Bugfix: Resolved bad sound quality when using integer sample types in non-x86 CPU</li>
<li>Bugfix: Fixed possible reading past end of array in BPM peak detection algorithm</li>
</ul>
<p><b>2.1.2:</b></p>
<ul>
<li>Bump version to 2.1.2 also in configure.ac. The earlier release had old version info for GNU autotools.</li>
</ul>
<p><b>2.1.1:</b></p>
<ul>
<li>Bugfixes: Fixed potential buffer overwrite bugs in WavFile routines. Replaced asserts with runtime exceptions.
</li>
<li>Android: Migrated the SoundTouch Android example to new Android Studio</li>
<li>Automake: unset ACLOCAL in bootstrap script in case earlier build script has set it</li>
</ul>
<p><b>2.1:</b></p>
<ul>
<li>Refactored C# interface example</li>
<li>Disable anti-alias filter when switch
SOUNDTOUCH_PREVENT_CLICK_AT_RATE_CROSSOVER defined because anti-alias
filter cause slight click if the rate change crosses zero during
processing</li>
<li>Added script for building SoundTouchDll dynamic-link-library for GNU platforms</li>
<li>Rewrote Beats-per-Minute analysis algorithm for more reliable BPM detection</li>
<li>Added BPM functions to SoundTouchDll API</li>
<li>Migrated Visual Studio project files to MSVC 201x format</li>
<li>Replaced function parameter value asserts with runtime exceptions</li>
<li>Code maintenance & style cleanup</li>
</ul>
<p><b>2.0:</b></p>
<ul>
<li>Added functions to get initial processing latency, duration ratio between the original input and processed
output tracks, and clarified reporting of input/output batch sizes</li>
<li>Fixed issue that added brief sequence of silence to beginning of output audio</li>
<li>Adjusted algorithm parameters to reduce reverberating effect at tempo slowdown</li>
<li>Bugfix: Fixed a glitch that could cause negative array indexing in quick seek algorithm</li>
<li>Bugfix: flush() didn't properly flush final samples from the pipeline on 2nd time in case that soundtouch
object instance was recycled and used for processing a second audio stream.</li>
<li>Bugfix: Pi value had incorrect 9th/10th decimals</li>
<li>Added C# example application that uses SoundTouch dll library for processing MP3 files</li>
</ul>
<p><b>1.9.2:</b></p>
<ul>
<li>Fix in GNU package configuration</li>
</ul>
<p><b>1.9.1:</b></p>
<ul>
<li>Improved SoundTouch::flush() function so that it returns precisely the desired amount of samples for exact
output duration control</li>
<li>Redesigned quickseek algorithm for improved sound quality when using the quickseek mode. The new quickseek
algorithm can find 99% as good results as the
default full-scan mode, while the quickseek algorithm is remarkable less
CPU intensive.</li>
<li>Added adaptive integer divider scaling for improved sound quality when using integer processing algorithm
</li>
</ul>
<p><b>1.9:</b></p>
<ul>
<li>Added support for parallel computation support via OpenMP primitives for better performance in multicore
systems.
Benchmarks show that achieved parallel processing speedup improvement
typically range from +30% (x86 dual-core) to +180% (ARM quad-core). The
OpenMP optimizations are disabled by default, see OpenMP notes above in this
readme file how to enabled these optimizations.</li>
<li>Android: Added support for Android devices featuring X86 and MIPS CPUs,
in addition to ARM CPUs.</li>
<li>Android: More versatile Android example application that processes WAV
audio files with SoundTouch library</li>
<li>Replaced Windows-like 'BOOL' types with native 'bool'</li>
<li>Changed documentation token to "dist_doc_DATA" in Makefile.am file</li>
<li>Miscellaneous small fixes and improvements</li>
</ul>
<p><b>1.8.0:</b></p>
<ul>
<li>Added support for multi-channel audio processing</li>
<li>Added support for <b>cubic</b> and <b>shannon</b> interpolation for rate and pitch shift effects besides
the original <b>linear</b> interpolation, to reduce aliasing at high frequencies due to interpolation.
Cubic interpolation is used as default for floating point processing, and linear interpolation for integer
processing.</li>
<li>Fixed bug in anti-alias filtering that limited stop-band attenuation to -10 dB instead of <-50dB, and
increased filter length from 32 to 64 taps to further reduce aliasing due to frequency folding.</li>
<li>Performance improvements in cross-correlation algorithm</li>
<li>Other bug and compatibility fixes</li>
</ul>
<p><b>1.7.1:</b></p>
<ul>
<li>Added files for Android compilation
</ul>
<p><b>1.7.0:</b></p>
<ul>
<li>Sound quality improvements/li>
<li>Improved flush() to adjust output sound stream duration to match better with
ideal duration</li>
<li>Rewrote x86 cpu feature check to resolve compatibility problems</li>
<li>Configure script automatically checks if CPU supports mmx & sse compatibility for GNU platform, and
the script support now "--enable-x86-optimizations" switch to allow disabling x86-specific optimizations.</li>
<li>Revised #define conditions for 32bit/64bit compatibility</li>
<li>gnu autoconf/automake script compatibility fixes</li>
<li>Tuned beat-per-minute detection algorithm</li>
</ul>
<p><b>1.6.0:</b></p>
<ul>
<li> Added automatic cutoff threshold adaptation to beat detection
routine to better adapt BPM calculation to different types of music</li>
<li> Retired 3DNow! optimization support as 3DNow! is nowadays
obsoleted and assembler code is nuisance to maintain</li>
<li>Retired "configure" file from source code package due to
autoconf/automake versio conflicts, so that it is from now on to be
generated by invoking "boostrap" script that uses locally available
toolchain version for generating the "configure" file</li>
<li>Resolved namespace/label naming conflicts with other libraries by
replacing global labels such as INTEGER_SAMPLES with more specific
SOUNDTOUCH_INTEGER_SAMPLES etc.<br>
</li>
<li>Updated windows build scripts & project files for Visual
Studio 2008 support</li>
<li> Updated SoundTouch.dll API for .NET compatibility</li>
<li> Added API for querying nominal processing input & output
sample batch sizes</li>
</ul>
<p><strong>1.5.0:</strong></p>
<ul>
<li> Added normalization to correlation calculation and improvement
automatic seek/sequence parameter calculation to improve sound quality</li>
<li> Bugfixes:
<ul>
<li> Fixed negative array indexing in quick seek algorithm</li>
<li> FIR autoalias filter running too far in processing buffer</li>
<li> Check against zero sample count in rate transposing</li>
<li> Fix for x86-64 support: Removed pop/push instructions from
the cpu detection algorithm.</li>
<li> Check against empty buffers in FIFOSampleBuffer</li>
<li> Other minor fixes & code cleanup</li>
</ul>
</li>
<li> Fixes in compilation scripts for non-Intel platforms</li>
<li> Added Dynamic-Link-Library (DLL) version of SoundTouch library
build, provided with Delphi/Pascal wrapper for calling the dll routines
</li>
<li> Added #define PREVENT_CLICK_AT_RATE_CROSSOVER that prevents a
click artifact when crossing the nominal pitch from either positive to
negative side or vice versa</li>
</ul>
<p><strong>1.4.1:</strong></p>
<ul>
<li> Fixed a buffer overflow bug in BPM detect algorithm routines if
processing more than 2048 samples at one call</li>
</ul>
<p><strong>1.4.0:</strong></p>
<ul>
<li> Improved sound quality by automatic calculation of time stretch
algorithm processing parameters according to tempo setting</li>
<li> Moved BPM detection routines from SoundStretch application into
SoundTouch library</li>
<li> Bugfixes: Usage of uninitialied variables, GNU build scripts,
compiler errors due to 'const' keyword mismatch.</li>
<li> Source code cleanup</li>
</ul>
<p><strong>1.3.1: </strong> </p>
<ul>
<li> Changed static class declaration to GCC 4.x compiler compatible
syntax.</li>
<li> Enabled MMX/SSE-optimized routines also for GCC compilers.
Earlier the MMX/SSE-optimized routines were written in
compiler-specific inline assembler, now these routines are migrated to
use compiler intrinsic syntax which allows compiling the same
MMX/SSE-optimized source code with both Visual C++ and GCC compilers.</li>
<li> Set floating point as the default sample format and added switch
to the GNU configure script for selecting the other sample format.</li>
</ul>
<p><strong>1.3.0: </strong> </p>
<ul>
<li> Fixed tempo routine output duration inaccuracy due to rounding
error</li>
<li> Implemented separate processing routines for integer and
floating arithmetic to allow improvements to floating point routines
(earlier used algorithms mostly optimized for integer arithmetic also
for floating point samples)</li>
<li> Fixed a bug that distorts sound if sample rate changes during
the sound stream</li>
<li> Fixed a memory leak that appeared in MMX/SSE/3DNow! optimized
routines</li>
<li> Reduced redundant code pieces in MMX/SSE/3DNow! optimized
routines vs. the standard C routines.</li>
<li> MMX routine incompatibility with new gcc compiler versions</li>
<li> Other miscellaneous bug fixes</li>
</ul>
<p><strong>1.2.1: </strong> </p>
<ul>
<li> Added automake/autoconf scripts for GNU platforms (in courtesy
of David Durham)</li>
<li> Fixed SCALE overflow bug in rate transposer routine.</li>
<li> Fixed 64bit address space bugs.</li>
<li> Created a 'soundtouch' namespace for SAMPLETYPE definitions.</li>
</ul>
<p><strong>1.2.0: </strong> </p>
<ul>
<li> Added support for 32bit floating point sample data type with
SSE/3DNow! optimizations for Win32 platform (SSE/3DNow! optimizations
currently not supported in GCC environment)</li>
<li> Replaced 'make-gcc' script for GNU environment by master
Makefile</li>
<li> Added time-stretch routine configurability to SoundTouch main
class</li>
<li> Bugfixes</li>
</ul>
<p><strong>1.1.1: </strong> </p>
<ul>
<li> Moved SoundTouch under lesser GPL license (LGPL). This allows
using SoundTouch library in programs that aren't released under GPL
license.</li>
<li> Changed MMX routine organiation so that MMX optimized routines
are now implemented in classes that are derived from the basic classes
having the standard non-mmx routines.</li>
<li> MMX routines to support gcc version 3.</li>
<li> Replaced windows makefiles by script using the .dsw files</li>
</ul>
<p><strong>1.0.1: </strong> </p>
<ul>
<li> "mmx_gcc.cpp": Added "using namespace std" and removed "return
0" from a function with void return value to fix compiler errors when
compiling the library in Solaris environment.</li>
<li> Moved file "FIFOSampleBuffer.h" to "include" directory to allow
accessing the FIFOSampleBuffer class from external files.</li>
</ul>
<p><strong>1.0: </strong> </p>
<ul>
<li> Initial release</li>
</ul>
<br><br>
<h3>5.2. SoundStretch application Change History </h3>
<p><b>2.4.0:</b></p>
<ul class="current_soundstretch">
<li>parse command-line argument values with double float precision.</li>
</ul>
<p><b>2.3.3:</b></p>
<ul>
<li>Added support for Asian / non-latin filenames in Windows. Gnu platform has supported them already earlier.</li>
</ul>
<p><b>1.9:</b></p>
<ul>
<li>Added support for WAV file 'fact' information chunk.</li>
</ul>
<p><b>1.7.0:</b></p>
<ul>
<li>Bugfixes in Wavfile: exception string formatting, avoid getLengthMs() integer
precision overflow, support WAV files using 24/32bit sample format.</li>
</ul>
<p><b>1.5.0:</b></p>
<ul>
<li> Added "-speech" switch to activate algorithm parameters more
suitable for speech processing than the default parameters tuned for
music processing.</li>
</ul>
<p><strong>1.4.0:</strong></p>
<ul>
<li> Moved BPM detection routines from SoundStretch application into
SoundTouch library</li>
<li> Allow using standard input/output pipes as audio processing
input/output streams</li>
</ul>
<p><strong>1.3.0:</strong></p>
<ul>
<li> Simplified accessing WAV files with floating point sample
format.</li>
</ul>
<p><strong>1.2.1: </strong> </p>
<ul>
<li> Fixed 64bit address space bugs.</li>
</ul>
<p><strong>1.2.0: </strong> </p>
<ul>
<li> Added support for 32bit floating point sample data type</li>
<li> Restructured the BPM routines into separate library</li>
<li> Fixed big-endian conversion bugs in WAV file routines (hopefully
:)</li>
</ul>
<p><strong>1.1.1: </strong> </p>
<ul>
<li> Fixed bugs in WAV file reading & added byte-order conversion
for big-endian processors.</li>
<li> Moved SoundStretch source code under 'example' directory to
highlight difference from SoundTouch stuff.</li>
<li> Replaced windows makefiles by script using the .dsw files</li>
<li> Output file name isn't required if output isn't desired (e.g. if
using the switch '-bpm' in plain format only)</li>
</ul>
<p><strong>1.1:</strong></p>
<ul>
<li> Fixed "Release" settings in Microsoft Visual C++ project file
(.dsp)</li>
<li> Added beats-per-minute (BPM) detection routine and command-line
switch "-bpm"</li>
</ul>
<p><strong>1.01: </strong> </p>
<ul>
<li> Initial release</li>
</ul>
<hr>
<h2>6. Acknowledgements </h2>
<p>Kudos for these people who have contributed to development or
submitted bugfixes:</p>
<ul>
<li> Arthur A</li>
<li> Paul Adenot</li>
<li> Richard Ash</li>
<li> Stanislav Brabec</li>
<li> Christian Budde</li>
<li> Jamie Bullock</li>
<li> Chris Bryan</li>
<li> Jacek Caban</li>
<li> Marketa Calabkova</li>
<li> Brian Cameron</li>
<li> Jason Champion</li>
<li> Giuseppe Cigala</li>
<li> David Clark</li>
<li> Patrick Colis</li>
<li> Miquel Colon</li>
<li> Jim Credland</li>
<li> Sandro Cumerlato</li>
<li> Gerry Fan</li>
<li> Justin Frankel</li>
<li> Masa H.</li>
<li> Jason Garland</li>
<li> Takashi Iwai</li>
<li> Thomas Klausner</li>
<li> Lu Zhihe</li>
<li> Luzpaz</li>
<li> Tony Mechelynck </li>
<li> Mathias Möhl</li>
<li> Yuval Naveh</li>
<li> Mats Palmgren </li>
<li> Chandni Patel</li>
<li> Paulo Pizarro</li>
<li> Andrey Ponomarenko</li>
<li> Blaise Potard</li>
<li> Michael Pruett</li>
<li> Rajeev Puran</li>
<li> RJ Ryan</li>