Native MIDI API

Die AMidi API ist in Android NDK r20b und höher verfügbar. Es ermöglicht App-Entwicklern, MIDI-Daten mit C/C++-Code zu senden und zu empfangen.

Android-MIDI-Apps verwenden in der Regel die midi API, um mit dem Android-MIDI-Dienst zu kommunizieren. MIDI-Apps sind in erster Linie auf MidiManager angewiesen, um ein oder mehrere MidiDevice-Objekte zu finden, zu öffnen und zu schließen und Daten über die MIDI-Eingabe- und Ausgabe-Ports des Geräts an und von jedem Gerät zu übergeben:

Wenn Sie AMidi verwenden, übergeben Sie die Adresse einer MidiDevice mit einem JNI-Aufruf an die native Codeebene. AMidi erstellt dann eine Referenz auf eine AMidiDevice, die die meisten Funktionen einer MidiDevice hat. Ihr nativer Code verwendet AMidi-Funktionen, die direkt mit einer AMidiDevice kommunizieren. Die AMidiDevice stellt eine direkte Verbindung zum MIDI-Dienst her:

Mit AMidi-Aufrufen können Sie die C/C++-Audio-/Steuerungslogik Ihrer App eng mit der MIDI-Übertragung verknüpfen. Es ist weniger Bedarf an JNI-Aufrufen oder Rückrufen an die Java-Seite Ihrer App erforderlich. Ein in C-Code implementierter digitaler Synthesizer kann beispielsweise Schlüsselereignisse direkt von einer AMidiDevice empfangen, anstatt auf einen JNI-Aufruf zu warten, um die Ereignisse von der Java-Seite zu senden. Oder ein algorithmischer Kompositionsprozess könnte eine MIDI-Wiedergabe direkt an eine AMidiDevice senden, ohne die Java-Seite aufzurufen, um die Schlüsselereignisse zu übertragen.

AMidi verbessert zwar die direkte Verbindung zu MIDI-Geräten, Apps müssen aber weiterhin MidiManager verwenden, um MidiDevice-Objekte zu finden und zu öffnen. AMidi kann dann den Rest übernehmen.

Manchmal müssen Sie Informationen von der UI-Ebene an den nativen Code weitergeben. Beispielsweise, wenn MIDI-Ereignisse als Reaktion auf Schaltflächen auf dem Bildschirm gesendet werden. Erstellen Sie dazu benutzerdefinierte JNI-Aufrufe an Ihre native Logik. Wenn Sie Daten zurücksenden müssen, um die Benutzeroberfläche zu aktualisieren, können Sie wie gewohnt von der nativen Schicht aus zurückrufen.

In diesem Dokument wird beschrieben, wie du eine AMidi-Anwendung mit nativem Code einrichtest. Außerdem findest du Beispiele zum Senden und Empfangen von MIDI-Befehlen. Ein vollständiges funktionierendes Beispiel finden Sie in der Beispiel-App NativeMidi.

AMidi verwenden

Alle Apps, die AMidi verwenden, haben dieselben Einrichtungs- und Abschlussschritte, unabhängig davon, ob sie MIDI senden oder empfangen oder beides.

AMidi starten

Auf Java-Seite muss die App eine angeschlossene MIDI-Hardware finden, eine entsprechende MidiDevice erstellen und an den nativen Code übergeben.

1. MIDI-Hardware mit der Java-Klasse MidiManager kennenlernen
2. Holen Sie sich ein Java-MidiDevice-Objekt, das der MIDI-Hardware entspricht.
3. Übergeben Sie das Java-MidiDevice mit JNI an den nativen Code.

Hardware und Ports erkennen

Die Eingabe- und Ausgabeportobjekte gehören nicht zur App. Sie stellen Ports auf dem MIDI-Gerät dar. Wenn MIDI-Daten an ein Gerät gesendet werden sollen, öffnet eine App eine MIDIInputPort und schreibt dann Daten darauf. Umgekehrt öffnet eine App eine MIDIOutputPort, um Daten zu empfangen. Damit die App ordnungsgemäß funktioniert, muss sie sicher sein, dass die geöffneten Ports den richtigen Typ haben. Die Geräte- und Porterkennung erfolgt auf Java-Seite.

