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
    • .in(port, [address], [type]) ⇒ Receiver
    • .out(port, [address], [type]) ⇒ Transmitter
  • inner
    • ~Receiver ⇐ EventEmitter
      • .config : Object
      • .close() ⇒ Receiver
      • "error" (err)
      • "ready"
      • "message" (command, data)
      • "goto" (cue, exec, [fade])
      • "pause" (exec)
      • "resume" (exec)
      • "fader" (position, exec, [fade])
      • "off" (exec)
    • ~Transmitter ⇐ EventEmitter
      • .config : Object
      • .send(command, data) ⇒ Transmitter
      • .goto(cue, [exec], [fade]) ⇒ Transmitter
      • .pause([exec]) ⇒ Transmitter
      • .resume([exec]) ⇒ Transmitter
      • .fader(position, [exec], [fade]) ⇒ Transmitter
      • .fire(macro) ⇒ Transmitter
      • .off([exec]) ⇒ Transmitter
      • .close() ⇒ Transmitter
      • "error" (err)
      • "ready"

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 ⇐ EventEmitter
  • .config : Object
  • .close() ⇒ Receiver
  • "error" (err)
  • "ready"
  • "message" (command, data)
  • "goto" (cue, exec, [fade])
  • "pause" (exec)
  • "resume" (exec)
  • "fader" (position, exec, [fade])
  • "off" (exec)

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 ⇐ EventEmitter
  • .config : Object
  • .send(command, data) ⇒ Transmitter
  • .goto(cue, [exec], [fade]) ⇒ Transmitter
  • .pause([exec]) ⇒ Transmitter
  • .resume([exec]) ⇒ Transmitter
  • .fader(position, [exec], [fade]) ⇒ Transmitter
  • .fire(macro) ⇒ Transmitter
  • .off([exec]) ⇒ Transmitter
  • .close() ⇒ Transmitter
  • "error" (err)
  • "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:

• Error

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:

• Error

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:

• Error

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:

• Error

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:

• Error

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:

• Error

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:

• Error

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 <[e-mail]>