node-libcec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fajitacat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# node-libcec
+
+Node.js bindings for [libcec](https://github.com/Pulse-Eight/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](https://www.pulse-eight.com/downloads).
+
+## Installation
+
+```bash
+npm install node-libcec
+```
+
+## Quick Start
+
+```javascript
+const { CECAdapter, LogicalAddress, DeviceType } = require('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
+
+```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
+
+#### Device Discovery
+
+- `getActiveDevices()` - Get array of active logical addresses
+- `pollDevice(address)` - Check if device exists
+- `isActiveDevice(address)` - Check if device is active
+- `getActiveSource()` - Get current active source address
+
+#### 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
+
+### Events
+
+```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
+```
+
+### Constants
+
+```javascript
+const {
+  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
+  AlertType         // SERVICE_DEVICE, CONNECTION_LOST, etc.
+} = require('node-libcec');
+```
+
+## Examples
+
+See the [examples](./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

package/binding.gyp

@@ -0,0 +1,62 @@
+{
+  "targets": [
+    {
+      "target_name": "cec",
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "sources": [
+        "src/native/cec_addon.cc",
+        "src/native/cec_adapter.cc",
+        "src/native/cec_callbacks.cc"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "/usr/include",
+        "/usr/local/include"
+      ],
+      "libraries": [
+        "-lcec"
+      ],
+      "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
+      "conditions": [
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "MACOSX_DEPLOYMENT_TARGET": "10.15"
+          },
+          "include_dirs": [
+            "/usr/local/include",
+            "/opt/homebrew/include"
+          ],
+          "libraries": [
+            "-L/usr/local/lib",
+            "-L/opt/homebrew/lib"
+          ]
+        }],
+        ["OS=='linux'", {
+          "cflags_cc": [
+            "-std=c++17",
+            "-fexceptions"
+          ],
+          "include_dirs": [
+            "/usr/include/libcec"
+          ]
+        }],
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1
+            }
+          },
+          "include_dirs": [
+            "C:/Program Files (x86)/Pulse-Eight/USB-CEC Adapter/include"
+          ],
+          "libraries": [
+            "-lC:/Program Files (x86)/Pulse-Eight/USB-CEC Adapter/cec.lib"
+          ]
+        }]
+      ]
+    }
+  ]
+}

package/lib/constants.js

