node-libcec

Node.js bindings for libcec - control CEC (Consumer Electronics Control) devices over HDMI.

Prerequisites

You must have libcec installed on your system:

Linux (Debian/Ubuntu):

sudo apt-get install libcec-dev

macOS (Homebrew):

brew install libcec

Windows: Install the Pulse-Eight USB-CEC Adapter software.

Installation

npm install node-libcec

Quick Start

import { CECAdapter, LogicalAddress, DeviceType } from 'node-libcec';

// Create adapter
const cec = new CECAdapter({
  deviceName: 'MyApp',
  deviceTypes: [DeviceType.RECORDING_DEVICE]
});

// Listen for events
cec.on('keypress', (key) => {
  console.log('Remote key pressed:', key.keycode);
});

cec.on('command', (cmd) => {
  console.log('CEC command received:', cmd);
});

// Connect to adapter (auto-detects port)
cec.open();

// Discover devices on the bus
const devices = cec.getActiveDevices();
devices.forEach(addr => {
  console.log(`Device ${addr}: ${cec.getDeviceOSDName(addr)}`);
});

// Control devices
cec.powerOnDevices(LogicalAddress.TV);
cec.setActiveSource();

// Cleanup
cec.close();

API

CECAdapter

Constructor Options

new CECAdapter({
  deviceName: 'node-libcec',           // OSD name (max 13 chars)
  deviceTypes: [DeviceType.RECORDING_DEVICE],
  physicalAddress: 0x1000,             // Optional: fixed physical address
  baseDevice: LogicalAddress.TV,       // Base device for address detection
  hdmiPort: 1,                         // HDMI port number
  activateSource: false                // Auto-activate as source on connect
});

Static Methods

• CECAdapter.detectAdapters() - Returns array of detected CEC adapters

Connection

• open(port?, timeout?) - Connect to adapter (auto-detects if no port)
• close() - Disconnect
• pingAdapter() - Check if adapter is responsive
• getAdapterVendorId() - Get USB vendor ID
• getAdapterProductId() - Get USB product ID
• getLibInfo() - Get libcec version info

Device Discovery

• getActiveDevices() - Get array of active logical addresses
• pollDevice(address) - Check if device exists
• isActiveDevice(address) - Check if device is active
• isActiveDeviceType(type) - Check if device type is active
• getActiveSource() - Get current active source address
• isActiveSource(address) - Check if device is active source
• isLibCECActiveSource() - Check if this adapter is active source

Device Information

• getDeviceOSDName(address) - Get device name
• getDeviceVendorId(address) - Get vendor ID
• getDevicePhysicalAddress(address) - Get physical address
• getDevicePowerStatus(address) - Get power status
• getDeviceCecVersion(address) - Get CEC version
• getDeviceMenuLanguage(address) - Get menu language

Power Control

• powerOnDevices(address?) - Power on device(s)
• standbyDevices(address?) - Put device(s) in standby

Source Control

• setActiveSource(deviceType?) - Set this adapter as active source
• setInactiveView() - Set this adapter as inactive

Audio Control

• volumeUp(sendRelease?) - Increase volume
• volumeDown(sendRelease?) - Decrease volume
• muteAudio() - Mute audio
• audioToggleMute() - Toggle mute
• audioStatus() - Get audio status

Commands

• transmit(command) - Send raw CEC command
• sendKeypress(destination, keycode, wait?) - Send remote keypress
• sendKeyRelease(destination, wait?) - Send key release
• setOSDString(address, duration, message) - Display message on device

Address Configuration

• setLogicalAddress(address?) - Set logical address
• setPhysicalAddress(address) - Set physical address
• setHDMIPort(baseDevice, port) - Set HDMI port
• getLogicalAddresses() - Get controlled logical addresses

Configuration

• getCurrentConfiguration() - Get current config object
• setConfiguration(config) - Update configuration
• rescanActiveDevices() - Rescan CEC bus for devices
• disableCallbacks() - Disable event callbacks

Events

cec.on('log', (message) => { });           // Library log messages
cec.on('keypress', (key) => { });          // Remote control keypresses
cec.on('command', (command) => { });       // CEC commands
cec.on('sourceActivated', (info) => { });  // Source activation changes
cec.on('alert', (alert) => { });           // System alerts
cec.on('configurationChanged', (config) => { }); // Config changes

Constants

import {
  LogicalAddress,   // TV, RECORDING_DEVICE_1, PLAYBACK_DEVICE_1, etc.
  DeviceType,       // TV, RECORDING_DEVICE, PLAYBACK_DEVICE, etc.
  PowerStatus,      // ON, STANDBY, IN_TRANSITION_*, UNKNOWN
  Opcode,           // STANDBY, ACTIVE_SOURCE, USER_CONTROL_PRESSED, etc.
  UserControlCode,  // SELECT, UP, DOWN, PLAY, PAUSE, etc.
  LogLevel,         // ERROR, WARNING, NOTICE, TRAFFIC, DEBUG
  DisplayControl,   // DISPLAY_FOR_DEFAULT_TIME, DISPLAY_UNTIL_CLEARED, etc.
  Version,          // V1_2, V1_3, V1_4, V2_0, etc.
  AlertType         // SERVICE_DEVICE, CONNECTION_LOST, etc.
} from 'node-libcec';

Examples

See the examples directory for more usage patterns:

• basic.js - Simple device discovery and event handling
• advanced.js - Interactive CLI with full feature demonstration

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Linux | Supported | Requires libcec-dev | | macOS | Supported | Requires Homebrew libcec | | Windows | Supported | Requires Pulse-Eight SDK |

Requirements

• Node.js >= 18.0.0
• libcec system library
• A CEC-compatible USB adapter (e.g., Pulse-Eight USB-CEC)

License

MIT