Hier ist eine Methode, mit der jedes MIDI-Gerät erkannt und seine Ports geprüft werden. Es wird entweder eine Liste von Geräten mit Ausgabeports für den Empfang von Daten oder eine Liste von Geräten mit Eingabeports für das Senden von Daten zurückgegeben. Ein MIDI-Gerät kann sowohl Eingabe- als auch Ausgabeports haben.

private fun getMidiDevices(isOutput: Boolean) : List {
    if (isOutput) {
        return mMidiManager.devices.filter { it.outputPortCount > 0 }
    } else {
        return mMidiManager.devices.filter { it.inputPortCount > 0 }
    }
}

private List getMidiDevices(boolean isOutput){
  ArrayList filteredMidiDevices = new ArrayList<>();

  for (MidiDeviceInfo midiDevice : mMidiManager.getDevices()){
    if (isOutput){
      if (midiDevice.getOutputPortCount() > 0) filteredMidiDevices.add(midiDevice);
    } else {
      if (midiDevice.getInputPortCount() > 0) filteredMidiDevices.add(midiDevice);
    }
  }
  return filteredMidiDevices;
}

Wenn Sie AMidi-Funktionen in Ihrem C/C++-Code verwenden möchten, müssen Sie AMidi/AMidi.h einbinden und eine Verknüpfung mit der amidi-Bibliothek herstellen. Sie finden sie im Android NDK.

Die Java-Seite sollte über einen JNI-Aufruf ein oder mehrere MidiDevice-Objekte und Portnummern an die native Schicht übergeben. Die native Schicht sollte dann die folgenden Schritte ausführen:

1. Ermitteln Sie für jede Java-MidiDevice mit AMidiDevice_fromJava() eine AMidiDevice.
2. Rufen Sie eine AMidiInputPort und/oder AMidiOutputPort von der AMidiDevice mit AMidiInputPort_open() und/oder AMidiOutputPort_open() ab.
3. Verwenden Sie die erhaltenen Ports, um MIDI-Daten zu senden und/oder zu empfangen.

AMidi beenden

Die Java-App sollte der nativen Schicht signalisieren, Ressourcen freizugeben, wenn sie das MIDI-Gerät nicht mehr verwendet. Das kann daran liegen, dass die Verbindung zum MIDI-Gerät getrennt wurde oder die App beendet wird.

Damit MIDI-Ressourcen freigegeben werden können, sollte Ihr Code folgende Aufgaben ausführen:

1. Beenden Sie das Lesen und/oder Schreiben an MIDI-Ports. Wenn Sie einen Lese-Thread verwendet haben, um nach Eingaben zu suchen (siehe unten Polling-Schleife implementieren), beenden Sie den Thread.
2. Schließen Sie alle geöffneten AMidiInputPort- und/oder AMidiOutputPort-Objekte mit den Funktionen AMidiInputPort_close() und/oder AMidiOutputPort_close().
3. Gib die AMidiDevice mit AMidiDevice_release() frei.

MIDI-Daten empfangen

Ein typisches Beispiel für eine MIDI-App, die MIDI empfängt, ist ein „virtueller Synthesizer“, der MIDI-Leistungsdaten zur Steuerung der Audiosynthese empfängt.

Eingehende MIDI-Daten werden asynchron empfangen. Daher ist es am besten, MIDI in einem separaten Thread zu lesen, der kontinuierlich einen oder mehrere MIDI-Ausgabeports abfragt. Dies kann ein Hintergrund- oder Audio-Thread sein. AMidi blockiert nicht beim Lesen von einem Anschluss und kann daher in einem Audio-Callback sicher verwendet werden.

MidiDevice und seine Ausgabeports einrichten

Eine App liest eingehende MIDI-Daten von den Ausgabeports eines Geräts. Die Java-Seite Ihrer App muss festlegen, welches Gerät und welche Ports verwendet werden sollen.

