STFファイル

STRAIGHTパラメタを保存するファイルのことを、STF(STraight Format)ファイルと呼びます。 ここでは、このSTFファイルを読み書きするためのAPIについて説明します。 なお、現在はファイルのみのサポートとなりますが、将来的にはストリーミングなども サポートする予定です。

STFの仕様

STFの構造

STFの構造は以下のようになっています。 [〜]で囲まれているのは省略可であることを示します。

'STRT'
       <16bit 0xfeff (エンディアン判定のため)> 
       <32bit ヘッダサイズ in byte(次のチャンクまでの大きさ)>
       <16bit ファイル形式(バージョン)ID> 
       <16bit チャネル数(原則1)>
       <32bit サンプリング周波数>
['CHKL' <32bit チャンクサイズ in byte> <4文字のチャンクが並んでいる>]
['NXFL' <32bit チャンクサイズ in byte> <相対パスファイル名文字列 NUL文字なし>]
'F0  '
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit 1>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <F0のデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]
['UVF0'
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit 1>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <非有声音部分のF0のデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]]
['PRLV'
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit 1>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <周期性レベルのデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]]
['F0CN'
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit 候補数>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <F0候補パラメータのデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]]
'AP  '
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit FFTポイント>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <非周期性指標のデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]
['APSG'
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit 2>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <非周期性指標に対するシグモイド関数のパラメータのデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]]
'SPEC'
       <32bit チャンクサイズ in byte> <64bit double シフト長> <32bit フレーム数> <32bit FFTポイント>
       <16bit ビット/サンプル(33=float)> <64bit double 重み係数,default=1.0>
       <32bit データサイズ> <スペクトログラムのデータ>
       [<シフト長が0の場合、64bit doubleの時間情報がフレーム数分 >]

STFファイル読み込み

読み込みの際は、チャンクのIDに応じて処理を変える必要があります。 一方、書き込みの際は、所望のチャンクを単に書き込めば良いだけなので、 読み込みよりも処理は単純になります。

STFファイル読み込み手順

  1. straightFileOpenでファイルを読み込みモードで開く
  2. straightFileLoadHeaderでファイル全体に関する情報を取り出す
  3. straightFileLoadChunkInfoで、各チャンクのIDとチャンクサイズを取り出す
  4. チャンクのIDに応じてデータを読み込み(straightFileLoadSpecgramなどを使用)、3.に戻る
  5. 全チャンクの読み込みが終了したらstraightFileCloseでファイルを閉じる

STFファイル読み込み 例

        if ((sf = straightFileOpen(inputFileName, "r")) != NULL) {
            if (straightFileLoadHeader(sf, straight) == ST_TRUE) {
                char chunkId[5];
                long chunkSize;

                source = straightSourceInitialize(straight, NULL);
                specgram = straightSpecgramInitialize(straight, NULL);
            
                while (straightFileLoadChunkInfo(sf, chunkId, &chunkSize) == ST_TRUE) {
		    if (strcmp(chunkId, "F0  ") == 0) {
			straightFileLoadF0(sf, source);
		    } else if (strcmp(chunkId, "UVF0") == 0) {
			straightFileLoadUnvoicedF0(sf, source);
		    } else if (strcmp(chunkId, "PRLV") == 0) {
			straightFileLoadPeriodicityLevel(sf, source);
		    } else if (strcmp(chunkId, "F0CN") == 0) {
			straightFileLoadF0Candidates(sf, source);
		    } else if (strcmp(chunkId, "AP  ") == 0 || strcmp(chunkId, "APSG") == 0) {
			straightFileLoadAperiodicity(sf, source);
		    } else if (strcmp(chunkId, "SPEC") == 0) {
			straightFileLoadSpecgram(sf, specgram);
		    } else {
			straightFileSkipChunk(sf, chunkSize);
		    }
                }
                :
                :
                straightSourceDestroy(source);
                straightSpecgramDestroy(specgram);
            }
            straightFileClose(sf);
        }

STFファイル書き込み

STFファイル書き込み手順

  1. straightFileOpenでファイルを書き込みモードで開く
  2. 必要に応じてチャンクリストの書き込み準備(straightFileSetChunkList)などを行う
  3. straightFileWriteHeaderでファイル全体に関する情報を書き込む
  4. 各チャンクを書き込む(straightFileWriteSpecgramChunkなどを使用)
  5. 全チャンクの書き込みが終了したらstraightFileCloseでファイルを閉じる

