mamsc
v1.1.0
Published
MIDI Schow Control over Ethernet for MA lighting
Downloads
30
Maintainers
Readme
mamsc
MIDI Schow Control over Ethernet for MA lighting
This is an implementation of the MIDI Show Control protocol used by MA lighting. While initially developed for the dot2 lineup it also works for grandMA with some slight differences which are documented below.
Limitations
MIDI Show Control inherited some of the limitations of MIDI. While the protocol
is specific to MA lighting control equipment it still has some limitations.
Executor numbers for example are 7 bit
. This means that the highest executor
value available is 127
. Macro numbers can in fact be 8 bit
.
If you are using dot2 you will be limited to the main executor and executors on
the first page. Additionally this implementation is limited to the command
format: All
.
Note
While this implementation was initially written for the dot2, it also works for
the grandMA. There are a few differences though. Executor 0
is used for the
main executor on the dot2. If you are using grandMA, executor 0
is actually
the first executor. So numbering of the executors for the grandMA is zero based.
Another important thing to note is that this implementation swaps the executor
and page numbers. While you see fader 1.2
(page 1, exec 2) being sent from the
console it will arive as 2.1
. The reason for this is that the page number is
optional or even useless on dot2 and so you can just drop the fraction.
Console/onPC configuration
You are required to set the MIDI Show Control mode to Ethernet
, exec to
Exec.Page
and the command format to All
. The rest of the configuration
depends on your needs. In and out ports need to be between 6000
and 6100
as per the MA documentation and shouldn't be the same to prevent loops.
MIDI channels are ignored when mode is set to Ethernet
.
Installation
$ npm install mamsc --save
Upgrading from v0.x to v1.x
This upgrade might have breaking changes for you since there has been a few API
changes.
In particular exec and cue numbers are now received and transmitted as Strings
rather then Numbers. This change has been made to fix an issue with page
numbers ending in zero which had been truncated before. Also cue numbers are
now standardized. Parameter positions haven't changed, only types.
If you are using the library for dot2 only then this fix is not needed for you
necessarily.
Unless you are dependent on Numbers in your implementation this upgrade won't
break your code. Numbers can still be send and will be converted internally.
API Reference
- mamsc
- static
- inner
mamsc.in(port, [address], [type]) ⇒ Receiver
Create a new MIDI Show Control over Ethernet Receiver.
The port needs to be between 6000
and 6100
as per the documentation. If
no address is defined, the socket is bound to all interfaces.
Kind: static method of mamsc
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| port | Number | | Port to listen for incoming messages on (needs to be between 6000
and 6100
) |
| [address] | String | '0.0.0.0' | Address to listen for incoming messages on |
| [type] | String | 'udp4' | The socket family: Either 'udp4'
or 'udp6'
|
Example
// Create a new receiver and receive MSC on port 6004 on all interfaces
const receiver = require('mamsc').in(6004)
mamsc.out(port, [address], [type]) ⇒ Transmitter
Create a new MIDI Show Control over Ethernet Transmitter.
The port needs to be between 6000
and 6100
as per the documentation. If
no address is defined, we brodcast to the local network.
Kind: static method of mamsc
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| port | Number | | Destination port (needs to be between 6000
and 6100
) |
| [address] | String | '255.255.255.255' | Destination hostname or IP address |
| [type] | String | 'udp4' | The socket family: Either 'udp4'
or 'udp6'
|
Example
// Create a new transmitter and brodcast MSC to port 6005 on the local network
const transmitter = require('mamsc').out(6005)
mamsc~Receiver ⇐ EventEmitter
MIDI Show Control over Ethernet Receiver
Kind: inner class of mamsc
Extends: EventEmitter
Emits: error, ready, message, goto, pause, resume, fader, off
receiver.config : Object
Kind: instance property of Receiver
Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [deviceId] | Number | 1 | Set this to a value between 0
and 111
to only listen for messages received for this device ID. We'll still react on messages send to everyone. |
| [groupId] | Number | 1 | Set this to a value between 1
and 15
to only listen for messages received for this group ID. We'll still react on messages send to everyone. |
receiver.close() ⇒ Receiver
Close the underlying socket and stop listening for incoming messages.
Kind: instance method of Receiver
"error" (err)
Emitted whenever an error accurs within the receiver. This could be either socket errors or errors from the protocol parser.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | err | Error | The error which occurred |
"ready"
Emitted when the underlying socket is created and the receiver starts listening for incomming messages.
Kind: event emitted by Receiver
"message" (command, data)
This is a general message event if you want to listen for all commands.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | command | String | The type of message received | | data | Object | Depends on the message type. See the individual events for details |
Example
// Create a new receiver and list for MSC on port 6001
const msc = require('mamsc').in(6001)
// Listen for all but the error events and log them to the console
msc.on('message', (command, data) => { console.log(command, data) })
"goto" (cue, exec, [fade])
Emitted if a Goto command is executed.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | cue | String | Cue Number | | exec | String | Executor Number | | [fade] | Number | Optional fade time |
"pause" (exec)
Emitted if a cue is paused.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | exec | String | Executor Number |
"resume" (exec)
Emitted if a paused cue is continued.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | exec | String | Executor Number |
"fader" (position, exec, [fade])
Emitted if a fader changed its position. The console only transmits the position of some faders.
Kind: event emitted by Receiver
| Param | Type | Description |
| --- | --- | --- |
| position | Object | |
| position.value | Number | Position value [0..128²-1]
|
| position.percent | Number | Position of the fader as percentage |
| exec | String | Executor Number |
| [fade] | Number | Optional fade time |
"off" (exec)
Emitted if a executor is switched off.
Kind: event emitted by Receiver
| Param | Type | Description | | --- | --- | --- | | exec | String | Executor Number |
mamsc~Transmitter ⇐ EventEmitter
MIDI Show Control over Ethernet Transmitter
Kind: inner class of mamsc
Extends: EventEmitter
Emits: error, ready
transmitter.config : Object
Kind: instance property of Transmitter
Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [deviceId] | Number | 1 | Set this to a value between 0
and 111
to restrict messages to a device and set sendTo to 'device'
|
| [groupId] | Number | 1 | Set this to a value between 1
and 15
to restrict messages to a group and set sendTo to 'group'
|
| [sendTo] | String | 'all' | If you want to restrict who should react on messages send you can set this to either 'device'
and set the deviceId or 'group'
and set the groupId accordingly. By default it is set to 'all'
so everyone will react on messages. |
transmitter.send(command, data) ⇒ Transmitter
Sends one of the defined commands by name. The command name is identical to the function name. Lookup the parameters for the command at each function definition.
Kind: instance method of Transmitter
Throws:
| Param | Type | Description | | --- | --- | --- | | command | String | Command to be send | | data | Object | Parameters for the command |
Example
// Create a new transmitter and brodcast MSC to port 6100
const msc = require('mamsc').out(6100)
// Set fader position of executor 12 on page 1 to 42%
msc.send('fader', { position: 42, exec: 12 })
// Goto cue Number 8.100 on the default executor with a fade time of 5 seconds
msc.send('goto', { cue: 8.100, fade: 5 })
transmitter.goto(cue, [exec], [fade]) ⇒ Transmitter
Goto a specific cue. If you don't define an executor then the main executor is assumed. An optional fade time can be defined in seconds.
Kind: instance method of Transmitter
Throws:
| Param | Type | Default | Description | | --- | --- | --- | --- | | cue | String | | Cue Number | | [exec] | String | main | Executor Number | | [fade] | Number | no fade | Optional fade time in seconds |
Example
// Create a new transmitter and send MSC to 10.6.7.2 port 6008
const msc = require('mamsc').out(6008, '10.6.7.2')
// Goto cue Number 4.000 on executor 7, page 1
msc.goto(4.000, 7.1)
transmitter.pause([exec]) ⇒ Transmitter
Pause an executor. If you don't define an executor then the main executor is assumed.
Kind: instance method of Transmitter
Throws:
| Param | Type | Default | Description | | --- | --- | --- | --- | | [exec] | String | main | Executor Number |
transmitter.resume([exec]) ⇒ Transmitter
Resume an executor. If you don't define an executor then the main executor is assumed.
Kind: instance method of Transmitter
Throws:
| Param | Type | Default | Description | | --- | --- | --- | --- | | [exec] | String | main | Executor Number |
transmitter.fader(position, [exec], [fade]) ⇒ Transmitter
Move a fader to a specific position. You can either set it by percentage
or using a value between 0
and 128²-1
. If you pass a Number, percentage
is used. If you don't define an executor then the main executor is
assumed. An optional fade time can be defined in seconds.
Kind: instance method of Transmitter
Throws:
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| position | Number | Object | | Pass a Number to set the position by percentage or an Object with one of the following properties: |
| position.percent | Number | | Position of the fader as percentage |
| position.value | Number | | Position of the fader using a value between 0
and 128²-1
|
| [exec] | String | main | Executor Number |
| [fade] | Number | no fade | Optional fade time |
Example
// Create a new transmitter and bordcast MSC to port 6004 on network 10.6.7.x
const msc = require('mamsc').out(6004, '10.6.7.255')
// Set fader position of executor 3 on page 1 to 50%
msc.fader(50, 3.1)
// Set fader position of executor 8 on page 1 to 50% with a fade time of 10 seconds
msc.fader({ value: 0x1fff }, 8, 10)
transmitter.fire(macro) ⇒ Transmitter
Fire a macro.
Kind: instance method of Transmitter
Throws:
| Param | Type | Description |
| --- | --- | --- |
| macro | Number | Macro number between 1
and 255
. |
transmitter.off([exec]) ⇒ Transmitter
Switch an executor off. If you don't define an executor then the main executor is assumed.
Kind: instance method of Transmitter
Throws:
| Param | Type | Default | Description | | --- | --- | --- | --- | | [exec] | String | main | Executor Number |
transmitter.close() ⇒ Transmitter
Close the underlying socket. After closing the socket no more messages can be send.
Kind: instance method of Transmitter
"error" (err)
Emitted whenever an error accurs within the transmitter. This is usually a socket error. User input errors are thrown and not emitted.
Kind: event emitted by Transmitter
| Param | Type | Description | | --- | --- | --- | | err | Error | The error which occurred |
"ready"
Emitted when the underlying socket is created and the transmitter is ready to send messages.
Kind: event emitted by Transmitter
License
Distributed under the MIT and GPL-3.0 licenses.
© 2018 Christian Volmering <[email protected]>