Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

API MIDI nativa

L'API AMidi è disponibile in Android NDK r20b e versioni successive. Consente agli sviluppatori di app di inviare e ricevere dati MIDI con codice C/C++.

Le app Android MIDI di solito utilizzano l'API midi per comunicare con il servizio Android MIDI. Le app MIDI dipendono principalmente da MidiManager per rilevare, aprire e chiudere uno o più oggetti MidiDevice e trasmettere dati da e verso ogni dispositivo tramite le porte MIDI di input e output del dispositivo:

Quando utilizzi AMidi, passi l'indirizzo di un MidiDevice al livello di codice nativo con una chiamata JNI. Da qui, AMidi crea un riferimento a un AMidiDevice che ha la maggior parte delle funzionalità di un MidiDevice. Il codice nativo utilizza le funzioni AMidi che comunicano direttamente con un AMidiDevice. Il AMidiDevice si connette direttamente al servizio MIDI:

Utilizzando le chiamate AMidi, puoi integrare strettamente la logica di controllo/audio C/C++ della tua app con la trasmissione MIDI. La necessità di chiamate JNI o di callback al lato Java dell'app è minore. Ad esempio, un sintetizzatore digitale implementato in codice C potrebbe ricevere eventi chiave direttamente da un AMidiDevice, anziché attendere una chiamata JNI per inviare gli eventi dal lato Java. In alternativa, un processo di composizione algoritmica potrebbe inviare una performance MIDI direttamente a un AMidiDevice senza richiamare il lato Java per trasmettere gli eventi chiave.

Sebbene AMidi migliori la connessione diretta ai dispositivi MIDI, le app devono comunque utilizzare MidiManager per rilevare e aprire gli oggetti MidiDevice. AMidi può proseguire da lì.

A volte potrebbe essere necessario passare informazioni dal livello UI al codice nativo. Ad esempio, quando gli eventi MIDI vengono inviati in risposta ai pulsanti sullo schermo. Per farlo, crea chiamate JNI personalizzate alla tua logica nativa. Se devi inviare dati per aggiornare la UI, puoi richiamare dal livello nativo come di consueto.

Questo documento mostra come configurare un'app con codice nativo AMidi, fornendo esempi di invio e ricezione di comandi MIDI. Per un esempio di funzionamento completo, consulta l'app di esempio NativeMidi.

Utilizza AMidi

Tutte le app che utilizzano AMidi hanno gli stessi passaggi di configurazione e chiusura, indipendentemente dal fatto che inviino o ricevano MIDI o entrambi.

Avvia AMidi

Sul lato Java, l'app deve rilevare un hardware MIDI collegato, creare un MidiDevice corrispondente e passarlo al codice nativo.

Scopri l'hardware MIDI con la classe Java MidiManager.
Ottieni un oggetto Java MidiDevice corrispondente all'hardware MIDI.
Passa l'oggetto MidiDevice Java al codice nativo con JNI.

Scopri l'hardware e le porte

Gli oggetti delle porte di input e output non appartengono all'app, ma rappresentano le porte sul dispositivo MIDI. Per inviare dati MIDI a un dispositivo, un'app apre un MIDIInputPort e poi scrive i dati al suo interno. Al contrario, per ricevere dati, un'app apre un MIDIOutputPort. Per funzionare correttamente, l'app deve assicurarsi che le porte che apre siano del tipo corretto. Il rilevamento di dispositivi e porte viene eseguito sul lato Java.

Ecco un metodo che rileva ogni dispositivo MIDI e ne esamina le porte. Restituisce un elenco di dispositivi con porte di uscita per la ricezione dei dati o un elenco di dispositivi con porte di ingresso per l'invio dei dati. Un dispositivo MIDI può avere sia porte di input che di output.

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

Per utilizzare le funzioni AMidi nel codice C/C++, devi includere AMidi/AMidi.h e creare un link alla libreria amidi. Entrambi sono disponibili in Android NDK.

Il lato Java deve passare uno o più oggetti MidiDevice e numeri di porta al livello nativo tramite una chiamata JNI. Il livello nativo deve quindi eseguire i seguenti passaggi:

Per ogni MidiDevice Java, ottieni un AMidiDevice utilizzando AMidiDevice_fromJava().
Ottenere un AMidiInputPort e/o un AMidiOutputPort dal AMidiDevice con AMidiInputPort_open() e/o AMidiOutputPort_open().
Utilizza le porte ottenute per inviare e/o ricevere dati MIDI.

Interrompi AMidi

L'app Java deve segnalare al livello nativo di rilasciare le risorse quando non utilizza più il dispositivo MIDI. Il motivo potrebbe essere che il dispositivo MIDI è stato scollegato o che l'app sta per essere chiusa.

Per rilasciare le risorse MIDI, il codice deve eseguire queste attività:

Interrompere la lettura e/o la scrittura sulle porte MIDI. Se utilizzavi un thread di lettura per eseguire il polling degli input (consulta Implementa un ciclo di polling di seguito), interrompi il thread.
Chiudi tutti gli oggetti AMidiInputPort e/o AMidiOutputPort aperti con le funzioni AMidiInputPort_close() e/o AMidiOutputPort_close().
Rilascia AMidiDevice con AMidiDevice_release().

Ricevi dati MIDI

Un esempio tipico di app MIDI che riceve dati MIDI è un "sintetizzatore virtuale" che riceve dati sul rendimento MIDI per controllare la sintesi audio.

