================================================================================
  mruopus.dll v1.0.0.0 — 使い方ガイド
  Copyright (C) 2025 ALC Software Laboratory. All rights reserved.
================================================================================


■ クイックスタート
────────────────────────────────────────────────────────────────────────────────

  1. mruopus.dll を呼び出し元 EXE と同じフォルダに配置する

  2. LoadLibrary で mruopus.dll を動的ロードする（スタティックリンク不要）

  3. GetProcAddress で必要な関数ポインタを取得する（OpusDllExports.h を参照）

  4. Opus_InternalInit() を呼び出して DLL を初期化する

  5. OpusPlayer_Create() でプレイヤーハンドルを作成する

  6. OpusPlayer_LoadFile() でファイルをロードして OpusPlayer_Play() で再生する

  7. 終了時に OpusPlayer_Destroy() → Opus_FinalizeAll() → FreeLibrary() の
     順で後処理を行う


■ API 早見表
────────────────────────────────────────────────────────────────────────────────

  【初期化 / 終了】
      Opus_InternalInit()       DLL 初期化（起動直後に 1 度呼ぶ）
      Opus_FinalizeAll()        DLL 終了処理（FreeLibrary 前に呼ぶ）
      Opus_GetVersionString()   バージョン文字列取得（wchar_t*）
      Opus_GetBuildInfo()       ビルド情報取得（SIMD レベル等）
      Opus_GetLastError()       最後のエラーメッセージ取得（char*）

  【再生 (OpusPlayer)】
      OpusPlayer_Create()                    プレイヤーハンドル作成
      OpusPlayer_Destroy(h)                  プレイヤー破棄
      OpusPlayer_LoadFile(h, path)           ファイルロード（wchar_t* パス）
      OpusPlayer_LoadFromMemory(h, data, sz) メモリバッファからロード
      OpusPlayer_Play(h)                     再生開始
      OpusPlayer_Stop(h)                     再生停止
      OpusPlayer_Pause(h, BOOL)              一時停止 / 再開
      OpusPlayer_SeekMs(h, ms)               ミリ秒シーク
      OpusPlayer_SetLoop(h, BOOL)            ループ設定
      OpusPlayer_SetVolume(h, vol)           音量設定（0.0〜1.0）
      OpusPlayer_GetVolume(h)                音量取得
      OpusPlayer_SetMute(h, BOOL)            ミュート設定
      OpusPlayer_IsMuted(h)                  ミュート状態取得
      OpusPlayer_SetPan(h, pan)              パン設定（-1.0〜1.0）
      OpusPlayer_GetPan(h)                   パン取得
      OpusPlayer_GetPositionMs(h)            現在位置取得（ms）
      OpusPlayer_GetTotalMs(h)               総時間取得（ms）
      OpusPlayer_GetTotalSamples(h)          総サンプル数取得
      OpusPlayer_IsPlaying(h)                再生中判定
      OpusPlayer_IsPaused(h)                 一時停止中判定
      OpusPlayer_StartFadeIn(h, ms)          フェードイン開始
      OpusPlayer_StartFadeOut(h, ms)         フェードアウト開始

  【再生速度変更】
      OpusPlayer_SetPlaybackRate(h, rate)             Simple モード（軽量）
      OpusPlayer_SetPlaybackRateHQ(h, rate, mode)     高品質速度変更
          mode: 0=Simple  1=WSOLA（ピッチ保持）  2=PhaseVocoder
      OpusPlayer_GetPlaybackRate(h)                   現在の再生速度取得

  【A-B リピート / ループ区間】
      OpusPlayer_SetRepeatSegment(h, msA, msB)      A-B リピート設定（ms）
      OpusPlayer_ClearRepeatSegment(h)              A-B リピート解除
      OpusPlayer_SetLoopRangeMs(h, start, end)      ループ区間設定（ms）
      OpusPlayer_SetLoopRangeSamples(h, s, e)       ループ区間設定（samples）
      OpusPlayer_EnableSeamlessLoop(h, BOOL)        シームレスループ有効化

  【キューポイント / コールバック】
      OpusPlayer_AddCuePoint(h, ms, id)    キューポイント追加
      OpusPlayer_ClearCuePoints(h)         キューポイント全削除
      OpusPlayer_SetCallbacks(h, onStarted, onStopped, onEndOfStream,
                              onCuePoint, user)

  【タグ (OpusTags)】
      OpusPlayer_GetTitle(h)        TITLE タグ取得（wchar_t*）
      OpusPlayer_GetArtist(h)       ARTIST タグ取得（wchar_t*）
      OpusPlayer_GetAlbum(h)        ALBUM タグ取得（wchar_t*）
      OpusPlayer_GetCommentCount(h) コメント総数取得
      OpusPlayer_GetComment(h, i)   i 番目のコメント取得（wchar_t*）

  【情報取得】
      OpusPlayer_GetSampleRate(h)   サンプルレート取得
      OpusPlayer_GetChannels(h)     チャンネル数取得
      OpusPlayer_GetBitrate(h)      ビットレート取得

  【クロスフェード (OpusCrossfade)】
      OpusCrossfade_Create()                       マネージャー作成
      OpusCrossfade_Destroy(h)                     マネージャー破棄
      OpusCrossfade_Play(h, path, loop)            再生開始
      OpusCrossfade_CrossfadeTo(h, path, ms, loop) クロスフェード切り替え
      OpusCrossfade_Stop(h, fadeMs)                停止（フェードアウト付き）
      OpusCrossfade_Pause(h, BOOL)                 一時停止 / 再開
      OpusCrossfade_SetVolume(h, vol)              マスター音量設定
      OpusCrossfade_IsPlaying(h)                   再生中判定
      OpusCrossfade_IsCrossfading(h)               クロスフェード中判定

  【効果音プール (OpusSePool)】
      OpusSePool_Init(voices)         プール初期化（最大ボイス数指定）
      OpusSePool_Finalize()           プール破棄
      OpusSePool_Play(path, vol)      SE 再生（ハンドル返却）
      OpusSePool_Stop(handle)         指定 SE 停止
      OpusSePool_StopAll()            全 SE 停止
      OpusSePool_SetVolume(h, vol)    ボイス音量設定
      OpusSePool_GetVolume(h)         ボイス音量取得
      OpusSePool_GetActiveCount()     再生中ボイス数取得

  【エンコード (OpusEncoder)】
      OpusEncoder_Create(ch, sr, br, app, frameMs)  エンコーダ作成
      OpusEncoder_GetHeaders(enc, ...)              ヘッダパケット取得
      OpusEncoder_EncodeFrame(enc, pcm, ...)        フレームエンコード
      OpusEncoder_PollPacket(enc, ...)              パケット取り出し
      OpusEncoder_Flush(enc, ...)                   フラッシュ
      OpusEncoder_Finish(enc, totalSamples)         EOS 通知
      OpusEncoder_FreeBuffer(buf)                   バッファ解放
      OpusEncoder_Destroy(enc)                      エンコーダ破棄
      Opus_WriteOggFileFromPacketsW(...)            Ogg ファイル書き出し

  【デバッグ】
      Opus_DebugSimd()                SIMD レベル表示
      Opus_DebugDumpAll()             全プレイヤー状態ダンプ
      Opus_DebugPlayerState(h)        指定プレイヤー状態ダンプ
      Opus_DebugPcmState(h)           PCM 出力状態ダンプ


