@arcanewizards/artnet 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# `@arcanewizards/artnet`
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@arcanewizards/artnet)
|
|
4
|
+
|
|
5
|
+
Art-Net timecode transport for Node.js applications.
|
|
6
|
+
|
|
7
|
+
This package exposes a small UDP-based API for sending and receiving Art-Net timecode packets and shares network-target configuration with `@arcanewizards/net-utils`.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
pnpm add @arcanewizards/artnet
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## API
|
|
16
|
+
|
|
17
|
+
`createArtnet(config)` returns an `ArtNet` instance with the following contract:
|
|
18
|
+
|
|
19
|
+
- `connect(): Promise<void>`
|
|
20
|
+
Opens the underlying UDP sockets for the configured mode.
|
|
21
|
+
- `sendTimecode(mode, timeMillis): Promise<void>`
|
|
22
|
+
Sends one Art-Net timecode packet. Calling this before `connect()` rejects. Negative `timeMillis` values are ignored because Art-Net timecode does not support negative positions.
|
|
23
|
+
- `on(event, listener)`
|
|
24
|
+
- `addListener(event, listener)`
|
|
25
|
+
- `removeListener(event, listener)`
|
|
26
|
+
Standard event-emitter style listeners.
|
|
27
|
+
- `destroy(): void`
|
|
28
|
+
Closes open sockets and emits the `destroy` event.
|
|
29
|
+
|
|
30
|
+
Supported events:
|
|
31
|
+
|
|
32
|
+
- `timecode`
|
|
33
|
+
Fired when a valid inbound Art-Net timecode packet is received.
|
|
34
|
+
- `error`
|
|
35
|
+
Fired when the instance encounters a socket or send error.
|
|
36
|
+
- `destroy`
|
|
37
|
+
Fired when `destroy()` is called.
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { createArtnet } from '@arcanewizards/artnet';
|
|
43
|
+
|
|
44
|
+
const artnet = createArtnet({
|
|
45
|
+
type: 'interface',
|
|
46
|
+
interface: 'en0',
|
|
47
|
+
mode: 'both',
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
artnet.on('timecode', (event) => {
|
|
51
|
+
console.log(
|
|
52
|
+
`Received ${event.mode} ${event.hours}:${event.minutes}:${event.seconds}:${event.frame} from ${event.host}:${event.port}`,
|
|
53
|
+
);
|
|
54
|
+
console.log(`Position in milliseconds: ${event.timeMillis}`);
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
artnet.on('error', (error) => {
|
|
58
|
+
console.error('Art-Net error', error);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
await artnet.connect();
|
|
62
|
+
|
|
63
|
+
const positionMillis = 12_345;
|
|
64
|
+
|
|
65
|
+
await artnet.sendTimecode('EBU', positionMillis);
|
|
66
|
+
|
|
67
|
+
artnet.destroy();
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
In the example above, `sendTimecode('EBU', 12_345)` encodes the position as 25 fps timecode. A receiving listener will not receive the timecode in the same precision,
|
|
71
|
+
as it will be decomposed into hours, minutes, seconds and frames.
|
|
72
|
+
|
|
73
|
+
## Timecode Types
|
|
74
|
+
|
|
75
|
+
### `ArtNetTimecode`
|
|
76
|
+
|
|
77
|
+
Represents a single Art-Net timecode value:
|
|
78
|
+
|
|
79
|
+
- `hours: number`
|
|
80
|
+
- `minutes: number`
|
|
81
|
+
- `seconds: number`
|
|
82
|
+
- `frame: number`
|
|
83
|
+
- `mode: TimecodeMode`
|
|
84
|
+
One of `FILM`, `EBU`, `DF`, or `SMPTE`.
|
|
85
|
+
- `timeMillis: number`
|
|
86
|
+
The same position converted to milliseconds by this package. For non-drop-frame modes this is a direct fps-based conversion. For `DF`, the package applies drop-frame math when converting between frame fields and milliseconds.
|
|
87
|
+
|
|
88
|
+
### `ArtNetTimecodeEvent`
|
|
89
|
+
|
|
90
|
+
Extends `ArtNetTimecode` with source-network metadata for inbound packets:
|
|
91
|
+
|
|
92
|
+
- `host: string`
|
|
93
|
+
Source IP address of the packet.
|
|
94
|
+
- `port: number`
|
|
95
|
+
Source UDP port of the packet.
|
|
96
|
+
|
|
97
|
+
That means a `timecode` listener receives both the interpreted timecode and where it came from on the network, which is useful when monitoring multiple Art-Net sources.
|
|
98
|
+
|
|
99
|
+
## Connection Modes
|
|
100
|
+
|
|
101
|
+
- `send`
|
|
102
|
+
Broadcasts Art-Net timecode packets.
|
|
103
|
+
- `receive`
|
|
104
|
+
Listens for inbound Art-Net timecode packets.
|
|
105
|
+
- `both`
|
|
106
|
+
Opens both paths on the same instance.
|
|
107
|
+
|
|
108
|
+
Targets follow the shared `ConnectionConfig` shape:
|
|
109
|
+
|
|
110
|
+
- `{ type: 'host', host: '192.168.1.50', port?: number }`
|
|
111
|
+
- `{ type: 'interface', interface: 'en0', port?: number }`
|
|
112
|
+
|
|
113
|
+
When sending through an interface target, the package resolves the interface broadcast address automatically.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcanewizards/artnet",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"@arcanewizards/typescript-config": "^0.0.0"
|
|
37
37
|
},
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"@arcanewizards/net-utils": "^0.1.
|
|
39
|
+
"@arcanewizards/net-utils": "^0.1.2"
|
|
40
40
|
},
|
|
41
41
|
"scripts": {
|
|
42
42
|
"build": "rm -rf dist && tsup && check-export-map",
|