openharmony 鸿蒙 using-ohmidi

2026-08-25 浏览 (1)

使用OH_MIDI进行MIDI开发(C/C++)

场景介绍

OH_MIDI是系统提供的Native MIDI API，从API version 24开始用于在C/C++层实现MIDI应用开发。当应用需要与外接MIDI设备（如USB MIDI键盘、蓝牙MIDI设备）进行数据交互时，可以使用OH_MIDI。典型使用场景包括：

  • 音乐创作应用：连接MIDI键盘，实时接收弹奏的音符并触发音源播放。
  • 乐器学习/教学应用：将MIDI键盘的弹奏数据接入应用，实现评分、伴奏等功能。
  • MIDI控制器应用：通过应用向外接MIDI设备发送控制指令（如切换音色、调节参数）。
  • MIDI数据处理工具：接收、解析和转发MIDI消息，用于音乐制作或设备调试。

通过OH_MIDI，开发者可以实现以下功能：

  • 创建MIDI客户端并管理与MIDI服务的连接。
  • 枚举和管理MIDI设备。
  • 打开和管理MIDI端口。
  • 发送和接收MIDI消息。
  • 处理MIDI事件和回调。
  • 实现低延迟的MIDI数据传输。

系统能力检查

使用MIDI进行开发前，先调用接口canIUse判断当前设备是否支持MIDI能力。当canIUse("SystemCapability.Multimedia.Audio.MIDI")返回值为true时，表示可以使用MIDI能力。

接口说明

OH_MIDI的主要接口包括：

开发准备

在使用OH_MIDI API之前，需要完成以下准备工作：

  • 在CMake脚本中链接动态库。

    target_link_libraries(entry PUBLIC
    libace_napi.z.so
    libohmidi.so
    libhilog_ndk.z.so
)

  • 添加头文件。

    #include "native_midi.h"
#include "native_midi_base.h"
#include <hilog/log.h>

声明权限

MIDI功能的权限需求根据使用场景不同而有所区别。

场景一：仅使用USB MIDI设备。

无需额外权限声明。

场景二：发现和连接BLE MIDI设备。

在module.json5中声明蓝牙权限：

"requestPermissions": [
    {
        "name": "ohos.permission.ACCESS_BLUETOOTH",
        "reason": "$string:bluetooth_permission_reason"
    }
]

开发步骤

创建MIDI客户端

创建MIDI客户端是使用MIDI API的第一步。

客户端是应用与MIDI系统服务的连接入口，负责管理与MIDI服务的所有交互。创建客户端前，需要先准备回调结构体：

系统已定义OH_MIDICallback结构体，开发者需要实现其中的回调函数：

  • onDeviceChange：当MIDI设备连接或断开时由系统自动调用。开发者在此回调中处理设备的接入和移除逻辑。
  • onError：当MIDI服务发生错误时调用。开发者在此回调中处理错误日志记录和异常恢复逻辑,如重新创建客户端。

通过调用OH_MIDIClient_Create接口创建MIDI客户端实例，传入回调结构体和用户数据。

// Create MIDI client
static napi_value CreateMIDIClient(napi_env env, napi_callback_info info)
{
    // ...
    std::lock_guard<std::mutex> lock(g_midiMutex);
    // ...
    OH_MIDIStatusCode status = OH_MIDIClient_Create(&g_midiClient, g_midiCallbacks, nullptr);
    // ...
}

销毁MIDI客户端

当不再需要MIDI功能时，应销毁客户端以释放资源。销毁前需要先关闭所有已打开的设备。

通过调用OH_MIDIClient_Destroy接口销毁MIDI客户端实例，释放所有关联资源。

static napi_value DestroyMIDIClient(napi_env env, napi_callback_info info)
{
    // ...
    std::lock_guard<std::mutex> lock(g_midiMutex);

    if (g_midiClient != nullptr) {
        CloseAllOpenedDevices();
        OH_MIDIClient_Destroy(g_midiClient);
        g_midiClient = nullptr;
    }
    CleanupAllPortContexts();

    // ...
}

枚举MIDI设备

