EMBEDDED AUDIO DRIVER / 日本語マニュアル

AURA Unity SDK

接続する、音を鳴らす、アプリに組み込む。Unity・C#・C++向けの導入と制御ガイド。

Version 1.0.0Windows x642026.10.25

AURA Unity SDK

Unity / C# / C++ からAURAを制御する、Windows x64用の組み込みDLLセットです。

バージョン:1.0.0 作成日:2026年10月25日

まず開くもの

ブラウザーで読む場合は、同じフォルダの 「マニュアルを開く.html」 をダブルクリックしてください。

フォルダ 入っているもの
01_Unityに入れる UnityのAssetsへコピーする完成品。DLL・操作画面付きサンプル・MIDI/CCD/PCMデータ
02_CSharpサンプル Unity以外のC#から呼び出すコンソールのソースと実行ファイル
03_CPPサンプル C++用ヘッダー、インポートライブラリ、DLL、実行サンプル
04_日本語マニュアル Unity導入、C#制御、C++制御、全API、PCM、トラブル対策
05_ソースとビルド DLLの完全なソース、再ビルド用PowerShell、検証コード
06_検証結果 ビルド・制御テスト・Unity実行のログ、配布ファイルのハッシュ

Unityに入れる手順

  1. 01_Unityに入れる/AURA_Unity_SDK.unitypackage をUnityでインポートします。フォルダで導入する場合は、同じ場所のAssetsの中身をUnityプロジェクトのAssetsへコピーします。
  2. 空のGameObjectを作り、Assets/AURA_SDK/Samples/AURAQuickStart.cs を追加します。
  3. 最初はInspectorの Simulation をONにしてPlayし、接続・演奏の操作を確認できます。このモードでは音は出ません。
  4. 実機ではSimulationをOFFにして、ポート一覧からAURAのCOMポートを選び「接続」を押します。

詳しい説明:Unity導入とC#制御

DLLは2つ使います

ファイル 役割
AURA.Unity.dll C#から使うクラス Aura.Embedded.AuraDriver を提供
AURA.Native.dll USB CDC通信、MIDI時計、APG音源制御を行う本体。C++からも直接呼び出せる

Unityでは両方を入れます。C++では AURA.Native.dll と aura_driver.h、AURA.Native.lib を使います。

完成したネイティブDLLの利用に、.NET 10ランタイムの追加インストールは不要です。ソースから再ビルドする場合と、C#コンソールサンプルを動かす場合は.NET 10 SDK/ランタイムが必要です。

できること

  • COMポート一覧、接続・切断、状態・エラーの取得
  • MIDIノート、コントロールチェンジ、ピッチベンド、APG波形の指定
  • MIDIファイルの再生・一時停止・停止・ループ・テンポ変更
  • CCD音色定義とAPG効果音JSONの読み込み
  • 全体・BGM・効果音の音量調整
  • CH10パーカッションをOFF / APG / PCMへ切り替え
  • 明示的な許可を受けた場合だけPCMプリセット全体を書き換え
  • 低レベルのレジスタ書き込み、音を出さない通信シミュレーション

音はAURA実機の音声出力から出ます。PCのスピーカーへ音を合成するDLLではありません。

PCMへの切り替えだけでは、内蔵データは消えません。 WritePcmPreset(..., true) を呼んだ場合に限り、内蔵PCM定義を同梱プリセットで置き換えます。

対応範囲

Windows x64向け。Unity 6用のC#ラッパーは.NET Standard 2.1で作成しています。C++は64bitのC ABIを使用します。macOS / Linux / Android / iOS / WebGL / 32bit Windows用DLLは同梱していません。

AURAはバイナリー通信v2・GATE制御に対応したファームウェアを使用します。このSDKで実機確認した版は1.062です。PCMは1.041以降が必要です。

実行確認の結果は 検証結果 を参照してください。

Unity導入とC#制御

1. Unityへコピーする

簡単に導入する場合は、01_Unityに入れる/AURA_Unity_SDK.unitypackageをダブルクリックするか、UnityのAssets → Import Package → Custom Packageで選び、Importします。以下のフォルダコピー方式も使用できます。

01_Unityに入れる/Assets の中の3フォルダを、Unityプロジェクトの Assets へコピーします。

