soundtouch.nim

SoundTouch.nim

 {.deadCodeElim: on.}
when defined(windows):
  const
    SoundTouchDLL* = "SoundTouchDLL.dll"
elif defined(macosx):
  const
    SoundTouchDLL* = "SoundTouchDLL.dylib"
else:
  const
    SoundTouchDLL* = "SoundTouchDLL.so"
## ////////////////////////////////////////////////////////////////////////////
## /
## / SoundTouch DLL wrapper - wraps SoundTouch routines into a Dynamic Load 
## / Library interface.
## /
## / Author        : Copyright (c) Olli Parviainen
## / Author e-mail : oparviai 'at' iki.fi
## / SoundTouch WWW: http://www.surina.net/soundtouch
## /
## //////////////////////////////////////////////////////////////////////////////
## 
##  License :
## 
##   SoundTouch audio processing library
##   Copyright (c) Olli Parviainen
## 
##   This library is free software; you can redistribute it and/or
##   modify it under the terms of the GNU Lesser General Public
##   License as published by the Free Software Foundation; either
##   version 2.1 of the License, or (at your option) any later version.
## 
##   This library 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
##   Lesser General Public License for more details.
## 
##   You should have received a copy of the GNU Lesser General Public
##   License along with this library; if not, write to the Free Software
##   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
## 
## //////////////////////////////////////////////////////////////////////////////

##  Linux-replacements for Windows declarations:

type
  DWORD* = cuint

const
  FALSE* = 0
  TRUE* = 1

## #endif
## / Create a new instance of SoundTouch processor.

proc soundtouch_createInstance*(): pointer {.
    importcpp: "soundtouch_createInstance(@)", dynlib: SoundTouchDLL.}
## / Destroys a SoundTouch processor instance.

proc soundtouch_destroyInstance*(h: pointer) {.
    importcpp: "soundtouch_destroyInstance(@)", dynlib: SoundTouchDLL.}
## / Get SoundTouch library version string

proc soundtouch_getVersionString*(): cstring {.
    importcpp: "soundtouch_getVersionString()", dynlib: SoundTouchDLL.}
## / Get SoundTouch library version string - alternative function for 
## / environments that can't properly void* character string as return value

proc soundtouch_getVersionString2*(versionString: cstring; bufferSize: cint) {.
    importcpp: "soundtouch_getVersionString2(@)", dynlib: SoundTouchDLL.}
## / Get SoundTouch library version Id

proc soundtouch_getVersionId*(): cuint {.importcpp: "soundtouch_getVersionId(@)",
                                      dynlib: SoundTouchDLL.}
## / Sets new rate control value. Normal rate = 1.0, smaller values
## / represent slower rate, larger faster rates.

proc soundtouch_setRate*(h: pointer; newRate: cfloat) {.
    importcpp: "soundtouch_setRate(@)", dynlib: SoundTouchDLL.}
## / Sets new tempo control value. Normal tempo = 1.0, smaller values
## / represent slower tempo, larger faster tempo.

proc soundtouch_setTempo*(h: pointer; newTempo: cfloat) {.
    importcpp: "soundtouch_setTempo(@)", dynlib: SoundTouchDLL.}
## / Sets new rate control value as a difference in percents compared
## / to the original rate (-50 .. +100 %);

proc soundtouch_setRateChange*(h: pointer; newRate: cfloat) {.
    importcpp: "soundtouch_setRateChange(@)", dynlib: SoundTouchDLL.}
## / Sets new tempo control value as a difference in percents compared
## / to the original tempo (-50 .. +100 %);

proc soundtouch_setTempoChange*(h: pointer; newTempo: cfloat) {.
    importcpp: "soundtouch_setTempoChange(@)", dynlib: SoundTouchDLL.}
## / Sets new pitch control value. Original pitch = 1.0, smaller values
## / represent lower pitches, larger values higher pitch.

proc soundtouch_setPitch*(h: pointer; newPitch: cfloat) {.
    importcpp: "soundtouch_setPitch(@)", dynlib: SoundTouchDLL.}
## / Sets pitch change in octaves compared to the original pitch  
## / (-1.00 .. +1.00);

proc soundtouch_setPitchOctaves*(h: pointer; newPitch: cfloat) {.
    importcpp: "soundtouch_setPitchOctaves(@)", dynlib: SoundTouchDLL.}
## / Sets pitch change in semi-tones compared to the original pitch
## / (-12 .. +12);

proc soundtouch_setPitchSemiTones*(h: pointer; newPitch: cfloat) {.
    importcpp: "soundtouch_setPitchSemiTones(@)", dynlib: SoundTouchDLL.}
## / Sets the number of channels, 1 = mono, 2 = stereo, n = multichannel

proc soundtouch_setChannels*(h: pointer; numChannels: cuint) {.
    importcpp: "soundtouch_setChannels(@)", dynlib: SoundTouchDLL.}
## / Sets sample rate.

proc soundtouch_setSampleRate*(h: pointer; srate: cuint) {.
    importcpp: "soundtouch_setSampleRate(@)", dynlib: SoundTouchDLL.}
## / Flushes the last samples from the processing pipeline to the output.
## / Clears also the internal processing buffers.
## 
## / Note: This function is meant for extracting the last samples of a sound
## / stream. This function may introduce additional blank samples in the end
## / of the sound stream, and thus it's not recommended to call this function
## / in the middle of a sound stream.

proc soundtouch_flush*(h: pointer) {.importcpp: "soundtouch_flush(@)",
                                  dynlib: SoundTouchDLL.}
