Sofie Quantel Gateway Client

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()

  cause Attempting to import an ES Module using CommonJS `require()` syntax.
  fix Change `const { Symbol } = require('pkg');` to `import { Symbol } from 'pkg';` or use a dynamic import `const { Symbol } = await import('pkg');` within an `async` function.

• TypeError: QuantelGateway is not a constructor

  cause Often occurs when trying to use a named export as a default export, or when `require()` is used on a package primarily structured for ESM.
  fix Ensure you are using named imports: `import { QuantelGateway } from 'tv-automation-quantel-gateway-client';` instead of `import QuantelGateway from 'tv-automation-quantel-gateway-client';`.

• QuantelGateway.init failed: Connection refused

  cause The client tried to establish a TCP connection to the Quantel Gateway, but the target machine actively refused it (e.g., no server running on that port, or firewall blocking).
  fix Verify that the Quantel Gateway application is running and listening on the specified host and port (`QUANTEL_GATEWAY_URL`). Check local and remote firewalls. Ensure the URL is correct.

• Error: Timeout: Could not connect to ISA: [URL]

  cause The client could not establish a connection to the Quantel ISA Manager within the expected timeframe, possibly due to network latency, incorrect URL, or the ISA Manager being offline.
  fix Confirm the `QUANTEL_ISA_URL` is correct and that the Quantel ISA system is operational and reachable from the machine hosting the Quantel Gateway.

Warnings

• breaking Version 4.0.0 requires Node.js version 18.0 or higher. Earlier Node.js versions are not supported and will lead to runtime errors, particularly with ESM imports or native module bindings.
  Fix: Upgrade your Node.js environment to version 18.0 or newer. Use `nvm` or your package manager to manage Node.js versions effectively.
• gotcha The client connects to a 'Quantel Gateway' application, which in turn communicates with the 'Quantel ISA SQ system'. Both the gateway and the ISA system must be installed, running, and accessible from the client's network environment.
  Fix: Ensure the Quantel Gateway application is running and its network address/port are correctly configured. Verify network connectivity between your application, the Gateway, and the ISA system. Refer to the Sofie Quantel Gateway documentation for setup.
• gotcha The `init` method requires a `serverID`. If the `serverID` is not known beforehand, you must first connect to the ISA using `connectToISA()` and then fetch available servers with `getServers(zoneId)` to determine valid IDs.
  Fix: Implement a discovery mechanism: `await quantelClient.connectToISA(isaUrl); const servers = await quantelClient.getServers(zoneId);` before calling `init` if `serverID` is dynamic or unknown.
• gotcha This library expects specific URLs for the Quantel Gateway and the ISA Manager. Incorrect URLs, port numbers, or network misconfigurations are common sources of connection failures.
  Fix: Double-check `quantel.gateway.url:port` and `quantel.isa.url` values. Ensure they are reachable from the host running the client application and that no firewalls are blocking the necessary ports.

Install

• npm install tv-automation-quantel-gateway-client npm
• yarn add tv-automation-quantel-gateway-client yarn
• pnpm add tv-automation-quantel-gateway-client pnpm

Imports

• QuantelGateway
  wrong:

  const QuantelGateway = require('tv-automation-quantel-gateway-client')

  correct:

  import { QuantelGateway } from 'tv-automation-quantel-gateway-client'

  The library is primarily designed for ESM usage. CommonJS `require` will result in a runtime error or incorrect object if the package is pure ESM.
• Q

  import { Q } from 'tv-automation-quantel-gateway-client'

  This is a named export for various utility types and interfaces related to Quantel operations.
• QuantelGatewayConfig

  import type { QuantelGatewayConfig } from 'tv-automation-quantel-gateway-client'

  Explicitly import types using `import type` for clarity and to avoid bundling type definitions at runtime in TypeScript.

Quickstart

This example demonstrates how to initialize the `QuantelGateway` client, connect to a specified gateway and ISA system, and then properly dispose of the client. It uses environment variables for configuration for easy setup.

import { QuantelGateway } from 'tv-automation-quantel-gateway-client';

async function runQuantelClient() {
  const quantelClient = new QuantelGateway();

  const gatewayUrl = process.env.QUANTEL_GATEWAY_URL ?? 'http://localhost:3000';
  const isaUrl = process.env.QUANTEL_ISA_URL ?? 'http://quantel.isa.manager:2099';
  const zoneId = process.env.QUANTEL_ZONE_ID ?? 'default';
  const serverId = process.env.QUANTEL_SERVER_ID ?? '1100'; // Example server ID

  try {
    console.log(`Attempting to connect to Gateway: ${gatewayUrl}, ISA: ${isaUrl}`);
    await quantelClient.init(gatewayUrl, isaUrl, zoneId, serverId);
    console.log('Successfully connected to Quantel Gateway.');

    // Example: Fetching server information if serverId is not initially known
    // await quantelClient.connectToISA(isaUrl);
    // const servers = await quantelClient.getServers(zoneId);
    // console.log('Available Servers:', servers.map(s => s.id));

    // Here you would add your logic to interact with Quantel, e.g., get clips, control playout
    console.log('Client is ready for Quantel operations.');

  } catch (error) {
    console.error('Failed to initialize Quantel Gateway client:', error);
    process.exit(1);
  } finally {
    // Always call dispose to clean up resources
    quantelClient.dispose();
    console.log('Quantel Gateway client disposed.');
  }
}

runQuantelClient();