Assets/
├─ Plugins/AURA/
│  ├─ AURA.Unity.dll                 C#用ラッパー
│  ├─ AURA.Unity.xml                 IDE用API説明
│  └─ x86_64/AURA.Native.dll         通信・演奏エンジン本体
├─ AURA_SDK/Samples/AURAQuickStart.cs 操作画面のサンプル
└─ StreamingAssets/AURA/
   ├─ PACKMENU.MID
   ├─ PACKMENU.ccd
   ├─ apg_effects.json
   └─ AURA_PCM_Preset.pdm

AURA.Unity.dll と AURA.Native.dll をセットで使います。DLL本体だけを別の名前に変更しないでください。

ネイティブDLLのInspector

AURA.Native.dll を選択して確認します。同梱のmetaファイルにも設定を収録しています。

項目 設定
Any Platform OFF
Editor ON、OS: Windows、CPU: x86_64
Standalone Windows x86_64 / Windows 64-bit

AURA.Unity.dll はマネージドDLLです。Auto Referenceを有効にします。asmdefで参照を制限しているプロジェクトでは、Precompiled ReferencesにこのDLLを追加してください。

Build Profiles / Build SettingsではWindows、x86_64を選びます。MonoとIL2CPPの両方で同じDLLセットを使います。

2. 画面付きサンプルを動かす

  1. シーンに空のGameObjectを作成します。
  2. AURAQuickStart を追加します。
  3. SimulationをONにしてPlayします。
  4. 「接続」を押し、MIDI再生や効果音のボタンを試します。
  5. 実機の音を出すときはPlayを止め、SimulationをOFFにします。再度Playし、AURAのCOMポートを選んで接続します。

サンプルのSimulationは通信の検証用です。PCMの書き込み操作を試しても実機のデータへ触れず、音も出ません。

COMポートはWindowsのデバイスマネージャーで確認できます。同じポートをAURA Hostやゲームの従来ドライバが使用している場合は、その接続を先に切断してください。

3. 最小のC#例

using Aura.Embedded;

var aura = new AuraDriver(); // 実機。シミュレーションは new AuraDriver(true)
string[] ports = AuraDriver.GetPorts();
aura.SetLevels(master: 120, music: 80, effects: 80);
aura.Connect("COM14");       // COM14は例。選択したAURAのポートへ変更する

Connect()は接続要求を出して戻ります。直後はまだ演奏できません。StateがConnectedになってから演奏APIを呼びます。

Unityで待機する例:

using System.Collections;
using Aura.Embedded;
using UnityEngine;

public sealed class AuraMinimum : MonoBehaviour
{
    AuraDriver aura;

    IEnumerator Start()
    {
        aura = new AuraDriver();
        aura.Connect("COM14"); // 実際に選択したポートへ変更

        float deadline = Time.realtimeSinceStartup + 8;
        while (aura != null && aura.State == AuraState.Connecting
               && Time.realtimeSinceStartup < deadline)
            yield return null;

        if (aura == null) yield break;
        if (!aura.Connected)
        {
            Debug.LogError(aura.LastError + " / " + aura.Status);
            yield break;
        }

        aura.SetTone(channel: 1, waveform: 0);
        aura.NoteOn(channel: 1, note: 60, velocity: 100);
        yield return new WaitForSecondsRealtime(0.3f);
        if (aura != null && aura.State == AuraState.Connected)
            aura.NoteOff(channel: 1, note: 60);
    }

    void OnDisable()
    {
        aura?.Dispose();
        aura = null;
    }
}

実際のアプリではポート選択UIから渡してください。AuraMinimumは最初の動作確認用です。再有効化時にも再接続する構成は、同梱のAURAQuickStartを参照してください。

4. 単音・音色・MIDIメッセージ

aura.SetTone(1, waveform: 14, duty: 128, volume: 160, pan: 128);
aura.NoteOn(1, 60, 100); // CH1、MIDIノート60、ベロシティ100
aura.NoteOff(1, 60);

aura.SendMidi(0xB0, 7, 100); // CH1、CC7: 音量100
aura.SendMidi(0xE0, 0, 64);  // CH1、ピッチベンド中央8192
aura.AllNotesOff();         // BGM・手動ノート・効果音を停止

NoteOn、NoteOff、SetToneのチャンネル番号は 1~16 です。SendMidiだけは標準MIDIのステータスバイトをそのまま指定するため、CH1は0x90、CH10は0x99のように下位4bitが0起点になります。

APGの割り当ては旋律20ボイス、APGドラム4ボイス、効果音8ボイスです。MIDIのProgram ChangeでGM音色を自動再現する機能はありません。波形はSetToneまたはCCDで指定します。

5. MIDIファイルとCCD