Dieses Snippet erstellt die MidiManager über den MIDI-Dienst von Android und öffnet eine MidiDevice für das erste gefundene Gerät. Wenn die MidiDevice geöffnet wurde, wird ein Callback an eine Instanz von MidiManager.OnDeviceOpenedListener() gesendet. Die Methode onDeviceOpened dieses Listeners wird aufgerufen, die dann startReadingMidi() aufruft, um den Ausgabeport 0 auf dem Gerät zu öffnen. Dies ist eine JNI-Funktion, die in AppMidiManager.cpp definiert ist. Diese Funktion wird im nächsten Snippet erläutert.

//AppMidiManager.kt
class AppMidiManager(context : Context) {
  private external fun startReadingMidi(midiDevice: MidiDevice,
  portNumber: Int)
  val mMidiManager : MidiManager = context.getSystemService(Context.MIDI_SERVICE) as MidiManager

  init {
    val midiDevices = getMidiDevices(true) // method defined in snippet above
    if (midiDevices.isNotEmpty()){
      midiManager.openDevice(midiDevices[0], {
        startReadingMidi(it, 0)
      }, null)
    }
  }
}

//AppMidiManager.java
public class AppMidiManager {
  private native void startReadingMidi(MidiDevice device, int portNumber);
  private MidiManager mMidiManager;
  AppMidiManager(Context context){
    mMidiManager = (MidiManager)
      context.getSystemService(Context.MIDI_SERVICE);
    List midiDevices = getMidiDevices(true); // method defined in snippet above
    if (midiDevices.size() > 0){
      mMidiManager.openDevice(midiDevices.get(0),
        new MidiManager.OnDeviceOpenedListener() {
        @Override
        public void onDeviceOpened(MidiDevice device) {
          startReadingMidi(device, 0);
        }
      },null);
    }
  }
}

Der native Code übersetzt das Java-MIDI-Gerät und seine Ports in Referenzen, die von AMidi-Funktionen verwendet werden.

Hier ist die JNI-Funktion, die eine AMidiDevice erstellt, indem AMidiDevice_fromJava() aufgerufen wird, und dann AMidiOutputPort_open() aufruft, um einen Ausgabeport auf dem Gerät zu öffnen:

AppMidiManager.cpp

AMidiDevice midiDevice;
static pthread_t readThread;

static const AMidiDevice* midiDevice = AMIDI_INVALID_HANDLE;
static std::atomic<AMidiOutputPort*> midiOutputPort(AMIDI_INVALID_HANDLE);

void Java_com_nativemidiapp_AppMidiManager_startReadingMidi(
        JNIEnv* env, jobject, jobject deviceObj, jint portNumber) {
    AMidiDevice_fromJava(j_env, deviceObj, &midiDevice);

    AMidiOutputPort* outputPort;
    int32_t result =
      AMidiOutputPort_open(midiDevice, portNumber, &outputPort);
    // check for errors...

    // Start read thread
    int pthread_result =
      pthread_create(&readThread, NULL, readThreadRoutine, NULL);
    // check for errors...

}

Polling-Schleife implementieren

Apps, die MIDI-Daten empfangen, müssen den Ausgabeport abfragen und reagieren, wenn AMidiOutputPort_receive() eine Zahl größer als null zurückgibt.

Bei Anwendungen mit geringer Bandbreite, z. B. einem MIDI-Scope, können Sie die Abfrage in einem Hintergrund-Thread mit niedriger Priorität (mit entsprechenden Zeiträumen) durchführen.

Bei Apps, die Audio generieren und strengere Echtzeit-Leistungsanforderungen haben, können Sie im Haupt-Callback für die Audiogenerierung (BufferQueue-Callback für OpenSL ES, AudioStream-Daten-Callback in AAudio) eine Abfrage durchführen. Da AMidiOutputPort_receive() nicht blockierend ist, hat dies nur sehr geringe Auswirkungen auf die Leistung.

Die Funktion readThreadRoutine(), die von der Funktion startReadingMidi() oben aufgerufen wird, könnte so aussehen:

void* readThreadRoutine(void * /*context*/) {
    uint8_t inDataBuffer[SIZE_DATABUFFER];
    int32_t numMessages;
    uint32_t opCode;
    uint64_t timestamp;
    reading = true;
    while (reading) {
        AMidiOutputPort* outputPort = midiOutputPort.load();
        numMessages =
              AMidiOutputPort_receive(outputPort, &opCode, inDataBuffer,
                                sizeof(inDataBuffer), &timestamp);
        if (numMessages >= 0) {
            if (opCode == AMIDI_OPCODE_DATA) {
                // Dispatch the MIDI data….
            }
        } else {
            // some error occurred, the negative numMessages is the error code
            int32_t errorCode = numMessages;
        }
  }
}

