TwinVQ encoder description

(C)Copyright 2000 NTT Cyber Space Laboratories

# TwinVQ encoder manual

TwinVQ Ver. 2.3

2000.10.4

NTT Cyber Space Labs.
Media Processing Project

Contents

- 1. Outline
  - 1.1 Contents of the package
  - 1.2 Structure of TwinVQ encoder
    - 1.2.1 TwinVQ is
    - 1.2.2 Data structure of TwinVQ
    - 1.2.3 Fundamental structure of TwinVQ
    - 1.2.4 Descriptions of each part
- 2. Construction of TwinVQ encoder
  - 2.1 Calling sequence
  - 2.2 Detail procedures
    - 2.2.1 Initialization
    - 2.2.2 Frame wise data acquisition
    - 2.2.3 Encoding
    - 2.2.4 Output bit streams
    - 2.2.5 Termination
- 3. Sample program based on encoder DLL
  - 3.1 Compile
  - 3.2 Execution
- 4. Manual of major functions
  - 4.1 TwinVQ encoder modules (encoder DLL)
  - 4.2 Bit stream writing modules
  - 4.3 Header generation modules
  - 4.4 Acquisition of audio data

## 1. Outline

### Contents of the package

Necessary files for TwinVQ DLL

tvqenc.dll
  TwinVQ encoder DLL
tvqenc.lib
  TwinVQ import library
tvqenc.h
  TwinVQ encoder header comprising function definition for DLL
twinvq.h
  TwinVQ header comprising function definition

Sample program for TwinVQ DLL

TestEnc.exe
  Encoder executable (console)
encoder.cxx
  encoder main program (console)
simple_enc.cxx
  encoder main program (minimum)
bstream_e.cxx, bstream_e.h
  TwinVQ bit stream generator
bfile_e.cxx, bfile_e.h, bfile.cxx, bfile.h
  Bitwise read/write program
Chunk.cxx, Chunk.h, ChunkHelper.cxx, ChunkHelper.h
  Header data generation program
TestEnc\
  workspace directory

### 1.2 Structure of TwinVQ

#### 1.2.1 TwinVQ is

TwinVQ is an audio coding software which converts audio signals into compressed bit streams

#### 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 Fundamental structure of TwinVQ encoder

TwinVQ encoder program consists of 5 processing modules as shown in Fig.2

Fig. 2 Structure of TwinVQ encoder program

#### 1.2.4 Description of each part

main program
  This module controls all TwinVQ processing modules and user interfaces.
  ->encoder.cxx
TwinVQ encoder (encoder DLL)
  This module compresses audio data (float PCM data) to TwinVQ index (struct data)
  ->tvqenc.dll
header generation
  Header information is written in header data object. -> Chunk.cxx, ChunkManager.cxx
Bit stream generation
  THis module makes TwinVQ output data from header data and audio data (Index struct)
  -> bstream_c.cxx, bfile.cxx
Audio data input
  This module converts audio input signal to internal audio data (float)
  ->encoder.cxx ( frtobuf(), fwrite() )

## 2. Construction of encoder

### 2.1 Calling procedure

Brief procedure of encoder is shown as follows.

    {
        < initilize >
        while( < read audio data frame by frame  >){
            < encoding >
            < bit stream generation >
        }
        < termination >
    }

This procedure is included in main program. Refer to `main() (encoder.cxx)`

### 2.2 Detailed process

#### 2.2.1 Initialization

Initialization is needed prior to the encoding process. Refer to encoder initialization manual for detail

#### 2.2.2 Read data frame by frame

In sample program, input audio data in 16 bit PCM format is obtained by `fread()` every frame. From "L,R,L,R" signed short data is converted to internal (float) data array by `buftofr()`

#### 2.2.3 Encoding

Audio data is compressed into INDEX format by using `TvqEncodeFrame()`

#### 1.2.4 Bit stream generation