using System.IO;
using UnityEngine;

string dir = Path.Combine(Application.streamingAssetsPath, "AURA");
aura.LoadMidi(Path.Combine(dir, "PACKMENU.MID"),
              Path.Combine(dir, "PACKMENU.ccd"));
aura.Play(loop: true);
aura.SetTempo(1.25); // 曲中テンポの1.25倍。0より大きく4以下
aura.Pause(true);
aura.Pause(false);
aura.Stop();        // BGMのみ停止。APG効果音は独立

double seconds = aura.Position;
bool playing = aura.Playing;
  • SMF形式0/1、PPQN時間分解能、曲中のテンポ変更・ランニングステータスに対応します。
  • SMF形式2、SMPTE時間分解能、SysEx音色転送、シークは対象外です。
  • LoadMidiはファイルを読み込むだけです。再生開始はPlayです。
  • Play(false)は曲末で停止、Play(true)はループします。新しいPlayは先頭から再生し、一時停止を解除します。
  • 同梱CCDはAURA-CCD Version 1、APG32用です。FM/EX/ADSRなど未対応のCCDはエラーにします。
  • JSONはUTF-8のBOMあり・なしに対応します。ファイルパスも日本語を使用できます。
  • 大きいファイルの読み込みは時間がかかるため、毎フレーム呼び出さないでください。

6. APG効果音

// 接続前にJSONを読み込み。省略すると内蔵の標準12効果音を使用
aura.LoadEffects(Path.Combine(dir, "apg_effects.json"));

// 接続後
aura.PlayEffect("SELECT");
aura.PlayEffect("ALLCLEAR");
string[] names = aura.EffectNames;

標準名:CLICK、COUNTDOWN、START_GO、CANSEL、CRASH、LEVELUP、ALLCLEAR、PUT、SCORE1、SCORE2、SELECT、TURN。CANSELは互換のため、この綴りを使用します。

効果音は複数ステップをAPGで合成してAURAへ送ります。WAVをPCのAudioSourceで再生する機能とは異なります。バンクは最大64効果音、1効果音128ステップまでです。

7. 音量とCH10

aura.SetLevels(master: 120, music: 80, effects: 70);
aura.SetDrums(AuraDrums.Off);     // CH10を鳴らさない
aura.SetDrums(AuraDrums.Apg, 80); // APG合成リズム
aura.SetDrums(AuraDrums.Pcm, 65); // 既存PCM定義を使う。消去・書込みなし

全体音量は0~200、BGM・効果音・PCM音量は0~100。PCM音量はPCMモードで使用します。CH10の切り替え時はBGMの演奏状態をいったん止め、再生中の曲を先頭へ戻します。

PCMプリセット全体の置き換えは PCM操作 を参照してください。

8. 終了とエラー

try { aura.NoteOn(1, 60, 100); }
catch (AuraException e) { Debug.LogError($"AURA {e.Code}: {e.Message}"); }

// 通信失敗は接続ワーカーから報告される
if (aura.State == AuraState.Error)
    Debug.LogError(aura.LastError);

aura.Disconnect(); // 非同期。完了後にStateがDisconnectedになる
aura.Dispose();    // 最後に必ず呼ぶ。切断後のリソースを解放

UnityではOnDisableで破棄すると、Play終了やスクリプトの再読み込み時に接続を残しにくくなります。Disposeは終了待ちで最大約2.5秒かかる場合があるため、毎フレーム呼び出さないでください。接続後のUSB送信とMIDI時計は専用スレッドで動き、UpdateでのPump呼び出しは不要です。

AURA.Native.dllの更新時はUnity Editorを終了してから置き換え、再起動します。NativeAOTのライブラリをFreeLibraryで途中アンロードしないでください。DisposeはAURAのハンドルを解放する操作です。

公式資料

C++制御とAPI一覧

1. プロジェクトに追加する

03_CPPサンプルに、ビルド済みのサンプルと必要ファイルを入れています。

ファイル 用途
include/aura_driver.h C ABI宣言。C++側でincludeする
lib/AURA.Native.lib Windows x64用インポートライブラリ。リンカーへ指定
bin/AURA.Native.dll 実行ファイルと同じフォルダへ置くDLL本体
bin/AuraCppSample.exe 最初はシミュレーションで動く確認用アプリ
main.cpp / CMakeLists.txt ソースとCMake構成

Visual Studioではx64を選びます。追加のインクルードディレクトリへinclude、追加ライブラリへAURA.Native.libを指定し、DLLをEXEの隣へコピーします。

