Natywny interfejs MIDI API

Interfejs AMidi API jest dostępny w Androidzie NDK r20b i nowszych. Umożliwia on programistom aplikacji wysyłanie i odbieranie danych MIDI za pomocą kodu C/C++.

Aplikacje MIDI na Androida zwykle używają interfejsu midi API do komunikacji z usługą MIDI na Androidzie. Aplikacje MIDI korzystają głównie z interfejsu MidiManager, aby wykrywać, otwierać, i zamykać co najmniej 1 obiekt MidiDevice oraz przekazywać dane do i z każdego urządzenia przez porty MIDI wejściowe i wyjściowe:

Gdy używasz AMidi, przekazujesz adres MidiDevice do warstwy kodu natywnego za pomocą wywołania JNI. AMidi tworzy wtedy odniesienie do AMidiDevice które ma większość funkcji MidiDevice. Kod natywny używa funkcji AMidi, które komunikują się bezpośrednio z AMidiDevice. AMidiDevice łączy się bezpośrednio z usługą MIDI:

Za pomocą wywołań AMidi możesz ściśle zintegrować logikę audio/sterowania C/C++ aplikacji z transmisją MIDI. Nie ma potrzeby wykonywania wywołań JNI ani wywołań zwrotnych do strony Java aplikacji. Na przykład syntezator cyfrowy zaimplementowany w kodzie C może odbierać zdarzenia klawiszy bezpośrednio z AMidiDevice, zamiast czekać na wywołanie JNI, które wyśle zdarzenia ze strony Java. Proces komponowania algorytmicznego może też wysyłać wykonanie MIDI bezpośrednio do AMidiDevice bez wywoływania strony Java w celu przesłania zdarzeń klawiszy.

Chociaż AMidi poprawia bezpośrednie połączenie z urządzeniami MIDI, aplikacje nadal muszą używać MidiManager do wykrywania i otwierania obiektów MidiDevice. AMidi może przejąć kontrolę.

Czasami może być konieczne przekazanie informacji z warstwy interfejsu do kodu natywnego. Na przykład gdy zdarzenia MIDI są wysyłane w odpowiedzi na naciśnięcie przycisków na ekranie. Aby to zrobić, utwórz niestandardowe wywołania JNI do logiki natywnej. Jeśli chcesz wysłać dane z powrotem, aby zaktualizować interfejs, możesz jak zwykle wywołać warstwę natywną.

Z tego dokumentu dowiesz się, jak skonfigurować aplikację z kodem natywnym AMidi. Znajdziesz w nim przykłady wysyłania i odbierania poleceń MIDI. Aby zobaczyć kompletny działający przykład, zapoznaj się z przykładową aplikacją NativeMidi.

Korzystanie z AMidi

Wszystkie aplikacje, które używają AMidi, mają te same kroki konfiguracji i zamykania, niezależnie od tego, czy wysyłają, odbierają czy robią obie te rzeczy.

Uruchamianie AMidi

Po stronie Java aplikacja musi wykryć podłączony sprzęt MIDI, utworzyć odpowiedni MidiDevice i przekazać go do kodu natywnego.

Wykryj sprzęt MIDI za pomocą klasy MidiManager w Javie.
Uzyskaj obiekt MidiDevice w Javie odpowiadający sprzętowi MIDI.
Przekaż MidiDevice w Javie do kodu natywnego za pomocą JNI.

Wykrywanie sprzętu i portów

Obiekty portów wejściowych i wyjściowych nie należą do aplikacji. Reprezentują porty na urządzeniu MIDI. Aby wysłać dane MIDI do urządzenia, aplikacja otwiera MIDIInputPort i zapisuje w nim dane. Aby odebrać dane, aplikacja otwiera MIDIOutputPort. Aby aplikacja działała prawidłowo, musi mieć pewność, że otwierane porty są odpowiedniego typu. Wykrywanie urządzeń i portów odbywa się po stronie Java.

Oto metoda, która wykrywa każde urządzenie MIDI i sprawdza jego porty. Zwraca listę urządzeń z portami wyjściowymi do odbierania danych lub listę urządzeń z portami wejściowymi do wysyłania danych. Urządzenie MIDI może mieć zarówno porty wejściowe, jak i wyjściowe.

Kotlin

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

Java

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;
}

