Codec 2 README
--------------

Codec 2 is an open source (LGPL licensed) speech codec for 3200 bit/s
and below.  For more information please see:

    http://rowetel.com/codec2.html

Also included is a FDMDV modem (README_fdmdv.txt), a coherent PSK
modem and an API for embedding FreeDV in other programs (see example
below).  For more information on building Codec 2 see README.cmake

SVN Repository
--------------

Check out the latest (development branch) code using:

  $ svn co https://svn.code.sf.net/p/freetel/code/codec2-dev codec2-dev

There are 3rd party GIT mirrors of Codec2 and FreeDV. Use Git at your
own risk.

  GIT IS NOT SUPPORTED!!!

All patches, support questions etc, need to be against the SVN
repository above.

Please do not email me (David), or the codec2-dev mailing list
suggesting we change to Git.  I get these emails every week.  Really,
I understand the arguments, but am content with SVN for now.

Quickstart
----------

Refer to INSTALL for more general building and installing instructions.

NOTE: You may not have the necessary speex libraries installed. Some
      distributions may have packages available 
      i.e. sudo apt-get install speex-*
      alternatively, visit http://www.speex.org and follow the instructions

1/ Listen to Codec 2:

   $ cd codec2-dev
   $ mkdir build_linux
   $ cd build_linux
   $ cmake ..
   $ make
   $ ./src/c2demo ../raw/hts1a.raw hts1a_c2.raw
   $ play -t raw -r 8000 -e signed-integer -b 16 ../raw/hts1a.raw
   $ play -t raw -r 8000 -e signed-integer -b 16 ./hts1a_c2.raw

2/ Compress, Decompress and then play a file:

   using 2400 bps bit rate encoding

   $ ./src/c2enc 2400 ../raw/hts1a.raw hts1a_c2.bit
   $ ./src/c2dec 2400 hts1a_c2.bit hts1a_c2_2400.raw 

   which can be played with

   $ play -t raw -r 8000 -e signed-integer -b 16 ./hts1a_c2_2400.raw

   using 700 bps bit rate encoding

   $ ./src/c2enc 700 ../raw/hts1a.raw hts1a_c2.bit
   $ ./src/c2dec 700 hts1a_c2.bit hts1a_c2_700.raw

   which can be played with

   $ play -t raw -r 8000 -e signed-integer -b 16 ./hts1a_c2_700.raw

3/ Same thing with pipes:

   $ ./src/c2enc 1300 ../raw/hts1a.raw - | ./src/c2dec 1300 - - | play -t raw -r 8000 -s -2 -

Embedded FreeDV API
-------------------

See freedv_api.h and freedv_api.c, and the demo programs freedv_tx &
freedv_rx.  Quickstart:

  $ ./freedv_tx 1600 ../../raw/hts1.raw - | ./freedv_rx 1600 - - | play -t raw -r 8000 -s -2 -q -
  $ cat freedv_rx_log.txt

Programs
--------
 
1/ c2demo encodes a file of speech samples, then decodes them and
saves the result.

2/ c2enc encodes a file of speech samples to a compressed file of
encoded bits.

3/ c2dec decodes a compressed file of bits to a file of speech
samples.

4/ c2sim is a simulation/development version of Codec 2.  It allows
selective use of the various Codec 2 algorithms.  For example
switching phase modelling or LSP quantisation on and off.

Debugging
---------

1/ To compile with debug symbols for using gdb:

  $ cd ~/codec2
  $ rm -Rf build_linux && mkdir build_linux
  $ cd build_linux
  $ CFLAGS=-g cmake ..
  $ make

2/ For dump file support:

  $ cd ~/codec2
  $ rm -Rf build_linux && mkdir build_linux
  $ cd build_linux
  $ CFLAGS=-DDUMP cmake ..
  $ make

Building Unit Tests
-------------------

The unittests are no longer built by default.  To build them:

  $ cd ~/codec2
  $ rm -Rf build_linux && mkdir build_linux
  $ cd build_linux
  $ cmake -DCMAKE_BUILD_TYPE=Debug ..
  $ make


Directories
-----------

  asterisk &  - unmaintained Asterisk support
  asterisk-11 
  cmake       - cmake support files
  octave      - Octave scripts used to support development
  script      - shell scripts for playing and converting raw files
  src         - C source code for Codec 2, FDMDV modem, COHPSK modem, FreeDV API
  raw         - speech files in raw format (16 bits signed linear 8 kHz)
  stm32       - Support for the STM32F4 microcontroller and SM1000 FreeDV Adaptor
  unittest    - unit test source code
  wav         - speech files in wave file format