2. 最小の呼び出し例

#include "aura_driver.h"
#include <chrono>
#include <thread>

int main() {
AuraHandle aura = 0;
if (aura_create(0, &aura) < 0) return 1;
// 0=実機。機器なしで試す場合は1を指定し、ポート名をSIMにする

int result = aura_connect(aura, "COM14"); // COM14は例
if (result < 0) { aura_destroy(aura); return 1; }

auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(8);
while (aura_get_state(aura) == AURA_CONNECTING) {
    if (std::chrono::steady_clock::now() > deadline) { aura_destroy(aura); return 1; }
    std::this_thread::sleep_for(std::chrono::milliseconds(10));
}

bool connected = aura_get_state(aura) == AURA_CONNECTED;
if (connected) {
    aura_set_levels(aura, 120, 80, 80);
    aura_set_tone(aura, 1, 0, 128, 160, 128);
    aura_note_on(aura, 1, 60, 100);
    std::this_thread::sleep_for(std::chrono::milliseconds(300));
    aura_note_off(aura, 1, 60);
    aura_effect(aura, "SELECT");
}
aura_disconnect(aura);
aura_destroy(aura);
return connected ? 0 : 1;
}

実際のコードでは戻り値を毎回確認してください。同梱main.cppは戻り値・接続期限・エラー文字列・終了時のハンドル解放を処理しています。

3. 文字列はUTF-8

すべてのconst char*はUTF-8です。UTF-16のwchar_t*をキャストして渡さないでください。Windowsのwmain引数やstd::wstringはWideCharToMultiByte(CP_UTF8, ...)で変換します。C++17のstd::filesystem::path::u8string()も利用できます。同梱サンプルは日本語を含むファイルパスに対応しています。

文字列取得APIは、終端NULを含む必要バイト数を返します。バッファは呼び出し元が所有します。

#include <vector>
#include <iostream>
// main関数など、ハンドルauraが有効な場所に記述
int n = aura_get_status(aura, nullptr, 0);
if (n > 0) {
    std::vector<char> buffer(n);
    int result = aura_get_status(aura, buffer.data(), n);
    if (result > 0) std::cout << buffer.data() << "\n";
}

値が変化してバッファ不足になった場合はAURA_BUFFER_TOO_SMALL (-8)です。必要サイズを再取得します。COMポートと効果音名の一覧は改行区切りで返ります。空リストは空文字列です。

4. MIDI・効果音・PCMの例

aura_load_midi(aura, u8"曲/PACKMENU.MID", u8"曲/PACKMENU.ccd");
aura_play(aura, 1);              // 1=ループ、0=1回
aura_set_tempo(aura, 1.25);
aura_pause(aura, 1);             // 一時停止
aura_pause(aura, 0);             // 再開
aura_effect(aura, "ALLCLEAR");

aura_set_drums(aura, AURA_DRUMS_PCM, 65); // 既存PCMを使用。書き込みなし
aura_note_on(aura, 10, 36, 100);          // CH10キック

// 利用者がYESを選んだ後だけ呼ぶ
int result = aura_write_pcm_preset(aura, u8"AURA_PCM_Preset.pdm", 1);
int percent = -1;
aura_get_pcm_progress(aura, &percent);   // 未実行-1、進捗0~100

PCMフラッシュの上書き操作は任意です。aura_set_drumsだけで消去しません。

5. ABIの共通規則

  • Windows x64、C ABI、__cdecl。
  • ハンドルはuint64_t。void*やWindowsの32bit unsigned longへ変更しません。
  • 整数はint32_t、レジスタアドレスはuint16_t、データはuint8_t、時刻・テンポはdouble。
  • 真偽はint32_tの0/1です。C++のboolをABI宣言へ置き換えません。
  • ポインターは呼び出し元が有効な領域を用意します。配列の長さと実際の領域を一致させます。引数文字列・配列はAPIが戻るまで有効に保ちます。
  • 通常の操作は0で要求受け付け、負数でエラーです。接続や演奏要求が完了したことを意味しません。状態と進捗で完了を確認します。
  • 状態取得は0~5、再生中取得は0/1、文字列取得は必要バイト数です。いずれも負数はエラーです。
  • 同じハンドルへの操作は内部で直列化します。破棄するハンドルに対する呼び出しは終了させてからaura_destroyします。
  • NativeAOTライブラリの途中アンロードは未対応です。FreeLibraryを呼ばず、必要なハンドルをaura_destroyし、DLLはプロセス終了までロードしておきます。