■ mruopus_sample の実行方法
────────────────────────────────────────────────────────────────────────────────

  mruopus_sample.cpp は LoadLibrary を使った動的ロードのサンプルソースです。
  コマンドライン引数で再生ファイルを指定する仕様のため、
  バッチファイルを使うと手軽に実行できます。

  【ビルド方法】

      Visual Studio 2022 でソリューションを開いてビルドします:

          sample\project\mruopus_sample.sln

      ビルド後、mruopus.dll はポストビルドイベントにより出力先
      (x64\Release\ 等) へ自動コピーされます。

      コマンドラインでビルドする場合は Developer Command Prompt を開き、
      sample\project\ フォルダで以下を実行してください:

          cl ..\src\mruopus_sample.cpp /std:c++20 /W3 /EHsc /Fe:mruopus_sample.exe

      その後、bin\mruopus.dll を実行ファイルと同じフォルダにコピーしてください。

  【実行方法 (1) — コマンドプロンプトから直接実行】

          mruopus_sample.exe bgm.opus
          mruopus_sample.exe bgm.opus se.opus
          mruopus_sample.exe bgm.opus se.opus next.opus

          引数 1: BGM ファイル（必須）
          引数 2: SE ファイル（省略可 / S キーで再生）
          引数 3: クロスフェード先ファイル（省略可 / X キーで切り替え）

  【実行方法 (2) — バッチファイルを使用（推奨）】

      以下の内容で run_sample.bat を作成して mruopus_sample.exe と
      同じフォルダに置き、ダブルクリックで起動します。

          @echo off
          cd /d "%~dp0"
          mruopus_sample.exe bgm.opus se.opus next.opus
          pause

      ※ pause を入れると終了後もコンソールが閉じず、結果を確認できます。

  【実行方法 (3) — ドラッグ&ドロップ起動バッチ】

      以下の内容で drop_play.bat を作成すると、音声ファイルをバッチアイコンに
      ドラッグ&ドロップするだけで再生できます。

          @echo off
          cd /d "%~dp0"
          if "%~1"=="" (
              echo ファイルをこのバッチにドラッグ&ドロップしてください。
              pause
              exit /b 1
          )
          mruopus_sample.exe "%~1" "%~2" "%~3"
          pause

  【操作キー一覧】

      Space      一時停止 / 再開
      Left       5 秒 巻き戻し
      Right      5 秒 早送り
      Up         音量 +10%
      Down       音量 -10%
      M          ミュート切り替え
      L          ループ切り替え
      I          フェードイン（2 秒）
      O          フェードアウト（2 秒）
      P          パン切り替え（左 → 中央 → 右）
      F          再生速度切り替え（1.0x / 1.25x / 1.5x / 0.75x、WSOLA モード）
      A          A-B リピート 設定 / 解除（現在位置から 10 秒間）
      C          キューポイント追加（現在位置 +3 秒）
      T          OpusTags 表示（Title / Artist / Album）
      D          デバッグ情報表示（DumpState / SIMD レベル）
      S          SE 再生（引数 2 が指定されている場合）
      X          クロスフェード切り替え（引数 3 が指定されている場合）
      Q / ESC    終了


