Matrox Monarch Control

TypeScript/Node.js module for controlling Matrox Monarch HD and HDX devices via their HTTP API.

Current state

Testing, first npm release

Requirements

• Node.js 18.0.0 or higher (uses native fetch)

Installation

npm install matrox-monarch-control

Quick Start

import { MonarchHD, MonarchHDX } from 'matrox-monarch-control';

// Connect to an HD device
const hd = new MonarchHD({ host: '192.168.1.100' });
const status = await hd.getStatus();
console.log(status);

// Connect to an HDX device
const hdx = new MonarchHDX({ host: '192.168.1.101' });
const hdxStatus = await hdx.getStatus();
console.log(hdxStatus);

Connection Options

Both MonarchHD and MonarchHDX accept the same connection options:

interface MonarchConnectionOptions {
  host: string;              // IP address or hostname (required)
  username?: string;         // Default: 'admin'
  password?: string;         // Default: 'admin'
  protocol?: 'http' | 'https'; // Default: 'http'
  timeout?: number;          // Request timeout in ms. Default: 5000
}

API Reference

MonarchHD

For Matrox Monarch HD devices.

Status & Input

// Get device status
const status = await hd.getStatus();
// Returns: { record: { state }, stream: { mode, state }, name }

// Get input status
const input = await hd.getInputStatus();
// Returns: { input, resolution, framerate, closedCaptions? }

Streaming & Recording

await hd.startStreaming();
await hd.stopStreaming();

await hd.startRecording();
await hd.stopRecording();

await hd.startStreamingAndRecording();
await hd.stopStreamingAndRecording();

Configuration

// RTSP settings
const rtsp = await hd.getRTSP();
await hd.setRTSP({ url: 'rtsp://...', port: 554 });

// RTMP settings
const rtmp = await hd.getRTMP();
await hd.setRTMP({ url: 'rtmp://...', streamName: 'live', username: '', password: '' });

// Recording filename
const filename = await hd.getRecordFileName();
await hd.setRecordFileName('recording_%d');

// Streaming bitrate
const bitrate = await hd.getStreamingVideoDataRate();
await hd.setStreamingVideoDataRate(5000);

MonarchHDX

For Matrox Monarch HDX devices with dual encoders.

Status & Input

// Get device status
const status = await hdx.getStatus();
// Returns: { encoder1: { mode, state }, encoder2: { mode, state }, name }

// Get input status
const input = await hdx.getInputStatus();

// Video/Audio input selection
const videoInput = await hdx.getVideoInput(); // 'SDI' | 'HDMI'
await hdx.setVideoInput('SDI');

const audioInput = await hdx.getAudioInput(); // 'ANALOG' | 'DIGITAL'
await hdx.setAudioInput('DIGITAL');

Encoder Control

// Control individual encoders
await hdx.startEncoder(1);
await hdx.stopEncoder(1);

await hdx.startEncoder(2);
await hdx.stopEncoder(2);

// Control both encoders
await hdx.startBothEncoders();
await hdx.stopBothEncoders();

Encoder Configuration

// RTSP settings per encoder
const rtsp1 = await hdx.getEncoderRTSP(1);
await hdx.setEncoderRTSP(1, { url: 'rtsp://...', port: 554 });

// RTMP settings per encoder
const rtmp1 = await hdx.getEncoderRTMP(1);
await hdx.setEncoderRTMP(1, { url: 'rtmp://...', streamName: 'live' });

Error Handling

The module provides specific error classes for different failure scenarios:

import {
  MonarchError,           // Base error class
  MonarchConnectionError, // Network/connection failures
  MonarchCommandError,    // Command returned FAILED
  MonarchBusyError,       // Device returned RETRY (busy)
} from 'matrox-monarch-control';

try {
  await hd.startStreaming();
} catch (error) {
  if (error instanceof MonarchBusyError) {
    // Device is busy, retry later
  } else if (error instanceof MonarchCommandError) {
    // Command failed
  } else if (error instanceof MonarchConnectionError) {
    // Could not connect to device
  }
}

All error classes include:

• message - Error description
• command - The command that was attempted
• response - Raw response from device (if any)

Types

All TypeScript types are exported:

import type {
  // Device & encoder states
  DeviceModel,      // 'HD' | 'HDX'
  EncoderState,     // 'ON' | 'READY' | 'DISABLED'
  StreamMode,       // 'RTSP' | 'RTMP' | 'DISABLED'
  EncoderMode,      // 'RTSP' | 'RTMP' | 'RECORD' | 'NONE'
  VideoInput,       // 'SDI' | 'HDMI'
  AudioInput,       // 'ANALOG' | 'DIGITAL'

  // Response types
  HDStatus,
  HDXStatus,
  InputStatus,
  RTSPConfig,
  RTMPConfig,
  CommandResponse,

  // Config
  MonarchConnectionOptions,
} from 'matrox-monarch-control';

Copyright

Juha Itäleino / jsilvanus, [email protected]

License

MIT