Aby używać funkcji AMidi w kodzie C/C++, musisz dołączyć AMidi/AMidi.h i połączyć się z biblioteką amidi. Oba te elementy znajdziesz w Androidzie NDK.

Strona Java powinna przekazać co najmniej 1 obiekt MidiDevice i numery portów do warstwy natywnej za pomocą wywołania JNI. Warstwa natywna powinna wykonać te czynności:

Dla każdego MidiDevice w Javie uzyskaj AMidiDevice za pomocą AMidiDevice_fromJava().
Uzyskaj AMidiInputPort lub AMidiOutputPort z AMidiDevice za pomocą AMidiInputPort_open() lub AMidiOutputPort_open().
Użyj uzyskanych portów do wysyłania lub odbierania danych MIDI.

Zatrzymywanie AMidi

Gdy aplikacja Java przestanie używać urządzenia MIDI, powinna wysłać do warstwy natywnej sygnał, aby zwolnić zasoby. Może to być spowodowane odłączeniem urządzenia MIDI lub zamknięciem aplikacji.

Aby zwolnić zasoby MIDI, kod powinien wykonać te czynności:

Zatrzymaj odczytywanie i/lub zapisywanie w portach MIDI. Jeśli używasz wątku odczytu do sondowania danych wejściowych (patrz Implementowanie pętli sondowania poniżej), zatrzymaj ten wątek.
Zamknij wszystkie otwarte obiekty AMidiInputPort lub AMidiOutputPort za pomocą AMidiInputPort_close() lub AMidiOutputPort_close() funkcji.
Zwolnij AMidiDevice za pomocą AMidiDevice_release().

Odbieranie danych MIDI

Typowym przykładem aplikacji MIDI, która odbiera MIDI, jest „wirtualny syntezator”, który odbiera dane wykonania MIDI w celu sterowania syntezą dźwięku.

Przychodzące dane MIDI są odbierane asynchronicznie. Dlatego najlepiej jest odczytywać MIDI w osobnym wątku, który stale sonduje co najmniej 1 port wyjściowy MIDI. Może to być wątek w tle lub wątek audio. AMidi nie blokuje się podczas odczytywania z portu, dlatego można go bezpiecznie używać w wywołaniu zwrotnym audio.

Konfigurowanie MidiDevice i jego portów wyjściowych

Aplikacja odczytuje przychodzące dane MIDI z portów wyjściowych urządzenia. Strona Java aplikacji musi określić, którego urządzenia i portów używać.

Ten fragment kodu tworzy MidiManager z usługi MIDI na Androidzie i otwiera MidiDevice dla pierwszego znalezionego urządzenia. Po otwarciu MidiDevice wywołanie zwrotne jest odbierane w instancji MidiManager.OnDeviceOpenedListener(). Wywoływana jest metoda onDeviceOpened tego odbiornika, która następnie wywołuje startReadingMidi() w celu otwarcia portu wyjściowego 0 na urządzeniu. Jest to funkcja JNI zdefiniowana w AppMidiManager.cpp. Ta funkcja jest opisana w następnym fragmencie kodu.

Kotlin

//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)
    }
  }
}

Java

//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);
    }
  }
}

Kod natywny tłumaczy urządzenie MIDI i jego porty po stronie Java na odniesienia używane przez funkcje AMidi.

Oto funkcja JNI, która tworzy AMidiDevice przez wywołanie AMidiDevice_fromJava(), a następnie wywołuje AMidiOutputPort_open() w celu otwarcia portu wyjściowego na urządzeniu:

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...

}

Implementowanie pętli sondowania

Aplikacje, które odbierają dane MIDI, muszą sondować port wyjściowy i reagować, gdy AMidiOutputPort_receive() zwraca liczbę większą od zera.

W przypadku aplikacji o niskiej przepustowości, takich jak zakres MIDI, możesz sondować w wątku w tle o niskim priorytecie (z odpowiednimi przerwami).

W przypadku aplikacji, które generują dźwięk i mają bardziej rygorystyczne wymagania dotyczące wydajności w czasie rzeczywistym, możesz sondować w głównym wywołaniu zwrotnym generowania dźwięku (wywołanie zwrotne BufferQueue w OpenSL ES, wywołanie zwrotne danych AudioStream w AAudio). Ponieważ AMidiOutputPort_receive() nie blokuje, wpływ na wydajność jest bardzo mały.