6. API一覧

正確な宣言はaura_driver.hにあります。hは生成したハンドルです。

C API C# API 用途・主な範囲
aura_version AuraDriver.Version SDKバージョン
aura_create(flags, &h) new AuraDriver(simulated) 0=実機、1=シミュレーション
aura_destroy(h) Dispose() 全音停止・接続資源解放
aura_ports AuraDriver.GetPorts() COM一覧、機器は開かない
aura_connect(h, port) Connect(port) 非同期接続。実機はCOMx、シミュレーションはSIM
aura_disconnect(h) Disconnect() 非同期切断
aura_get_state(h) State 状態0~5
aura_get_status Status 説明文
aura_get_firmware Firmware 識別したファーム番号
aura_get_last_error LastError / AuraException 非同期/同期エラー
aura_set_levels(h, master, music, effects) SetLevels 全体0~200、BGM/効果音0~100
aura_set_tone(h, ch, wave, duty, volume, pan) SetTone CH1~16、波形0~81、duty/pan0~255、volume0~200
aura_load_ccd(h, path) LoadCcd APG32用CCD Version 1
aura_load_effects(h, path) LoadEffects APG効果音JSON。切断中に呼ぶ
aura_effect_names EffectNames 効果音名一覧
aura_load_midi(h, path, optional_ccd) LoadMidi CCD不要時はnullptr/null。64MB以下
aura_play(h, loop) Play 先頭から再生。loop0/1
aura_stop(h) Stop BGM停止
aura_pause(h, paused) Pause BGM/旋律ノートの一時停止0/1。効果音は独立
aura_set_tempo(h, multiplier) SetTempo 0より大きく4以下
aura_get_position(h, &seconds) Position 現在の曲内秒数
aura_is_playing(h) Playing 0=再生していない、1=再生中。一時停止も1
aura_midi(h, status, data1, data2) SendMidi status0x80~0xEF、データ0~127
aura_note_on(h, ch, note, velocity) NoteOn CH1~16、note/velocity0~127
aura_note_off(h, ch, note) NoteOff CH1~16、note0~127
aura_all_notes_off(h) AllNotesOff BGM・手動ノート・効果音停止
aura_effect(h, name) PlayEffect 名前でAPG効果音を開始
aura_set_drums(h, mode, volume) SetDrums mode0=OFF、1=APG、2=PCM。volume0~100
aura_write_pcm_preset(h, path, approved) WritePcmPreset approved=1/trueでのみ内蔵データ置換
aura_get_pcm_progress(h, &percent) PcmProgress 未実行-1、以後0~100
aura_write_registers(h, addresses, values, count) WriteRegisters 1~4096件、アドレス0~0x1FB5、値0~255
aura_simulation_stats(h, &registers, &pcm, &flash) GetSimulationStatistics シミュレーション専用、ハンドルの累計

7. 状態一覧

値 C# / C++ 意味
0 Disconnected / AURA_DISCONNECTED 切断済み
1 Connecting / AURA_CONNECTING ポートを開いてAURA識別・認証中
2 Connected / AURA_CONNECTED 通常の演奏命令を受け付ける
3 Transferring / AURA_TRANSFERRING PCM書き込み中。新しい演奏操作を待つ
4 Error / AURA_ERROR 接続・通信失敗。LastErrorを確認
5 Disconnecting / AURA_DISCONNECTING 停止・ポート解放中

8. エラー一覧

コード 意味 対応
-1 引数・データ形式が不正 範囲、MIDI/JSON/CCD形式を確認
-2 無効なハンドル 生成・破棄の対応を確認
-3 未接続 State=Connectedを待つ
-4 処理中・変更不可 接続/切断/PCM転送完了を待つ
-5 ファイル・I/Oエラー ファイルパスとアクセス権を確認
-6 未対応 実機専用/シミュレーション専用、PCM対応版を確認
-7 その他の内部例外 エラー文字列と検証ログを保存
-8 文字列バッファ不足 必要バイト数を取り直す
-9 PCM上書き未承認 利用者のYESなしでは書き込まない
-10 送信キューが満杯 毎フレームの連続送信を減らす

同期エラーは、戻り値が負数になった直後、同じスレッドでaura_get_last_error(0, ...)から取得します。接続ワーカーの失敗はaura_get_last_error(h, ...)です。C#ラッパーは同期エラーをAuraExceptionへ変換します。

PCMと効果音データ

