Unityアセット「MIDI Plugin for Mobile devices」をリリースしました

Unity向けプラグインをアセットストアにてリリースしました。 

MIDI Plugin for Mobile devices

この記事ではプラグインの機能について紹介します。

機能

このプラグインはMIDIイベントの送受信機能をUnityのモバイル(iOS/Android)プロジェクトに追加します。

• MIDIイベントの受信と送信
• MIDI 1.0に定義されている、全ての種類のMIDIメッセージを扱うことができます。
• USB MIDI
• Android のみ
• Bluetooth MIDI (BLE MIDI)
• iOS と Android
• Apple Network MIDI (RTP-MIDI)
• iOS のみ

Android ベースの VRデバイスにも対応

プラグインはOculus Quest 2のような、AndroidベースのVRデバイスでも動作します。実世界のMIDI機器と呼応するVRオブジェクトを簡単に作成できます。VR世界のキューブを指したときにMIDIモジュールから音を出したり、その逆に実世界のMIDIキーボードを演奏したときにVR上のオブジェクトに反応させることができます。

サンプルシーンを試す

プラグインのインストール

• Unity Asset Storeからプラグインをインストールします。
• iOS または Androidのプラットフォームを選択し、サンプルシーンを含めてビルドします。
• サンプルシーン 「MidiSampleScene.unity」は Assets/MIDI/Samples/Scenes ディレクトリにあります。
• プラグインはUnity Editorでは動かないので、アプリバイナリをビルドして、実際のデバイスにインストールする必要があります。

MidiSampleScene

アプリでサンプルシーンを開くと、いくつかのGUIが現われます。

左のウィンドウではMIDIデバイスを選択し、いくつかのMIDIメッセージを送信できます。

右のウィンドウでは受信したMIDIメッセージが確認できます。

MIDIデバイスとの接続

• Android
• USB / Bluetooth MIDIデバイスは自動的に発見、接続されてGUIの「Device」のリストに表示されます。
• iOS
• Apple Network MIDIデバイスは自動的に接続され、GUIの「Device」のリストに表示されます。
• アプリが起動したときにBluetooth MIDIデバイスを選択します。

これらの初期化処理は MidiManager クラスの InitializeMidi メソッドに実装されています。

新しい機器の接続 / 切断 のイベントは IMidiDeviceEventHandler インタフェースを実装することで受信できます。

デバイス名はMidiManager クラスの GetDeviceName メソッドで取得できます。デバイス名をまだ受信できていない場合、空(null)になっている場合があります。

MIDI イベントの送信

MIDIイベントの送信処理のコードはこのように記述します。 

MIDI イベントの受信

MIDIイベントの受信処理のコードはこのように記述します。

オープンソース

パッケージ内のいくつかの部分はオープンソースプロジェクトです。以下のリストはパッケ0ージの依存ライブラリです。

全てのリポジトリは自作のものです。機能のリクエストや不具合報告など、githubにてお気軽にご連絡ください。

• Android Bluetooth MIDI ライブラリ: https://github.com/kshoji/BLE-MIDI-for-Android
• Android USB MIDI ライブラリ: https://github.com/kshoji/USB-MIDI-Driver
• iOS 向け Unity MIDI プラグイン: https://github.com/kshoji/Unity-MIDI-Plugin-iOS

Published Unity asset: MIDI Plugin for Mobile devices

I published a new plugin asset for Unity at the Store. 

MIDI Plugin for Mobile devices

This article explains about this plugin's features.

Features

This plugin enables MIDI event transceive functions to mobile Unity project(iOS/Android)

• MIDI Event Receiving and Sending
• The plugin can treat the all kind of MIDI events defined in MIDI 1.0.
• USB MIDI
• Android only
• Bluetooth MIDI (BLE MIDI)
• both of iOS and Android
• Apple Network MIDI (RTP-MIDI)
• iOS only

Works with Android-based VR devices

This plugin also work with Android-based VR devices, such as Oculus Quest 2. It can easily create app that VR objects interact with real MIDI instruments. When I pointed an cube in the VR world, the real-world MIDI module plays a sound. And vice versa, When I play real-world keyboard, the VR objects will be interacted with playing MIDI note.

How to try with a sample scene

Install the plugin

• Install the plugin from Unity Asset Store.
• Select the app's platform; iOS or Android, and build the app with sample scene.
• The sample scene 'MidiSampleScene.unity' is found at Assets/MIDI/Samples/Scenes directory.
• The plugin doesn't work with Unity Editor, so you should build the app binary and install it into the real devices.

MidiSampleScene

Start app with Sample scene, some GUI will be appeared.

The left window is for selecting MIDI device, and sending some MIDI messages.

The right window is for viewing received MIDI messages.

Connect with MIDI devices

• Android
• USB / Bluetooth MIDI devices will be automatically detected, connected, and displayed on GUI 'Device' list.
• iOS
• Apple Network MIDI devices are automatically connected and displayed on GUI 'Device' list.
• Select Bluetooth MIDI devices at the first time the app launched.