Eine App, die eine native Audio-API wie OpenSL ES oder AAudio verwendet, kann dem Callback für die Audiogenerierung MIDI-Empfangscode hinzufügen. Dazu ist folgender Code erforderlich:

void bqPlayerCallback(SLAndroidSimpleBufferQueueItf bq, void */*context*/)
{
    uint8_t inDataBuffer[SIZE_DATABUFFER];
    int32_t numMessages;
    uint32_t opCode;
    uint64_t timestamp;

    // Read MIDI Data
    numMessages = AMidiOutputPort_receive(outputPort, &opCode, inDataBuffer,
        sizeof(inDataBuffer), &timestamp);
    if (numMessages >= 0 && opCode == AMIDI_OPCODE_DATA) {
        // Parse and respond to MIDI data
        // ...
    }

    // Generate Audio…
    // ...
}

Das folgende Diagramm veranschaulicht den Ablauf einer MIDI-Lese-App:

MIDI-Daten senden

Ein typisches Beispiel für eine MIDI-Programmier-App ist ein MIDI-Controller oder -Sequencer.

MidiDevice und seine Eingabeports einrichten

Eine App schreibt ausgehende MIDI-Daten in die Eingabeports eines MIDI-Geräts. Die Java-Seite Ihrer App muss festlegen, welches MIDI-Gerät und welche Ports verwendet werden sollen.

Der folgende Einrichtungscode ist eine Variante des obigen Beispiels für den Empfänger. Er erstellt die MidiManager aus dem MIDI-Dienst von Android. Anschließend öffnet er die erste gefundene MidiDevice und ruft startWritingMidi() auf, um den ersten Eingabeport auf dem Gerät zu öffnen. Dies ist ein JNI-Aufruf, der in AppMidiManager.cpp definiert ist. Die Funktion wird im nächsten Snippet erläutert.

//AppMidiManager.kt
class AppMidiManager(context : Context) {
  private external fun startWritingMidi(midiDevice: MidiDevice,
  portNumber: Int)
  val mMidiManager : MidiManager = context.getSystemService(Context.MIDI_SERVICE) as MidiManager

  init {
    val midiDevices = getMidiDevices(false) // method defined in snippet above
    if (midiDevices.isNotEmpty()){
      midiManager.openDevice(midiDevices[0], {
        startWritingMidi(it, 0)
      }, null)
    }
  }
}

//AppMidiManager.java
public class AppMidiManager {
  private native void startWritingMidi(MidiDevice device, int portNumber);
  private MidiManager mMidiManager;

  AppMidiManager(Context context){
    mMidiManager = (MidiManager)
      context.getSystemService(Context.MIDI_SERVICE);
    List midiDevices = getMidiDevices(false); // method defined in snippet above
    if (midiDevices.size() > 0){
      mMidiManager.openDevice(midiDevices.get(0),
        new MidiManager.OnDeviceOpenedListener() {
        @Override
        public void onDeviceOpened(MidiDevice device) {
          startWritingMidi(device, 0);
        }
      },null);
    }
  }
}

Hier ist die JNI-Funktion, die eine AMidiDevice erstellt, indem AMidiDevice_fromJava() aufgerufen wird, und dann AMidiInputPort_open() aufruft, um einen Eingabeport auf dem Gerät zu öffnen:

AppMidiManager.cpp

void Java_com_nativemidiapp_AppMidiManager_startWritingMidi(
       JNIEnv* env, jobject, jobject midiDeviceObj, jint portNumber) {
   media_status_t status;
   status = AMidiDevice_fromJava(
     env, midiDeviceObj, &sNativeSendDevice);
   AMidiInputPort *inputPort;
   status = AMidiInputPort_open(
     sNativeSendDevice, portNumber, &inputPort);

   // store it in a global
   sMidiInputPort = inputPort;
}

MIDI-Daten senden