PCMを使うだけなら書き込み不要

aura.SetDrums(AuraDrums.Pcm, volume: 80);
aura.NoteOn(channel: 10, note: 36, velocity: 100);

この操作はAURAに現在保存されているPCM音色を使います。PCM定義データを消去・書き換えません。保存済みの音色配置が同梱プリセットと違う場合、別の音になったり、鳴らない場合があります。

同梱プリセットは128スロット形式のAURA_PCM_Preset.pdmです。サイズ964,096バイト、ヘッダー・データ・各スロットのCRCを検査してから送ります。対応するAURAファームウェアは1.041以降です。

YESを選んだ場合だけプリセット全体を置き換える

同梱Unityサンプルでは、PCMボタンを押すと次の確認が出ます。

AURA内蔵のPCM定義データ消えるけど良い?

選択 実行する操作
YES / プリセットを書き込む WritePcmPreset(path, true)。現在の内蔵PCM全体を置き換える
No / 書き込まず既存データで使う SetDrums(Pcm, volume)。消去・書き込みをしない
// UIでYESを選んだ後だけ実行
aura.WritePcmPreset(presetPath, explicitlyApproved: true);

// 終了を確認。転送中は新しい演奏操作を送らない
if (aura.State == AuraState.Transferring)
    Debug.Log($"PCM書き込み {aura.PcmProgress}%");

falseで呼ぶとエラー-9になり、ファイルの送信・消去を行いません。転送は専用ワーカーで実行します。State=ConnectedかつPcmProgress=100で正常完了です。失敗時はState=ErrorとLastErrorを確認します。

書き込み中の電源断・USB切断は、不完全なプリセットになる可能性があります。転送完了まで接続を維持してください。SDKに自動バックアップ・元データの復元機能はありません。

CH10の主なノート割り当て

スロット 主なMIDIノート 用途
0 35、36 キック
1 38、40 スネア
2 41、43、45、47 低いタム系
3 48、50 高いタム系
4 42、44 クローズドハイハット
5 46 オープンハイハット
6 49、51、59 シンバル系
7 37、71~74など リム・短い打楽器系
8 52、53、55、57 追加シンバル系
9 39、54、56、58など 補助打楽器系

完全な対応はソースCore/PcmPreset.csのRhythmSlotを参照してください。対応表にないノートはPCMモードでは発音しません。

APG効果音JSON

apg_effects.jsonは次の形です。時刻と長さは秒単位です。

{
  "effects": [
    {
      "name": "MY_CLICK",
      "steps": [
        {
          "time": 0.0,
          "duration": 0.08,
          "note": 84,
          "waveform": 0,
          "velocity": 100,
          "volume": 120,
          "duty": 128,
          "pan": 128
        }
      ]
    }
  ]
}

切断中にLoadEffects(path)で読み込み、接続後にPlayEffect("MY_CLICK")で呼びます。

キー 値
name 空でない一意の名前
time 開始までの秒数、0~10
duration 発音する秒数、0より大きく5以下
note MIDIノート0~127
waveform APG波形0~81
velocity 0~127
volume 0~200
duty / pan 0~255、pan中央128

複数ステップの開始時刻をずらすと短い旋律になります。同じ開始時刻なら和音にできます。効果音専用の8ボイスを超える発音は古い音から入れ替えます。

データファイルの扱い

MIDI、CCD、JSON、PDMはDLLの外に置きます。UnityではStreamingAssets/AURAを使い、C#・C++のコンソールサンプルはSDKフォルダ内の同じデータを探します。

APG効果音・MIDIはPC内で解析し、AURAへレジスタ/PCM発音命令を送信します。音声の最終出力はAURA実機です。SF2のPC合成やWAVプレイヤーはこのSDKに含めていません。

トラブル対策と再ビルド

接続・再生で困ったとき

