-------------------------------------------------------------------------------
【  名  称  】 WaveFile Device
【ファイル名】 kbwavefile.kpi
【バージョン】 0.07
【 Platform 】 x86(32bit)/x64(64bit)
【 公 開 日 】 2022/10/22
-------------------------------------------------------------------------------

【概要】

  デコーダプラグインから得た PCM を WAVE ファイルに出力するためのデバイスプラグ
インです。このプラグインは使い方に注意が必要です。使用する前に必ず【使用方法】
をお読み下さい。

【使用方法】

・「演奏メニュー」で「単曲リピート」をオフ
・「演奏メニュー」で「全曲リピート」をオフ
・「演奏メニュー」で「単曲再生」をオン
・以下はオリジナルの音質のまま出力したい場合に設定
  ・音量100% (音量バーが非表示の場合は「演奏2」->「Volume」->「Max」)
  ・リプレイゲイン無効(「演奏2」->「ReplayGain」->「Disable」)
  ・エコー無効(「演奏2」->「Echo」のチェックを外す)
  ・再生速度x1.0(「演奏2」->「Tempo」)
・デバイス設定画面で「Wave File」を選択し、「デバイスへの出力ビット数」で出力
  したいビット深度にチェックを入れる(複数項目を選択している場合は上の方にある
  ものが適用されます)
・デバイス設定画面で「Wave File」の「プラグインへの再生周波数要求」を適切な値に
  する(多くの場合、0 か 44100)
・デバイス設定画面で「Wave File」を選択して「開く」
  (または「ツール」->「WAVE Device」で「Wave File」を選択)
・再生時にファイルダイアログが表示されるので、出力先のファイル名を指定する
・「再生バッファサイズ」の設定は意味を持ちません。

  単曲リピートや全曲リピートが有効だと、演奏を停止するか 2GB の上限に達するまで
WAV ファイルを出力し続けるため、必ずオフにして下さい。

  プラグインロード後初回のデバイスオープン時のみ、このドキュメントファイルの表
示を促すダイアログが表示されます。ダイアログの表示が煩わしい場合は、プラグイン
の設定画面で表示をオフにすることが出来ます。設定方法は、

  「ツール」->「プラグイン設定」-> kbwavefile.kpi を選択 ->
  「ダイアログ非表示」を true にする

となります。

【出力ビット数】

  デバイス設定画面の「デバイスへの出力ビット数」をデコーダプラグインが返すビッ
ト数より大きくしても音質が向上することはありません。通常はデコーダプラグインが
返すビット深度に合わせるか、16bit にして下さい。実用上は 16bit か 24bit で十分
です。

  32bit float や 64bit float も選択可能ですが、音質面での利点はほとんどありませ
ん。出力した WAV ファイルを後で編集する場合には float でも良いかもしれません。
(デコーダが float で返した場合)

  デコーダプラグインが 64bit float を返したからといって 64bit float で WAV 出力
しても、多くの場合は無意味です。プラグインによっては内部の演算精度が 64bit 未満
でも 64bit float で返すものがあるためです。64bit であるに越したことはありません
が、デバイスへの最終出力段で 32bit 以下に切り捨てられるのがほとんどです。

  エコーや音量制御(100%以外)、リプレイゲインが有効な場合など、プラグインから得
た PCM に対して本体側で何らかの加工をする場合、加工後のデータが出力されます。こ
の場合は「デバイスへの出力ビット数」を大きくした方が音質は有利に働きます。

  音量を 100% 以外にして出力ビット数を大きくした方が音質が向上するという意味で
はありません。100% 以外にすることによる音質の劣化を軽減できるという意味です。


【再生周波数】

  MIDI 対応プラグインやゲーム音源対応プラグインの多くは本体からの再生周波数の
要求に応じます。デバイス設定画面の「プラグインへの再生周波数要求」で設定して
下さい。通常は 44100Hz にすることをお勧めします。


【応用編】

  演奏リストを連続再生時、本体はギャップレスに曲を繋げて再生します。再生時のデ
バイスプラグインに kbwavefile.kpi を使用し、

「単曲リピート」をオフ
「全曲リピート」をオフ
「未再生の曲だけ再生」(演奏リスト上で右クリック)をオフ
「連続再生」をオン

にして演奏リストの先頭の曲を再生すると、リストに登録されている全ての曲をギャッ
プレスで繋げて１つの WAV ファイルにすることが出来ます。

  滅多に発生しない筈ですが、連続再生の途中でファイルオープンダイアログが表示さ
れた場合、ギャップレスで繋げての再生に失敗しています。再生周波数が異なる曲を登
録している場合は必ず失敗します。


【使用上の注意】

  作成可能な WAV ファイルの最大サイズは 2GB です。2GB に到達した時点でダイアロ
グを表示して WAV ファイル出力を終了します。

  演奏リストに登録されている全ての曲を(1 つの WAV ファイルとしてではなく)個別に