创建客户端后，可以枚举系统中当前可用的MIDI设备。枚举设备分为两步：

  1. 获取设备数量：调用OH_MIDIClient_GetDeviceCount接口获取当前连接的设备数量。

  2. 获取设备信息：分配足够大的缓冲区，调用OH_MIDIClient_GetDeviceInfos接口填充设备详细信息。

注意：

如果应用未获得蓝牙权限（ohos.permission.ACCESS_BLUETOOTH），蓝牙MIDI设备将不会包含在枚举结果中。

通过OH_MIDIClient_GetDeviceCount接口获取设备数量，再通过OH_MIDIClient_GetDeviceInfos接口获取设备详细信息。

static napi_value GetDeviceInfos(napi_env env, napi_callback_info info)
{
    std::lock_guard<std::mutex> lock(g_midiMutex);
    // ...

    size_t count = 0;
    OH_MIDIStatusCode status = OH_MIDIClient_GetDeviceCount(g_midiClient, &count);
    // ...
    std::vector<OH_MIDIDeviceInformation> devices(count);
    size_t actualCount = 0;
    status = OH_MIDIClient_GetDeviceInfos(g_midiClient, devices.data(), count, &actualCount);
    // ...
}

打开MIDI设备

需要打开设备才能进行数据传输。根据设备类型不同，打开方式有所区别：USB MIDI设备通过OH_MIDIClient_OpenDevice接口同步打开，BLE MIDI设备通过OH_MIDIClient_OpenBLEDevice接口异步打开。

打开USB MIDI设备（同步）

通过OH_MIDIClient_OpenDevice接口同步打开USB MIDI设备，传入设备ID获取设备句柄。

static napi_value OpenDevice(napi_env env, napi_callback_info info)
{
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);
    std::lock_guard<std::mutex> lock(g_midiMutex);
    // ...
    OH_MIDIDevice *device = nullptr;
    OH_MIDIStatusCode status = OH_MIDIClient_OpenDevice(g_midiClient, deviceId, &device);
    if (status == OH_MIDI_STATUS_OK && device != nullptr) {
        g_openedDevices[deviceId] = device;
        OH_LOG_INFO(LOG_APP, "[OpenDevice] device stored, total opened devices=%{public}zu", g_openedDevices.size());
    }
    // ...
}

打开BLE MIDI设备（异步）

BLE MIDI设备的打开是异步操作，使用OH_MIDIClient_OpenBLEDevice接口。

BLE设备地址可通过以下方式获取：

  1. BLE扫描发现：使用蓝牙API扫描MIDI BLE设备。

  2. 历史记录：从持久化存储加载之前连接过的设备地址。

  3. 用户输入：让用户手动输入MAC地址。

MIDI BLE设备可通过服务UUID 03B80E5A-EDE8-4B33-A751-6CE34EC4C700 进行过滤识别。

通过OH_MIDIClient_OpenBLEDevice接口异步打开BLE MIDI设备，传入设备MAC地址和结果回调。

// Open BLE device asynchronously
static napi_value OpenBLEDevice(napi_env env, napi_callback_info info)
{
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    // Get device address
    size_t addrLen = 0;
    napi_get_value_string_utf8(env, args[0], nullptr, 0, &addrLen);
    std::string deviceAddr(addrLen, '\0');
    napi_get_value_string_utf8(env, args[0], &deviceAddr[0], addrLen + 1, &addrLen);

    // ...

    std::lock_guard<std::mutex> lock(g_midiMutex);

    // ...
    OH_MIDIStatusCode status = OH_MIDIClient_OpenBLEDevice(g_midiClient, deviceAddr.c_str(),
                                                           OnBLEDeviceOpened, nullptr);
    // ...
}

通过OH_MIDIClient_OnDeviceOpened回调接收BLE设备打开结果，在回调中获取设备句柄和设备信息。

static void OnBLEDeviceOpened(void *userData, bool opened, OH_MIDIDevice *device, OH_MIDIDeviceInformation info)
{
    std::string deviceAddr = info.deviceAddress;
    // ...
}

注意：

  • BLE设备连接是异步连接，结果通过回调返回。
  • 回调在非主线程执行，如需更新UI请使用线程安全机制。
  • 连接成功后，后续的端口操作应在回调中进行。
  • 使用OH_MIDIClient_CloseDevice关闭设备。