STFファイル書き込み 例

            source = straightSourceInitialize(straight, NULL);
            straightSourceCompute(straight, source, NULL, 0);

            specgram = straightSpecgramInitialize(straight, NULL);
            straightSpecgramCompute(straight, source, specgram, NULL, 0);

            if ((sf = straightFileOpen(outputFileName, "w")) != NULL) {
                fprintf(stderr, "Output file: %s\n", outputFileName);

                straightFileSetChunkList(sf, "F0  AP  SPEC");
                straightFileWriteHeader(sf, straight);
                straightFileWriteF0Chunk(sf, source);
                straightFileWriteAperiodicityChunk(sf, source);
                straightFileWriteSpecgramChunk(sf, specgram);

                straightFileClose(sf);
            }
                
            straightSourceDestroy(source);
            straightSpecgramDestroy(specgram);

StraightFile型

目的
STFファイルを扱うための基本となるデータ型です。
データ型
型の定義は以下の通りです。ただし、構造体の中身は隠蔽されています。
#include <straight/straight.h>

typedef struct _StraightFile *StraightFile;
説明
stragihtFileOpen により得られるもので、STFファイル関連のほとんどの関数で、第1引数として 指定する必要があります。
関連項目
stragihtFileOpen

straightFileOpen

目的
STFファイルを開きます。
書式
#include <straight/straight.h>

StraightFile straightFileOpen(char *filename, char *mode);
引数
filename
ファイル名を指定します。
mode
ファイルを開くときのモードを指定します。 読み込みの際は"r"を、書き込みの際は"w"を指定します。
戻り値
ファイルを開くのに成功するとStraightFileが返り、失敗するとNULLが返ります。 読み込みの際に、ファイルがSTFファイルでない場合には、ファイルを開くのに失敗します。
説明
ファイルの読み書きが終了したら、 straightFileClose を呼び出してファイルを閉じて下さい。
関連項目
straightFileClose

straightFileClose

目的
STFファイルを閉じます。
書式
#include <straight/straight.h>

stBool straightFileClose(StraightFile sf);
引数
sf
straightFileOpenによって得られる StraightFileを指定します。
戻り値
呼び出しに成功するとST_TRUE型が返り、失敗するとST_FALSEが返ります。
説明
ファイルの読み書きが終了したら、この関数を呼び出してファイルを閉じる必要があります。
関連項目
straightFileOpen

STFファイルの情報の取得

目的
STFファイルの情報を取得します。
書式
#include <straight/straight.h>

char *straightFileGetNextFile(StraightFile sf);
char *straightFileGetChunkList(StraightFile sf);
stBool straightFileGetEndian(StraightFile sf, stBool *bigEndianFlag);
引数
sf
straightFileOpenによって得られる StraightFileを指定します。
bigEndianFlag
ファイルのエンディアンがビッグエンディアンであるかどうかを取得するためのstBool型変数のアドレスを指定します。 ビッグエンディアンであった場合はST_TRUEが返り、 リトルエンディアンであった場合はST_FALSEが返ります。
戻り値
戻り値の型がstBool型の場合、呼び出しに成功するとST_TRUE型が返り、失敗するとST_FALSEが返ります。 char*型の場合、呼び出しに成功するとStraightFile内部の文字列へのポインタが返り、失敗するとNULLが返ります。 文字列へのポインタはメモリ解放などを行ってはいけません。 また、この文字列へのポインタは、ファイルをクローズすると無効になります。
説明
straightFileGetNextFileは、'NXFL'チャンクの内容を、 straightFileGetChunkListは、'CHKL'チャンクの内容を取得します。 該当するチャンクが存在しない場合はNULLが返ります。

straightFileGetEndianは、ファイルのエンディアン情報を取得します。

これらの関数は、通常、読み込みモードで開いているファイルに対して使用します。 straightFileLoadHeaderを呼び出す前は、正しい情報は取得できません。

関連項目
straightFileOpenSTFファイルの情報の設定

STFファイルの情報の設定

目的
STFファイルの情報を設定します。
書式
#include <straight/straight.h>

stBool straightFileSetNextFile(StraightFile sf, char *nextFile);
stBool straightFileSetChunkList(StraightFile sf, char *chunkList);
stBool straightFileSetEndian(StraightFile sf, stBool bigEndianFlag);
引数
sf
straightFileOpenによって得られる StraightFileを指定します。
bigEndianFlag
ファイルのエンディアンをビッグエンディアンにするかどうかを設定するためのstBool型変数を指定します。 ビッグエンディアンにする場合はST_TRUEを指定し、 リトルエンディアンにする場合はST_FALSEを指定します。
戻り値
呼び出しに成功するとST_TRUE型が返り、失敗するとST_FALSEが返ります。
説明
straightFileSetNextFileは、'NXFL'チャンクの内容を、 straightFileSetChunkListは、'CHKL'チャンクの内容を設定します。 これらを呼び出さない場合は、該当のチャンクはファイルに作られません。

