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に入れる手順
01_Unityに入れる/AURA_Unity_SDK.unitypackage をUnityでインポートします。フォルダで導入する場合は、同じ場所のAssetsの中身をUnityプロジェクトのAssetsへコピーします。
- 空のGameObjectを作り、
Assets/AURA_SDK/Samples/AURAQuickStart.cs を追加します。
- 最初はInspectorの Simulation をONにしてPlayし、接続・演奏の操作を確認できます。このモードでは音は出ません。
- 実機では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. 画面付きサンプルを動かす
- シーンに空のGameObjectを作成します。
AURAQuickStart を追加します。
- SimulationをONにしてPlayします。
- 「接続」を押し、MIDI再生や効果音のボタンを試します。
- 実機の音を出すときは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, ®isters, &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
作成するもの:
- NativeAOTで
AURA.Native.dllを作成
- .NET Standard 2.1で
AURA.Unity.dllを作成
- Unity用の配布場所へコピー
- C++用インポートライブラリをコピーし、C++サンプルをコンパイル
- C#コンソールサンプルをビルド
-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ファームウェアとは別フォルダに作成した。元プロジェクトのソース・音色データを上書きしていない。