1. J.A. Roberts Tunney
  2. soundtouch4c


.. -*-restructuredtext-*-


A wrapper for soundtouch so you can use it in C programs

:Version: 0.5b
:Copyright: Copyright (c) 2006-2009 J.A. Roberts Tunney and Anthony Minessale II
:Maintainer: J.A. Roberts Tunney <jtunney@lobstertech.com>
:Website: <http://lobstertech.com/2006/aug/23/soundtouch4c/>
:Manual section: 7
:Manual group: Audio Processing


This library provides an API allowing C projects to use the SoundTouch
library (which is written in C++.)  Using soundtouch4c, you can do
cool stuff like change pitch and tempo on audio in real-time.



If you downloaded soundtouch4c as a tarball from Lobstertech,
please do the following::

  # you need SoundTouch 3.1+
  sudo apt-get install libsoundtouch libsoundtouch-dev build-essential

  tar -xvzf soundtouch4c-x.x.tar.gz
  cd soundtouch4c-x.x
  sudo make install

You also get a happy little man page::

  man soundtouch4c

If you have problems, you might want to try following the *full*
instructions on the Asterisk Voice Changer web page.

The following platforms have been tested:

* Ubuntu 9.04 Jaunty 64-bit
* Ubuntu 8.10 Interpid 64-bit
* Red Hat Enterprise Linux 5 32-bit

If you have problems, please email <jtunney@lobstertech.com>.

Mercurial Installation

If you want the bleeding edge source code, building becomes a bit
trickier because you need to install all this wacky GNU AutoTools

  sudo apt-get install mercurial build-essential autoconf \
      libtool automake m4 autotools-dev libsoundtouch-dev rst2man

  hg clone http://bitbucket.org/jart/soundtouch4c
  cd soundtouch4c
  sudo make install

You can run the following command to upgrade to (pull) the latest
source code from BitBucket::

  make upgrade
  sudo make install

Some other useful commands for advanced users::

  ./configure --help
  make tags
  make distclean
  make maintainer-clean
  make uninstall

  make distcheck
  make dist-bzip2 dist-zip


See ``src/example.c`` for a sample program written in C that uses this
library.  You can also check out the Asterisk Voice Changer.

How to invoke the sample app to pitch shift screaming monkeys.  First
you need sox so we can convert/play raw audio files::

  sudo apt-get install sox libsox-fmt-all

Now run the demo which will create a new darker version::

  FORMAT="-s -b 16 -r 8000 -c 1"
  play $FORMAT data/monkeys-8khz-slin.raw
  play $FORMAT data/monkeys-8khz-slin-deepened.raw

You can convert wav/gsm/ogg/etc. files to this format::

  sox lol.mp3 $FORMAT data/lol.raw


To compile your own program using libsoundtouch4c, this should get you

  cp libsoundtouch4c/src/example.c proggy.c
  gcc proggy.c -o my-proggy -g -lsoundtouch4c


If you use GNU AutoTools, you can copy `m4/soundtouch4c.m4` to your
``m4`` directory to check that libsoundtouch4c is installed::


Developer Reference


* ``soundtouch4c_t``: void pointer


* ``soundtouch4c_t SoundTouch_construct(void)``
* ``void SoundTouch_destruct(soundtouch4c_t st)``
* ``void SoundTouch_setRate(soundtouch4c_t st, float newRate)``
* ``void SoundTouch_setTempo(soundtouch4c_t st, float newTempo)``
* ``void SoundTouch_setRateChange(soundtouch4c_t st, float newRate)``
* ``void SoundTouch_setTempoChange(soundtouch4c_t st, float newTempo)``
* ``void SoundTouch_setPitch(soundtouch4c_t st, float newPitch)``
* ``void SoundTouch_setPitchOctaves(soundtouch4c_t st, float newPitch)``
* ``void SoundTouch_setPitchSemiTonesInt(soundtouch4c_t st, int newPitch)``
* ``void SoundTouch_setPitchSemiTonesFloat(soundtouch4c_t st, float newPitch)``
* ``void SoundTouch_setChannels(soundtouch4c_t st, uint numChannels)``
* ``void SoundTouch_setSampleRate(soundtouch4c_t st, uint srate)``
* ``void SoundTouch_flush(soundtouch4c_t st)``
* ``void SoundTouch_putSamples(soundtouch4c_t st, int16_t *samples, uint numSamples)``
* ``void SoundTouch_clear(soundtouch4c_t st)``
* ``int SoundTouch_setSetting(soundtouch4c_t st, uint settingId, uint value)``
* ``uint SoundTouch_getSetting(soundtouch4c_t st, uint settingId)``
* ``uint SoundTouch_numUnprocessedSamples(soundtouch4c_t st)``
* ``uint SoundTouch_receiveSamplesEx(soundtouch4c_t st, int16_t *output, uint maxSamples)``
* ``uint SoundTouch_receiveSamples(soundtouch4c_t st, uint maxSamples)``
* ``uint SoundTouch_numSamples(soundtouch4c_t st)``
* ``int SoundTouch_isEmpty(soundtouch4c_t st)``