TwinVQ decoder DLL

(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

- Contents
  - 1.1 Contents of the package
  - 1.2 Structure of TwinVQ decoder DLL
    - 1.2.1 TwinVQ is
    - 1.2.2 Data structure of TwinVQ
    - 1.2.3 Structure of TwinVQ decoder module
    - 1.2.4 Description of elementary modules
- 2.2 Construction of decoder program
  - 2.1 Calling sequence of decoder functions
  - 2.2 Description of each procedure
    - 2.2.1 Initialization
    - 2.2.2 Reading bit stream
    - 2.2.3 decoding
    - 2.2.4 Output
    - 2.2.5 Termination
- 3. Operation of sample program
  - 3.1 Compile
  - 3.2 Execution
- 4. Manual of functions
  - 4.1 TwinVQ decoder DLLL
  - 4.2 Bit stream input module
  - 4.3 Header manager module
  - 4.4 Audio output module
  - 4.5 Utilities

## 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.

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.

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.

- termination of TwinVQ decoder... `TvqTerminate()`
- release memory...free()

## 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.