Node.js bindings for libcec - control CEC devices over HDMI
npm install node-libcecNode.js bindings for libcec - control CEC (Consumer Electronics Control) devices over HDMI.
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.
`bash`
npm install node-libcec
`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();
`
#### 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()
- - DisconnectpingAdapter()
- - Check if adapter is responsivegetAdapterVendorId()
- - Get USB vendor IDgetAdapterProductId()
- - Get USB product IDgetLibInfo()
- - Get libcec version info
#### Device Discovery
- getActiveDevices() - Get array of active logical addressespollDevice(address)
- - Check if device existsisActiveDevice(address)
- - Check if device is activeisActiveDeviceType(type)
- - Check if device type is activegetActiveSource()
- - Get current active source addressisActiveSource(address)
- - Check if device is active sourceisLibCECActiveSource()
- - Check if this adapter is active source
#### Device Information
- getDeviceOSDName(address) - Get device namegetDeviceVendorId(address)
- - Get vendor IDgetDevicePhysicalAddress(address)
- - Get physical addressgetDevicePowerStatus(address)
- - Get power statusgetDeviceCecVersion(address)
- - Get CEC versiongetDeviceMenuLanguage(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 sourcesetInactiveView()
- - Set this adapter as inactive
#### Audio Control
- volumeUp(sendRelease?) - Increase volumevolumeDown(sendRelease?)
- - Decrease volumemuteAudio()
- - Mute audioaudioToggleMute()
- - Toggle muteaudioStatus()
- - Get audio status
#### Commands
- transmit(command) - Send raw CEC commandsendKeypress(destination, keycode, wait?)
- - Send remote keypresssendKeyRelease(destination, wait?)
- - Send key releasesetOSDString(address, duration, message)
- - Display message on device
#### Address Configuration
- setLogicalAddress(address?) - Set logical addresssetPhysicalAddress(address)
- - Set physical addresssetHDMIPort(baseDevice, port)
- - Set HDMI portgetLogicalAddresses()
- - Get controlled logical addresses
#### Configuration
- getCurrentConfiguration() - Get current config objectsetConfiguration(config)
- - Update configurationrescanActiveDevices()
- - Rescan CEC bus for devicesdisableCallbacks()
- - Disable event callbacks
`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
`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';
See the examples directory for more usage patterns:
- basic.js - Simple device discovery and event handlingadvanced.js` - Interactive CLI with full feature demonstration
-
| Platform | Status | Notes |
|----------|--------|-------|
| Linux | Supported | Requires libcec-dev |
| macOS | Supported | Requires Homebrew libcec |
| Windows | Supported | Requires Pulse-Eight SDK |
- Node.js >= 18.0.0
- libcec system library
- A CEC-compatible USB adapter (e.g., Pulse-Eight USB-CEC)
MIT