TwinVQ エンコーダ DLL 説明書

(C)Copyright 2000 NTT Cyber Space Laboratories

# TwinVQ エンコーダ説明書

TwinVQ Ver. 2.3

平成12年10月4日

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

目次

- １．概要
  - １．１　パッケージの内容
  - １．２　TwinVQ エンコーダの構成
    - １．２．１　TwinVQ エンコーダとは
    - １．２．２　TwinVQ データの構成
    - １．２．３　TwinVQ エンコーダの基本構成
    - １．２．４ 各部の説明
- ２．エンコーダの構成方法
  - ２．１　エンコーダ関数の呼出し手順
  - ２．２　各手順の詳細
    - ２．２．１　初期化
    - ２．２．２　フレームごとのデータの読み出し
    - ２．２．３　エンコード処理
    - ２．２．４　ビットストリーム書き込み
    - ２．２．５　終了処理
- ３．エンコーダ DLL 利用のサンプルプログラム
  - ３．１　コンパイル方法
  - ３．２　実行方法
- ４．　主な関数のマニュアル
  - ４．１　TwinVQ エンコーダモジュール (エンコーダ DLL)
  - ４．２　ビットストリーム書き込みモジュール
  - ４．３　ヘッダ作成モジュール
  - ４．４　オーディオデータ入力

## １．概要

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

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

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

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

TestEnc.exe
  テストエンコーダの実行ファイル（コンソールアプリケーション）
encoder.cxx
  エンコーダメインプログラム（コンソールプログラム）
simple_enc.cxx
  最小版エンコーダメインプログラム
bstream_e.cxx, bstream_e.h
  TwinVQ ビットストリーム書き込みモジュール
bfile_e.cxx, bfile_e.h, bfile.cxx, bfile.h
  ファイルへのビット単位書き込み・読み出しツールプログラム
Chunk.cxx, Chunk.h, ChunkHelper.cxx, ChunkHelper.h
  ヘッダデータ作成プログラム
TestEnc\
  サンプルプログラムをコンパイルするためのワークスペースディレクトリ

### １．２　TwinVQ エンコーダの構成

#### １．２．１　TwinVQ エンコーダとは

TwinVQ エンコーダは、オーディオデータを入力し、そのデータを圧縮して TwinVQ データ（ビットストリーム）を生成するプログラムです。

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

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

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

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

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

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

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

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

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

メインプログラム
  TwinVQ エンコーダの各モジュールの動作を制御します。ユーザインタフェースもこの部分に持たせます。
  ⇒対応ファイル： encoder.cxx
TwinVQエンコーダ（エンコーダＤＬＬ）
  オーディオデータを入力し、これを圧縮して TwinVQ オーディオデータを出力します。入力オーディオデータは、float型の配列に記録された PCM 信号をの形式を使い、TwinVQオーディオデータは、 TwinVQオーディオデータ構造体 (INDEX)形式で出力します。
  このモジュールは DLL の形態（エンコーダDLL）で提供しています。
  ⇒対応ファイル： tvqenc.dll
ヘッダ作成
  ヘッダ情報を作成します。ヘッダ情報は、ヘッダデータオブジェクト （CChunkChunk クラスのインスタンス）に書き込んでゆき、出来上がったヘッダデータオブジェクトを出力します。ヘッダ情報の入力方法は、ヘッダデータオブジェクトへの書き込みに必要な情報が取得できればどのようなものであってもかまいません。サンプルプログラムでは、コマンドラインからエンコーダセットアップ情報の入力を行い、設定ファイルから補助情報の入力を行っています。
  ⇒対応ファイル： Chunk.cxx, ChunkManager.cxx
ビットストリーム書き込み
  ヘッダデータ（ヘッダデータオブジェクト形式）と TwinVQオーディオデータ（INDEX構造体）を入力し、TwinVQデータに変換して出力します。様々な出力デバイスの形態の違いは、このモジュールで吸収します。サンプルプログラムでは、ファイル入力の形態で提供しています。
  ⇒対応ファイル： bstream_c.cxx, bfile.cxx
オーディオデータ入力
  入力デバイスのインタフェースから受け取ったオーディオ信号を、内部形式のオーディオデータ （`float[]`型の配列）に変換して出力します。様々な入力デバイスの形態の違いは、このモジュールで吸収します。サンプルプログラムでは、ファイル入力の形態で提供しています。
  ⇒対応ファイル： encoder.cxx ( frtobuf(), fwrite() )

## ２．エンコーダの構成方法

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

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

    {
        <初期化>
        while( <フレームごとのオーディオデータ読み込み> ){
            <エンコード処理>
            <ビットストリーム書き込み>
        }
        <終了処理>
    }

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

### ２．２　各手順の詳細

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

初期化は、TwinVQ エンコーダプログラムを動作させる前に必ず行う必要があります。初期化手順の詳細については、エンコーダ初期化マニュアルを参照してください。

#### ２．２．２　フレームごとのデータの読み出し

フレームごとに、オーディオデータを読み出します。サンプルプログラムでは、16 bit PCM ファイルから `fread()` 関数を使って読み出しています。読み出したデータは、 "L,R,L,R" という順番で並んでいる short データなので、これを `buftofr()` 関数を使って TwinVQ の入力フレームに変換しています。

#### ２．２．３　エンコード処理

エンコード処理では、入力フレームのオーディ信号を圧縮して INDEX 形式のビットストリーム情報を出力します。`TvqEncodeFrame()` 関数を使います。

#### ２．２．４　ビットストリーム書き込み

ビットストリームの書き込みは、フレームごとに行います。サンプルプログラムでは、`TvqWriteBsFrame()` という関数がソースコードで用意されています。この関数は、TwinVQ エンコーダモジュールが出力した符号化インデックス (`INDEX`) をビットストリームに変換し、ビットストリームファイルに書き込みます。

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