Da das Timing der ausgehenden MIDI-Daten gut verstanden und von der App selbst gesteuert wird, kann die Datenübertragung im Hauptthread der MIDI-App erfolgen. Aus Leistungsgründen (wie in einem Sequencer) können die Generierung und Übertragung von MIDI jedoch in einem separaten Thread erfolgen.

Apps können MIDI-Daten jederzeit senden. Beachte, dass AMidi beim Schreiben von Daten blockiert.

Hier ist eine Beispiel-JNI-Methode, die einen MIDI-Befehlsbuffer empfängt und ausgibt:

void Java_com_nativemidiapp_TBMidiManager_writeMidi(
JNIEnv* env, jobject, jbyteArray data, jint numBytes) {
   jbyte* bufferPtr = env->GetByteArrayElements(data, NULL);
   AMidiInputPort_send(sMidiInputPort, (uint8_t*)bufferPtr, numBytes);
   env->ReleaseByteArrayElements(data, bufferPtr, JNI_ABORT);
}

Das folgende Diagramm veranschaulicht den Ablauf einer MIDI-Schreib-App:

Callbacks

Auch wenn es sich nicht streng genommen um eine AMidi-Funktion handelt, muss Ihr nativer Code möglicherweise Daten an die Java-Seite zurückgeben, um beispielsweise die Benutzeroberfläche zu aktualisieren. Dazu müssen Sie Code auf der Java-Seite und der nativen Schicht schreiben:

• Erstellen Sie eine Callback-Methode auf Java-Seite.
• Schreiben Sie eine JNI-Funktion, in der die Informationen zum Aufrufen des Callbacks gespeichert werden.

Wenn es Zeit für den Rückruf ist, kann Ihr nativer Code

Hier ist die Java-seitige Callback-Methode onNativeMessageReceive():

//MainActivity.kt
private fun onNativeMessageReceive(message: ByteArray) {
  // Messages are received on some other thread, so switch to the UI thread
  // before attempting to access the UI
  runOnUiThread { showReceivedMessage(message) }
}

//MainActivity.java
private void onNativeMessageReceive(final byte[] message) {
        // Messages are received on some other thread, so switch to the UI thread
        // before attempting to access the UI
        runOnUiThread(new Runnable() {
            public void run() {
                showReceivedMessage(message);
            }
        });
}

Hier ist der C-Code für die JNI-Funktion, mit der ein Rückruf zu MainActivity.onNativeMessageReceive() eingerichtet wird. Java MainActivity ruft beim Start initNative() auf:

MainActivity.cpp

/**
 * Initializes JNI interface stuff, specifically the info needed to call back into the Java
 * layer when MIDI data is received.
 */
JNICALL void Java_com_example_nativemidi_MainActivity_initNative(JNIEnv * env, jobject instance) {
    env->GetJavaVM(&theJvm);

    // Setup the receive data callback (into Java)
    jclass clsMainActivity = env->FindClass("com/example/nativemidi/MainActivity");
    dataCallbackObj = env->NewGlobalRef(instance);
    midDataCallback = env->GetMethodID(clsMainActivity, "onNativeMessageReceive", "([B)V");
}

Wenn es an der Zeit ist, Daten zurück an Java zu senden, ruft der native Code die Callback-Pointer ab und erstellt den Callback:

AppMidiManager.cpp

// The Data Callback
extern JavaVM* theJvm;              // Need this for allocating data buffer for...
extern jobject dataCallbackObj;     // This is the (Java) object that implements...
extern jmethodID midDataCallback;   // ...this callback routine

static void SendTheReceivedData(uint8_t* data, int numBytes) {
    JNIEnv* env;
    theJvm->AttachCurrentThread(&env, NULL);
    if (env == NULL) {
        LOGE("Error retrieving JNI Env");
    }

    // Allocate the Java array and fill with received data
    jbyteArray ret = env->NewByteArray(numBytes);
    env->SetByteArrayRegion (ret, 0, numBytes, (jbyte*)data);

    // send it to the (Java) callback
    env->CallVoidMethod(dataCallbackObj, midDataCallback, ret);
}

Weitere Informationen

• AMidi-Referenz
• Die vollständige Native MIDI-Beispiel-App finden Sie auf GitHub.