关闭MIDI设备

通过OH_MIDIClient_CloseDevice接口关闭已打开的MIDI设备，释放设备资源。

static napi_value CloseDevice(napi_env env, napi_callback_info info)
{
    // ...
    std::lock_guard<std::mutex> lock(g_midiMutex);
    // ...
    auto it = g_openedDevices.find(deviceId);
    if (it != g_openedDevices.end()) {
        // 清理该设备的所有InputPortContext
        CleanupInputPortContextsForDevice(deviceId);
        OH_MIDIStatusCode status = OH_MIDIClient_CloseDevice(g_midiClient, it->second);
        g_openedDevices.erase(it);
        // ...
    } else {
        // ...
    }

    // ...
    return result;
}

获取端口信息

打开设备后，需要获取设备的端口信息并打开输入或输出端口来发送或接收MIDI数据。

每个MIDI设备可能提供多个端口，每个端口都有明确的方向（输入或输出）。需要先枚举所有端口，根据应用需求找到对应的输入端口和输出端口，然后分别打开。

通过OH_MIDIClient_GetPortCount接口获取端口数量，再通过OH_MIDIClient_GetPortInfos接口获取端口详细信息。

static napi_value GetPortInfos(napi_env env, napi_callback_info info)
{
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);
    // ...

    std::lock_guard<std::mutex> lock(g_midiMutex);

    // ...

    size_t count = 0;
    OH_MIDIStatusCode status = OH_MIDIClient_GetPortCount(g_midiClient, deviceId, &count);
    // ...

    std::vector<OH_MIDIPortInformation> ports(count);
    size_t actualCount = 0;
    status = OH_MIDIClient_GetPortInfos(g_midiClient, deviceId, ports.data(), count, &actualCount);
    // ...
}

MIDI端口管理

打开输入端口

接收MIDI消息，需要打开输入端口并注册接收回调函数。当设备发送MIDI数据时，回调函数会被调用。

回调函数应在独立线程中执行，需要使用互斥锁或其他同步机制来保证线程安全。回调中的events数据仅在此回调期间有效，如需保留必须复制。

通过OH_MIDIDevice_OnReceived回调接收MIDI数据，回调中获取事件数组及其数据。

static void OnMIDIReceived(void *userData, const OH_MIDIEvent *events, size_t eventCount)
{
    // userData指向InputPortContext
    InputPortContext* context = static_cast<InputPortContext*>(userData);
    // ...
}

通过OH_MIDIDevice_OpenInputPort接口打开输入端口，传入OH_MIDIPortDescriptor结构配置端口参数，并注册数据接收回调。

static napi_value OpenInputPort(napi_env env, napi_callback_info info)
{
    InputPortArgs args = ParseInputPortArgs(env, info);

    std::lock_guard<std::mutex> lock(g_midiMutex);

    napi_value result;
    auto it = g_openedDevices.find(args.deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        OH_LOG_ERROR(LOG_APP, "[OpenInputPort] client is null or device not opened");
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }

    // Construct port descriptor
    OH_MIDIPortDescriptor descriptor;
    descriptor.portIndex = args.portIndex;
    descriptor.protocol = static_cast<OH_MIDIProtocol>(args.protocol);

    // Create input port context for thread-safe callback handling
    auto context = std::make_shared<InputPortContext>(args.deviceId, args.portIndex);

    OH_MIDIStatusCode status = OH_MIDIDevice_OpenInputPort(it->second, descriptor, OnMIDIReceived, context.get());
    // ...
}

关闭输入端口

使用OH_MIDIDevice_CloseInputPort接口关闭已打开的输入端口。关闭端口后，该端口将不再接收MIDI消息，注册的回调函数也将不再被调用。

