TwinVQ デコーダ DLL 説明書

(C)Copyright 2000 NTT Cyber Space Laboratories

# TwinVQ デコーダ説明書

TwinVQ Ver. 2.3

平成12年10月4日

NTT サイバースペース研究所
メディア処理プロジェクト

目次

- １．概要
  - １．１　パッケージの内容
  - １．２　TwinVQ デコーダの構成
    - １．２．１　TwinVQ デコーダとは
    - １．２．２　TwinVQ データの構成
    - １．２．３　TwinVQ デコーダの基本構成
    - １．２．４ 各部の説明
- ２．デコーダプログラムの構成方法
  - ２．１　デコーダ関数の呼出し手順
  - ２．２　各手順ブロックの詳細
    - ２．２．１　初期化
    - ２．２．２　ビットストリームの読出し
    - ２．２．３　デコード処理
    - ２．２．４　出力処理
    - ２．２．５　終了処理
- ３．サンプルプログラムの操作方法
  - ３．１　コンパイル
  - ３．２　実行
- ４．主な関数のマニュアル
  - ４．１　TwinVQ デコーダモジュール(デコーダDLL）
  - ４．２　ビットストリーム読み出しモジュール
  - ４．３　ヘッダマネージャモジュール
  - ４．４　オーディオデータ出力
  - ４．５　その他ユーティリティ

## １．概要

### １．１　パッケージの内容

パッケージに入っているファイルは以下のとおりです。

●TwinVQ DLL 利用に必要なファイル：

tvqdec.dll
  TwinVQ デコーダ DLL
tvqdec.lib
  TwinVQ デコーダDLLのインポートライブラリ
tvqdec.h
  TwinVQ デコーダDLL関数の宣言を含むヘッダファイル
twinvq.h
  TwinVQ関連の定義情報を含むヘッダファイル

●TwinVQ DLL 利用のサンプルプログラム：

TestDec.exe
  テストデコーダの実行ファイル（コンソールアプリケーション）
decoder.cxx
  デコーダメインプログラム (コンソールプログラム)
simple_dec.cxx
  最小版デコーダメインプログラム
bstream.cxx, bstream.h
  TwinVQビットストリーム読出しルーチン群
bfile.cxx, bfile.h
  ファイルへのビット単位読出しツールプログラム
HeaderManager.cxx, HeaderManager.h, Chunk.cxx, Chunk.h
  ビットストリームファイルのヘッダ読み出しプログラム
TestDec\
  サンプルプログラムをコンパイルするためのワークスペースディレクトリ

### １．２　TwinVQ デコーダの構成

#### １．２．１　TwinVQ デコーダとは

TwinVQ デコーダは、圧縮された TwinVQ データ（ビットストリーム）を解凍し、オーディオデータを出力するプログラムです。

TwinVQ データの入力デバイスと、オーディオデータの出力デバイスは、決められたインタフェースに従った入出力ができれば何であってもかまいません。サンプルプログラムでは、入力も出力もファイルに対して行っています。

#### １．２．２　TwinVQ データの構成

TwinVQ データの形式はあらかじめ決まっており、図１のようにヘッダ部とオーディオデータ部を持っています。オーディオデータ部には、圧縮されたオーディオ信号が記録されています。ヘッダ部には、オーディオデータを解凍するのに必要なパラメータや、曲名などの、補助情報が記録されています。

図１： TwinVQ データの基本構造

なお、TwinVQ データ形式についての詳細については、TwinVQ データフォーマット説明書をご覧ください。

#### １．２．３　TwinVQ デコーダの基本構成

TwinVQ デコーダプログラムは図２のように、５つのモジュールで構成します。モジュール間では、様々な形式でデータがやり取りされます。データの流れのうち、緑色の線で書かれたものは、入出力デバイスの種類によってインタフェースが変わります。サンプルプログラムでは、入力側も出力側もファイル入出力と標準出力のインタフェースを使っています。

図２：TwinVQ デコーダプログラムの構成

#### １．２．４ 各部の説明

メインプログラム
  TwinVQ デコーダの各モジュールの動作を制御します。ユーザインタフェースもこの部分に持たせます。
  ⇒対応ファイル： decoder.cxx
TwinVQデコーダ（デコーダＤＬＬ）
  TwinVQ オーディオデータを解凍してオーディオデータを出力します。TwinVQオーディオデータは、 TwinVQオーディオデータ構造体 (INDEX)形式で入力し、出力オーディオデータには float型の配列に記録されたPCM形式を使います。
  このモジュールは DLL の形態（デコーダDLL）で提供しています。
  ⇒対応ファイル： tvqdec.dll
ヘッダマネージャ
  ヘッダ情報を整理して保管します。あるヘッダ情報について取得のリクエストがあると、その情報を渡します。
  ヘッダマネージャは、C++クラス(CHeaderManager)により実現しています。初期化時にヘッダのデータが必要ですので、ヘッダデータオブジェクト（CChunkChunk クラスのインスタンス）を参照します。
  ⇒対応ファイル： HeaderManager.cxx, Chunk.cxx
ビットストリーム読出し
  入力された TwinVQ データを解読し、ヘッダデータとTwinVQオーディオデータそれぞれについて、ヘッダマネージャとTwinVQデコーダに読み取れるデータ形式（CChunkChunk クラスのオブジェクトとINDEX構造体）に変換します。様々な入力デバイスの形態の違いは、このモジュールで吸収します。サンプルプログラムでは、ファイル入力の形態で提供しています。ファイルポインタとして、ビットストリーム読み書き用のファイル型 BFILE 型のポインタを使っています。
  ⇒対応ファイル： bstream.cxx, bfile.cxx
オーディオデータ出力
  TwinVQ デコーダモジュールから受け取った内部形式のオーディオデータを、出力デバイスのインタフェースに変換して出力します。サンプルプログラムでは、ファイル出力の形態で提供しています。
  ⇒対応ファイル： decoder.cxx ( frtobuf(), fwrite() )

## ２．デコーダプログラムの構成方法

### ２．１　デコーダ関数の呼出し手順

デコーダを動作させる手順の概要は以下のとおりです。

    {
        <初期化>
        while( <ビットストリームのフレームごとの読出し> ){
            <デコード処理>
            <出力処理>
        }
        <終了処理>
    }

この手順はデコーダメインプログラムに持たせます。詳しくは、サンプルプログラムの main() (decoder.cxx) 関数を参照してください。

以降のセクションでは、上の手順の各ブロックについての説明をします。

### ２．２　各手順ブロックの詳細

#### ２．２．１　初期化

初期化は、TwinVQ デコーダプログラムを動作させる前に必ず行う必要があります。

初期化ブロックでは、TwinVQ を構成する全モジュールの初期化を行います。

初期化は、TwinVQデコーダモジュールとビットストリーム読出しモジュールの両方について行います。また、オーディオデータ出力用の float 配列のメモリアロケーションを行っておく必要があります（TvqDecodeFrame() のマニュアル参照）。

これらの初期化処理は次の順序で行ってください。詳しくは、サンプルプログラム中 `InitializeDecoder()` (decoder.cxx) を参照してください。

1. ビットストリームヘッダを読み出し、ヘッダデータオブジェクトを生成する... `TvqGetBsHeaderInfo()`
2. ヘッダマネージャを生成・初期化する... `CHeaderManager::Create()`
3. デコーダセットアップ情報を取得する ... `TvqGetStandardChunkInfo()`
4. TwinVQデコーダモジュールの初期化... `TvqInitialize()`
5. ビットストリーム読出しモジュールの初期化... `TvqInitBsReader()`
6. オーディオデータ出力モジュールの初期化... `TvqGetFrameSize(), TvqGetNumChannels()` と `malloc()` 等

なお、初期化後には、ヘッダマネージャにアクセスすることにより、ヘッダ情報を表示することができます。詳しくは、サンプルプログラムのメインプログラム中の `message()` 関数を参照してください。

#### ２．２．２　ビットストリームの読出し

ビットストリームの読出しは、フレームごとに行います。添付のサンプルプログラムでは、`TvqReadBsFrame()` 関数がソースコードで用意されています。この関数は、ビットストリームを解読し、TwinVQデコーダモジュールに入力できる符号化インデックス (`INDEX`) 形式に変換します。

#### ２．２．３　デコード処理

デコード処理では、INDEX 形式のビットストリーム情報を解凍してオーディオ信号を出力します。`TvqDecodeFrame()` 関数を使います。

#### ２．２．４　出力処理

フレームごとに、オーディオデータを書き込みます。サンプルプログラムでは、`frtobuf()` 関数を使って TwinVQ の出力オーディオフレームを 16 bit PCM データに変換しています。この PCM データを `fwrite()` 関数を使ってファイルに出力します。

#### ２．２．５　終了処理

終了処理は、一つのビットストリームをデコードした後に必ず行う必要があります。終了処理として、以下の項目を行う必要があります。順序の制約はありません。

- TwinVQデコーダモジュールの終了処理... `TvqTerminate()`
- 初期化の際データバッファに割り当てたメモリの解放... free() 等。

## ３．サンプルプログラムの操作方法

### ３．１　コンパイル

パッケージには、コンパイル済みの実行ファイル TestDec.exe がすでに入っていますが、改めてコンパイルする場合には、Visual C++ 6.0 用のワークスペース TestDec.dsw または ModEnc.dsw を使ってビルドしてください。Linux システムでお使いの場合には、ModEnc ディレクトリ上で、make してください。

### ３．２　実行

DOS プロンプト(Windows NT の場合はコマンドプロンプト)から実行します。

        > TestDec <ビットストリームファイル名> <出力オーディオファイル名> [ff | rew]

で実行できます。
サポートしている出力オーディオファイルの形式は、*.wav 形式またはヘッダなし 符号つき 16 bit PCM です。１サンプルは　2Byte データで格納されています。ステレオの場合は、L, R, L, R の順でサンプルが並んでいます。
引数リストに ff または rew を入れると、FF または REW 再生のデモンストレーションモードになります。

なお、デコーダサンプルプログラム decoder.cxx の他に、TwinVQ デコーダを最小限に構成する simple_dec.cxx が収納されています。このプログラムは decoder.cxx と差し替えて利用することができます。

## ４．主な関数のマニュアル

### ４．１　TwinVQ デコーダモジュール(デコーダDLL）

TwinVQ デコーダモジュールは、デコーダ DLL から提供されています。デコーダ DLL 関数は、次の3つのカテゴリーに分けられます。

1. 初期化／終了処理用関数
2. デコード処理用関数
3. 問い合わせ関数

使用できるデコーダ DLL 関数は以下の表のとおりです。

表１：　使用できるデコーダ DLL 関数
カテゴリ | 関数名 | 必須 | 概要
初期化／終了処理用関数 | `TvqInitialize()` | ○ | TwinVQ デコーダモジュールを初期化する。
`TvqTerminate()` | ○ | TwinVQ デコーダモジュールの終了処理をする。
`TvqGetVectorInfo()` | ○ | VQ ビット情報を初期化する。ビットストリーム読み出しモジュールのサブプログラム。
`TvqResetFrameCounter()` |  | フレームカウンタをリセットする。
デコード処理用関数 | `TvqDecodeFrame()` | ○ | フレームごとにデコード処理をする
`TvqWtypeToBtype()` | ○ | ウィンドウタイプをブロックタイプに翻訳する。ビットストリーム読み出しモジュールのサブプログラム。
`TvqUpdateVectorInfo()` | ○ | VQ ビット情報を更新する。ビットストリーム読み出しモジュールのサブプログラム。
`TvqSetFrameCounter()` |  | フレームカウンタを任意の値にセットする。
問い合わせ関数 | `TvqCheckVersion()` | ○ | バージョン ID 番号
`TvqGetSetupInfo()` |  | セットアップ情報
`TvqGetConfInfo()` | ○ | TwinVQ モジュールの設定パラメータ
`TvqGetFrameSize()` | ○ | フレームサイズ
`TvqGetNumChannels()` | ○ | チャネル数
`TvqGetBitRate()` |  | ビットレート
`TvqGetSamplingRate()` |  | サンプリング周波数
`TvqGetNumFixedBitsPerFrame()` | ○ | １フレームあたりのビット数
`TvqGetNumFrames()` |  | フレームカウンタの値
`TvqGetModuleVersion()` |  | TwinVQ デコーダモジュールのバージョン

### ４．２　ビットストリーム読み出しモジュール

表２：　使用できるビットストリーム読み出しモジュール関数
カテゴリ | 関数名 | 必須 | 概要
初期化用 | `TvqGetBsHeaderInfo()` | ○ | ビットストリームヘッダの読み取り
`TvqinitBsReader()` | ○ | ビットストリーム読み出しモジュールの初期化
提供機能 | `TvqReadBsFrame()` | ○ | ビットストリームのフレーム単位の読み取り
`TvqSkipFrame()` |  | ビットストリームのフレーム単位のスキップ
`TvqGetBsFramePoint()` |  | ビットストリームの現在位置をフレーム番号で返す

### ４．３　ヘッダマネージャモジュール

ヘッダマネージャは、`CHeaderManager` クラスとして用意されています。

### ４．４　オーディオデータ出力

`frtobuf()`
  TwinVQ 出力データフレームを PCM データバッファに変換する。

### ４．５　その他ユーティリティ

CChunk
  ヘッダデータチャンククラス
bopen(), bclose(), bread(), bwrite(), bseek()
  ビットストリームファイル読み書き関数