@alexanderolsen/port-manager
v1.2.82
Published
Abstracts the rt-midi API into a simplified list of devices. Automatically links input + output ports, and provides callbacks when available ports change.
Downloads
62
Maintainers
Readme
port-manager
Port manager simplifies interacting with MIDI devices by providing a layer of abstraction on top of the rt-midi API. Rather than interacting with individual input and output ports, pairs of input+output ports are grouped together and thought of as a single device (PortPair
in code). Devices also provide convenience methods for interacting with the underlying ports.
Features
- Automatically couple input and output ports
- Automatically distinguishes between ports with the same name; "APC" and "APC" become "APC0" and "APC1"
- Invokes callbacks when list of available devices changes
Installation
Install using NPM:
npm i @alexanderolsen/port-manager
or yarn:
yarn add @alexanderolsen/port-manager
Usage
const manager = require('@alexanderolsen/port-manager')
let listenerId = manager.addListener((devices) => {
devices.forEach((device) => {
console.log(device.id, device.name, device.hasInput, device.hasOutput);
});
});
or
// If transpiling, you can use `import`s
import { get } from '@alexanderolsen/port-manager';
let deviceName = 'MidiDevice';
let deviceId = 'MidiDevice0'; // {deviceName}{nth device with the given name}
let device = get(deviceId);
device.send([172, 22, 1]);
device.onMessage((deltaTime, message) => {
// do something with the message
});
device.close();
API Reference
The require
'd object exposes:
/**
* Add a callback to be invoked if the list of available MIDI ports changes.
*
* @param { Function } cb The function to be invoked
* @return { string } The id used to remove the listener using `removeListener(id)`
*/
export function addListener(cb) {...}
/**
* Remove the listener associated with the given id.
*
* @param { string } id The id associated with the callback. Received from `addListener(cb)`
*/
export function removeListener(id) {...}
/**
* Return a list of all of the available devices
* @return { PortPair[] } Array of `PortPair`s
*/
export function all() {...}
/**
* Returns the device with the given id, or null if no such device exists.
*
* @param { string } id String formatted `{DeviceName}{nth occurrence of device (if multiple devices with same name)}`
* @return { PortPair } A representation of both input and output ports
*/
export function get(id) {...}
PortPair
get
and all
return a PortPair
and a PortPair[]
respectively. PortPair
s can be thought of as one singular device which has the following API:
/**
* Couples input and output ports. Each pair doesn't necessarily have to have both an input and
* output port; pairs of (iPort && null) or (null ** oPort) may exist.
*/
class PortPair {
/**
* Open the input and/or output ports if not null.
*/
open() {...}
/**
* Open the input and/or output ports if not null.
*/
close() {...}
/**
* Send a message through the output port. If output port is null, does nothing.
*/
send(msg) {}
/**
* Set a callback to be invoked when the input port receives a message. If input port is null, does nothing.
*/
onMessage(cb) {}
/** getters */
get id() { ... } // `{deviceName}{occurrenceNumber}`
get name() { ... } // device name
get hasInput() { ... } // is input port != null?
get hasOutput() { ... } // is output port != null?
get occurrenceNumber() { ... } // nth device with the given name
}
Building From Source
git clone https://github.com/aolsenjazz/port-manager
cd port-manager
npm run build
Production files are placed in the build directory.
Examples
To run the examples:
cd examples
node notifications.js
node on-message.js
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
License
Licenses are available in LICENSE.md
.