// Close input port
static napi_value CloseInputPort(napi_env env, napi_callback_info info)
{
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);

    uint32_t portIndex = 0;
    napi_get_value_uint32(env, args[1], &portIndex);

    OH_LOG_INFO(LOG_APP, "[CloseInputPort] ++enter, deviceId=%{public}lld, portIndex=%{public}u",
                (long long)deviceId, portIndex);

    std::lock_guard<std::mutex> lock(g_midiMutex);

    napi_value result;
    auto it = g_openedDevices.find(deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        OH_LOG_ERROR(LOG_APP, "[CloseInputPort] client is null or device not opened");
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }

    OH_MIDIStatusCode status = OH_MIDIDevice_CloseInputPort(it->second, portIndex);

    // Clean up input port context
    auto key = std::make_pair(deviceId, portIndex);
    auto contextIt = g_inputPortContexts.find(key);
    if (contextIt != g_inputPortContexts.end()) {
        if (contextIt->second != nullptr) {
            contextIt->second->Stop();
        }
        g_inputPortContexts.erase(contextIt);
    }
    // ...
}

打开输出端口

通过OH_MIDIDevice_OpenOutputPort接口打开输出端口，传入OH_MIDIPortDescriptor结构配置端口参数和协议。

static napi_value OpenOutputPort(napi_env env, napi_callback_info info)
{
    size_t argc = 3;
    napi_value args[3] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);

    uint32_t portIndex = 0;
    napi_get_value_uint32(env, args[1], &portIndex);

    int32_t protocol = static_cast<int32_t>(MIDI_PROTOCOL_1_0); // Default to MIDI 1.0
    napi_get_value_int32(env, args[MIDI_ARG_INDEX_2], &protocol);

    OH_LOG_INFO(LOG_APP, "[OpenOutputPort] ++enter, deviceId=%{public}lld, portIndex=%{public}u, protocol=%{public}d",
                (long long)deviceId, portIndex, protocol);

    std::lock_guard<std::mutex> lock(g_midiMutex);

    napi_value result;
    auto it = g_openedDevices.find(deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        OH_LOG_ERROR(LOG_APP, "[OpenOutputPort] client is null or device not opened");
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }

    OH_MIDIPortDescriptor descriptor;
    descriptor.portIndex = portIndex;
    descriptor.protocol = static_cast<OH_MIDIProtocol>(protocol);
    
    OH_MIDIStatusCode status = OH_MIDIDevice_OpenOutputPort(it->second, descriptor);
    // ...
}

关闭输出端口

使用OH_MIDIDevice_CloseOutputPort接口关闭已打开的输出端口。关闭端口后，将无法再通过该端口发送MIDI消息。

// Close output port
static napi_value CloseOutputPort(napi_env env, napi_callback_info info)
{
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);

    uint32_t portIndex = 0;
    napi_get_value_uint32(env, args[1], &portIndex);

    OH_LOG_INFO(LOG_APP, "[CloseOutputPort] ++enter, deviceId=%{public}lld, portIndex=%{public}u",
                (long long)deviceId, portIndex);

    std::lock_guard<std::mutex> lock(g_midiMutex);

    napi_value result;
    auto it = g_openedDevices.find(deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        OH_LOG_ERROR(LOG_APP, "[CloseOutputPort] client is null or device not opened");
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }
    OH_MIDIStatusCode status = OH_MIDIDevice_CloseOutputPort(it->second, portIndex);
    // Remove protocol info for this output port
    if (status == OH_MIDI_STATUS_OK) {
        auto key = std::make_pair(deviceId, portIndex);
        g_outputPortProtocols.erase(key);
    }
    // ...
}

发送MIDI消息

发送MIDI消息需要先构造UMP（Universal MIDI Packet）格式的数据，再通过OH_MIDIDevice_Send接口发送。UMP是Universal MIDI Packet的缩写，是MIDI 2.0标准统一使用的数据包格式。

发送自定义MIDI消息

构造OH_MIDIEvent事件数组，通过OH_MIDIDevice_Send接口发送MIDI消息。