症状 確認すること
DllNotFoundException AURA.Unity.dllとAURA.Native.dllをセットで配置。ネイティブDLLのEditor/Windows x64設定を確認。DLL名を変更しない
BadImageFormatException 32bitプロセスで開いていないか確認。SDKはx64用
EntryPointNotFoundException ラッパーとネイティブDLLの版が不一致。2つとも同じSDK版へ交換し、Unityを再起動
ポート一覧にない WindowsのデバイスマネージャーでCOM認識を確認。USBケーブルとAURA電源を確認し、再検索
ポートを開けない AURA Host、別のUnity/Game、シリアルモニターが同じポートを使っていないか確認
Connectの直後に-3 非同期接続中。State=Connectedを待ってから演奏する
StateがError LastErrorを表示。誤ったポート、識別失敗、認証、未対応ファーム、USB切断などを確認
接続直後にRUN状態が外れる 初期化時のERR BIN not-runは、ワーカー内で最大2回再試行。繰り返す場合は他のホスト、USB、ファーム状態を確認
長時間無音の後に通信エラー ファームの無音タイムアウトで認証が失効する構成がある。切断完了後にConnectし直す
シミュレーションで音が出ない 正常。通信検証専用なので音は出ない。実機はSimulationをOFFにしてCOMを選ぶ
実機なのにPCスピーカーから音が出ない AURAの音声出力へ接続したスピーカー/ヘッドホンを確認
一部のMIDI音色がGMと違う GMプログラム番号から全音色を再現するSDKではない。CCDまたはSetToneでAPG波形を指定
MIDIファイルを拒否する SMF0/1・PPQN形式を使用。SMF2/SMPTEは未対応
PCMが鳴らない CH10の対応ノートか、音量が0でないか、保存済みプリセットのスロット配置を確認
PCM要求が-6 PCMにはファームウェア1.041以降が必要
-9が出る 明示的な承認なしでPCM書き込みを要求している。NoではSetDrumsだけ呼ぶ
-10が出る キュー上限256件。毎フレーム同じ音量・音色を再送せず、変更時だけ送る
Play終了後にポートが残る OnDisableでDisposeを呼ぶ。独自の常駐オブジェクト、他アプリの接続も確認

スレッドと寿命

接続・USB・MIDI時計を専用スレッドで処理します。Unityオブジェクトを操作するコールバックはDLLから呼びません。アプリ側がState、Status、Position、PcmProgressを必要なときに読みます。

同じハンドルのAPIは内部で直列化されます。ファイル解析は呼び出したスレッドで行うため、大きなMIDI/JSONを毎フレーム読み込まないでください。音量も値が変わったときだけ送ります。

Dispose後のハンドルは使えません。C#のDisposeは繰り返し呼べます。C++はaura_destroyを1回呼び、ハンドル変数を0にしておきます。

DLLを再ビルドする

必要なもの:

  • .NET 10 SDK
  • Visual Studioの「C++によるデスクトップ開発」:MSVC x64とWindows SDK
  • Unity実行確認を行う場合:Unity 6000.3.23f1、Windows IL2CPPモジュール

初回の再ビルドではNativeAOTのツールをNuGetから取得します。完成済みDLLとオフラインHTMLマニュアルを使うだけなら、この取得は不要です。

PowerShellでSDKの05_ソースとビルドへ移動し、実行します。

.\Build.ps1 -Test

作成するもの:

  1. NativeAOTでAURA.Native.dllを作成
  2. .NET Standard 2.1でAURA.Unity.dllを作成
  3. Unity用の配布場所へコピー
  4. C++用インポートライブラリをコピーし、C++サンプルをコンパイル
  5. C#コンソールサンプルをビルド
  6. -Testでは、実機を開かずにシミュレーションテストを実行

Set-Toolchain.ps1はVisual StudioとWindows SDKを探し、そのPowerShellプロセス内のビルド環境を設定します。システム全体のPATHは変更しません。

Coreは、元のUnityゲームに組み込まれていた通信・MIDI・APGコードをSDK用に分離したものです。NativeがC ABI公開とハンドル管理、ManagedがC#ラッパーです。ゲーム本体やAURAファームウェアのソースを参照せず、このフォルダ内のソースからDLLを再作成できます。

Unityでも実行確認する

.\Build-UnityVerification.ps1 -Backend Mono
.\Build-UnityVerification.ps1 -Backend IL2CPP

検証用の独立したUnityプロジェクトを05_ソースとビルド/out/UnityVerificationへ作ります。ビルドは別プロセスで開始し、PIDとログの場所を表示します。ログにAURA_UNITY_BUILD_OKと正常終了が出てから次のバックエンドを実行してください。同じ検証プロジェクトを2つのEditorで同時に開かないでください。

ビルド後のEXEを次の引数で起動すると、シミュレーションで制御して終了します。

.\out\UnityVerification\Builds\Mono\AuraSdkVerification.exe -batchmode -nographics -logFile mono_runtime.log
.\out\UnityVerification\Builds\IL2CPP\AuraSdkVerification.exe -batchmode -nographics -logFile il2cpp_runtime.log

