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):
``bash
sudo apt-get install libcec-dev
`

macOS (Homebrew):
`bash
brew install libcec
`

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

Installation

`bash
npm install node-libcec
`

Quick Start

`javascript
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

$3

#### Constructor Options

`javascript
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

$3

`javascript
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
`

$3

`javascript
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