static napi_value SendMIDI(napi_env env, napi_callback_info info)
{
    size_t argc = 3;
    napi_value args[3] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);
    uint32_t portIndex = 0;
    napi_get_value_uint32(env, args[1], &portIndex);

    OH_LOG_DEBUG(LOG_APP, "[SendMIDI] deviceId=%{public}lld, portIndex=%{public}u", (long long)deviceId, portIndex);

    bool isArray = false;
    napi_is_array(env, args[MIDI_ARG_INDEX_2], &isArray);
    if (!isArray) {
        napi_value result;
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_GENERIC_INVALID_ARGUMENT), &result);
        return result;
    }

    std::vector<OH_MIDIEvent> events;
    std::vector<std::vector<uint32_t>> eventDataBuffers;
    ParseMIDIEventsFromArray(env, args[MIDI_ARG_INDEX_2], events, eventDataBuffers);
    uint32_t eventCount = static_cast<uint32_t>(events.size());

    std::lock_guard<std::mutex> lock(g_midiMutex);
    napi_value result;
    auto it = g_openedDevices.find(deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }

    uint32_t eventsWritten = 0;
    OH_MIDIStatusCode status = OH_MIDIDevice_Send(it->second, portIndex, events.data(), eventCount, &eventsWritten);
    napi_create_object(env, &result);
    napi_value statusValue;
    napi_create_int32(env, static_cast<int32_t>(status), &statusValue);
    napi_set_named_property(env, result, "status", statusValue);
    napi_value writtenValue;
    napi_create_uint32(env, eventsWritten, &writtenValue);
    napi_set_named_property(env, result, "eventsWritten", writtenValue);
    return result;

UMP格式说明

OH_MIDI强制使用UMP（Universal MIDI Packet）格式。常用的MIDI 1.0通道消息（MT=0x2，32位）构造方式如下：

位字段说明
31-28MT消息类型，MIDI 1.0通道消息为0x2。
27-24Group保留位，填0。
23-20Status状态码（如0x9=Note On，0x8=Note Off）。
19-16Channel通道号（0-15）。
15-8Data1第一个数据字节（如音符编号）。
7-0Data2第二个数据字节（如力度）。

常用MIDI消息UMP构造示例

// Build MIDI 1.0 Note On UMP (32-bit, 1 word)
static void BuildMIDI1NoteOn(uint32_t channel, uint32_t note, uint32_t velocity, uint32_t* umpData)
{
    // UMP format: MT[31-28]=0x2, Group[27-24]=0x0, Status[23-20]=0x9
    // Channel[19-16], Data1[15-8]=note, Data2[7-0]=velocity
    umpData[0] = (MIDI_UMP_MT_1_0 << MIDI_UMP_WORDS_28)|(0x0 << MIDI_UMP_SHIFT_24)|
                 (MIDI_UMP_STATUS_NOTE_ON << MIDI_UMP_SHIFT_20)|
                 ((channel & MIDI_CHANNEL_MASK) << MIDI_UMP_WORDS_16)|
                 ((note & MIDI_NOTE_MASK) << MIDI_UMP_SHIFT_8)|(velocity & MIDI_NOTE_MASK);
}

// Build MIDI 1.0 Note Off UMP (32-bit, 1 word)
static void BuildMIDI1NoteOff(uint32_t channel, uint32_t note, uint32_t velocity, uint32_t* umpData)
{
    // UMP format: MT[31-28]=0x2, Group[27-24]=0x0, Status[23-20]=0x8
    // Channel[19-16], Data1[15-8]=note, Data2[7-0]=velocity
    umpData[0] = (MIDI_UMP_MT_1_0 << MIDI_UMP_WORDS_28)|(0x0 << MIDI_UMP_SHIFT_24)|
                 (MIDI_UMP_STATUS_NOTE_OFF << MIDI_UMP_SHIFT_20)|
                 ((channel & MIDI_CHANNEL_MASK) << MIDI_UMP_WORDS_16)|
                 ((note & MIDI_NOTE_MASK) << MIDI_UMP_SHIFT_8)|(velocity & MIDI_NOTE_MASK);
}

常用CC控制器编号参考

编号名称用途
1Modulation Wheel颤音深度
7Volume音量
10Pan声像
11Expression表情
64Sustain Pedal延音踏板
65Portamento滑音
71Resonance共振
74Filter Cutoff滤波器截止

发送系统专有消息(SysEx)

系统专有消息（System Exclusive）：用于传输制造商特定的数据。使用OH_MIDIDevice_SendSysEx接口可以发送超过常规MIDI消息长度的SysEx消息。

