===========================================
 QUALCOMM PureVoice Windows/Linux SDK v3.5
===========================================

This QUALCOMM PureVoice SDK provides High level API's and Mid level API's 
that manipulate Microsoft Waveform (.wav) and PureVoice QCP (.qcp) files for
Microsoft Windows and Linux.  It is distributed in two files, according to
the operating system:

    purevoice_sdk-3.5.zip           [Windows]
    purevoice_32bit_sdk-3.5.tar.gz  [Linux-32 bit]
    purevoice_64bit_sdk-3.5.tar.gz  [Linux-64 bit]

This library represents a major redesign of the previous SDK version.  A new
library, the Qualcomm Speech Codec Library (QSCL), obsoletes the old
Qualcomm PureVoice Library (QPL).  The new library is a complete rewrite
with an improved internal structure.  All definitions which could conflict
with Microsoft's COM (e.g. DEFINE_GUID, IUnknown, etc.) have been replaced
with similar definitions (e.g. DEFINE_QSCL_GUID, IQsclUnknown, etc.)


High Level
  * Converts a wave file (8-kHz, 16-bit PCM) into PureVoice (.qcp)
    file and vice versa as well as memory based conversion.


Mid Level
  * Opens .qcp file in either READ or WRITE mode
  * Closes .qcp file
  * Reads blocks of PureVoice data and decodes to linear 8-kHz, 16-bit PCM 
    samples.
  * Writes blocks of PCM data into PureVoice format after encoding.
  * Retrieves a length of file in blocks.
  * Retrieves format information about a file (block size, sampling rate, etc.)

==========
 Contents
==========
  * readme.txt (this file)

Files for Qualcomm Speech Codec Library (QSCL):
  * qscl.h            - Contains the necessary defines and interface classes
  * qscl.dll          - PureVoice library (Windows only,
                        obsoletes old "qpl.dll")
  * qscl.lib          - Import LIB for qscl.dll (Windows only)
  * libqscl.a         - PureVoice library static link archive (Linux only)
  * libqscl.so.1.15.0 - PureVoice library shared object (Linux only)

A sample program which uses QSCL, to convert WAV to QCP in files:
  * example/example.cpp    - Sample source code
  * example/example.vcproj - Project file for Microsoft Visual
                             Studio .NET 2003 (Windows only)
  * example/makefile.linux - Makefile for building example
                             in Linux (Linux only)
  * example/test.wav       - Sample .WAV input file 

Second sample program which uses QSCL, to convert WAV to QCP in memory:
  * example2/example2.cpp    - Sample source code
  * example2/example2.vcproj - Project file for Microsoft Visual
                               Studio .NET 2003 (Windows only)
  * example2/makefile.linux  - Makefile for building example
                               in Linux (Linux only)
  * example2/test.wav        - Sample .WAV input file 

Command line wav<->qcp file conversion tool which can convert wave files 
into QCP files in different rate setttings, including a fixed fullrate:
  * pvconv.exe   [Windows]
  * pvconv       [Linux]

=========================================================
Objects and their interfaces (see qscl.h for more detail)
=========================================================

 QsclFile
  |
  --> IQsclConvertFile [converts .qcp <-> .wav files]
  |     |
  |     |-convertFile  convert qcp to wav and vice-versa
  |     |-getProgress  get progress of conversion
  |
  --> IQsclFile [reads or writes .qcp files]
  |     |
  |     |-open         open file
  |     |-close        close file
  |     |-read         read and decode
  |     |-write        encode and write
  |     |-seek         if reading, change current position in file
  |     |-tell         return current position in file
  |     |-getFileSize  get file length in number of blocks
  |     |-getInfo      return file information structure
  |
  --> IQsclFileOptions
        |
        |-getCnfgChunk  extract optional "cnfg" chunk from QCP file
        |-setCnfgChunk  add/replace optional "cnfg" chunk from QCP file
        |-getTextChunk  extract optional "text" chunk from QCP file
        |-setTextChunk  add/replace optional "text" chunk from QCP file
        |-getLablChunk  extract optional "labl" chunk from QCP file
        |-setLablChunk  add/replace optional "labl" chunk from QCP file

------------------------------------------------------------------------------

 QsclCodecQcelp           - IS-733 Qualcomm PureVoice speech codec
 QsclCodecQcelpSmartRate  - PureVoice in reduced rate mode (SmartRate)
 QsclCodecPcm             - PCM class (used to specify raw audio)
 QsclCodecUlaw            - G.711 (mu-law) audio
  |
  --> IQsclCodec
  |     |
  |     |-configure       specify rate set (full rate, variable rate, etc.)
  |     |                 and set codec-specific mode
  |     |                 parameter (not used for QCELP)
  |     |-getInfo         get info on CODEC
  |     |-getRateSetInfo  return number of bytes needed to store a
  |     |                 packet with a given rate byte
  |     |-getName         return display name of CODEC
  |     |-getVersion      return current version of CODEC
  |     |-getAvgBitrate   return average bitrate of CODEC
  |     |-convert         encode or decode
  |
  --> IQsclError
        |
        |-wasLastError  returns indicator of whether or not
        |               CODEC encountered an error
        |-getLastError  returns display message for last error encountered
 
