クイックスタート
1
DLL を配置する
mrutheora.dll を呼び出し元 EXE と同じフォルダに配置します。Visual C++ 再頒布可能パッケージ (vcredist) が未インストールの場合はインストールしてください。
2
DLL を動的ロードする
LoadLibraryW(L"mrutheora.dll") で DLL をロードします。スタティックリンクやインポートライブラリは不要です。
3
Win32 ウィンドウを作成する
映像描画先となる Win32 ウィンドウ (HWND) を作成します。Theora_Start() にこのハンドルを渡します。
4
ロードして再生する
Theora_Create() → Theora_LoadFile() → Theora_Start(h, hwnd, x, y, w, h, scale, loop) の順で再生開始。
終了時は Theora_Stop() → Theora_Destroy()。
API 早見表
基本操作
| Theora_Create() | プレイヤーハンドル作成 |
| Theora_Destroy(h) | プレイヤー破棄 |
| Theora_LoadFile(h, path) | OGV ファイルロード（wchar_t* パス） |
| Theora_Start(h, hwnd, x, y, w, h, scale, loop) | 再生開始・描画先ウィンドウ指定 |
| Theora_Stop(h) | 再生停止 |
| Theora_Pause(h, BOOL) | 一時停止 / 再開 |
| Theora_SeekMs(h, ms) | ミリ秒シーク |
| Theora_StepFrame(h) | 1 フレーム進める（一時停止中のみ有効） |
| Theora_IsPlaying(h) | 再生中判定 |
| Theora_IsPaused(h) | 一時停止中判定 |
ループ / 速度 / 情報取得
| Theora_SetLoop(h, BOOL) | ループ設定 |
| Theora_SetLoopRange(h, startMs, endMs) | 区間ループ設定（ms） |
| Theora_SetSpeed(h, speed) | 再生速度設定（0.25〜4.0） |
| Theora_GetPositionMs(h) | 現在位置取得（ms） |
| Theora_GetDurationMs(h) | 総時間取得（ms） |
| Theora_GetFrameIndex(h) | 現在フレームインデックス取得 |
| Theora_GetTotalFrames(h) | 総フレーム数取得 |
| Theora_GetWidth(h) | 映像幅取得（px） |
| Theora_GetHeight(h) | 映像高さ取得（px） |
| Theora_GetFps(h) | フレームレート取得 |
| Theora_HasAudio(h) | 音声トラック有無 |
| Theora_IsSynced(h) | 映像音声同期状態取得 |
| Theora_GetDriftMs(h) | 映像音声ドリフト量取得（ms） |
描画 / スケーリング
| Theora_SetTarget(h, hwnd, x, y, w, h, scale) | 描画先ウィンドウ・位置・サイズを変更 |
| Theora_SetScaleMode(h, mode) | スケーリングモード（TH_SCALE_NEAREST / TH_SCALE_LINEAR） |
| Theora_OnResize(h, w, h) | ウィンドウリサイズ通知 |
フレーム取得
| Theora_GetCurrentFrameBitmap(h, hWnd) | 現在フレームを HBITMAP で取得 |
| Theora_CopyCurrentFrameBgra32(h, dst, ...) | 現在フレームを BGRA32 バッファへコピー |
| Theora_CopyCurrentFrameYuv420(h, ...) | 現在フレームを YUV420 バッファへコピー |
音量
| Theora_SetVolume(h, vol) | 音量設定（0.0〜1.0） |
| Theora_GetVolume(h) | 音量取得 |
| Theora_SetMute(h, BOOL) | ミュート設定 |
| Theora_IsMuted(h) | ミュート状態取得 |
マスク
| Theora_SetMaskRect(h, ...) | 単一矩形マスク設定 |
| Theora_SetMaskRects(h, rects, count) | 複数矩形マスク設定 |
| Theora_AnimateMaskRect(h, ...) | 矩形マスクのアニメーション設定 |
| Theora_SetMaskBitmap(h, ...) | ビットマップマスク設定 |
| Theora_UpdateMaskBitmap(h, ...) | ビットマップマスク更新 |
| Theora_SetMaskBlendMode(h, mode) | マスクブレンドモード設定 |
| Theora_SetMaskCombineMode(h, mode) | マスク合成モード設定 |
テキストオーバーレイ / キューポイント / コールバック
| Theora_DrawTextOverlay(h, text, ...) | テキストオーバーレイ描画 |
| Theora_DrawTextOverlayEx(h, text, ...) | テキストオーバーレイ描画（拡張版・フォント指定） |
| Theora_AddCuePoint(h, ms, id) | キューポイント追加 |
| Theora_ClearCuePoints(h) | キューポイント全削除 |
| Theora_SetCallbacks(h, ...) | イベントコールバック設定（onStarted / onStopped / onEndOfStream / onCuePoint） |
エンコード (TheoraEncoder) / バージョン情報
| TheoraEncoder_Create(w, h, ...) | エンコーダ作成 |
| TheoraEncoder_GetHeaders(enc, ...) | ヘッダパケット取得 |
| TheoraEncoder_EncodeFrame(enc, ...) | YUV420 フレームエンコード |
| TheoraEncoder_Flush / Finish / Destroy | フラッシュ・終了・破棄 |
| TheoraEncoder_GetVersion() | libtheora バージョン文字列 |
| Theora_GetVersionString() | DLL バージョン文字列 |
| Theora_GetBuildInfo() | ビルド情報（SIMD レベル等） |
| Theora_DumpState(h) | デバッグ状態文字列取得 |
mrutheora_sample の実行方法
mrutheora_sample は Win32 ウィンドウアプリケーションです。ウィンドウ内に OGV 動画が直接描画されます。
ビルド方法
Visual Studio 2022 でソリューションを開いてビルドします。
sample\project\VC2022\mrutheora_sample.sln
ℹ️
ビルド後、mrutheora.dll はポストビルドイベントにより出力先へ自動コピーされます。
コマンドラインでビルドする場合は Developer Command Prompt を開き、sample\project\VC2022\ フォルダで以下を実行します。
cl ..\..\src\mrutheora_sample.cpp /std:c++20 /W3 /EHsc /Fe:mrutheora_sample.exe user32.lib gdi32.lib
実行方法 (1) — コマンドプロンプトから直接実行
bin\ フォルダ内で実行します。
mrutheora_sample.exe sample.ogv
実行方法 (2) — バッチファイル / ドラッグ&ドロップ
run_sample.bat
@echo off
cd /d "%~dp0"
mrutheora_sample.exe "%~1"
ℹ️
OGV ファイルを run_sample.bat にドラッグ&ドロップするだけで再生できます。
操作キー一覧
Space 一時停止 / 再開
← Left 5 秒 巻き戻し
→ Right 5 秒 早送り
↑ Up 音量 +10%
↓ Down 音量 -10%
M ミュート切り替え
L ループ切り替え
ESC 終了
最小実装例（C++ / LoadLibrary）
// mrutheora.dll を動的ロードして OGV を再生する最小限のコード
#include <windows.h>
typedef void* THEORA_HANDLE;
typedef int THEORA_ScaleMode;
int WINAPI WinMain(HINSTANCE hInst, HINSTANCE, LPWSTR, int) {
HMODULE hDll = LoadLibraryW(L"mrutheora.dll");
auto Create = (THEORA_HANDLE (__cdecl*)()) GetProcAddress(hDll, "Theora_Create");
auto Destroy = (void (__cdecl*)(THEORA_HANDLE)) GetProcAddress(hDll, "Theora_Destroy");
auto Load = (BOOL (__cdecl*)(THEORA_HANDLE, const wchar_t*))
GetProcAddress(hDll, "Theora_LoadFile");
auto Start = (BOOL (__cdecl*)(THEORA_HANDLE, HWND, int, int, int, int, THEORA_ScaleMode, BOOL))
GetProcAddress(hDll, "Theora_Start");
auto Stop = (void (__cdecl*)(THEORA_HANDLE)) GetProcAddress(hDll, "Theora_Stop");
// ウィンドウ作成 (省略: 通常は RegisterClassEx + CreateWindowEx)
HWND hWnd = /* ... */ nullptr;
THEORA_HANDLE h = Create();
Load(h, L"sample.ogv");
Start(h, hWnd, 0, 0, 320, 240, 1 /*LINEAR*/, TRUE);
// メッセージループ (省略)
Stop(h);
Destroy(h);
FreeLibrary(hDll);
return 0;
}
トラブルシューティング
LoadLibrary が失敗する
mrutheora.dll が EXE と同じフォルダにあるか確認してください。EXE と DLL のビット数（x86 / x64）が一致しているか、Visual C++ 再頒布可能パッケージがインストール済みかも確認してください。
映像が表示されない
Theora_Start() に渡す HWND が有効か確認してください。WM_CREATE ハンドラ内で呼ぶか、ウィンドウ作成後に呼ぶ必要があります。また OGV ファイルが有効な Ogg Theora 形式かどうかも確認してください。
音が出ない
OGV に音声トラック (Ogg Vorbis) が含まれているか Theora_HasAudio() で確認してください。出力デバイスがミュートされていないかも確認してください。
映像と音がずれる
Theora_GetDriftMs() で映像音声ドリフト量を確認できます。重い処理と並行して再生している場合、CPU 負荷を下げるか再生速度を調整してください。
EXE 終了時にクラッシュする
FreeLibrary() の前に必ず Theora_Stop() → Theora_Destroy() を呼んでください。内部スレッドが残ったままプロセスが終了するとクラッシュします。