// 发送大型SysEx消息。
void SendSysExExample(OH_MIDIDevice *device, uint32_t outputPortIndex){
    // 构造SysEx数据。
    std::vector<uint8_t> sysexData;
    sysexData.push_back(0xF0);  // SysEx开始标志。
    // 添加厂商ID和数据。
    sysexData.push_back(0x43);  // 厂商ID示例。
    sysexData.push_back(0x10);
    sysexData.push_back(0x4C);
    sysexData.push_back(0x00);
    sysexData.push_back(0x00);
    sysexData.push_back(0x7E);
    sysexData.push_back(0xF7);  // SysEx结束标志。

    OH_MIDIStatusCode status = OH_MIDIDevice_SendSysEx(
        device, outputPortIndex, sysexData.data(), sysexData.size());

    if (status != OH_MIDI_STATUS_OK) {
        OH_LOG_ERROR(LOG_APP, "[SendSysEx] Failed: %{public}d", (int)status);
    }
}

清空输出缓冲区

通过OH_MIDIDevice_FlushOutputPort接口清空指定端口的输出缓冲区，丢弃所有待发送消息。

static napi_value FlushOutputPort(napi_env env, napi_callback_info info)
{
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    int64_t deviceId = 0;
    napi_get_value_int64(env, args[0], &deviceId);

    uint32_t portIndex = 0;
    napi_get_value_uint32(env, args[1], &portIndex);

    std::lock_guard<std::mutex> lock(g_midiMutex);

    napi_value result;
    auto it = g_openedDevices.find(deviceId);
    if (g_midiClient == nullptr||it == g_openedDevices.end()) {
        OH_LOG_ERROR(LOG_APP, "[FlushOutputPort] client is null or device not opened");
        napi_create_int32(env, static_cast<int32_t>(OH_MIDI_STATUS_INVALID_DEVICE_HANDLE), &result);
        return result;
    }

    OH_MIDIStatusCode status = OH_MIDIDevice_FlushOutputPort(it->second, portIndex);
    // ...
}

使用userData传递上下文数据

OH_MIDI API提供客户端级别、BLE连接级别和端口连接级别三个层级的userData参数，分别传递给不同作用域的回调。

APIuserData范围传递给的回调典型用途
OH_MIDIClient_Create客户端级别onDeviceChange、onError全局应用状态、设备管理。
OH_MIDIClient_OpenBLEDeviceBLE连接级别OnBLEDeviceOpened区分并发连接请求、携带连接上下文。
OH_MIDIDevice_OpenInputPort端口级别OnMIDIReceived端口特定的处理逻辑。

注意：

三个userData是独立的，可以传递不同的上下文对象。端口关闭后，对应的回调不再被调用，此时释放端口级userData是安全的。

userData使用场景对比

场景推荐使用示例数据
设备热插拔处理客户端级设备列表、连接状态。
错误日志记录客户端级日志文件句柄、错误计数。
端口事件统计端口级事件计数、时间戳记录。
多端口区分处理端口级端口ID、端口名称。
跨回调共享状态客户端级应用配置、全局状态。

注意事项

  1. 资源管理顺序：关闭客户端时会自动关闭所有设备和端口。建议应用按端口->设备->客户端的顺序关闭资源，以保证代码逻辑清晰。

  2. 线程安全：MIDI回调函数（OnMIDIReceived、OnDeviceChange、OnError）在独立的线程中执行。需要注意线程安全，即访问共享资源时应该使用互斥锁等同步机制。

  3. 内存安全：OnMIDIReceived回调中的events数组及其中所有数据指针是临时的，仅在此回调期间有效。必须在回调返回前复制任何需要保留的数据。访问过期指针会导致未定义行为（崩溃、内存损坏）。

  4. 错误处理：所有MIDI接口调用都应该检查返回值，并正确处理错误情况。

  5. 性能优化：在回调函数中禁止执行超过1毫秒的操作或阻塞I/O，以确保MIDI消息的实时处理不受影响。在回调中执行耗时操作或阻塞I/O会严重影响MIDI消息的实时处理，可能导致音频延迟或丢帧。

  6. UMP格式：SDK始终使用UMP（Universal MIDI Packet）格式进行数据传输，无论选择MIDI 1.0还是MIDI 2.0协议。需要了解UMP消息格式以正确构造和解析MIDI消息。

  7. 缓冲区管理：发送接口是非阻塞的，当缓冲区满时会返回OH_MIDI_STATUS_WOULD_BLOCK。应用应该检查返回值，并在缓冲区可用时重新尝试发送未完成的数据。

  8. 协议兼容性：请求MIDI 2.0协议但设备仅支持MIDI 1.0时，服务会自动进行降级转换，这将导致丢失数据精度或特定消息类型（如SysEx）。

  9. 权限申请：访问蓝牙MIDI设备需要申请ohos.permission.ACCESS_BLUETOOTH权限。

  10. 设备热插拔：应用应该处理设备连接和断开事件，及时更新内部状态并释放相关资源。

  11. 资源释放顺序：OH_MIDIClient_Destroy()会自动关闭所有已打开的设备和端口。但如果初始化过程中发生错误需要提前退出函数，应按以下顺序手动释放资源：

    第一步：关闭已打开的端口（OH_MIDIDevice_CloseInputPort/OH_MIDIDevice_CloseOutputPort）。详见midi端口管理中的关闭输入端口和关闭输出端口示例

    第二步：关闭已打开的设备（OH_MIDIClient_CloseDevice）。详见关闭MIDI设备示例。

    第三步：销毁客户端（OH_MIDIClient_Destroy）。详见销毁MIDI客户端示例。