straightFileSetEndianは、ファイルのエンディアン情報を設定します。 この関数を呼び出さない場合は、その環境のネイティブのエンディアンとなります。

これらの関数は、通常、書き込みモードで開いているファイルに対して使用します。 straightFileWriteHeaderを呼び出す前にこれらの関数を呼び出す必要があります。

関連項目
straightFileOpenSTFファイルの情報の取得

STFファイル読み込み関数

目的
STFファイルからの読み込みを行います。
書式
#include <straight/straight.h>

stBool straightFileLoadHeader(StraightFile sf, Straight straight);
stBool straightFileLoadChunkInfo(StraightFile sf, char *chunkId, long *chunkSizePtr);
stBool straightFileSkipChunk(StraightFile sf, long chunkSize);

stBool straightFileLoadF0(StraightFile sf, StraightSource source);
stBool straightFileLoadAperiodicity(StraightFile sf, StraightSource source);
stBool straightFileLoadSpecgram(StraightFile sf, StraightSpecgram specgram);
引数
sf
straightFileOpenによって得られる StraightFile型変数を指定します。
straight
straightInitialize で得られたStraight型変数を指定します。
chunkId
チャンクIDを4文字の文字列で指定します。
chunkSizePtr
チャンクサイズを取得するために、long型変数のアドレスを指定します。
chunkSize
straightFileSkipChunkで読み飛ばすチャンクのチャンクサイズを指定します。 通常、straightFileLoadChunkInfoで得られるチャンクサイズを指定します。
source
straightSourceInitialize で得られたStraightSource型変数を指定します。
specgram
straightSpecgramInitialize で得られたStraightSpecgram型変数を指定します。
戻り値
呼び出しに成功するとST_TRUE型が返り、失敗するとST_FALSEが返ります。
説明
これらの関数は、読み込みモードで開いているファイルに対して使用します。 それ以外のモードで開いているファイルに対してこれらの関数を呼び出した際の動作は不定です。

straightFileLoadHeaderは、STFファイルのヘッダに情報を読み込みます。 その他の読み込みを行う前に呼び出す必要があります。

straightFileLoadChunkInfoは、次のチャンクのチャンクIDとチャンクサイズを 読み込みます。STRAIGHTパラメタのチャンクの読み込みを行う前に毎回呼び出す必要があります。 なお、実装としては、実際にこの関数を呼び出してからチャンクIDとチャンクサイズを 読み出すようにはなっていません。

straightFileSkipChunkは、straightFileLoadChunkInfoで得られたチャンクID が不明なものであった場合に、そのチャンクを読み飛ばすための関数です。 straightFileLoadChunkInfoで得られたチャンクサイズを第2引数に指定して下さい。

straightFileLoadF0straightFileLoadAperiodicitystraightFileLoadSpecgramは、それぞれ 'F0 'チャンク、'AP 'チャンク、'SPEC'チャンクの内容を読み込みます。 straightFileLoadChunkInfoで得られるチャンクIDに応じて 適切な関数を呼び出す必要があります。このチャンクIDに対応しない 関数が呼び出された場合の動作は不定です。

関連項目
straightFileOpenSTFファイルの情報の取得

STFファイル書き込み関数

目的
STFファイルへの書き込みを行います。
書式
#include <straight/straight.h>

stBool straightFileWriteHeader(StraightFile sf, Straight straight);
stBool straightFileWriteF0Chunk(StraightFile sf, StraightSource source);
stBool straightFileWriteAperiodicityChunk(StraightFile sf, StraightSource source);
stBool straightFileWriteSpecgramChunk(StraightFile sf, StraightSpecgram specgram);
引数
sf
straightFileOpenによって得られる StraightFile型変数を指定します。
straight
straightInitialize で得られたStraight型変数を指定します。
source
straightSourceInitialize で得られたStraightSource型変数を指定します。
specgram
straightSpecgramInitialize で得られたStraightSpecgram型変数を指定します。
戻り値
呼び出しに成功するとST_TRUE型が返り、失敗するとST_FALSEが返ります。
説明
これらの関数は、書き込みモードで開いているファイルに対して使用します。 それ以外のモードで開いているファイルに対してこれらの関数を呼び出した際の動作は不定です。

straightFileWriteHeaderは、STFファイルのヘッダに情報を書き込みます。 その他の書き込みを行う前に呼び出す必要があります。

straightFileWriteF0ChunkstraightFileWriteAperiodicityChunkstraightFileWriteSpecgramChunkは、それぞれ 'F0 'チャンク、'AP 'チャンク、'SPEC'チャンク全体を書き込みます。

関連項目
straightFileOpenSTFファイルの情報の設定

Last modified: "2013-04-26 20:01:19 hideki"