------------------------------------------------------------------------------

==============================
CHANGES SINCE 3.4
==============================

* Built using the latest GCC compiler, where the latest libstdc++ is used.

* Updated the libqscl library to support the generation of both 32-bit and
  64-bit libraries.

* Updated license and legal information.

==============================
CHANGES SINCE 3.0
==============================

* IQsclCodec::getRateSetInfo now returns 0xFFFFFFFF rather than 0 for rate
  bytes which are not valid for the codec, so that they can be distinguished
  from rates which are valid but have zero payload.

* Fixed bug in handling of seeking with QSCL_HANDLE_CLIENT, which prevented
  it from working when converting files using IQsclConvertFile.

* Fixed bug in IQsclFile::open which caused problems when trying to open
  a QCP file without decoding it.

* Fixed bug in writing RIFF chunks, where area searched for a chunk could
  extend past the end of the file, causing access violations.

* Eased restriction on reading RIFF files with malformed RIFF size field.
  The files will open now without throwing an exception, but if the RIFF
  size field is ignored if it doesn't match the actual file size.

* Added second example, which shows how to perform memory-based file
  conversions using QSCL_HANDLE_CLIENT.

* Name of dynamic link library in Linux is now "libqscl.so.1" instead
  of "libqscl.so", so that dlopen can find the library without the admin
  needing to specifically create a symbolic link - ldconfig will create the
  "libqscl.so.1" link automatically.

* Updated license and legal information.

==============================
CHANGES SINCE 2.1
==============================

* Renamed all symbols which could conflict with Microsoft COM

* Reorganized internals to follow stricter coding guidelines

* No need to reset CODEC to switch between encoding/decoding

* CODEC now can be queried for display name, version, and average bitrate

* Added G.711 (mu-law) audio support (QsclCodecUlaw)

* Added padded, header-less, and native rate sets

* Command line argument -e for pvconv changed to -r, and parameter meaning
  changed from number (e.g. 1, 2, etc.) to identifier (e.g. vfr, ffr, etc.)


==============================
FAQ
==============================
Q: There is one extra byte at the end of the file.
A: This is by design.  The QCP file format follows RIFF file format
   format, which requires that all chunks in the file are word
   (16 bit) aligned.  So if the real size happens to be odd size, then
   we'll add a pad byte.

Q: What happened to IQPLPvHrCodec, IQPLPvVrHrCodec, IQPLPvFrCodec, etc.?
A: Each codec and rate set combination is no longer represented by its own
   interface.  Instead, all codec types use the same new interface,
   IQsclCodec, and the "configure" method of this interface takes a "rateSet"
   argument, to select the rate set combination (e.g. ID_RateVariable for
   variable rate, ID_RateFixedHalfWithHeader for fixed half rate with rate
   byte, etc.)

Q: I recorded a QCP file on my cellphone, but it seems to use some other
   codec besides PureVoice.  The PureVoice player complains about an
   unsupported codec, "TIA IS-127 Enhanced Variable Rate Codec, Speech
   Service Option 3 ".  Does Qualcomm or the PureVoice SDK support this
   codec, and if so how can I obtain that version?
A: This codec, commonly called "EVRC", along with a few other codecs which
   are supported in the QCP file format, contains the intellectual
   property of other companies, which requires licensing from their
   respective owners.  Qualcomm licenses these technologies for
   its own use, but does not pass these licenses onto the users of the
   free PureVoice software.  Please contact your service provider or
   carrier, to inquire about support for codecs such as this one.

Q: I downloaded the "pvconv" program, but it just flashes a window on the
   screen when I run it.  What is going on?
A: The "pvconv" program is what is called a "command-line utility".  It is a
   special program that cannot be run by clicking or double-clicking an icon
   in Windows Explorer or file manager.  It can only be run by typing its
   command name, followed by the name of the file you want to convert, in
   the window of a program commonly called the "DOS prompt", "command prompt",
   or "command-line interpreter".  On modern versions of Microsoft Windows,
   this program can be started by going to the "Start" menu, choosing the
   "Programs" menu option, then the "Accessories" menu option, and then the
   "Command Prompt" menu option.  Next, use the "cd" command to change the
   current working directory to where the pvconv.exe program is located on
   your hard drive.  Then, type "pvconv <filename>", where <filename> is the
   complete path to the file you want to convert
   (e.g. "C:\downloads\mysound.wav").


==============================
LICENSE AND LEGAL INFORMATION
==============================

Copyright (c) 2010 QUALCOMM Incorporated. All rights reserved. QUALCOMM, QCELP, and PureVoice are registered
trademarks of QUALCOMM Incorporated. QUALCOMM is also a registered servicemark of QUALCOMM Incorporated.
Windows is a trademark of Microsoft Corporation registered in the U.S. and other countries. All other trademarks and
service marks are the property of their respective owners

Please refer to 'pv_license.pdf' for the license and legal information.