调测验证

验证设备枚举

使用以下方法验证MIDI设备是否正确枚举：

  1. 检查日志输出：确认设备数量、设备名称、设备类型等信息正确显示。
  2. 对比系统设备列表：与系统设置中显示的MIDI设备列表对比。
  3. 测试热插拔：连接/断开设备，通过调试输出或日志确认OnDeviceChange回调在设备连接时触发一次，在设备断开时再触发一次。

调试UMP消息格式

UMP消息格式遵循MIDI 2.0标准。常见UMP消息类型：

  • 0x2：MIDI 1.0 Channel Voice Message（32位）。
  • 0x3：MIDI 1.0 System Message（32位）。
  • 0x4：MIDI 2.0 Channel Voice Message（64位）。

调试时可以输出原始UMP数据进行验证：

OH_LOG_DEBUG(LOG_APP, "UMP Data: 0x%{public}08X", umpData[0]);

常用调试工具

日志输出：使用OH_LOG系列宏输出详细调试信息。

日志记录建议

在开发阶段，建议在接口调用、错误处理和关键业务逻辑状态变更处添加包含时间戳、方法名、参数值和返回值的详细日志：

#define MIDI_LOG_TAG "[MIDI]"

#define MIDI_LOGI(fmt, ...) OH_LOG_INFO(LOG_APP, MIDI_LOG_TAG "[INFO] " fmt, ##__VA_ARGS__)
#define MIDI_LOGE(fmt, ...) OH_LOG_ERROR(LOG_APP, MIDI_LOG_TAG "[ERROR] " fmt, ##__VA_ARGS__)
#define MIDI_LOGD(fmt, ...) OH_LOG_DEBUG(LOG_APP, MIDI_LOG_TAG "[DEBUG] " fmt, ##__VA_ARGS__)

// 使用示例。
MIDI_LOGI("Device opened: ID=%{public}lld", targetDeviceId);
MIDI_LOGE("Failed to send message: %{public}d", result);
MIDI_LOGD("UMP Data: 0x%{public}08X", umpData[0]);

常见问题

发送消息时返回OH_MIDI_STATUS_WOULD_BLOCK

表示发送缓冲区已满，无法立即发送消息。原因和处理方法如下：

  1. 发送速度超过缓冲区处理能力：降低发送频率（通常在发送大量SysEx消息的场景）。

  2. 缓冲区未及时处理：考虑使用OH_MIDIDevice_FlushOutputPort接口清空缓冲区。

  3. 处理部分发送：检查eventsWritten参数，了解实际发送了多少事件。

示例处理代码：

uint32_t eventsWritten = 0;
OH_MIDIStatusCode result = OH_MIDIDevice_Send(device, portIndex, events, count, &eventsWritten);
if (result == OH_MIDI_STATUS_WOULD_BLOCK) {
    OH_LOG_WARN(LOG_APP, "Buffer full, partial send: %{public}u/%{public}u", eventsWritten, count);

    // 选项1：稍后重试剩余事件。
    OH_MIDIEvent *remaining = &events[eventsWritten];
    size_t remainingCount = count - eventsWritten;

    // 选项2：丢弃未发送的事件。
    // OH_LOG_WARN(LOG_APP, "Dropped %{public}zu events", remainingCount);
}