■ 最小実装例（C++ / LoadLibrary）
────────────────────────────────────────────────────────────────────────────────

  // mruopus.dll を動的ロードして bgm.opus を再生する最小限のコード

  #include <windows.h>

  typedef void* OPUS_HANDLE;

  int wmain() {
      HMODULE hDll = LoadLibraryW(L"mruopus.dll");

      auto Init    = (BOOL (__cdecl*)())             GetProcAddress(hDll, "Opus_InternalInit");
      auto Fin     = (void (__cdecl*)())             GetProcAddress(hDll, "Opus_FinalizeAll");
      auto Create  = (OPUS_HANDLE (__cdecl*)())      GetProcAddress(hDll, "OpusPlayer_Create");
      auto Destroy = (void (__cdecl*)(OPUS_HANDLE))  GetProcAddress(hDll, "OpusPlayer_Destroy");
      auto Load    = (BOOL (__cdecl*)(OPUS_HANDLE, const wchar_t*))
                                                     GetProcAddress(hDll, "OpusPlayer_LoadFile");
      auto Play    = (BOOL (__cdecl*)(OPUS_HANDLE))  GetProcAddress(hDll, "OpusPlayer_Play");
      auto Stop    = (void (__cdecl*)(OPUS_HANDLE))  GetProcAddress(hDll, "OpusPlayer_Stop");

      Init();
      OPUS_HANDLE h = Create();
      Load(h, L"bgm.opus");
      Play(h);

      Sleep(5000);   // 5 秒再生

      Stop(h);
      Destroy(h);
      Fin();
      FreeLibrary(hDll);
      return 0;
  }


■ トラブルシューティング
────────────────────────────────────────────────────────────────────────────────

  【LoadLibrary が失敗する】
      ・mruopus.dll が EXE と同じフォルダにあるか確認してください。
      ・EXE と DLL のビット数 (x86 / x64) が一致しているか確認してください。
      ・Visual C++ 再頒布可能パッケージがインストール済みか確認してください。

  【OpusPlayer_Play が FALSE を返す】
      ・Opus_InternalInit() を呼んでいるか確認してください。
      ・Opus_GetLastError() でエラー内容を確認してください。
      ・ファイルが有効な Ogg Opus 形式か確認してください。

  【音が出ない】
      ・出力デバイスが存在し、ミュートされていないか確認してください。
      ・他のアプリが WASAPI 排他モードでデバイスを占有していないか確認してください。
      ・OpusPlayer_GetVolume() で音量が 0 になっていないか確認してください。

  【再生速度変更で音質が低い】
      ・SetPlaybackRateHQ() で mode=1 (WSOLA) を指定してください。
        ピッチを保ちつつより自然な速度変更が可能です。
        mode=0 (Simple) は線形補間のみのため音質が低下します。

  【EXE 終了時にクラッシュする】
      ・FreeLibrary() 前に必ず Opus_FinalizeAll() を呼んでください。
        内部スレッドが join されずにプロセスが終了するとクラッシュします。


================================================================================
  ALC Software Laboratory
  Copyright (C) 2025 ALC Software Laboratory. All rights reserved.
================================================================================
