pirate-midi-usb

Easily interact with Pirate Midi devices over USB from JavaScript

[!WARNING]
The device API was overhauled in Bridge OS 2.x - Use [email protected] to interact with devices on Bridge OS 1.x (or just upgrade, it's great)

• Install
• Usage
• API
  • Use getDevices to retrieve available devices
  • Use PirateMidiDevice methods to interact with the device
  • Managing the connection
  • Mock device
  • Debugging & testing
• Examples
• Thanks

Install

npm install pirate-midi-usb

Usage

import { getDevices } from 'pirate-midi-usb';

const devices = await getDevices();

await device[0].goToBank(2);

API

This package implements the Pirate Midi Device API to interact with Bridge4 and Bridge6 devices, see the API documentation for the underlying details.

Use getDevices to retrieve available devices

Scans USB devices and returns a promise with an array of PirateMidiDevice instances (one per device) to interact with.

Note In the browser a dialog will be triggered for the user to select and give access to a single device. Currently only a single device will be returned.

import { getDevices } from 'pirate-midi-usb';

const devices = await getDevices();

const bridge6 = device.find(device => device.deviceName === 'Bridge6');

Each instance of a device is returned with the deviceInfo prefetched. This information could be used to select a specific device when multiple are connected. When no devices are found an empty array will be returned

Use PirateMidiDevice methods to interact with the device

Check PirateMidiDevice.ts to see all implemented methods.

Managing the connection

Devices may be plugged out while your app/script is running. When a device it returned it is ready to use but you should monitor the connection and respond accordingly to avoid interacting with an unavailable device:

const [device] = await getDevices();

// Activate UI

device.on('disconnect', () => {
  // Deactivate UI
});

// When the same device is plugged in again the instance will auto-reconnect and fire a "connect" event.
device.on('connect', () => {
  // Activate UI
});

Note This behaviour is only implemented for browsers at the moment.

Mock device

To aid in testing or running a demo, a mock device can be created using getMockDevice:

// Provide device data to the mock
const device = await getMockDevice({
  deviceInfo,
  globalSettings,
  bankSettings,
});

// Methods will behave as if a real device is connected BUT it's state will never change from the data given.
device.getGlobalSettings()

The mock device is static, set.. and control methods will respond as usual but have no actual effect.

Debugging

Debugging is enabled via a debug-like logger.

In Node, use environment variables to enable logging. The logs can be filtered by prefix and wildcards.

• DEBUG=pmu:* - high level logs
• DEBUG=pmu-verbose:* - verbose (large output!) logs
• DEBUG=pmu:runCommand - a specific feature
• DEBUG=pmu:runCommand,pmu:sendReceive - multiple features
• DEBUG=pmu* - all logs from this library
• DEBUG=* - all debug logs (note this may include other libraries in your app)

In the browser, set the same values to localStorage.debug.

Examples

See the examples folder, check out the intro example to get started!

Run examples by their filename:

npm run examples:intro

Thanks

Thanks to Pirate Midi for the awesome devices and the openness.

This repo was started with typescript-npm-package-template