如何正确处理设备热插拔

正确的设备热插拔处理流程：

  1. 监听设备变化回调：在OnDeviceChange中处理连接和断开事件。
  2. 更新设备列表：设备断开时及时移除，设备连接时重新枚举。
  3. 释放相关资源：设备断开时，关闭该设备相关的所有端口和设备句柄。
  4. 错误处理：访问已断开的设备会返回错误，需要检查错误码并记录日志或通知用户。

蓝牙MIDI设备连接失败处理

蓝牙MIDI设备连接常见问题及解决方案：

  1. 权限未声明：确保在module.json5中声明了ohos.permission.ACCESS_BLUETOOTH权限。
  2. 蓝牙未开启：连接前确保系统蓝牙已开启。
  3. 地址错误：确认蓝牙设备地址格式正确（例如"AA:BB:CC:DD:EE:FF"）。
  4. 超时问题：蓝牙连接是异步的，等待时间通常需要1-3秒（具体时间因设备型号和性能而异）。

说明：

  • OH_MIDIClient_OpenBLEDevice是异步API，调用后立即返回。
  • 连接结果通过回调函数异步通知，不阻塞主线程。
  • 推荐在回调中处理后续操作（如打开端口），而非同步等待。
  • 实际应用中需要保存device句柄（例如通过userData或全局变量），以便后续调用OH_MIDIClient_CloseDevice清理资源。

在回调中访问数据时程序崩溃处理

通常是由于线程安全或内存生命周期问题导致。

  1. 内存生命周期问题：OnMIDIReceived回调中的events数据仅在回调期间有效，不能保存指针供后续使用。
  2. 线程安全问题：回调在独立线程执行，访问共享数据需要加锁。
  3. 解决方案如下：
    • 在回调中复制需要的数据。
    • 使用互斥锁保护共享资源。
    • 避免在回调中执行耗时操作。

错误示例：

// 错误：保存指针供后续使用。
static const OH_MIDIEvent *g_savedEvents;

static void OnMIDIReceived(void *userData, const OH_MIDIEvent *events, size_t eventCount) {
    g_savedEvents = events; // 错误！回调结束后events无效。
}

// 在其他地方访问g_savedEvents会导致崩溃。

正确示例：

// 正确：复制数据。
struct MIDIMessage {
    std::vector<uint32_t> umpData;
};

// 使用线程安全的队列存储消息。
static void OnMIDIReceived(void *userData, const OH_MIDIEvent *events, size_t eventCount) {
    for (size_t i = 0; i < eventCount; i++) {
        // 分配内存并复制数据。
        MIDIMessage msg;
        msg.umpData.assign(events[i].data, events[i].data + events[i].length);

        // 将复制的数据添加到队列（需要加锁）。
        // enqueue_message(msg);
    }
}

完整示例

完整的示例代码可以在示例项目中查看：

  • 示例项目路径：https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/Media/Audio/Midi。

示例项目展示了：

  • 创建和销毁MIDI客户端。
  • 设备枚举和设备变化回调。
  • 打开/关闭设备（USB和BLE）。
  • 获取端口信息。
  • 打开/关闭输入输出端口。
  • 发送MIDI消息（包括Note On/Off和SysEx）。
  • 接收MIDI消息回调。
  • 使用userData传递上下文数据。

相关参考

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 public-audio-spatialization-management

openharmony 鸿蒙 audio-session-management

openharmony 鸿蒙 using-opensl-es-for-playback

openharmony 鸿蒙 using-ohaudio-for-recording

openharmony 鸿蒙 audio-kit-intro

openharmony 鸿蒙 audio-workgroup

openharmony 鸿蒙 audio-collaborative-management-sys

openharmony 鸿蒙 audio-recording-concurrency

openharmony 鸿蒙 audio-recording-overview

openharmony 鸿蒙 audio-suite-manual-rendering

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/xj4Hftxm