(C)Copyright 2000 NTT Cyber Space Laboratories

TwinVQ decoder manual

TwinVQ Ver. 2.3

2000.10.4

NTT Cyber Space Labs.
Media Processing Project

Table of contents

1. Outline

1.1 Contents of the package

* Files for TwinVQ DLL
tvqdec.dll
TwinVQ decoder DLL
tvqdec.lib
Inport library for TwinVQ decoder DLL
tvqdec.h
Header file including declaration of TwinVQ decoder DLL

twinvq.h
Header file including definition of TwinVQ
* Sample program using TwinVQ decoder DLL
TestDec.exe
TwinVQ decoder executable code (console)
decoder.cxx
TwinVQ decoder main program (console)
simple_dec.cxx
Minimum version of the main program
bstream.cxx, bstream.h
TwinVQ bitstream reading functions
bfile.cxx, bfile.h
Bitwise read functions.
HeaderManager.cxx, HeaderManager.h, Chunk.cxx, Chunk.h
Modules for processing of bit stream header.
TestDec\
Workspace directory for TwinVQ test decoder

1.2 Structure of TwinVQ decoder

1.2.1 TwinVQ decoder

TwinVQ decoder is a program which decodes TwinVQ compressed bit stream and generates output signal. In sample program, both input and output are assumed file.

1.2.2 Data structure of TwinVQ

TwinVQ has data structure shown in Fig.1. The audio part consists of compressed bit streams, and the header part includes decoding parameters and side information.

TwinVQ data structure

Details are described in the data format manual.

1.2.3 Structure of TwinVQ decoder

TwinVQ decoder program consists of five major modules shown in Fig.2. Interface of green line depends on the input and output devices.

TwinVQ decoder
Fig. 1 Structure of TwinVQ decoder

1.2.4 Description of each module

main program
This program controls all modules including user interface modules.
-> decoder.cxx
TwinVQ decoder (decoder DLL)
This module decompress the TwinVQ bit stream. Input is a struct (INDEX) of compressed data and output is float array of PCM data.
-> tvqdec.dll
Header manager
This module stores header information in the form of CHeaderManager class of C++. The initialization module of bit stream decoding gets header information from header data object (instance of CChunkChunk object)
-> HeaderManager.cxx, Chunk.cxx
Reading bit stream
This module reads both header and compressed audio bit stream, and converts them into BCChunkChunk object and INDEX struct respectively. A file is used as input device in the sample program, although various input devices are allowable. BFILE type file pointer is used.
-> bstream.cxx, bfile.cxx
Audio data output
This module converts TwinVQ internal audio data into output data depending on the output interface. Output device is a file in the sample program.
-> decoder.cxx ( frtobuf(), fwrite() )

Construction of decoder program


2.1 Calling sequence of decoder functions

{
    <initialization >
    while( < reading bit stream > ){
        < decode process >
        < output process >
    }
    < termination >
}

Above procedures are included in main() (decoder.cxx)

2.2 Detailed procedure for each module

2.2.1 Initialization

Both decoder module and bit stream reading module are initialized. Memory allocation (flat array) is necessary for audio output. (Refer to TvqDecodeFrame() .)

Initialization should be carried out as the following order. For details, refer to InitializeDecoder() (decoder.cxx)

  1. Read bit stream header and generate header data object.... TvqGetBsHeaderInfo()
  2. Initialize header object... CHeaderManager::Create()
  3. Get decoder setup information... TvqGetStandardChunkInfo()
  4. Initialize TwinVQ decoder module... TvqInitialize()
  5. Initialize bit stream reading module... TvqInitBsReader()
  6. Initializa audio output module... TvqGetFrameSize(), TvqGetNumChannels() and malloc().

After initialization, header information can be retrieved by using header manager. Refer to message().

2.2.2 Bit stream reading

Bit stream reading is carried out every frame. In sample program, TvqReadBsFrame() reads bit stream and converts the information into (INDEX) format for TwinVQ decoder module.

2.2.3 Decoding

INDEX format is decompressed to audio signal by TvqDecodeFrame().

2.2.4 Audio output

Audio signal is written to output device. In sample program, frtobuf() converts the audio signal into 16 bit PCM, and fwrite() writes it on output file.

2.2.5 Termination

Termination process is needed at the end of bit stream.


3. Operation of sample program

3.1 compile

TestDec.exe can be build by Visual C++ 6.0 using workspace TestDec.dsw or ModEnc.dsw. For Linux users, do "make" in "ModEnc/" directory.

3.2 Execution

Decoder can be executed in DOS prompt (command prompt for Windows NT) as follows.


    > TestDec <bitstream file name > <output file name > [ff | rew]

For output file, both *.wav format and headerless signed 16-bit integer format are supported. Every sample is stored in 2 Bytes. In case of stereo, samples are stored in the order of L, R, L, R.

ff or rew option is used for Fast Forward and Rewind demonstration.

There is minimum version of the main program, simple_dec.cxx, in the package. The decoder.cxx file can be replaced by this program.


4. Manual of functions

4.1 TwinVQ decoder module

TwinVQ decoder module is provided in DLL form. Functions can be classified into the following three categories.

  1. initialization/termination
  2. decoding process
  3. inquiry function

Functions are listed below.

Table 1: TwinVQ decoder module functions
category function name mandatory outline
initialization/termination TvqInitialize() Yes initialize decoder module
TvqTerminate() Yes terminate decoder module
TvqGetVectorInfo() Yes Initialize setup information
TvqResetFrameCounter()   reset frame counter
decode process TvqDecodeFrame() Yes frame wise decoding process
TvqWtypeToBtype() Yes translate window-type to block-type
TvqUpdateVectorInfo() Yes update setup information
TvqSetFrameCounter()   set frame counter
inquiry TvqCheckVersion() Yes format version ID
TvqGetSetupInfo()   setup information
TvqGetConfInfo() Yes quntizater configuration parameter
TvqGetFrameSize() Yes frame size
TvqGetNumChannels() Yes number of channels
TvqGetBitRate()   bit rate
TvqGetSamplingRate()   sampling rate
TvqGetNumFixedBitsPerFrame() Yes bits per frame
TvqGetNumFrames()   frame counter
TvqGetModuleVersion()   version of software

4.2 bit stream reading

Table 2: bitstream reading functions
category function mandatory outline
initialize TvqGetBsHeaderInfo() Yes read bit stream header
TvqinitBsReader() Yes initialize bit stream reading module
process TvqReadBsFrame() Yes frame wise bit stream reading
TvqSkipFrame()   frame skip
TvqGetBsFramePoint()   current frame number

4.3 Header manager

Header manager is prepared as CHeaderManager class of C++.

4.4 Audio output

frtobuf()
convert signal values to output buffer in PCM format.

4.5 Other utility

CChunk
header data chunk class.
bopen(), bclose(), bread(), bwrite(), bseek()
bit stream I/O functions.