エンコード処理を終了、または、エンコード条件を変更するために再度初期化をする時には、終了処理を行う必要があります。終了処理は、次の項目からなります。処理の順序の制約はありません。

- TwinVQ エンコーダモジュールの終了処理... TvqEncTerminate() 関数を使う。
- データバッファに割り当てたメモリの解放... free() など。

## ３．エンコーダ DLL 利用のサンプルプログラム

### ３．１　コンパイル方法

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

### ３．２　実行方法

DOS プロンプトから実行します。

    	TestEnc [オプション] <入力オーディオファイル名> <出力ビットストリームファイル名>

で実行できます。オプションの内容とデフォルト値は以下の通りです。サポートされているパラメータの組み合わせはこちらをご覧ください。

セットアップパラメータ | 指定オプション名 | デフォルト | 備考
サンプリング周波数モード | -f <#> | 44 |
全チャネルトータルの ビットレート | -b <#> | 96 |
チャネルモード | -c <#> | 1 （ステレオ） | モノラル： 0
N_CAN | -n <#> | 16 | 1, 2, 4, 8, 16, 32 のいずれか 値が大きいほど高音質。 値が小さいほど高速。
ファイルタイプ | -t <string> | wav | ファイルタイプを指定、wav なら WAV ファイル、raw ならヘッダなしファイル
タイトル | -T <string> | "" |
コメント | -C <string> | "" |
アーティスト | -A <string> | "" |
著作権情報 | -R <string> | "" |
ヘッダ情報の格納ディレクトリ | -h <string> | "header_info" | 拡張ヘッダ情報のパラメータファイルを置くディレクトリ

サポートしている入力オーディオファイルの形式は、*.wav 形式又はヘッダなし 16 bit PCM です。ヘッダなし 16 bit PCM ファイルについて、１サンプルは 2Byte データで格納されています。ステレオの場合は、L, R, L, R の順でサンプルが並んでいます。

ヘッダ情報のうち、標準チャンクの情報は全て引数で指定できますが、それ以外のヘッダ情報は、実行ディレクトリに置かれた header_info ディレクトリの下にあるパラメータファイルによって与えます。追加情報のチャンクIDはファイル名によって指定し、その内容はファイルにテキスト形式で記述します。フィールドはスペースまたは改行によって指定します。SCNDチャンクを構成するサブチャンクは、header_info\SCND ディレクトリにパラメータファイルを置くことで指定します。なお、header_info ディレクトリは、-h オプションによって別のディレクトリに変更することができます。ヘッダ情報についての詳細は、TwinVQ データフォーマット説明書を参照ください。

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

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

### ４．１　TwinVQ エンコーダモジュール (エンコーダ DLL)

エンコーダ DLL 関数は、次の3つのカテゴリーに分けられます。

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

エンコードを実行するには、最初に１回初期化を行ってから、フレームごとにエンコード処理を行います。終了処理はエンコードを終了、または符号化条件を変えるために再度初期化を行う時に行います。問い合わせ関数は、TwinVQエンコーダの内部状態を問い合わせるための関数です。

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

表１：　使用できるエンコーダ DLL 関数
カテゴリ | 関数名 | 必須 | 概要
初期化／終了処理用関数 | `TvqEncInitialize()` | ○ | TwinVQ エンコーダモジュールを初期化する。
`TvqEncTerminate()` | ○ | TwinVQ エンコーダモジュールの終了処理をする。
`TvqEncGetVectorInfo()` | ○ | VQ ビット情報を初期化する。ビットストリーム書き出しモジュールのサブプログラム。
`TvqEncResetFrameCounter()` |  | フレームカウンタをリセットする。
エンコード処理用関数 | `TvqEncodeFrame()` | ○ | フレームごとにエンコード処理をする
`TvqEncUpdateVectorInfo()` | ○ | VQ ビット情報を更新する。ビットストリーム書き出しモジュールのサブプログラム。
`TvqEncSetFrameCounter()` |  | フレームカウンタを任意の値にセットする。
問い合わせ関数 | `TvqEncCheckVersion()` | ○ | バージョン ID 番号
`TvqGetVersionID()` | ○ | バージョン ID 文字列
`TvqEncGetSetupInfo()` |  | セットアップ情報
`TvqEncGetConfInfo()` | ○ | TwinVQ モジュールの設定パラメータ
`TvqEncGetFrameSize()` | ○ | フレームサイズ
`TvqEncGetNumChannels()` | ○ | チャネル数
`TvqEncGetBitRate()` |  | ビットレート
`TvqEncGetSamplingRate()` |  | サンプリング周波数
`TvqEncGetNumFixedBitsPerFrame()` |  | １フレームあたりのビット数
`TvqEncGetNumPreCand()` |  | VQ 予備選択数
`TvqEncGetNumFrames()` |  | フレームカウンタの値
`TvqEncGetModuleVersion( )` |  | エンコーダモジュールのバージョン

### ４．２　ビットストリーム書き込みモジュール

表２：　使用できるビットストリーム書き込みモジュールの関数
カテゴリ | 関数名 | 必須 | 概要
初期化用 | `TvqPutBsHeaderInfo()` | ○ | ビットストリームヘッダを書き込み
`TvqinitBsWriter()` | ○ | ビットストリーム書き込みモジュールの初期化
機能関数 | `TvqWriteBsFrame()` | ○ | ビットストリームのフレーム単位の書き込み

### ４．３　ヘッダ作成モジュール

`TvqCreateHeaderChunk()`
  ヘッダチャンクの作成

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

`buftofr()`
  オーディオデータファイルからの入力オーディオ情報を TwinVQ 入力バッファ形式に変換する