WAV ファイル出力することを一括して行うことは出来ません。デバイスプラグイン側で
は曲が切り替わったことを知る方法がないため、対応するにはデバイスプラグインの仕
様変更が必要となります。

  デコード中にシークしたり停止ボタンを押すと、その時点で WAV ファイル出力を終了
します。


【ベンチマークテスト】

  プラグイン設定画面で「ベンチマークテスト」を true にすると「Benchmark Test」
という名前のデバイスが列挙されるようになり、デコーダプラグインの処理速度を計測
することが出来ます。基本的にこの機能はプラグイン開発者向けのものです。

  例えば本体同梱の kbmpg123.kpi ではデコーダを選択することが出来ますが、お使い
の環境で最も高速なデコーダを選択するのに役立ちますので、一般ユーザ向けにも使い
道がなくはないです。

  現状の KbMedia Player 本体の仕様では、デコーダプラグインから取得したデータを
デバイスプラグインに渡す過程で(ベンチマークテスト時であっても)様々な処理を行う
ため、ここで計測される結果はデコーダプラグイン自体の純粋な速度よりも遅くなりま
す。

  例えばアーカイブ内のデータを再生する場合は、アーカイブを展開しながら処理する
ことによる影響も計測結果に反映されます。従ってアーカイブの展開処理の速度の計測
にも役立ちます。が、内部的にメモリ上に展開する形式では、メモリ上に展開するまで
かかる時間は計測結果に反映されないことに注意が必要です。今のところ、リアルタイ
ムに展開処理を行いながら再生可能な形式は LZH/ZIP/TAR/TGZ のみです。これら以外の
形式はメモリ上(CAB/RAR/7z)またはディスク上(GCA)に展開が「終わった後から」計測を
始めるので、ディスク上のデータと同じかむしろ良い結果が得られたりします。

  64bit版の本体から32bit版のプラグインを使った場合(またはその逆)の速度への影響
などもベンチマークで計測することが出来ます。作者の環境では、おおむね30〜40%程度
のパフォーマンスの低下を確認することが出来ます。

  ベンチマークテストは長めの曲を「単曲リピート」を有効にして行うと比較的精度が
高い計測結果が得られます。曲長が短かったり、先頭へのシークが遅い形式だと先頭へ
のシーク時間が計測結果に大きく左右されるため、計測の精度は低くなります。

  ベンチマークテストにおける「デバイスへの出力ビット数」による計測結果の差はデ
コーダプラグインの速度とは関係ありません。プレイヤー本体の内部処理によるものと
なります。プラグイン自体に出力ビット数を変更する設定があり、プラグインの方で設
定を変えた場合の結果はこの限りではありません。

-------------------------------------------------------------------------------

【更新履歴】

Version 0.07(2022/10/22)

・64bit 版でダイアログ表示時に落ちる可能性があったのを修正

/*---------------------------------------------------------------------------*/

Version 0.06(2019/02/27)

・デコーダの速度を計測するためのベンチマークモードを追加
　・プラグインの設定で「ベンチマークテスト」を true にすると「Benchmark Test」
　　というデバイスが列挙されるようになる
　・デコーダプラグインから取得したデータをデバイスプラグインに渡すまで本体が様
　　々な処理を行うので、純粋なデコーダの速度を計測してるとは言えない
・初回のダイアログ時に「はい」を選択すると次回もダイアログが表示されるのを修正
・ダイアログを本体とは独立したスレッドから呼び出すようにした
　・予期せぬ再入が起こって本体がフリーズするのを回避するため
　・ダイアログを閉じるまで本体は「応答なし」になる(閉じれば復活するのでフリーズ
　　するよりマシ)

/*---------------------------------------------------------------------------*/

Version 0.05(2017/04/09)

・コンパイラを VS2017 に変更

/*---------------------------------------------------------------------------*/

Version 0.04(2017/02/26)

・プラグインロード後の初回デバイスオープン時に「使用上の注意」ダイアログを表
　示するようにした
　・表示が煩わしい場合は表示されないようにすることも出来る
・設定ダイアログ対応
　・ダイアログ非表示
　　・true にすれば「使用上の注意」ダイアログが表示されなくなる
　・出力先
　　・前回出力したファイル名が自動的に保存されるため、ここで設定する意味はあ
　　　まりない

/*---------------------------------------------------------------------------*/

Version 0.03(2017/01/17)

・正式版リリースに伴う細かい修正
・本体同梱としたが、使い方が特殊なため敢えてアーカイブしたまま同梱

/*---------------------------------------------------------------------------*/

Version 0.02(2016/12/25)

・他の同等ツールと比べてサイズが 2 バイト大きな WAV を出力していたのを修正
　(データ自体は不正ではなかったはず)

/*---------------------------------------------------------------------------*/

Version 0.01(2016/12/18)

・初版

-------------------------------------------------------------------------------
Kobarin(hidkob@pb.highway.ne.jp)
https://kobarin.sakura.ne.jp/