These initializations are implemented at InitializeMidi method in MidiManager class.

New connection / disconnection events can be received by implementing IMidiDeviceEventHandler interface.

The device's name can be got from GetDeviceName method in MidiManager class. The device's name may sometimes empty(null) if the name has not noticed yet.

Sending MIDI events

The implementation for sending MIDI events will be like this. 

Receiving MIDI events

The implementation for receiving MIDI events will be like this.

Open Source

Some parts of this package are Open Source project. The below list are dependency libraries in the package.

All repositories below are owned by me, feel free to feature request or issue reporting.

• Android Bluetooth MIDI library: https://github.com/kshoji/BLE-MIDI-for-Android
• Android USB MIDI library: https://github.com/kshoji/USB-MIDI-Driver
• Unity MIDI Plugin for iOS: https://github.com/kshoji/Unity-MIDI-Plugin-iOS

BLE MIDIの仕様でハマりそうなところ集

MIDI公式サイトでBLE MIDIの仕様書が公開されていたので、ハマりそうな部分について書いておきます。主にタイムスタンプについてです。
BLE MIDIのデバイスやライブラリを自前で実装してみようかな、という方にとって参考になるかもしれません。

BLE MIDIのタイムスタンプの仕様

BLE MIDIのデータの形式はこんな感じです(仕様書より)。従来のMIDI 1.0なメッセージにタイムスタンプ情報が付いた形です。BLEの1パケットに収まらない場合は分割することもできます。

上図はSysExというデータで、システムエクスクルーシブメッセージといい、機器の設定情報などをバイナリで送受信するためのものです。

• SysEx開始は 0xF0 (最初の緑色背景のデータ) 
• SysEx終端は 0xF7 (最後の緑色背景のデータ)
• SysEx終端が来るまでが、データです。データの内容・長さは自由です。
• SysEx終端もMIDIメッセージなので、「直前1バイト」に、タイムスタンプ下位7bitと0x80を論理和(OR)したデータが入ります (水色背景のデータ)
• タイムスタンプは、下位7ビットと、ヘッダ内にある上位の6ビット分と組み合わせて13ビット(0〜8191、ミリ秒)の値になります。この値で通信のレイテンシを吸収します。

ハマりポイント1: タイムスタンプの精度

タイムスタンプは送信側デバイスのクロック精度に依存するので、送信側のタイムスタンプの値が1000増えたからといって、受信側の時計でも正確に1000ミリ秒が経過しているとは限りません。

単体のキーボードや音源など、マイコンで処理しているデバイスでは精度がわりと怪しくなります。あくまで前回のイベントからの間隔として扱うのが良さそうです。8192ミリ秒までの間隔しか測れないので気をつけます。

ハマりポイント2: タイムスタンプの上限値跨ぎ処理

1パケットで複数のMIDIメッセージを受信することがあり、それらのタイムスタンプ下位が0xFFを跨いだ場合(図の例だと、SysEx開始時が0xFFで、SysEx終端が0x00のとき)や、タイムスタンプ全体の値が8191を跨いだ場合も、デバッグしていて微妙にハマります。8秒遅れてイベントが発火したり…。

こちらは、前回のイベントのタイムスタンプとの差がマイナスなら8192を足す、みたいな対処で回避できるでしょう。

ハマりポイント3: SysExデータの末尾に現れるタイムスタンプ情報

SysEx終端の直前にタイムスタンプ下位が入るので、その1バイトだけを除いたデータをSysExデータとする必要があります。先頭の0xF0と末尾の0xF7を含めたデータを返却することを前提としたAPIであれば、ちょっとだけ面倒な実装になりそうです。

ハマりポイント4: たまにSysExデータが欠ける

これが一番デカい罠だと思います。

SysExとタイムスタンプの仕様を見て、素直に「SysEx終端：0xF7が来るまでデータを読んだら、その直前の1バイトをタイムスタンプとして扱う」という解析処理を書いていると、仕様の罠にハマります。

そういう風に実装すると、イベントの発火タイミングが最大で127ミリ秒ズレて、その際にデータが欠損します。これはSysEx送受信の128回に1度の確率で発生します。

何故こんなことになるかというと…

タイムスタンプ下位7bitが0x77だった場合、送信されるバイト値は0xF7になります。0xF7を受信したからといって、この時点ではSysExをイベントキュー等に入れてはいけません。

正しくは「0xF7を受信したら次のデータ1バイトをチェックし、次も0xF7なら次のデータまでがSysEx、それ以外ならこのデータまでがSysEx」という風に実装する必要があります。

BLE MIDIは様々なデバイス間で使われる通信プロトコルのため、送受信の実装が拙いデバイスについても、異常動作しないように対応する必要があります。

具体的にはこの2つです。

• SysEx受信のときは、0xF7の2回受信を考慮して解析する。
• SysEx送信のときは、タイムスタンプの値として0xF7を送信しない。

以上、BLE MIDIを実装する際のハマりポイントでした。

Android用のBLE MIDIライブラリのご紹介

