=========================================== QUALCOMM PureVoice Windows/Linux SDK v3.1 =========================================== 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: purevoicesdk3_1.zip [Windows] purevoicesdk3_1_tar.gz [Linux] 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.1.4 - 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.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 ", where is the complete path to the file you want to convert (e.g. "C:\downloads\mysound.wav"). ============================== LICENSE AND LEGAL INFORMATION ============================== THIS PRODUCT CONTAINS SOFTWARE, THE USE OF WHICH IS LICENSED BY ______________________________________ (LICENSOR) TO ITS CUSTOMERS FOR THEIR USE ONLY AS SET FORTH BELOW. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS AGREEMENT, DO NOT USE THE SOFTWARE. USING ANY PART OF THE SOFTWARE INDICATES THAT YOU ACCEPT THESE TERMS. Licensor grants to the user a nonexclusive license to use the accompanying software programs (the "Software"), subject to the terms and conditions set forth in this License Agreement, solely for use on general-purpose computer systems or servers running on Windows, Macintosh, Linux or Unix operating systems (a) to only encode QCELP content (convert to the QCELP format) for personal or business purposes, or (b) to encode and decode QCELP content solely for personal or internal business purposes . The user may not commercially distribute, sublicense, resell, or otherwise transfer for any consideration, or reproduce for any such purposes, the Software or any modification or derivation thereof, either alone or in conjunction with any other product or program. The user may not modify the Software. Further, no license is granted to user in the human readable code of the Software (source code). Except as expressly provided herein, this License Agreement does not grant you any rights to patents, copyrights, trade secrets, trademarks, or any other rights in respect to the Software. Modification, reverse engineering, reverse compiling, or disassembly of the Software is expressly prohibited. If applicable law limits such activities, any information so discovered must be promptly disclosed to Licensor and shall be deemed to be the confidential proprietary information of Licensor's licensor. The user shall not export or re-export the Software or accompanying documentation (or any copies thereof) or any products utilizing the Software or such documentation in violation of any applicable laws or regulations of the United States or the country in which you obtained them. You acknowledge and agree that the structure, sequence and organization of the Software are the valuable trade secrets of Licensor and its licensors. You agree to hold such trade secrets in confidence. You further acknowledge and agree that ownership of, and title to, the Software and all subsequent copies thereof regardless of the form or media are held by Licensor and/or its licensors. THE SOFTWARE IS PROVIDED TO THE USER ''AS IS.'' LICENSOR AND/OR ITS LICENSORS MAKE NO WARRANTIES, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THE SOFTWARE AND/OR ASSOCIATED MATERIALS PROVIDED TO THE USER, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR AGAINST INFRINGEMENT. LICENSOR AND/OR ITS LICENSORS DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED. FURTHERMORE, LICENSOR AND/OR ITS LICENSORS DO NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE OR ANY DOCUMENTATION PROVIDED THEREWITH IN TERMS OF THEIR CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY LICENSOR OR A LICENSOR AUTHORIZED REPRESENTATIVE SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE THE SCOPE OF THIS WARRANTY. LIMITATION OF LIABILITY - LICENSOR AND ITS LICENSORS ARE NOT LIABLE FOR ANY CLAIMS OR DAMAGES WHATSOEVER, INCLUDING PROPERTY DAMAGE, PERSONAL INJURY, INTELLECTUAL PROPERTY INFRINGEMENT, LOSS OF PROFITS, OR INTERRUPTION OF BUSINESS, OR FOR ANY SPECIAL, CONSEQUENTIAL OR INCIDENTAL DAMAGES, HOWEVER CAUSED, WHETHER ARISING OUT OF BREACH OF WARRANTY, CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE. This License Agreement is effective until terminated. You may terminate it at any time by destroying the Software and documentation together with all copies and merged portions in any form. It will also terminate immediately if you fail to comply with any term or condition of this License Agreement. Upon such termination you agree to destroy the Software and documentation, together with all copies and merged portions in any form. This License Agreement shall be governed by the laws of the State of California without regard to conflict of law principles. Any action to construe or enforce this License Agreement shall be brought only in a court of competent jurisdiction in San Diego County, California. Copyright (c) 2004 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