@@ -0,0 +1,275 @@
+/**
+ * CEC Logical Addresses
+ */
+const LogicalAddress = {
+  TV: 0,
+  RECORDING_DEVICE_1: 1,
+  RECORDING_DEVICE_2: 2,
+  TUNER_1: 3,
+  PLAYBACK_DEVICE_1: 4,
+  AUDIO_SYSTEM: 5,
+  TUNER_2: 6,
+  TUNER_3: 7,
+  PLAYBACK_DEVICE_2: 8,
+  RECORDING_DEVICE_3: 9,
+  TUNER_4: 10,
+  PLAYBACK_DEVICE_3: 11,
+  RESERVED_1: 12,
+  RESERVED_2: 13,
+  FREE_USE: 14,
+  BROADCAST: 15,
+  UNKNOWN: 15
+};
+
+/**
+ * CEC Device Types
+ */
+const DeviceType = {
+  TV: 0,
+  RECORDING_DEVICE: 1,
+  RESERVED: 2,
+  TUNER: 3,
+  PLAYBACK_DEVICE: 4,
+  AUDIO_SYSTEM: 5
+};
+
+/**
+ * CEC Power Status
+ */
+const PowerStatus = {
+  ON: 0x00,
+  STANDBY: 0x01,
+  IN_TRANSITION_STANDBY_TO_ON: 0x02,
+  IN_TRANSITION_ON_TO_STANDBY: 0x03,
+  UNKNOWN: 0x99
+};
+
+/**
+ * CEC Opcodes
+ */
+const Opcode = {
+  ACTIVE_SOURCE: 0x82,
+  IMAGE_VIEW_ON: 0x04,
+  TEXT_VIEW_ON: 0x0D,
+  INACTIVE_SOURCE: 0x9D,
+  REQUEST_ACTIVE_SOURCE: 0x85,
+  ROUTING_CHANGE: 0x80,
+  ROUTING_INFORMATION: 0x81,
+  SET_STREAM_PATH: 0x86,
+  STANDBY: 0x36,
+  RECORD_OFF: 0x0B,
+  RECORD_ON: 0x09,
+  RECORD_STATUS: 0x0A,
+  RECORD_TV_SCREEN: 0x0F,
+  CLEAR_ANALOGUE_TIMER: 0x33,
+  CLEAR_DIGITAL_TIMER: 0x99,
+  CLEAR_EXTERNAL_TIMER: 0xA1,
+  SET_ANALOGUE_TIMER: 0x34,
+  SET_DIGITAL_TIMER: 0x97,
+  SET_EXTERNAL_TIMER: 0xA2,
+  SET_TIMER_PROGRAM_TITLE: 0x67,
+  TIMER_CLEARED_STATUS: 0x43,
+  TIMER_STATUS: 0x35,
+  CEC_VERSION: 0x9E,
+  GET_CEC_VERSION: 0x9F,
+  GIVE_PHYSICAL_ADDRESS: 0x83,
+  GET_MENU_LANGUAGE: 0x91,
+  REPORT_PHYSICAL_ADDRESS: 0x84,
+  SET_MENU_LANGUAGE: 0x32,
+  DECK_CONTROL: 0x42,
+  DECK_STATUS: 0x1B,
+  GIVE_DECK_STATUS: 0x1A,
+  PLAY: 0x41,
+  GIVE_TUNER_DEVICE_STATUS: 0x08,
+  SELECT_ANALOGUE_SERVICE: 0x92,
+  SELECT_DIGITAL_SERVICE: 0x93,
+  TUNER_DEVICE_STATUS: 0x07,
+  TUNER_STEP_DECREMENT: 0x06,
+  TUNER_STEP_INCREMENT: 0x05,
+  DEVICE_VENDOR_ID: 0x87,
+  GIVE_DEVICE_VENDOR_ID: 0x8C,
+  VENDOR_COMMAND: 0x89,
+  VENDOR_COMMAND_WITH_ID: 0xA0,
+  VENDOR_REMOTE_BUTTON_DOWN: 0x8A,
+  VENDOR_REMOTE_BUTTON_UP: 0x8B,
+  SET_OSD_STRING: 0x64,
+  GIVE_OSD_NAME: 0x46,
+  SET_OSD_NAME: 0x47,
+  MENU_REQUEST: 0x8D,
+  MENU_STATUS: 0x8E,
+  USER_CONTROL_PRESSED: 0x44,
+  USER_CONTROL_RELEASE: 0x45,
+  GIVE_DEVICE_POWER_STATUS: 0x8F,
+  REPORT_POWER_STATUS: 0x90,
+  FEATURE_ABORT: 0x00,
+  ABORT: 0xFF,
+  GIVE_AUDIO_STATUS: 0x71,
+  GIVE_SYSTEM_AUDIO_MODE_STATUS: 0x7D,
+  REPORT_AUDIO_STATUS: 0x7A,
+  SET_SYSTEM_AUDIO_MODE: 0x72,
+  SYSTEM_AUDIO_MODE_REQUEST: 0x70,
+  SYSTEM_AUDIO_MODE_STATUS: 0x7E,
+  SET_AUDIO_RATE: 0x9A,
+  REPORT_SHORT_AUDIO_DESCRIPTORS: 0xA3,
+  REQUEST_SHORT_AUDIO_DESCRIPTORS: 0xA4,
+  START_ARC: 0xC0,
+  REPORT_ARC_STARTED: 0xC1,
+  REPORT_ARC_ENDED: 0xC2,
+  REQUEST_ARC_START: 0xC3,
+  REQUEST_ARC_END: 0xC4,
+  END_ARC: 0xC5,
+  CDC: 0xF8,
+  NONE: 0xFD
+};
+
+/**
+ * CEC User Control Codes (Remote buttons)
+ */
+const UserControlCode = {
+  SELECT: 0x00,
+  UP: 0x01,
+  DOWN: 0x02,
+  LEFT: 0x03,
+  RIGHT: 0x04,
+  RIGHT_UP: 0x05,
+  RIGHT_DOWN: 0x06,
+  LEFT_UP: 0x07,
+  LEFT_DOWN: 0x08,
+  ROOT_MENU: 0x09,
+  SETUP_MENU: 0x0A,
+  CONTENTS_MENU: 0x0B,
+  FAVORITE_MENU: 0x0C,
+  EXIT: 0x0D,
+  TOP_MENU: 0x10,
+  DVD_MENU: 0x11,
+  NUMBER_ENTRY_MODE: 0x1D,
+  NUMBER11: 0x1E,
+  NUMBER12: 0x1F,
+  NUMBER0: 0x20,
+  NUMBER1: 0x21,
+  NUMBER2: 0x22,
+  NUMBER3: 0x23,
+  NUMBER4: 0x24,
+  NUMBER5: 0x25,
+  NUMBER6: 0x26,
+  NUMBER7: 0x27,
+  NUMBER8: 0x28,
+  NUMBER9: 0x29,
+  DOT: 0x2A,
+  ENTER: 0x2B,
+  CLEAR: 0x2C,
+  NEXT_FAVORITE: 0x2F,
+  CHANNEL_UP: 0x30,
+  CHANNEL_DOWN: 0x31,
+  PREVIOUS_CHANNEL: 0x32,
+  SOUND_SELECT: 0x33,
+  INPUT_SELECT: 0x34,
+  DISPLAY_INFORMATION: 0x35,
+  HELP: 0x36,
+  PAGE_UP: 0x37,
+  PAGE_DOWN: 0x38,
+  POWER: 0x40,
+  VOLUME_UP: 0x41,
+  VOLUME_DOWN: 0x42,
+  MUTE: 0x43,
+  PLAY: 0x44,
+  STOP: 0x45,
+  PAUSE: 0x46,
+  RECORD: 0x47,
+  REWIND: 0x48,
+  FAST_FORWARD: 0x49,
+  EJECT: 0x4A,
+  FORWARD: 0x4B,
+  BACKWARD: 0x4C,
+  STOP_RECORD: 0x4D,
+  PAUSE_RECORD: 0x4E,
+  ANGLE: 0x50,
+  SUB_PICTURE: 0x51,
+  VIDEO_ON_DEMAND: 0x52,
+  ELECTRONIC_PROGRAM_GUIDE: 0x53,
+  TIMER_PROGRAMMING: 0x54,
+  INITIAL_CONFIGURATION: 0x55,
+  SELECT_BROADCAST_TYPE: 0x56,
+  SELECT_SOUND_PRESENTATION: 0x57,
+  PLAY_FUNCTION: 0x60,
+  PAUSE_PLAY_FUNCTION: 0x61,
+  RECORD_FUNCTION: 0x62,
+  PAUSE_RECORD_FUNCTION: 0x63,
+  STOP_FUNCTION: 0x64,
+  MUTE_FUNCTION: 0x65,
+  RESTORE_VOLUME_FUNCTION: 0x66,
+  TUNE_FUNCTION: 0x67,
+  SELECT_MEDIA_FUNCTION: 0x68,
+  SELECT_AV_INPUT_FUNCTION: 0x69,
+  SELECT_AUDIO_INPUT_FUNCTION: 0x6A,
+  POWER_TOGGLE_FUNCTION: 0x6B,
+  POWER_OFF_FUNCTION: 0x6C,
+  POWER_ON_FUNCTION: 0x6D,
+  F1_BLUE: 0x71,
+  F2_RED: 0x72,
+  F3_GREEN: 0x73,
+  F4_YELLOW: 0x74,
+  F5: 0x75,
+  DATA: 0x76,
+  AN_RETURN: 0x91,
+  AN_CHANNELS_LIST: 0x96,
+  UNKNOWN: 0xFF
+};
+
+/**
+ * CEC Log Level
+ */
+const LogLevel = {
+  ERROR: 1,
+  WARNING: 2,
+  NOTICE: 4,
+  TRAFFIC: 8,
+  DEBUG: 16,
+  ALL: 31
+};
+
+/**
+ * CEC Display Control (for OSD strings)
+ */
+const DisplayControl = {
+  DISPLAY_FOR_DEFAULT_TIME: 0x00,
+  DISPLAY_UNTIL_CLEARED: 0x40,
+  CLEAR_PREVIOUS_MESSAGE: 0x80,
+  RESERVED_FOR_FUTURE_USE: 0xC0
+};
+
+/**
+ * CEC Version
+ */
+const Version = {
+  UNKNOWN: 0x00,
+  V1_2: 0x01,
+  V1_2A: 0x02,
+  V1_3: 0x03,
+  V1_3A: 0x04,
+  V1_4: 0x05,
+  V2_0: 0x06
+};
+
+/**
+ * Alert Types
+ */
+const AlertType = {
+  SERVICE_DEVICE: 1,
+  CONNECTION_LOST: 2,
+  PERMISSION_ERROR: 3,
+  PORT_BUSY: 4,
+  PHYSICAL_ADDRESS_ERROR: 5
+};
+
+module.exports = {
+  LogicalAddress,
+  DeviceType,
+  PowerStatus,
+  Opcode,
+  UserControlCode,
+  LogLevel,
+  DisplayControl,
+  Version,
+  AlertType
+};