npm package: @jsilvanus/matrox-monarch-control
Description: TypeScript npm module for controlling Matrox Monarch HD and HDX devices via their HTTP API
Author: jsilvanus
Latest version: 0.6.0

# 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

```bash
npm install matrox-monarch-control
```

## Quick Start

```typescript
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:

```typescript
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

```typescript
// 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

```typescript
await hd.startStreaming();
await hd.stopStreaming();

await hd.startRecording();
await hd.stopRecording();

await hd.startStreamingAndRecording();
await hd.stopStreamingAndRecording();
```

#### Configuration

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```typescript
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:

```typescript
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, <jsilvanus@gmail.com>

## License

MIT