AMidi एपीआई, Android NDK r20b और इसके बाद के वर्शन में उपलब्ध है. इससे ऐप्लिकेशन डेवलपर, C/C++ कोड का इस्तेमाल करके MIDI डेटा भेज और पा सकते हैं.
Android MIDI ऐप्लिकेशन, आम तौर पर midi
एपीआई का इस्तेमाल करते हैं, ताकि वे Android MIDI सेवा से कम्यूनिकेट कर सकें. MIDI ऐप्लिकेशन, मुख्य रूप से MidiManager
पर निर्भर करते हैं. इसकी मदद से, एक या उससे ज़्यादा MidiDevice
ऑब्जेक्ट खोजे, खोले, और बंद किए जाते हैं. साथ ही, डिवाइस के MIDI इनपुट और आउटपुट पोर्ट के ज़रिए, हर डिवाइस को डेटा भेजा और उससे डेटा पाया जाता है:
AMidi का इस्तेमाल करते समय, JNI कॉल के साथ नेटिव कोड लेयर को MidiDevice
का पता दिया जाता है. इसके बाद, AMidi, AMidiDevice
का रेफ़रंस बनाता है. इसमें MidiDevice
की ज़्यादातर सुविधाएं होती हैं. आपके नेटिव कोड में AMidi फ़ंक्शन का इस्तेमाल किया जाता है. ये फ़ंक्शन, AMidiDevice
से सीधे कम्यूनिकेट करते हैं. AMidiDevice
, MIDI सेवा से सीधे कनेक्ट होता है:
AMidi कॉल का इस्तेमाल करके, अपने ऐप्लिकेशन के C/C++ ऑडियो/कंट्रोल लॉजिक को एमआईडीआई ट्रांसमिशन के साथ इंटिग्रेट किया जा सकता है. इसमें JNI कॉल या आपके ऐप्लिकेशन के Java साइड पर कॉलबैक की ज़रूरत कम होती है. उदाहरण के लिए, C कोड में लागू किया गया डिजिटल सिंथेसाइज़र, Java साइड से इवेंट भेजने के लिए JNI कॉल का इंतज़ार करने के बजाय, सीधे AMidiDevice
से मुख्य इवेंट पा सकता है. इसके अलावा, एल्गोरिदम से कंपोज़ करने की प्रोसेस, MIDI परफ़ॉर्मेंस को सीधे AMidiDevice
पर भेज सकती है. इसके लिए, मुख्य इवेंट ट्रांसमिट करने के लिए Java साइड पर वापस कॉल करने की ज़रूरत नहीं होती.
AMidi, एमआईडीआई डिवाइसों से सीधे तौर पर कनेक्ट करने की सुविधा देता है. हालाँकि, ऐप्लिकेशन को अब भी MidiManager
का इस्तेमाल करके MidiDevice
ऑब्जेक्ट खोजने और खोलने होंगे. AMidi इसे आगे बढ़ा सकता है.
कभी-कभी, आपको यूज़र इंटरफ़ेस (यूआई) लेयर से जानकारी को नेटिव कोड में पास करने की ज़रूरत पड़ सकती है. उदाहरण के लिए, जब स्क्रीन पर मौजूद बटन के जवाब में MIDI इवेंट भेजे जाते हैं. इसके लिए, अपने नेटिव लॉजिक में कस्टम JNI कॉल बनाएं. अगर आपको यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए डेटा वापस भेजना है, तो हमेशा की तरह नेटिव लेयर से वापस कॉल किया जा सकता है.
इस दस्तावेज़ में, AMidi नेटिव कोड ऐप्लिकेशन को सेट अप करने का तरीका बताया गया है. इसमें MIDI कमांड भेजने और पाने, दोनों के उदाहरण दिए गए हैं. काम करने वाले पूरे उदाहरण के लिए, NativeMidi सैंपल ऐप्लिकेशन देखें.
AMidi का इस्तेमाल करना
AMidi का इस्तेमाल करने वाले सभी ऐप्लिकेशन के लिए, सेटअप और बंद करने का तरीका एक जैसा होता है. भले ही, वे MIDI भेजते हों, पाते हों या दोनों काम करते हों.
AMidi शुरू करना
Java की ओर से, ऐप्लिकेशन को अटैच किए गए MIDI हार्डवेयर का पता लगाना होगा. साथ ही, उससे जुड़ा MidiDevice
बनाना होगा और उसे नेटिव कोड में पास करना होगा.
- Java
MidiManager
क्लास की मदद से, एमआईडीआई हार्डवेयर के बारे में जानें. - एमआईडीआई हार्डवेयर से जुड़ा Java
MidiDevice
ऑब्जेक्ट पाएं. - JNI की मदद से, Java
MidiDevice
को नेटिव कोड में पास करें.
हार्डवेयर और पोर्ट के बारे में जानकारी
इनपुट और आउटपुट पोर्ट ऑब्जेक्ट, ऐप्लिकेशन से जुड़े नहीं होते. ये MIDI डिवाइस पर मौजूद पोर्ट को दिखाते हैं. किसी डिवाइस को MIDI डेटा भेजने के लिए, कोई ऐप्लिकेशन MIDIInputPort
खोलता है और फिर उसमें डेटा लिखता है. इसके उलट, डेटा पाने के लिए कोई ऐप्लिकेशन MIDIOutputPort
खोलता है. ऐप्लिकेशन को यह पक्का करना होगा कि वह जिन पोर्ट को खोल रहा है वे सही टाइप के हैं. ऐसा करने पर ही ऐप्लिकेशन ठीक से काम कर पाएगा. डिवाइस और पोर्ट की पहचान, Java की मदद से की जाती है.
यहां एक ऐसा तरीका बताया गया है जिससे हर MIDI डिवाइस का पता लगाया जा सकता है और उसके पोर्ट देखे जा सकते हैं. यह फ़ंक्शन, डेटा पाने के लिए आउटपुट पोर्ट वाले डिवाइसों की सूची या डेटा भेजने के लिए इनपुट पोर्ट वाले डिवाइसों की सूची दिखाता है. किसी एमआईडीआई डिवाइस में इनपुट पोर्ट और आउटपुट पोर्ट, दोनों हो सकते हैं.
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 ListgetMidiDevices(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; }
अपने C/C++ कोड में AMidi फ़ंक्शन इस्तेमाल करने के लिए, आपको AMidi/AMidi.h
को शामिल करना होगा और इसे amidi
लाइब्रेरी से लिंक करना होगा. ये दोनों, Android NDK में मिल सकते हैं.
Java को एक या उससे ज़्यादा MidiDevice
ऑब्जेक्ट और पोर्ट नंबर, JNI कॉल के ज़रिए नेटिव लेयर को पास करने चाहिए. इसके बाद, नेटिव लेयर को यह तरीका अपनाना चाहिए:
- हर Java
MidiDevice
के लिए,AMidiDevice_fromJava()
का इस्तेमाल करकेAMidiDevice
पाएं. AMidiInputPort_open()
और/याAMidiOutputPort_open()
की मदद से,AMidiDevice
सेAMidiInputPort
और/याAMidiOutputPort
पाएं.- एमआईडीआई डेटा भेजने और/या पाने के लिए, मिले हुए पोर्ट का इस्तेमाल करें.
AMidi को बंद करें
जब Java ऐप्लिकेशन, एमआईडीआई डिवाइस का इस्तेमाल नहीं कर रहा हो, तब उसे नेटिव लेयर को संसाधन रिलीज़ करने का सिग्नल देना चाहिए. ऐसा इसलिए हो सकता है, क्योंकि एमआईडीआई डिवाइस डिसकनेक्ट हो गया है या ऐप्लिकेशन बंद हो रहा है.
एमआईडीआई संसाधनों को रिलीज़ करने के लिए, आपके कोड को ये काम करने चाहिए:
- एमआईडीआई पोर्ट से डेटा पढ़ना और/या लिखना बंद करें. अगर आपने इनपुट के लिए पोल करने के लिए, पढ़ने की थ्रेड का इस्तेमाल किया था, तो थ्रेड को बंद करें. इसके बारे में ज़्यादा जानने के लिए, नीचे पोलिंग लूप लागू करना लेख पढ़ें.
AMidiInputPort_close()
और/याAMidiOutputPort_close()
फ़ंक्शन का इस्तेमाल करके, खुले हुएAMidiInputPort
और/याAMidiOutputPort
ऑब्जेक्ट बंद करें.AMidiDevice_release()
के साथAMidiDevice
को रिलीज़ करें.
एमआईडीआई डेटा पाना
एमआईडीआई पाने वाले किसी एमआईडीआई ऐप्लिकेशन का एक सामान्य उदाहरण "वर्चुअल सिंथेसाइज़र" है. यह ऑडियो सिंथेसिस को कंट्रोल करने के लिए, एमआईडीआई परफ़ॉर्मेंस डेटा पाता है.
इनकमिंग MIDI डेटा, एसिंक्रोनस तरीके से मिलता है. इसलिए, एमआईडीआई को किसी अलग थ्रेड में पढ़ना सबसे अच्छा होता है. यह थ्रेड, एक या एक से ज़्यादा एमआईडीआई आउटपुट पोर्ट को लगातार पोल करता है. यह बैकग्राउंड थ्रेड या ऑडियो थ्रेड हो सकता है. AMidi, पोर्ट से डेटा पढ़ते समय ब्लॉक नहीं करता है. इसलिए, इसका इस्तेमाल ऑडियो कॉलबैक के अंदर सुरक्षित तरीके से किया जा सकता है.
MidiDevice और उसके आउटपुट पोर्ट सेट अप करना
कोई ऐप्लिकेशन, डिवाइस के आउटपुट पोर्ट से आने वाले MIDI डेटा को पढ़ता है. आपके ऐप्लिकेशन के Java साइड को यह तय करना होगा कि कौनसे डिवाइस और पोर्ट इस्तेमाल किए जाएं.
इस स्निपेट से, Android की MIDI सेवा से MidiManager
बनता है. साथ ही, यह MidiDevice
को उस पहले डिवाइस के लिए खोलता है जिसे यह ढूंढता है. जब MidiDevice
खोला जाता है, तब MidiManager.OnDeviceOpenedListener()
के किसी इंस्टेंस को कॉलबैक मिलता है. इस लिसनर के onDeviceOpened
तरीके को कॉल किया जाता है. इसके बाद, यह डिवाइस पर आउटपुट पोर्ट 0 खोलने के लिए startReadingMidi()
को कॉल करता है. यह AppMidiManager.cpp
में तय किया गया JNI फ़ंक्शन है. इस फ़ंक्शन के बारे में अगले स्निपेट में बताया गया है.
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); ListmidiDevices = 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); } } }
नेटिव कोड, Java-साइड एमआईडीआई डिवाइस और उसके पोर्ट को AMidi फ़ंक्शन में इस्तेमाल किए गए रेफ़रंस में बदलता है.
यहां JNI फ़ंक्शन दिया गया है. यह AMidiDevice_fromJava()
को कॉल करके AMidiDevice
बनाता है. इसके बाद, डिवाइस पर आउटपुट पोर्ट खोलने के लिए AMidiOutputPort_open()
को कॉल करता है:
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...
}
पोलिंग लूप लागू करना
जिन ऐप्लिकेशन को MIDI डेटा मिलता है उन्हें आउटपुट पोर्ट को पोल करना होगा. साथ ही, जब AMidiOutputPort_receive()
शून्य से बड़ी संख्या दिखाता है, तब उन्हें जवाब देना होगा.
कम बैंडविथ वाले ऐप्लिकेशन, जैसे कि MIDI स्कोप के लिए, कम प्राथमिकता वाली बैकग्राउंड थ्रेड में पोल किया जा सकता है. इसके लिए, स्लीप मोड का इस्तेमाल करें.
ऑडियो जनरेट करने वाले और रीयलटाइम परफ़ॉर्मेंस से जुड़ी सख्त ज़रूरी शर्तों वाले ऐप्लिकेशन के लिए, ऑडियो जनरेट करने वाले मुख्य कॉलबैक में पोल किया जा सकता है. यह BufferQueue
OpenSL ES के लिए कॉलबैक और AAudio में AudioStream डेटा कॉलबैक होता है.
AMidiOutputPort_receive()
नॉन-ब्लॉकिंग है. इसलिए, इससे परफ़ॉर्मेंस पर बहुत कम असर पड़ता है.
ऊपर दिए गए startReadingMidi()
फ़ंक्शन से कॉल किया गया readThreadRoutine()
फ़ंक्शन ऐसा दिख सकता है:
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), ×tamp);
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;
}
}
}
नेटिव ऑडियो एपीआई (जैसे, OpenSL ES या AAudio) का इस्तेमाल करने वाला कोई ऐप्लिकेशन, ऑडियो जनरेशन कॉलबैक में इस तरह से मिडी पाने का कोड जोड़ सकता है:
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), ×tamp);
if (numMessages >= 0 && opCode == AMIDI_OPCODE_DATA) {
// Parse and respond to MIDI data
// ...
}
// Generate Audio…
// ...
}
इस डायग्राम में, MIDI फ़ाइलें पढ़ने वाले ऐप्लिकेशन का फ़्लो दिखाया गया है:
एमआईडीआई डेटा भेजना
एमआईडीआई लिखने वाले ऐप्लिकेशन का एक सामान्य उदाहरण, एमआईडीआई कंट्रोलर या सीक्वेंसर है.
MidiDevice और उसके इनपुट पोर्ट सेट अप करना
कोई ऐप्लिकेशन, एमआईडीआई डिवाइस के इनपुट पोर्ट पर आउटगोइंग एमआईडीआई डेटा लिखता है. आपके ऐप्लिकेशन के Java साइड को यह तय करना होगा कि कौनसे एमआईडीआई डिवाइस और पोर्ट इस्तेमाल किए जाएं.
यहां दिया गया सेटअप कोड, ऊपर दिए गए उदाहरण का एक वैरिएशन है. यह Android की एमआईडीआई सेवा से MidiManager
बनाता है. इसके बाद, यह पहलीMidiDevice
को खोलता है और डिवाइस पर पहले इनपुट पोर्ट को खोलने के लिए startWritingMidi()
को कॉल करता है. यह AppMidiManager.cpp
में तय किया गया JNI कॉल है. इस फ़ंक्शन के बारे में अगले स्निपेट में बताया गया है.
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); ListmidiDevices = 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); } } }
यहां JNI फ़ंक्शन दिया गया है. यह AMidiDevice_fromJava()
को कॉल करके AMidiDevice
बनाता है. इसके बाद, डिवाइस पर इनपुट पोर्ट खोलने के लिए AMidiInputPort_open()
को कॉल करता है:
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 डेटा के समय को ऐप्लिकेशन खुद समझता है और कंट्रोल करता है. इसलिए, डेटा ट्रांसमिशन को MIDI ऐप्लिकेशन के मुख्य थ्रेड में किया जा सकता है. हालांकि, परफ़ॉर्मेंस की वजहों से (जैसे कि सीक्वेंसर में) MIDI को जनरेट और ट्रांसमिट करने का काम, किसी अलग थ्रेड में किया जा सकता है.
ऐप्लिकेशन, ज़रूरत पड़ने पर एमआईडीआई डेटा भेज सकते हैं. ध्यान दें कि AMidi, डेटा लिखते समय ब्लॉक करता है.
यहां एक JNI तरीके का उदाहरण दिया गया है, जो MIDI कमांड का बफ़र पाता है और उसे लिखता है:
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);
}
इस डायग्राम में, MIDI लिखने वाले ऐप्लिकेशन का फ़्लो दिखाया गया है:
कॉलबैक
हालांकि, यह AMidi की सुविधा नहीं है, लेकिन आपके नेटिव कोड को Java साइड पर डेटा वापस भेजने की ज़रूरत पड़ सकती है. उदाहरण के लिए, यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए. इसके लिए, आपको Java साइड और नेटिव लेयर में कोड लिखना होगा:
- Java की तरफ़ से एक कॉलबैक तरीका बनाएं.
- एक ऐसा JNI फ़ंक्शन लिखें जो कॉलबैक को शुरू करने के लिए ज़रूरी जानकारी सेव करता हो.
जब कॉल बैक करने का समय होता है, तब आपका नेटिव कोड
यहां 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); } }); }
यहां JNI फ़ंक्शन के लिए C कोड दिया गया है. यह MainActivity.onNativeMessageReceive()
पर कॉलबैक सेट अप करता है. Java MainActivity
कॉल
initNative()
at startup:
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");
}
जब डेटा को Java पर वापस भेजने का समय आता है, तो नेटिव कोड, कॉलबैक पॉइंटर को वापस पाता है और कॉलबैक बनाता है:
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);
}
अन्य संसाधन
- AMidi रेफ़रंस
- github पर नेटिव MIDI का पूरा सैंपल ऐप्लिकेशन देखें.