dhd-control-api
Version:
Typescript library for the DHD Control API
90 lines (69 loc) • 5.62 kB
Markdown
# DHD Control API
[](https://github.com/bitebroadcast/dhd-control-api/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/dhd-control-api)
[](https://github.com/bitebroadcast/dhd-control-api/blob/main/LICENSE)
### _**Warning:** This library is still under active development and not yet ready for production use. The API is subject to change._
This TypeScript library provides a type-safe interface to DHD audio cores via the new [DHD Control API](https://developer.dhd.audio/docs/API/control-api/), supported in firmware version 10.3 and above. Before using this library, please read the [API usage disclaimer](https://developer.dhd.audio/docs/api/license-agreement/) in the DHD developer documentation.
Please refer to the [official documentation](https://developer.dhd.audio/docs/API/control-api/) for more information on the DHD Control API.
## Installation
This library is available on [npm](npmjs.com/package/dhd-control-api). Install it easily with your preferred package manager:
```sh
pnpm add dhd-control-api
```
## Usage
This library provides a `DHD` class that you can use to interact with a DHD audio core. Once you've created an instance of the `DHD` class, it connects automatically to the DHD device and authenticates using the provided token. You do not have to worry about managing (re)connecting or authentication yourself.
On initialization, the `DHD` class takes an options object with the following properties:
| Property | Type | Required | Default | Description |
| ---------------- | --------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host` | `string` | Yes | | The hostname or IP address of the DHD device. |
| `token` | `string` | Yes | | The token from DHD WebApps user management. |
| `connectionType` | `websocket` \| `rest` | No | `websocket` | The type of connection to use when connecting to the DHD device. Please note that the connection via REST has a [rate limit of 1 request per second.](https://developer.dhd.audio/docs/API/control-api/rest-usage#rate-limiting) |
| `secure` | `boolean` | No | `false` | Connect to the DHD device using a secure WebSocket connection or HTTPS-requests. |
| `autoConnect` | `boolean` | No | `true` | Connect to the DHD device automatically when the instance is created. Only applies to WebSocket connections. |
| `autoReconnect` | `boolean` | No | `true` | Automatically reconnect to the DHD device if the connection is lost. Only applies to WebSocket connections. |
```typescript
import { DHD } from 'dhd-control-api';
const dhd = new DHD({
host: '10.0.0.1', // IP address of the DHD core
token: 'dhd-web-apps-token', // Token from DHD WebApps user management
});
(async () => {
try {
// Example usage
// Get data from DHD device
const levelDetect = await dhd.get('/audio/levels/{levelDetectID}', {
params: { levelDetectID: 1 },
});
const logics = await dhd.get('/control/logics');
const fader = await dhd.get('/audio/mixers/{mixerID}/faders/{faderID}', {
params: { mixerID: 1, faderID: 16 },
});
// Set parameters in DHD device
const logic263 = await dhd.set('/control/logics/{logicID}', {
params: { logicID: 263 },
payload: { value: true },
});
const potentiometer5 = await dhd.set('/audio/pots/{potID}', {
params: { potID: 5 },
payload: { value: -12 },
});
const faderEq = await dhd.set(
'/audio/mixers/{mixerID}/faders/{faderID}/params/eq{eqID}',
{
params: { mixerID: 1, faderID: 16, eqID: 1 },
payload: { on: true, gain: 3, frequency: 1250 },
},
);
} catch (error) {
// Handle errors
console.error('An error occurred:', error);
}
})();
```
## Debug logging
This library uses the [debug](https://www.npmjs.com/package/debug) package for logging. To enable debug logging, set the `DEBUG` environment variable to `dhd-control-api:*`:
```sh
DEBUG=dhd-control-api:* node my-app.js
```
---
_BITE Broadcast and this library are not affiliated with or endorsed by DHD Audio GmbH. This is an independent project._