去年から、Android端末上でBLE MIDI通信を使えるようにするライブラリを作っていました。(→前回の記事を参照)
AppleがBluetooth Low Energy MIDI Specification(PDF)を公開していたのを先日見つけたので、その仕様に合うよう実装してみました。

このライブラリを使って出来ること：

• AndroidアプリとBLE MIDIなデバイスとが接続でき、演奏やイベントの記録などをすることができます。
• iOSやOS X上で動くBLE MIDIなアプリとも接続できます。
• Android LollipopかつPeripheral機能がサポートされている端末では、端末をBLE MIDIデバイスとして振る舞わせることができます。

注意:

このAppleの仕様は、まだMIDI公式から承認されていません。以前問い合わせをしたところ、「ドラフトの仕様はあるが絶賛議論中だよ。議論を見たかったら会員になってね♡」とのことでした。公式としてリリースされる仕様ではAppleのものとの食い違いが出てくるかもしれません。頑張って追従します。

ライブラリの機能

このライブラリを使うことで、AndroidはBLE MIDI CentralとPeripheralの機能を使えるようになります。

BLE MIDI Central機能とは

AndroidアプリがBLE MIDIデバイスを探して、接続します。アプリはデバイスとMIDIメッセージを送受信できます。
この機能にはAndroid JellyBean MR2(4.3 / API Level 18)以降が必要です。ペアリング機能を使うにはAndroid KitKat(4.4 / API Level 19)以降が必要です。

BLE MIDI Peripheral機能とは

AndroidアプリがBLE MIDIデバイスとして振舞います。アプリは他の端末上(Android, iOS, OS X)のCentralなアプリから接続して使用されます。

MIDI over Bluetooth LE library for Android

I've been developing the library to enable BLE MIDI feature on the Android devices from last year. The Apple Bluetooth Low Energy MIDI Specification(PDF) had revealed at December 2014. And finally, I implemented all of features on the specification.

Using this library, the app can connect with BLE MIDI devices, and BLE MIDI compatible iOS/Android/OS X apps. On the Android Lollipop, the app can act as BLE MIDI device.

Note:

This Apple's specification has not been approved by MIDI Manufacturers Association(MMA). I've asked about the specification to MMA at the past, but it was under discussion with MMA members.

The MMA's official release version's specification might be different from Apple's one.

The library's features

With this library, the Android can provide BLE MIDI Central / Peripheral features.

BLE MIDI Central feature

The Android app can host BLE MIDI devices. The app can receive MIDI messages from BLE MIDI devices, and send MIDI messages to them.
This feature requires Android KitKat(4.4 / API Level 19) or later.

BLE MIDI Peripheral feature

The Android app can pretend as BLE MIDI device. The application on the another machine(Android / iOS / OS X) can connect with the Android app.

複数PCの楽器アプリ同士を繋ぐUSB MIDIケーブルを作ってみた

AndroidタブレットとMacを接続して演奏してみたかったので、USB MIDIクライアントを2つ結合したものを作ってみました。
近い将来、これを使ってAndroidタブレット用のPCDJコントローラでも作れたらいいな、という感じです。

方針

今回は、AVRのV-USBを使って、USB MIDIを扱います。ソースコードはMICO-MOCOを参考にしました。

MICO-MOCOではUSB MIDI→レガシーMIDIに変換する必要があったので、送受信を含めるとATtiny2313のメモリには収まらなかったのですが、今回のものは「USB MIDIのプロトコルをそのままブリッジする」という作りになっているため、プロトコル変換処理をばっさり省略できています。
MIDIを介さない利点として「31250baudでシリアル通信する必要がない」という点が挙げられます。クロックが最速20MHzのものを選択できるので、取りこぼしが少なくなることが期待できます(今回の試作では、16MHz/125000baudで通信しています)。送受信用のバッファは短かいですし、USB MIDIのプロトコルそのままなので、MIDIのパケット長はレガシーMIDIよりも長くなっていますが…。

Android USB MIDI Driverのご紹介

Android USB MIDI Driverって?

「Android 3.1 (API Level 12)以降向けの、USB MIDIを使うためのライブラリ」です。
Android 3系のタブレットや、Android4系のスマートフォンを使って、特に改造やroot化することなしに、USB MIDI対応の楽器や機器を繋げることができるようになります。

注意：端末がUSB Host機能に対応している必要があります。USB Host対応端末であっても、USB MIDI機器が認識しない場合があります。

USB MIDI対応デバイスの例：キーボード、電子ピアノ、シンセサイザー、音源モジュールなどの楽器・コントローラ、変換ケーブルなどのPC用MIDIインタフェースなど。

ライブラリのソースコードは、こちらのgithubリポジトリからダウンロードできます。Apache ライセンス バージョン 2.0です。
https://github.com/kshoji/USB-MIDI-Driver

応用アプリの例

• (楽器のほうの)キーボードを使ってプレゼンを操作
• 演奏をディスプレイ上にリアルタイムで可視化
• TENORI-ON/monomeのようなインタラクティブなシーケンサー
• 加速度やジャイロなどのセンサーを使用したコントローラ

などなど…