I dati MIDI in entrata vengono ricevuti in modo asincrono. Pertanto, è meglio leggere i dati MIDI in un thread separato che esegue continuamente il polling di una o più porte di output MIDI. Potrebbe trattarsi di un thread in background o di un thread audio. AMidi non si blocca durante la lettura da una porta, pertanto è sicuro da utilizzare all'interno di un callback audio.

Configura un MidiDevice e le relative porte di output

Un'app legge i dati MIDI in entrata dalle porte di uscita di un dispositivo. Il lato Java della tua app deve determinare quale dispositivo e quali porte utilizzare.

Questo snippet crea l'oggetto MidiManager dal servizio MIDI di Android e apre un oggetto MidiDevice per il primo dispositivo che trova. Quando MidiDevice viene aperto, viene ricevuto un callback a un'istanza di MidiManager.OnDeviceOpenedListener(). Viene chiamato il metodo onDeviceOpened di questo listener, che a sua volta chiama startReadingMidi() per aprire la porta di output 0 sul dispositivo. Questa è una funzione JNI definita in AppMidiManager.cpp. Questa funzione è spiegata nello snippet successivo.

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

Il codice nativo traduce il dispositivo MIDI lato Java e le relative porte in riferimenti utilizzati dalle funzioni AMidi.

Ecco la funzione JNI che crea un AMidiDevice chiamando AMidiDevice_fromJava(), quindi chiama AMidiOutputPort_open() per aprire una porta di output sul dispositivo:

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

}

Implementa un loop di polling

Le app che ricevono dati MIDI devono eseguire il polling della porta di output e rispondere quando AMidiOutputPort_receive() restituisce un numero maggiore di zero.

Per le app a larghezza di banda ridotta, come un oscilloscopio MIDI, puoi eseguire il polling in un thread in background a bassa priorità (con pause appropriate).

Per le app che generano audio e hanno requisiti di prestazioni in tempo reale più rigidi, puoi eseguire il polling nel callback principale di generazione dell'audio (il callback BufferQueue per OpenSL ES, il callback dei dati AudioStream in AAudio). Poiché AMidiOutputPort_receive() non è bloccante, l'impatto sulle prestazioni è minimo.

La funzione readThreadRoutine() chiamata dalla funzione startReadingMidi() precedente potrebbe avere il seguente aspetto:

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

Un'app che utilizza un'API audio nativa (come OpenSL ES o AAudio) può aggiungere il codice di ricezione MIDI al callback di generazione dell'audio in questo modo:

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

Il seguente diagramma illustra il flusso di un'app di lettura MIDI:

Invia dati MIDI

Un esempio tipico di app di scrittura MIDI è un controller o un sequencer MIDI.

Configura un MidiDevice e le relative porte di ingresso

Un'app scrive i dati MIDI in uscita nelle porte di ingresso di un dispositivo MIDI. Il lato Java della tua app deve determinare quale dispositivo e quali porte MIDI utilizzare.

Il codice di configurazione riportato di seguito è una variante dell'esempio di ricezione riportato sopra. Crea l'oggetto MidiManager dal servizio MIDI di Android. Quindi apre il primoMidiDevice che trova e chiama startWritingMidi() per aprire la prima porta di input sul dispositivo. Si tratta di una chiamata JNI definita in AppMidiManager.cpp. La funzione è spiegata nello snippet successivo.

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

Ecco la funzione JNI che crea un AMidiDevice chiamando AMidiDevice_fromJava(), quindi chiama AMidiInputPort_open() per aprire una porta di input sul dispositivo:

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

Invia dati MIDI

Poiché la tempistica dei dati MIDI in uscita è ben compresa e controllata dall'app stessa, la trasmissione dei dati può essere eseguita nel thread principale dell'app MIDI. Tuttavia, per motivi di prestazioni (come in un sequencer), la generazione e la trasmissione di MIDI possono essere eseguite in un thread separato.

Le app possono inviare dati MIDI ogni volta che è necessario. Tieni presente che AMidi si blocca durante la scrittura dei dati.

Ecco un esempio di metodo JNI che riceve un buffer di comandi MIDI e lo scrive:

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

Il seguente diagramma illustra il flusso di un'app di scrittura MIDI:

Richiamate

Anche se non si tratta di una funzionalità strettamente legata ad AMidi, il tuo codice nativo potrebbe dover passare i dati al lato Java (ad esempio per aggiornare l'interfaccia utente). Per farlo, devi scrivere il codice sia sul lato Java sia sul livello nativo:

Crea un metodo di callback sul lato Java.
Scrivi una funzione JNI che memorizzi le informazioni necessarie per richiamare il callback.

Quando è il momento di eseguire il callback, il codice nativo può creare

Ecco il metodo di callback lato 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);
            }
        });
}

Ecco il codice C per la funzione JNI che configura il callback per MainActivity.onNativeMessageReceive(). Chiamate Java MainActivity initNative() all'avvio:

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

Quando è il momento di inviare i dati a Java, il codice nativo recupera i puntatori di callback e costruisce il 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);
}

Risorse aggiuntive

Riferimento AMidi
Consulta l'app di esempio MIDI nativa completa su GitHub.

API MIDI nativa Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Utilizza AMidi

Avvia AMidi

Scopri l'hardware e le porte

Kotlin

Java

Interrompi AMidi

Ricevi dati MIDI

Configura un MidiDevice e le relative porte di output

Kotlin

Java

Implementa un loop di polling

Invia dati MIDI

Configura un MidiDevice e le relative porte di ingresso

Kotlin

Java

Invia dati MIDI

Richiamate

Kotlin

Java

Risorse aggiuntive

API MIDI nativa