2012年12月22日

vorbisfileのov_read()ドキュメンテーション和訳

ov_read()の使い方が気になったのでドキュメント(リファレンスか?)を和訳してみた。

使用上の注意。
ov_read()、一回の呼び出しで1パケットのデコード。
512、2034、4096など、デコードされるバイトサイズもまちまち。

チャンネル/サンプルレートに変化があると*bitstreamの値がインクリメントされるので、それに合わせov_info()を読み直して変化に対応する必要がある。(*bitstreamの値がインクリメントされるフォーマットを検証していないので未確認。)

vorbisfile version 1.3.2

ov_read()

"vorbis/vorbisfile.h"の中で宣言されている。

これはループ内でVorbisファイルをデコードするのに用いられる主機能。要求されたエンディアンの種類、符号の有無、そしてワードのサイズによりデコードされるPCMオーディオを、指定されたバイト数を最大とし返される。オーディオがマルチチャンネルなら、チャンネルは出力バッファ中でインターリーブ(挟み込み。訳注:ステレオ16ビットなら、左用2バイト、右用2バイト、左用2バイト、右用2バイトと続く)される。渡されたバッファが大きい場合、ov_read()はバッファを埋め尽くさない;渡されたバッファサイズは要求サイズではなくリミットとして扱われる。

出力チャンネルはストリームオーダーなのでリマップされない。Vorbisはチャンネルオーダーを以下のように定義している:
  • 1チャンネル - モノラルのストリーム。
  • 2チャンネル - ステレオ。チャンネルオーダー:左、右
  • 3チャンネル - 1d-サラウンドエンコーディング。チャンネルオーダー:左、中央、右
  • 4チャンネル - 4チャンネルサラウンド。チャンネルオーダー:フロント左、フロント右、リア左、リア右。
  • 5チャンネル - 5チャンネルサラウンド。チャンネルオーダー:フロント左、中央、フロント右、リア左、リア右。
  • 6チャンネル - 5.1サラウンド。チャンネルオーダー:フロント左、中央、フロント右、リア左、リア右、LFE。
  • 7チャンネル - 6.1サラウンド。チャンネルオーダー:フロント左、中央、フロント右、サイド左、サイド右、リア中央、LFE。
  • 8チャンネル - 7.1サラウンド。チャンネルオーダー:フロント左、中央、フロント右、サイド左、サイド右、リア左、リア右、LFE。
  • 8チャンネルを超えるチャンネルの使用とオーダーは未定義。

この点までの注意として、トップレベルのアプリケーションが特にかまわないなら、Vorbisfile APIはチェインしている複数の論理ビットストリーム特性をトップレベルのアプリケーションからほぼ隠蔽することができる。とはいえオーディオバックのリード中に、アプリケーションは複数のビットストリームセクションが同じ数のチャンネルもしくはサンプリングレートを使用するとは限らないことを気に留めなければならない。

ov_read()は、トップレベルのアプリケーションがチャンネル及び/もしくはサンプルレートの変化を把握できるように、PCMデータと伴に(*bitstreamの中に)現在のデコードされたシーケンシャル論理ビットストリームのインデックス(しるし)を渡して返す。この数字はシーク不可ストリームだとしてもチェイン境界線でインクリメントする。シーク可能ストリームでは、それは物理ビットストリーム内の実際のチェインインデックスを意味する。

long ov_read(OggVorbis_File *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);

パラメータ
vf
OggVorbis_File構造体のためのポインタ -- これは全ての外部libvorbisfile関数で使用される。
buffer
出力バッファのためのポインタ。デコードされた出力はこのバッファに入る。
length
バッファに読み込むためのバイト数。バッファサイズと同一でなければならない。一般的な値は4096
bigendianp
ビッグもしくはリトルエンディアンのバイトパックを指定する。0がリトルエンディアンで、1がビッグエンディアン。一般的な値は0
word
ワードのサイズを指定する。可能な引数は、1で8ビットサンプル、または2で16ビットサンプル。一般的な値は2
sgned
符号付きか符号なしデータか。0が符号なし、1が符号付き。一般的には1
bitstream
現在の論理ビットストリーム番号のためのポインタ。

戻り値
OV_HOLE
データ中に中断があったことを示す。(以下1つ:ページ間のゴミ、リキャプチャで同期のロスが続く、または不正なページ)
OV_EBADLINK
libvorbisfileに無効なストリームセクションが供給される、もしくは要求されたリンクが不正なことを示す。
OV_EINVAL
イニシャルファイルヘッダが読めない、もしくは不正、またはvfのイニシャルオープンコールが失敗したことを示す。
0
EOFを示す。
n
読み込んだ実際のバイト数を示す。ov_read()は発動ごとに最大1つのvorbisパケットをデコードするので、返される値はたいていlengthより小さい。

Notes

一般的な使用:
bytes_read = ov_read(&vf, buffer, 4096,0,2,1,&current_section)
これは符号付き16ビットのリトルエンディアンのサンプルを、バッファに最大で4096バイト読み込む。

原典:
http://xiph.org/vorbis/doc/vorbisfile/ov_read.html
posted by 齋藤聡 at 12:33 | Comment(0) | Linux | このブログの読者になる | 更新情報をチェックする
この記事へのコメント
コメントを書く
お名前:

メールアドレス:

ホームページアドレス:

コメント:

認証コード: [必須入力]


※画像の中の文字を半角で入力してください。