## / Adds 'numSamples' pcs of samples from the 'samples' memory position into
## / the input of the object. Notice that sample rate _has_to_ be set before
## / calling this function, otherwise throws a runtime_error exception.

proc soundtouch_putSamples*(h: pointer; samples: ptr cfloat; numSamples: cuint) {.
    importcpp: "soundtouch_putSamples(@)", dynlib: SoundTouchDLL.}
  ## /< Pointer to sample buffer.
  ## /< Number of sample frames in buffer. Notice
  ## /< that in case of multi-channel sound a single 
  ## /< sample frame contains data for all channels.
## / int16 version of soundtouch_putSamples(): This accept int16 (short) sample data
## / and internally converts it to float format before processing

proc soundtouch_putSamples_i16*(h: pointer; samples: ptr cshort; numSamples: cuint) {.
    importcpp: "soundtouch_putSamples_i16(@)", dynlib: SoundTouchDLL.}
  ## /< Pointer to sample buffer.
  ## /< Number of sample frames in buffer. Notice
  ## /< that in case of multi-channel sound a single 
  ## /< sample frame contains data for all channels.
## / Clears all the samples in the object's output and internal processing
## / buffers.

proc soundtouch_clear*(h: pointer) {.importcpp: "soundtouch_clear(@)",
                                  dynlib: SoundTouchDLL.}
## / Changes a setting controlling the processing system behaviour. See the
## / 'SETTING_...' defines for available setting ID's.
## / 
## / \return 'nonzero' if the setting was successfully changed, otherwise zero

proc soundtouch_setSetting*(h: pointer; settingId: cint; value: cint): cint {.
    importcpp: "soundtouch_setSetting(@)", dynlib: SoundTouchDLL.}
  ## /< Setting ID number. see SETTING_... defines.
  ## /< New setting value.
## / Reads a setting controlling the processing system behaviour. See the
## / 'SETTING_...' defines for available setting ID's.
## /
## / \return the setting value.

proc soundtouch_getSetting*(h: pointer; settingId: cint): cint {.
    importcpp: "soundtouch_getSetting(@)", dynlib: SoundTouchDLL.}
  ## /< Setting ID number, see SETTING_... defines.
## / Returns number of samples currently unprocessed.

proc soundtouch_numUnprocessedSamples*(h: pointer): cuint {.
    importcpp: "soundtouch_numUnprocessedSamples(@)", dynlib: SoundTouchDLL.}
## / Adjusts book-keeping so that given number of samples are removed from beginning of the 
## / sample buffer without copying them anywhere. 
## /
## / Used to reduce the number of samples in the buffer when accessing the sample buffer directly
## / with 'ptrBegin' function.

proc soundtouch_receiveSamples*(h: pointer; outBuffer: ptr cfloat; maxSamples: cuint): cuint {.
    importcpp: "soundtouch_receiveSamples(@)", dynlib: SoundTouchDLL.}
  ## /< Buffer where to copy output samples.
  ## /< How many samples to receive at max.
## / int16 version of soundtouch_receiveSamples(): This converts internal float samples
## / into int16 (short) return data type

proc soundtouch_receiveSamples_i16*(h: pointer; outBuffer: ptr cshort; maxSamples: cuint): cuint {.
    importcpp: "soundtouch_receiveSamples_i16(@)", dynlib: SoundTouchDLL.}
  ## /< Buffer where to copy output samples.
  ## /< How many samples to receive at max.
## / Returns number of samples currently available.

proc soundtouch_numSamples*(h: pointer): cuint {.
    importcpp: "soundtouch_numSamples(@)", dynlib: SoundTouchDLL.}
## / Returns nonzero if there aren't any samples available for outputting.

proc soundtouch_isEmpty*(h: pointer): cint {.importcpp: "soundtouch_isEmpty(@)",
    dynlib: SoundTouchDLL.}
## / Create a new instance of BPM detector

proc bpm_createInstance*(numChannels: cint; sampleRate: cint): pointer {.
    importcpp: "bpm_createInstance(@)", dynlib: SoundTouchDLL.}
## / Destroys a BPM detector instance.

proc bpm_destroyInstance*(h: pointer) {.importcpp: "bpm_destroyInstance(@)",
                                     dynlib: SoundTouchDLL.}
## / Feed 'numSamples' sample frames from 'samples' into the BPM detector.

proc bpm_putSamples*(h: pointer; samples: ptr cfloat; numSamples: cuint) {.
    importcpp: "bpm_putSamples(@)", dynlib: SoundTouchDLL.}
  ## /< Pointer to sample buffer.
  ## /< Number of samples in buffer. Notice
  ## /< that in case of stereo-sound a single sample
  ## /< contains data for both channels.
## / Feed 'numSamples' sample frames from 'samples' into the BPM detector.
## / 16bit int sample format version.

proc bpm_putSamples_i16*(h: pointer; samples: ptr cshort; numSamples: cuint) {.
    importcpp: "bpm_putSamples_i16(@)", dynlib: SoundTouchDLL.}
  ## /< Pointer to sample buffer.
  ## /< Number of samples in buffer. Notice
  ## /< that in case of stereo-sound a single sample
  ## /< contains data for both channels.
## / Analyzes the results and returns the BPM rate. Use this function to read result
## / after whole song data has been input to the class by consecutive calls of
## / 'inputSamples' function.
## /
## / \return Beats-per-minute rate, or zero if detection failed.

proc bpm_getBpm*(h: pointer): cfloat {.importcpp: "bpm_getBpm(@)",
                                   dynlib: SoundTouchDLL.}