libs/soundtouch/README

   1 SoundTouch sound processing library v1.01
   2 =========================================
   3 Copyright (c) Olli Parviainen 2002
   4
   5 A library for changing tempo, pitch and playback rate of digital sound.
   6
   7
   8 SoundStretch sound processing application v1.1
   9 ==============================================
  10 Copyright (c) Olli Parviainen 2002-2003
  11
  12 A command-line application for changing tempo, pitch and playback rates
  13 of WAV sound files. This program also demonstrates how the "SoundTouch"
  14 library can be used to process sound in own programs.
  15
  16
  17 SoundStretch Usage Instructions
  18 ===============================
  19
  20 SoundStretch Usage syntax:
  21      soundstretch infile.wav outfile.wav [switches]
  22
  23 Where:
  24
  25    "infile.wav" is the name of the input sound data file (in .WAV audio
  26                 file format).
  27
  28    "outfile.wav" is the name of the output sound file where the resulting
  29                  sound is saved (in .WAV audio file format).
  30
  31    [switches] are one or more control switches.
  32
  33 Available control switches are:
  34
  35   -tempo=n : Change sound tempo by n percents (n = -95.0 .. +5000.0 %)
  36
  37   -pitch=n : Change sound pitch by n semitones (n = -60.0 .. + 60.0 semitones)
  38
  39   -rate=n  : Change sound playback rate by n percents (n = -95.0 .. +5000.0 %)
  40
  41   -bpm=n   : Detect the Beats-Per-Minute (BPM) rate of the sound and adjust the
  42              tempo to meet 'n' BPMs. If this switch is defined, the "-tempo=n"
  43              switch value is ignored.
  44
  45              If "=n" is omitted, i.e. switch "-bpm" is used alone, the
  46              program just calculates and displays the BPM rate but doesn't
  47              adjust tempo according to the BPM value.
  48
  49   -quick   : Use quicker tempo change algorithm. Gains speed but loses sound
  50              quality.
  51
  52   -naa     : Don't use anti-alias filtering in samplerate transposing. Gains
  53              speed but loses sound quality.
  54
  55   -license : Displays the program license text (GPL)
  56
  57 Notes:
  58   * The numerical switch values can be entered using either integer (e.g.
  59     "-tempo=123") or decimal (e.g. "-tempo=123.45") numbers.
  60
  61   * The "-naa" and/or "-quick" switches can be used to reduce CPU usage
  62     while compromising some sound quality
  63
  64   * The BPM detection algorithm works by detecting repeating low-frequency
  65     (<250Hz) sound patterns and thus works mostly with most rock/pop music
  66     with bass or drum beat. The BPM detection doesn't work on pieces such
  67     as classical music without distinct, repeating bass frequency patterns.
  68     Also pieces with varying tempo, varying bass patterns or very complex
  69     bass patterns (jazz, hiphop) may produce odd BPM readings.
  70
  71     In cases when the bass pattern drifts a bit around a nominal beat rate
  72     (e.g. drummer is again drunken :), the BPM algorithm may report incorrect
  73     harmonic one-halft of one-thirdth of the correct BPM value; in such case
  74     the system could for example report BPM value of 50 or 100 instead of
  75     correct BPM value of 150.
  76
  77
  78 Usage examples:
  79 ===============
  80
  81   Example 1
  82   =========
  83
  84   The following command increases tempo of the sound file "originalfile.wav"
  85   by 12.5% and saves result to file "destinationfile.wav":
  86
  87       soundstretch originalfile.wav destinationfile.wav -tempo=12.5
  88
  89
  90   Example 2
  91   =========
  92
  93   The following command decreases the sound pitch (key) of the sound file
  94   "orig.wav" by two semitones and saves the result to file "dest.wav":
  95
  96       soundstretch orig.wav dest.wav -pitch=-2
  97
  98
  99   Example 3
 100   =========
 101
 102   The following command processes the file "orig.wav" by decreasing the
 103   sound tempo by 25.3% and increasing the sound pitch (key) by 1.5 semitones.
 104   Result is saved to file "dest.wav":
 105
 106       soundstretch orig.wav dest.wav -tempo=-25.3 -pitch=1.5
 107
 108
 109   Example 4
 110   =========
 111
 112   The following command detects the BPM rate of the file "orig.wav" and
 113   adjusts the tempo to match 100 beats per minute. Result is saved to
 114   file "dest.wav":
 115
 116       soundstretch orig.wav dest.wav -bpm=100
 117
 118
 119
 120 Building Instructions
 121 =====================
 122
 123 The package contains executable binaries for Win32 platform in the "bin"
 124 directory.
 125
 126 To build the library and application executable for other platforms or to
 127 re-build the delivered binaries, run either of the scripts in the package
 128 root directory:
 129
 130 "make-win.bat" for Microsoft Windows environment, or
 131 "make-gcc"     for GNU/Linux or Unix environment with a gcc compiler.
 132
 133
 134
 135 Change History
 136 ==============
 137
 138
 139    SoundTouch library Change History
 140    =================================
 141
 142    v1.01:
 143    - "mmx_gcc.cpp": Added "using namespace std" and removed "return 0" from a
 144      function with void return value to fix compiler errors when compiling
 145      the library in Solaris environment.
 146
 147    - Moved file "FIFOSampleBuffer.h" to "include" directory to allow accessing
 148      the FIFOSampleBuffer class from external files.
 149
 150    v1.0: Initial release
 151
 152
 153    SoundStretch application Change History
 154    =======================================
 155
 156   v1.1:
 157    - Fixed "Release" settings in Microsoft Visual C++ project file (.dsp)
 158
 159    - Added beats-per-minute (BPM) detection routine and command-line switch
 160      "-bpm"
 161
 162   v1.01: Initial release
 163
 164
 165 Acknowledgements
 166 ================
 167
 168 Many thanks to Stuart Lamble for translating the MMX optimizations from
 169 MS Visual C++ syntax into gcc syntax for joy of all Linux users.
 170
 171 Thanks also to Manish Bajpai, whose WAV file reading routines I've used
 172 as base of the WavInFile & WavOutFile classes, that are being used in
 173 the soundstrecth program for accessing WAV audio files.
 174
 175
 176 LICENSE:
 177 ========
 178
 179 This program is free software; you can redistribute it and/or modify it
 180 under the terms of the GNU General Public License as published by the
 181 Free Software Foundation; either version 2 of the License, or (at your
 182 option) any later version.
 183
 184 This program is distributed in the hope that it will be useful, but
 185 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 186 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 187 for more details.\n"
 188
 189 You should have received a copy of the GNU General Public License along
 190 with this program; if not, write to the Free Software Foundation, Inc., 59
 191 Temple Place, Suite 330, Boston, MA  02111-1307 USA