成功時のログ:AURA_UNITY_SDK_OK。これらの検証はAURA実機のPCMを書き換えません。

Test-UnityVerification.ps1 -Backend Mono(またはIL2CPP)を使うと、最新DLLの配置、実行、終了コード、成功マーカーをまとめて検査できます。Unityパッケージを作り直す場合は、検証用Editorを終了した後にExport-UnityPackage.ps1を実行します。

コンソールサンプル

# SDK直下で実行。機器には接続しない
.\02_CSharpサンプル\bin\AuraConsole.exe --simulate
.\03_CPPサンプル\bin\AuraCppSample.exe --simulate

# 自分のAURAのポートを指定した場合だけ実機へ接続し、短く演奏する
.\02_CSharpサンプル\bin\AuraConsole.exe --port COM14
.\03_CPPサンプル\bin\AuraCppSample.exe --port COM14

実機サンプルもPCMプリセット書き込みAPIは呼びません。C++サンプルの実行に.NETランタイムは不要です。C#コンソールサンプルは.NET 10ランタイムを使用します。

同梱ファイルの由来

  • 通信/APG/MIDIコア:既存PACKAGE_Unity/Assets/Scripts/AudioからSDK用にコピー・拡張。
  • MIDI、CCD、APG JSON、PCMプリセット:元プロジェクトのサンプルデータからコピー。
  • NativeAOTランタイムのライセンスと第三者表記:このフォルダ内のライセンスに同梱。
  • AURA通信仕様・レジスターマップの参照用コピー:参考資料。

DLLのビルド日時・ハッシュ・確認したファームウェアなどは06_検証結果/検証結果.mdを参照してください。

AURA Unity SDK 検証結果

作成日:2026年10月25日 SDK 1.0.0 Windows x64

完成品

  • AURA.Native.dll:.NET 10.0.11 NativeAOTによるネイティブ共有ライブラリ。C ABI。利用側への.NET追加インストールは不要。
  • AURA.Unity.dll:.NET Standard 2.1のC#ラッパー。
  • C#コンソールとC++サンプル:コンパイル・実行成功。

制御テスト

build_and_tests.logに記録。18項目が成功。

ポート列挙、無効ハンドル、Win32ポートエラー、RUN状態の再同期、UTF-8/BOM付きCCD・JSON、接続失敗と再接続、パラメーター検証、リアルタイムMIDI、APG効果音、SMF再生・一時停止・テンポ、PCM発音、承認なしのPCM書き込み拒否、承認済み転送、1回再生・ループ・再開、全音停止、終了処理を確認。

承認済みPCMの書き込みテストはシミュレーション内で実行した。実機のPCM領域への書き込みは行っていない。

Unity

  • Unity 6000.3.23f1、Windows x64 Mono:ビルド・実行成功。
  • Unity 6000.3.23f1、Windows x64 IL2CPP:ビルド・実行成功。
  • 実行時は同梱DLLと同じハッシュのネイティブDLLを使用。MIDI時計、Pause、APG、CH10 PCM、未承認書き込みの拒否をシミュレーションで確認。

unity_mono_runtime.logの成功マーカー:AURA_UNITY_SDK_OK: Mono。unity_il2cpp_runtime.logの成功マーカー:AURA_UNITY_SDK_OK: IL2CPP。いずれも終了コード0。

実機

COM14のAURA 1.062を確認。C#コンソールで3回連続の接続・演奏命令・切断が成功し、C++サンプルも接続・制御成功。

  • hardware_csharp_COM14.log
  • hardware_cpp_COM14.log

接続初期化と終了処理のACK、およびMIDI/APG/PCMの送信を確認した。音声出力の聴感・録音による検証は行っていない。実機サンプルはPCMプリセット書き込みAPIを使用しない。

配布物

native_exports.txt:公開C関数一覧。

native_dependencies.txt:ネイティブDLLの依存先。Windows標準APIとUCRT。

SHA256SUMS.txt:完成した配布ファイルのSHA-256。

unitypackage_contents.txt:Unityインポート対象。検証専用スクリプトやシーンが入っていないことを確認。パッケージ検証.txtにDLL一致・C関数32個のエクスポート照合を記録。

Unityログは配布に必要な成功・エラー行を抽出したもの。生ログのローカル保存先は05_ソースとビルド/out/verification_raw_logsで、配布ZIPへは含めていない。

このSDKは元のUnityゲームとAURAファームウェアとは別フォルダに作成した。元プロジェクトのソース・音色データを上書きしていない。