Funkcja readThreadRoutine() wywoływana z funkcji startReadingMidi() powyżej może wyglądać tak:

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;
        }
  }
}

Aplikacja korzystająca z natywnego interfejsu audio API (np. OpenSL ES lub AAudio) może dodać kod odbierania MIDI do wywołania zwrotnego generowania dźwięku w ten sposób:

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…
    // ...
}

Na diagramie poniżej przedstawiono przepływ aplikacji do odczytywania MIDI:

Wysyłanie danych MIDI

Typowym przykładem aplikacji do zapisywania MIDI jest kontroler lub sekwencer MIDI.

Konfigurowanie MidiDevice i jego portów wejściowych

Aplikacja zapisuje wychodzące dane MIDI w portach wejściowych urządzenia MIDI. Strona Java aplikacji musi określić, którego urządzenia MIDI i portów używać.

Poniższy kod konfiguracji jest odmianą powyższego przykładu odbierania. Tworzy MidiManager z usługi MIDI na Androidzie. Następnie otwiera pierwszy znaleziony MidiDevice i wywołuje startWritingMidi() w celu otwarcia pierwszego portu wejściowego na urządzeniu. Jest to wywołanie JNI zdefiniowane w AppMidiManager.cpp. Ta funkcja jest opisana w następnym fragmencie kodu.

Kotlin

//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)
    }
  }
}

Java

//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);
    }
  }
}

Oto funkcja JNI, która tworzy AMidiDevice przez wywołanie AMidiDevice_fromJava(), a następnie wywołuje AMidiInputPort_open() w celu otwarcia portu wejściowego na urządzeniu:

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;
}

Wysyłanie danych MIDI

Ponieważ czas wysyłania wychodzących danych MIDI jest dobrze znany i kontrolowany przez samą aplikację, transmisja danych może odbywać się w głównym wątku aplikacji MIDI. Jednak ze względu na wydajność (jak w przypadku sekwencera) generowanie i transmisja MIDI mogą odbywać się w osobnym wątku.

Aplikacje mogą wysyłać dane MIDI w dowolnym momencie. Pamiętaj, że AMidi blokuje się podczas zapisywania danych.

Oto przykład metody JNI, która odbiera bufor poleceń MIDI i zapisuje go:

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);
}

Na diagramie poniżej przedstawiono przepływ aplikacji do zapisywania MIDI:

Wywołania zwrotne

Chociaż nie jest to funkcja AMidi, kod natywny może potrzebować przekazywać dane z powrotem do strony Java (np. w celu zaktualizowania interfejsu). Aby to zrobić, musisz napisać kod po stronie Java i w warstwie natywnej:

Utwórz metodę wywołania zwrotnego po stronie Java.
Napisz funkcję JNI, która przechowuje informacje potrzebne do wywołania zwrotnego.

Gdy nadejdzie czas na wywołanie zwrotne, kod natywny może utworzyć

Oto metoda wywołania zwrotnego po stronie Java, onNativeMessageReceive():

Kotlin

//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) }
}

Java

//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);
            }
        });
}

Oto kod C funkcji JNI, która konfiguruje wywołanie zwrotne do MainActivity.onNativeMessageReceive(). MainActivity w Javie wywołuje initNative() podczas uruchamiania:

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");
}

Gdy nadejdzie czas na wysłanie danych z powrotem do Javy, kod natywny pobiera wskaźniki wywołania zwrotnego i tworzy wywołanie zwrotne:

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);
}

Dodatkowe materiały

Dokumentacja AMidi
Zobacz kompletną przykładową aplikację Native MIDI w GitHubie.

Natywny interfejs MIDI API Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Korzystanie z AMidi

Uruchamianie AMidi

Wykrywanie sprzętu i portów

Kotlin

Java

Zatrzymywanie AMidi

Odbieranie danych MIDI

Konfigurowanie MidiDevice i jego portów wyjściowych

Kotlin

Java

Implementowanie pętli sondowania

Wysyłanie danych MIDI

Konfigurowanie MidiDevice i jego portów wejściowych

Kotlin

Java

Wysyłanie danych MIDI

Wywołania zwrotne

Kotlin

Java

Dodatkowe materiały

Natywny interfejs MIDI API