From INDEX format data binary bit stream data is generated by `TvqWriteBsFrame()`

#### 2.2.5 Termination

Termination is

- Termination of encoder by means of TvqEncTerminate()
- Release memory by free()

## Sample program for encoder DLL

### 3.1 Compile

TestEnc.exe can be build in TestEnc.dsw workspace of VC++ 6.0. For Linux users, do "make" in "ModEnc/" directory.

### 3.2 Execution

Execution is done in DOS prompt environment

    	TestEnc [option] <inpu data file > <Output bit stream file >

The options are listed below. Possible option set is described here.

Table 1: Command line options
setup parameters | option name | default | remarks
sampling frequency | -f <#> | 44 | 44 (44.1 kHz) for example
total bitrate [kbit/s] | -b <#> | 96 |
channel mode | -c <#> | 1 stereo | monaural :0
N_CAN | -n <#> | 16 | either 4, 8, 16, 32 the larger number, the higher quality and the slower.
file type | -t <string> | "wav" | wav or raw (no header)
title | -T <string> | "" |
comment | -C <string> | "" |
artist | -A <string> | "" |
copyright information | -R <string> | "" |
direcoty name for header contents | -h <string> | "header_info" | directory for header information

Input audio signal is assumed to be signed 16 bit PCM (2Byte per sample). Stereo signal has sample order of L, R, L, and R.

All standard chunk contents in a header information can be specified by command line. Optional chunk contents can be specified by parameter file in the directory of header_info. The SCND subchunk can be specified by parameter files in the directory of header_info\SCNDheader_info can be specified by -h option. Detailed header format is described in TwinVQ data format manual.

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

## 4. Function manual

### 4.1 TwinVQ encoder module (encoder DLL)

The encoder DLL functions can be divided into following three categories

1. initialize/termination
2. encode process
3. inquiry

Prior to the encoding process for each frame, initialization is needed. Inquiry functions are used for getting various TwinVQ parameters.

Available DLL's are listed below.

Table 2: TwinVQ encoder module functions
category | function name | essential | outline
Initialization | `TvqEncInitialize()` | Yes | TwinVQ encoder initialization
`TvqEncTerminate()` | Yes | TwinVQ encoder termination
`TvqEncGetVectorInfo()` | Yes | information initialization for TwinVQ bit stream output
`TvqEncResetFrameCounter()` |  | reset frame counter
encoding | `TvqEncodeFrame()` | Encode | Frame wise encoding process
`TvqEncUpdateVectorInfo()` | Yes | update information for TwinVQ bit stream generation
`TvqEncSetFrameCounter()` |  | set frame counter
inquiry | `TvqEncCheckVersion()` | Yes | version ID number
`TvqGetVersionID()` | Yes | version ID string
`TvqEncGetSetupInfo()` |  | setup information
`TvqEncGetConfInfo()` | Yes | configuration parameter for TwinVQ
`TvqEncGetFrameSize()` | Yes | frame size
`TvqEncGetNumChannels()` | Yes | Channel number
`TvqEncGetBitRate()` |  | bit rate
`TvqEncGetSamplingRate()` |  | sampling rate
`TvqEncGetNumFixedBitsPerFrame()` | Yes | number of bits
`TvqEncGetNumPreCand()` |  | number of preselection candidates
`TvqEncGetNumFrames()` |  | frame counter
`TvqEncGetModuleVersion( )` |  | encoder module version

### 4.2 Bit stream generation module

Table 3: Bitstream generation module functions
category | function name | mandatory | outline
initialization | `TvqPutBsHeaderInfo()` | Yes | output bit stream header
`TvqinitBsWriter()` | Yes | initialization output module
framewise process | `TvqWriteBsFrame()` | Yes | framewise bit stream generation

### 4.3 Header generation module

`TvqCreateHeaderChunk()`
  generation of header chunk

### 4.4 Audio data input

`buftofr()`
  conversion from audio file to input buffer