{"id":15873,"library":"tv-automation-quantel-gateway-client","title":"Sofie Quantel Gateway Client","description":"This is a client library specifically designed for communication with the Sofie Quantel Gateway, an integral component of the open-source Sofie TV Automation System. It acts as an abstraction layer, allowing Node.js applications to interact with Quantel ISA (Integrated Production Archive) systems. The library facilitates discovery of clips, management of playout control on Quantel servers, and handles the underlying HTTP REST API communication with the Quantel Gateway, which itself bridges to the complex Quantel ISA System's CORBA API. Currently at version 4.0.0, the package primarily supports modern Node.js environments (>=18.0) and ships with TypeScript type definitions, providing a robust and type-safe interface for broadcast automation workflows. It focuses on simplifying interaction with professional broadcast hardware within the Sofie ecosystem, abstracting away low-level network and protocol complexities.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/nrkno/tv-automation-quantel-gateway-client","tags":["javascript","quantel-gateway","quantel","sofie","typescript"],"install":[{"cmd":"npm install tv-automation-quantel-gateway-client","lang":"bash","label":"npm"},{"cmd":"yarn add tv-automation-quantel-gateway-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add tv-automation-quantel-gateway-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const QuantelGateway = require('tv-automation-quantel-gateway-client')","symbol":"QuantelGateway","correct":"import { QuantelGateway } from 'tv-automation-quantel-gateway-client'"},{"note":"This is a named export for various utility types and interfaces related to Quantel operations.","symbol":"Q","correct":"import { Q } from 'tv-automation-quantel-gateway-client'"},{"note":"Explicitly import types using `import type` for clarity and to avoid bundling type definitions at runtime in TypeScript.","symbol":"QuantelGatewayConfig","correct":"import type { QuantelGatewayConfig } from 'tv-automation-quantel-gateway-client'"}],"quickstart":{"code":"import { QuantelGateway } from 'tv-automation-quantel-gateway-client';\n\nasync function runQuantelClient() {\n  const quantelClient = new QuantelGateway();\n\n  const gatewayUrl = process.env.QUANTEL_GATEWAY_URL ?? 'http://localhost:3000';\n  const isaUrl = process.env.QUANTEL_ISA_URL ?? 'http://quantel.isa.manager:2099';\n  const zoneId = process.env.QUANTEL_ZONE_ID ?? 'default';\n  const serverId = process.env.QUANTEL_SERVER_ID ?? '1100'; // Example server ID\n\n  try {\n    console.log(`Attempting to connect to Gateway: ${gatewayUrl}, ISA: ${isaUrl}`);\n    await quantelClient.init(gatewayUrl, isaUrl, zoneId, serverId);\n    console.log('Successfully connected to Quantel Gateway.');\n\n    // Example: Fetching server information if serverId is not initially known\n    // await quantelClient.connectToISA(isaUrl);\n    // const servers = await quantelClient.getServers(zoneId);\n    // console.log('Available Servers:', servers.map(s => s.id));\n\n    // Here you would add your logic to interact with Quantel, e.g., get clips, control playout\n    console.log('Client is ready for Quantel operations.');\n\n  } catch (error) {\n    console.error('Failed to initialize Quantel Gateway client:', error);\n    process.exit(1);\n  } finally {\n    // Always call dispose to clean up resources\n    quantelClient.dispose();\n    console.log('Quantel Gateway client disposed.');\n  }\n}\n\nrunQuantelClient();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.0 or newer. Use `nvm` or your package manager to manage Node.js versions effectively.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a discovery mechanism: `await quantelClient.connectToISA(isaUrl); const servers = await quantelClient.getServers(zoneId);` before calling `init` if `serverID` is dynamic or unknown.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import an ES Module using CommonJS `require()` syntax.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()"},{"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';`.","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.","error":"TypeError: QuantelGateway is not a constructor"},{"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.","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).","error":"QuantelGateway.init failed: Connection refused"},{"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.","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.","error":"Error: Timeout: Could not connect to ISA: [URL]"}],"ecosystem":"npm"}