{"id":16564938,"url":"https://github.com/k-yle/sacn","last_synced_at":"2025-04-06T10:10:18.443Z","repository":{"id":35146104,"uuid":"212753202","full_name":"k-yle/sACN","owner":"k-yle","description":"💡 🎭 Send \u0026 Receive sACN data (DMX over IP) in node.js","archived":false,"fork":false,"pushed_at":"2024-11-15T07:47:56.000Z","size":3087,"stargazers_count":37,"open_issues_count":3,"forks_count":13,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-30T09:05:44.530Z","etag":null,"topics":["artnet","dmx","dmx512","dmxking","e131","e133","enttec","lighting","rdm","sacn","stage-lighting"],"latest_commit_sha":null,"homepage":"https://npm.im/sacn","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-yle.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-04T06:51:49.000Z","updated_at":"2025-03-24T11:04:02.000Z","dependencies_parsed_at":"2024-03-11T09:30:19.384Z","dependency_job_id":"bce918a7-ded0-46cf-80e5-aea7f2428650","html_url":"https://github.com/k-yle/sACN","commit_stats":{"total_commits":50,"total_committers":6,"mean_commits":8.333333333333334,"dds":0.56,"last_synced_commit":"80990ca85db4201c68853b5f750104f67ff0a015"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-yle%2FsACN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-yle%2FsACN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-yle%2FsACN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-yle%2FsACN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-yle","download_url":"https://codeload.github.com/k-yle/sACN/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464197,"owners_count":20942969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artnet","dmx","dmx512","dmxking","e131","e133","enttec","lighting","rdm","sacn","stage-lighting"],"created_at":"2024-10-11T20:45:34.284Z","updated_at":"2025-04-06T10:10:18.404Z","avatar_url":"https://github.com/k-yle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sACN receiver \u0026 sender in node.js\n\n[![Build Status](https://github.com/k-yle/sACN/workflows/Build%20and%20Test/badge.svg)](https://github.com/k-yle/sACN/actions)\n[![Coverage Status](https://coveralls.io/repos/github/k-yle/sACN/badge.svg?branch=main)](https://coveralls.io/github/k-yle/sACN?branch=main)\n[![npm version](https://badge.fury.io/js/sacn.svg)](https://badge.fury.io/js/sacn)\n[![npm](https://img.shields.io/npm/dt/sacn.svg)](https://www.npmjs.com/package/sacn)\n[![install size](https://packagephobia.com/badge?p=sacn)](https://packagephobia.com/result?p=sacn)\n\n💡 This module can receive [DMX](https://en.wikipedia.org/wiki/DMX512) data sent via [sACN](https://en.wikipedia.org/wiki/E1.31) from professional lighting consoles (e.g. [ETC](https://www.etcconnect.com/), [Onyx](https://obsidiancontrol.com/)).\n\n🎭 It can also send data to DMX fixtures that support sACN, e.g. LED lights, smoke machines, etc.\n\n## Install\n\n```bash\nnpm install sacn\n```\n\n## Usage - Receiver\n\n🔦 Sending [RDM](\u003chttps://en.wikipedia.org/wiki/RDM_(lighting)\u003e) data to fixtures is not implemented yet, see [issue #1](https://github.com/k-yle/sACN/issues/1).\n\n```js\nconst { Receiver } = require('sacn');\n\nconst sACN = new Receiver({\n  universes: [1, 2],\n  // see table 1 below for all options\n});\n\nsACN.on('packet', (packet) =\u003e {\n  console.log('got dmx data:', packet.payload);\n  // see table 2 below for all packet properties\n});\n\nsACN.on('PacketCorruption', (err) =\u003e {\n  // trigged if a corrupted packet is received\n});\n\nsACN.on('PacketOutOfOrder', (err) =\u003e {\n  // trigged if a packet is received out of order\n});\n\n/* advanced usage below */\n\nsACN.on('error', (err) =\u003e {\n  // trigged if there is an internal error (e.g. the supplied `iface` does not exist)\n});\n\n// start listening to a new universe (universe 3 in this example)\nsACN.addUniverse(3);\n\n// stop listening to a universe 1\nsACN.removeUniverse(1);\n\n// close all connections; terminate the receiver\nsACN.close();\n\nsACN.universes; // is a list of the universes being listened to\n```\n\n### Table 1 - Options for Receiver\n\n| Name        | Type       | Purpose                                                                                                                                     | Default |\n| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `universes` | `number[]` | Required. List of universes to listen to. Must be within 1-63999                                                                            | `[]`    |\n| `port`      | `number`   | Optional. The multicast port to use. All professional consoles broadcast to the default port.                                               | `5568`  |\n| `iface`     | `string`   | Optional. If the computer is connected to multiple networks, specify which network adaptor to use by using this computer's local IP address | `null`  |\n| `reuseAddr` | `boolean`  | Optional. Allow multiple programs on your computer to listen to the same sACN universe.                                                     | `false` |\n\n### Table 2 - Packet properties\n\n```js\n{\n  \"sourceName\": \"Onyx\", // controller that sent the packet\n  \"sourceAddress\": \"192.168.1.69\", // ip address of the controller\n  \"universe\": 1, // DMX universe\n  \"sequence\": 172, // packets are numbered 0-255 to keep them in order\n  \"priority\": 100, // 0-200. used if multiple controllers send to the same universe\n  \"payload\": { // an object with the percentage values of DMX channels 1-512\n    1: 100,\n    2: 50,\n    3: 0\n  },\n\n  /* there are more low-level properties which most\n     users won't need, see the ./src/packet.ts file */\n}\n```\n\n## Usage - Sender\n\n```js\nconst { Sender } = require('sacn');\n\nconst sACNServer = new Sender({\n  universe: 1,\n  // see table 3 below for all options\n});\n\nasync function main() {\n  await sACNServer.send({\n    payload: {\n      // Required. An object with the percentages (0-100) for each DMX channel.\n      // You can use 0-255 instead of 0-100 by setting `useRawDmxValues: true`\n      // per packet, or in the `defaultPacketOptions`.\n      1: 100,\n      2: 50,\n      3: 0,\n    },\n    sourceName: \"My NodeJS app\", // optional. LED lights will use this as the name of the source lighting console.\n    priority: 100, // optional. value between 0-200, in case there are other consoles broadcasting to the same universe\n  });\n\n  sACNServer.close(); // terminate the server when your app is about to exit.\n}\n\nmain(); // wrapped in a main() function so that we can `await` the promise\n```\n\n### Table 3 - Options for Sender\n\n| Name                   | Type      | Purpose                                                                                                    | Default |\n| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- |\n| `universe`             | `number`  | Required. The universe to send to. Must be within 1-63999                                                  |         |\n| `port`                 | `number`  | Optional. The multicast port to use. All professional consoles broadcast to the default port.              | `5568`  |\n| `reuseAddr`            | `boolean` | Optional. Allow multiple programs on your computer to send to the same sACN universe.                      |\n| `defaultPacketOptions` | `object`  | Optional. You can specify options like `sourceName`, `cid`, `priority` and `useRawDmxValues` here instead of on every packet |\n| `iface`                | `string`  | Optional. Specifies the IPv4 address of the network interface/card to use.                                 | OS default interface (=active internet connection)\n| `minRefreshRate`       | `number`  | Optional. How often the data should be re-sent (*in Hertz/Hz*), even if it hasn't changed. By default data will only be sent once (equivilant of setting `refreshRate: 0`). To re-send data 5 times per second (`5Hz`), set `refreshRate: 5`. This is equivilant to `200ms`.                                 | `0`\n| `useUnicastDestination`| `string`  | Optional. Setting this attribute to an IPv4 address will cause data to be sent directly to that device, instead of broadcasting to the whole LAN. |\n\n# Contribute\n\n```bash\nnpm run build # compile typescript\nnpm test # run tests\n```\n\n# Network Requirements\n\n- [x] Multicast must be enabled\u003csup id=\"footnote-source1\"\u003e[1](#footnote1)\u003c/sup\u003e. sACN uses port `5568` on `239.255.x.x`\n- [x] Network infrastructure that supports at least 100Mbps (100BaseT)\n\n# Protocol Docs\n\nThe Architecture for Control Networks (ACN) and derived protocols are created by the Entertainment Services and Technology Association.\n\n- sACN is defined in [ANSI E1.31](./docs/E1.31-2018.pdf)\n- RDMNet is defined in [ANSI E1.33](./docs/E1.33-2019.pdf)\n\n---\n\n\u003csmall id=\"footnote1\"\u003e\n\n1\u0026shy;. Unicast is also supported by default, but this is not how sACN normally works. See [_Table 3_](#table-3---options-for-sender) for how to send data directly to a unicast address. [↩](#footnote-source1)\n\n\u003c/small\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-yle%2Fsacn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-yle%2Fsacn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-yle%2Fsacn/lists"}