DMX Personality

Note that all multi-channel parameters are read big-endian. i.e. coarse setting followed by fine.

Parameters shown in italics are reserved but not currently implemented.

Universe

The MagicHD personality has been designed to fit within a single universe of DMX.

Block	Channels	Offset
Output layer	50	0
Text layer	33	50
reserved	17
Layer 1	42	100
reserved	8
Layer 2	42	150
reserved	8
Layer 3	42	200
reserved	8
Layer 4	42	250
reserved	8
Layer 5	42	300
reserved	8
Layer 6	42	350
reserved	8
Layer 7	42	400
reserved	8
Layer 8	42	450
reserved	8
spare	12

Output Layer

Parameter	Channels	Offset	Default	Type
Intensity	1	0	0	Colour scale
Position X	2	1	32768	Screen offset
Position Y	2	3	32768	Screen offset
Scale X	2	5	32768	Scale
Scale Y	2	7	32768	Scale
Rotation	2	9	32768	Angle
Mirror/flip	1	11	0	Mirror / flip
Red	1	12	255	Colour scale
Green	1	13	255	Colour scale
Blue	1	14	255	Colour scale
Colour effect	1	15	0	Colour effect
FX parameter R	1	16	0	Number or Colour Scale depending on effect
FX parameter G	1	17	0	Number or Colour Scale depending on effect
FX parameter B	1	18	0	Number or Colour Scale depending on effect
Mask folder	1	19	3	Number
Mask file	1	20	0	Number
Mask invert	1	21	0	Flag
Mask mirror/flip	1	22	0	Mirror / flip
Keystone A	2	23	0	Keystone
Keystone B	2	25	65535	Keystone
Keystone C	2	27	0	Keystone
Keystone D	2	29	0	Keystone
Keystone E	2	31	65535	Keystone
Keystone F	2	33	65535	Keystone
Keystone X	2	35	65535	Keystone
Keystone Y	2	37	0	Keystone
HUD control	1	39	0	HUD control bitmask
Audio Volume	1	40	255	Audio scale
Physical effect	1	41	0	Physical effect
Phys FX parameter 1	1	42	0	Number or Scroll Speed depending on effect
Phys FX parameter 2	1	43	0	Number or Scroll Speed depending on effect
Phys FX parameter 3	1	44	0	Number or Scroll Speed depending on effect
reserved	3	45
Control Function	1	48	0	Control Function (MagicHD Box only)
Control Enable	1	49	0	Control Enable (MagicHD Box only)

Text Layer

Parameter	Channels	Offset	Default	Type
Intensity	1	0	0	Colour scale
Position X	2	1	32768	Screen offset
Position Y	2	3	32768	Screen offset
Scale X	2	5	32768	Scale
Scale Y	2	7	32768	Scale
Rotation	2	9	32768	Angle
Red	1	11	255	Colour scale
Green	1	12	255	Colour scale
Blue	1	13	255	Colour scale
Background red	1	14	0	Colour scale
Background green	1	15	0	Colour scale
Background blue	1	16	0	Colour scale
Background transparency	1	17	192	Colour scale
Text folder	1	18	5	Number
Text file	1	19	0	Number
Font	1	20	0	Number
Text lines	1	21	1	Number
Scroll direction	1	22	0	Direction
Scroll speed	2	23	0	Speed factor
Loop	1	25	0	Text loop mode
Scroll char	2	26	10005	Scroll position
Scroll line	2	28	10005	Scroll position
Scroll time	2	30	0	Duration
Border	1	32	0	Number

Media Layers

Parameter	Channels	Offset	Default	Type
Intensity	1	0	0	Colour scale
xref:media-layers:media_layers.adoc#position[Position X>>	2	1	32768	<<_screen_offset,Screen offset]
xref:media-layers:media_layers.adoc#position[Position Y>>	2	3	32768	<<_screen_offset,Screen offset]
Scale X	2	5	32768	Scale
Scale Y	2	7	32768	Scale
Rotation	2	9	32768	Angle
Mirror/flip	1	11	0	Mirror / flip
Stretch	1	12	0	<<_layer_stretch_mode,Layer stretch mode]
Red	1	13	255	Colour scale
Green	1	14	255	Colour scale
Blue	1	15	255	Colour scale
Colour effect	1	16	0	Colour effect
FX parameter R	1	17	0	Number or Colour Scale depending on effect
FX parameter G	1	18	0	Number or Colour Scale depending on effect
FX parameter B	1	19	0	Number or Colour Scale depending on effect
Blend	1	20	0	Blend type
Folder	1	21	0	Number
File	1	22	1	Number
Start frame	3	23	0	Number
End frame	3	26	16777215	Number
Speed	2	29	39321	Speed factor
Play mode	1	31	2	Play mode
Transition	2	32	0	Transition type
Mask opacity	1	34	0	Colour scale
Mask folder	1	35	3	Number
Mask file	1	36	1	Number
Mask invert	1	37	0	Flag
Mask mirror/flip	1	38	0	Mirror / flip
Mask stretch	1	39	0	Layer stretch mode
Audio Gain	1	40	0	Audio scale
Audio Pan	1	41	128	Audio pan
Physical effect	1	42	0	Physical effect
Phys FX parameter 1	1	43	0	Number or Scroll Speed depending on effect
Phys FX parameter 2	1	44	0	Number or Scroll Speed depending on effect
Phys FX parameter 3	1	45	0	Number or Scroll Speed depending on effect

Parameter Types

The best way to understand the effect of parameters is to turn on the HUD, watch the corresponding arameter change as you turn an encoder wheel, and see the effect on the output.

Angle

Angles are specified by two consecutive DMX channels, with the values 0-65535 representing the range -180° to +179.995°. One bit is 0.0055°. 32768 is 0.0°. Positive rotation is clockwise.

Audio Pan

Audio pan controls stereo panning using a linear scale of 0-255 with 0 representing full left, 128 centre, and 255 full right. 128 is the default.

Audio Scale

Audio scale controls audio parameters using a linear scale with the values 0-255 representing the range 0 to 1.0.

Blend Type

When blending two layers together, the colour of each pixel in the resulting image is controlled by the blend setting.

Value	Effect	Notes
0	Normal	Layers are blended by their intensity.
1	Add Colour	The higher layer is added to the lower layer.
2	Subtract Colour	The higher layer is subtracted from the lower layer.
3	Max Colour	The result uses the highest value from each layer.

Value

Effect

Notes

Normal

Layers are blended by their intensity.

Add Colour

The higher layer is added to the lower layer.

Subtract Colour

The higher layer is subtracted from the lower layer.

Max Colour

The result uses the highest value from each layer.

Colour Effect

Colour effect is usually accompanied by up to 3 additional parameters called FX-R, FX-G and FX-B.

Value	Effect	Notes
0	None
1	B&W
2	RGB select	FX parameters are numbers, selecting the mapping for R,G and B colour channels as follows:
0	Black
1	R
2	G
3	B
4	Intensity⁽¹⁾
5	inverse R
6	inverse G
7	inverse B
8	inverse intensity⁽¹⁾
3	Posterise	FX parameters are numbers, selecting the number of colour steps for R,G and B:
0	1 step, i.e. 1 bit colour.
1
2	2 steps
…
255	255 steps, i.e. normal
4	Colourise	FX parameters are colour scale values, controlling colourisation of the basic B&W image.
5	Mask⁽²⁾	Use the layer as a mask. FX-R selects the mode:
0	Transparency = intensity⁽¹⁾, colour unchanged.
1	As 0, with inverted colour
2	Transparency = inverse intensity⁽¹⁾, colour unchanged
3	As 2, with inverted colour
4	Transparency comes from the media’s alpha channel. Opaque pixels become fixed colour.
FX-G	Hue	0-254	Hue⁽⁵⁾
255	White.
FX-B	Lightness	0 is black, whatever hue is chosen.
5	Transparency = intensity⁽¹⁾, colour as for 4⁽⁶⁾.
6	Transparency = inverse intensity⁽¹⁾, colour as for 4⁽⁶⁾.
6	Key⁽²⁾⁽³⁾	Chroma Key. FX parameters are colour scale values, specifying the colour to match. The matched colour is made transparent.
FX-R	Hue⁽⁵⁾.
FX-G	Selectivity	0	Narrow
255	Wide
FX-B	Transparency	0	Gradual
255	All transparent
7	Hue Offset⁽⁴⁾	FX-R controls the hue offset:
0	0°	No effect
128	180°	Turns red into cyan, yellow into blue etc.
255	360°	No effect
8	Hue Filter⁽⁴⁾	Apply a bandpass filter to the hue. Filtered out hue becomes black & white.
FX-R	Hue⁽⁵⁾.
FX-G	Selectivity	0	Narrow
255	Wide
FX-B	Fall-off	0	Triangle
255	Square
9	Invert	Invert RGB. Shortcut for RGB select with parameters (5,6,7).
10	Curve 1	Not implemented yet.
11	Curve 2	Not implemented yet.
12	Curve 3	Not implemented yet.

Value

Effect

Notes

None

B&W

RGB select

FX parameters are numbers, selecting the mapping for R,G and B colour channels as follows:

Black

Intensity⁽¹⁾

inverse R

inverse G

inverse B

inverse intensity⁽¹⁾

Posterise

FX parameters are numbers, selecting the number of colour steps for R,G and B:

1 step, i.e. 1 bit colour.

2 steps

…

255

255 steps, i.e. normal

Colourise

FX parameters are colour scale values, controlling colourisation of the basic B&W image.

Mask⁽²⁾

Use the layer as a mask. FX-R selects the mode:

Transparency = intensity⁽¹⁾, colour unchanged.

As 0, with inverted colour

Transparency = inverse intensity⁽¹⁾, colour unchanged

As 2, with inverted colour

Transparency comes from the media’s alpha channel. Opaque pixels become fixed colour.

FX-G

Hue

0-254

Hue⁽⁵⁾

255

White.

FX-B

Lightness

0 is black, whatever hue is chosen.

Transparency = intensity⁽¹⁾, colour as for 4⁽⁶⁾.

Transparency = inverse intensity⁽¹⁾, colour as for 4⁽⁶⁾.

Key⁽²⁾⁽³⁾

Chroma Key. FX parameters are colour scale values, specifying the colour to match. The matched colour is made transparent.

FX-R

Hue⁽⁵⁾.

FX-G

Selectivity

Narrow

255

Wide

FX-B

Transparency

Gradual

255

All transparent

Hue Offset⁽⁴⁾

FX-R controls the hue offset:

0°

No effect

128

180°

Turns red into cyan, yellow into blue etc.

255

360°

No effect

Hue Filter⁽⁴⁾

Apply a bandpass filter to the hue. Filtered out hue becomes black & white.

FX-R

Hue⁽⁵⁾.

FX-G

Selectivity

Narrow

255

Wide

FX-B

Fall-off

Triangle

255

Square

Invert

Invert RGB.

Shortcut for RGB select with parameters (5,6,7).

Curve 1

Not implemented yet.

Curve 2

Not implemented yet.

Curve 3

Not implemented yet.

(1) Intensity is the overall brightness of the image; effectively the black & white version of it.

(2) Not implemented in the output layer, because it is an inter-layer effect.

(3) The best way to understand this effect is to select some media in layer 1, then select the HSL image from folder 3 (masks) in layer 2, then play with the effect parameters.

(4) The best way to understand this effect is to select the HSL image from folder 3 (masks) then play with the effect parameters.

(5) Hue refers to the HSL colour model

(6) Leave Hue and Lightness at 0 for no colour, so that the mask just controls the transparency of the layer below.

Colour Scale

Colour, intensity, transparency etc. are specified by a linear scale with the values 0-255 representing the range 0 to 1.0.

Control Enable

This parameter must held at 255 while Control Function is programmed.

This parameter is only applicable to the MagicHD Box product.

Control Function

Any setting must be held for at least 5 seconds, with Control Enable enabled, before the corresponding function will happen.

Value	Function
0	No Function
1-10	Turn Off
11-20	Standby
21-30	Turn On
31-40	Reboot

This parameter is only applicable to the MagicHD Box product.

Direction

Direction (e.g. for scrolling) is encoded as follows:

Value	Direction	Notes
0	None	Stops scrolling but does not reset position
1	Left
2	Right
3	Up
4	Down
5	Char/Line	This mode allows text to be scrolled in X/Y simultaneously, to any position.
6	Top Left	Resets scroll position to top left and stays there

Duration

Linear scale with the values 0 to 65535 representing the range 0 to 10 seconds. Note that all 65536 values are mapped, but the resolution is only 1ms.

Value	Duration/ms
0-6	0
7-13	1
6554-6560	1000
65535	9999

Flag

Flags map the DMX value to a boolean value as follows:

Value	Meaning
0	False, off
1-255	True, on

Value

Meaning

False, off

1-255

True, on

HUD Control Bitmask

The HUD control channel is treated as a bitmask except for a few special values:

Bits	Parameter	Value
0-3	Layer	0-7	Media layers
		8	Text layer
		9	Output layer
		10+	none
4-5	Position	0	Off
		1	Left
		2	Centre
		3	Right
6-7	Unused
all		255	Grid overlay

Keystone

Linear scale with the values 0 to 65535 representing the range 0 to +1.0. The default value is 0.0 (0) or 1.0 (65535) depending on the corner.

Layer Stretch Mode

Value	Mode	Original Aspect Ratio	Notes
0	Stretch to fill screen	Preserved
1	Stretch to fill screen X	Preserved	Other dimension might exceed the target area and become clipped.
2	Stretch to fill screen Y	Preserved	Ditto
3	Stretch X and Y to fill screen	Lost
4	Stretch X & Y to layer 1	-	Match aspect ratio & size to layer 1
5	Stretch X & Y to layer 2	-	Match aspect ratio & size to layer 2
6	Stretch X & Y to layer 3	-	Match aspect ratio & size to layer 3
7	Stretch X & Y to layer 4	-	Match aspect ratio & size to layer 4

Mirror / Flip

Value	Effect	Notes
0	Normal
1	Horizontal flip
2	Vertical flip
3	H&V flip
4-5	Horizontal mirror	Reflected about vertical centre line
6-7	H Mirror & V flip
8,10	Vertical mirror	Reflected about the horizontal centre line
9,11	V mirror & H flip
12-15	H & V mirror	Horizontal and Vertical mirroring combined
16-255	-	Reserved

Mirroring is not available in all places a "Mirror/Flip" channel appears. In such cases just the first 4 options apply.

Number

The DMX channel value is used as sent, with no decoding.

Note that the media start and end frame parameters use 3 channels. Their range is therefore 0 to 16777215 (2²⁴-1). At a typical frame rate of 30 frames a second, the largest value corresponds to 155 hours, or nearly 6½ days. Although this might seem excessive, it does mean that points within a media file can be specified with frame accuracy regardless of length or speed.

Values greater than the number of frames in the clip are taken to mean ``the end''. i.e. a 200 frame clip will restart at 200 frames, rather than 6½ days later, if the end frame is left at the default of 16777215.

Physical Effect

Physical effect is usually accompanied by up to 3 additional parameters called FX-1, FX-2 and FX-3.

Value	Effect	Notes
0	None
1	Shake Gentle	FX-1	Horizontal amplitude	Range ±0.1 of screen width
FX-2	Vertical amplitude	Range ±0.1 of screen height
FX-3	Rotation amplitude	Range ±5°
2	Shake	FX-1	Horizontal amplitude	Range ±1 screen width
FX-2	Vertical amplitude	Range ±1 screen height
FX-3	Rotation amplitude	Range ±180°
3	Scroll	FX-1	Horizontal	,scroll speed
FX-2	Vertical	,scroll speed
4	Scroll to Index	FX-1	Horizontal index	Range 0 to 255/256 of screen width
FX-2	Vertical index	Range 0 to 255/256 of screen height
5	Tile	FX-1	Horizontal tiles	Range 1 to 255
FX-2	Vertical tiles	Range 1 to 255
FX-3	Mirroring	0-63	None
64-127	Horizontal mirror odd tiles
128-191	Vertical mirror odd tiles
192-255	H+V mirror odd tiles

Value

Effect

Notes

None

Shake Gentle

FX-1

Horizontal amplitude

Range ±0.1 of screen width

FX-2

Vertical amplitude

Range ±0.1 of screen height

FX-3

Rotation amplitude

Range ±5°

Shake

FX-1

Horizontal amplitude

Range ±1 screen width

FX-2

Vertical amplitude

Range ±1 screen height

FX-3

Rotation amplitude

Range ±180°

Scroll

FX-1

Horizontal

,scroll speed

FX-2

Vertical

,scroll speed

Scroll to Index

FX-1

Horizontal index

Range 0 to 255/256 of screen width

FX-2

Vertical index

Range 0 to 255/256 of screen height

Tile

FX-1

Horizontal tiles

Range 1 to 255

FX-2

Vertical tiles

Range 1 to 255

FX-3

Mirroring

0-63

None

64-127

Horizontal mirror odd tiles

128-191

Vertical mirror odd tiles

192-255

H+V mirror odd tiles

Changing between Scroll and Scroll to Index does not reset the position, so they can be combined to give static and moving scrolls.

Play Mode

Value	Action	Notes
0	Once	Play clip once, hold last frame (hold first frame if playing backwards).
1	Once-then-black	Play clip once, then go to black
2	Loop	Loop in the current direction of play
3	Bounce	Reverse direction at first/last frame.
4	First frame	Show start frame⁽¹⁾.
5	Last frame	Show the end frame⁽¹⁾.
6	Pause	Show the current frame, regardless of speed.
7	Next frame	Advance to the next frame then automatically pause⁽²⁾.
8	Once Rsrt Int 0	Same as Once, but media restarts when intensity is increase above 0.
9	OnceB Rsrt Int0	Same as Once-then-black, but media restarts when intensity is increased above 0.
10	Loop Rsrt Int 0	Same as Loop, but media restarts when intensity is increased above 0.
11	Bnce Rsrt Int 0	Same as Bounce, but media restarts when intensity is increased above 0.

Value

Action

Notes

Once

Play clip once, hold last frame

(hold first frame if playing backwards).

Once-then-black

Play clip once, then go to black

Loop

Loop in the current direction of play

Bounce

Reverse direction at first/last frame.

First frame

Show start frame⁽¹⁾.

Last frame

Show the end frame⁽¹⁾.

Pause

Show the current frame, regardless of speed.

Next frame

Advance to the next frame then automatically pause⁽²⁾.

Once Rsrt Int 0

Same as Once, but media restarts when intensity is increase above 0.

OnceB Rsrt Int0

Same as Once-then-black, but media restarts when intensity is increased above 0.

Loop Rsrt Int 0

Same as Loop, but media restarts when intensity is increased above 0.

Bnce Rsrt Int 0

Same as Bounce, but media restarts when intensity is increased above 0.

(1) Note that these modes ignore playback speed and always show the selected frame. If the start or end frames are changed, the displayed frame will change. This allows the user to view the start and end points as they are moved around within a clip.

(2) Play mode must go back to Pause before this mode can be used again.

Scale

Pseudo-logarithmic scale factor with the values 0 to 65535 corresponding to a multiplication factor of 0.0 to 10.0, with 32768 being 1.0.

Screen Offset

Linear scale, with the values 0 to 65535 corresponding to an offset in screen position of -1.0 to +1.0. 32768 corresponds to 0, i.e. no offset. A value of 0 in the X position of a layer, for example, would move the layer one screen width to the left (-1), effectively taking it just out of view (if its width was unchanged).

Scroll Position

Linear scale, with the values 0 to 65535 corresponding to a scroll position of -100.0 to + 555.0. When scrolling in X the position is in characters. When scrolling in Y the position is in lines. (0,0) is the top left of the first character in a piece of text.

Scroll Speed

When used to scroll the content of a layer, the speed is in units of width or height. In other words, a speed of 1.0 will scroll the entire width (or height) in 1 second.

Value	Speed	Notes
0	0	Reset to start position
1-127	1.0 - 0.008	Negative (Left, Down)
128	0	Stop
129-255	0.008 - 1.0	Positive (Right, Up)

Speed Factor

Speed is represented as a multiplier to be applied to the normal speed, with the values 0-65535 encoded linearly as follows:

Value	Speed Multiplier	Notes
0	-500%	Backwards at 5 times normal speed
26214	-100%	Backwards
32768	0	Stop
39321	100%	Forwards at normal speed
65535	+500%	Forwards at 5 times normal speed

Text Loop Mode

Value	Action	Text Behaviour
0	Loop	Scrolling loops round
1	Stop	Scroll then stop
2	Bounce	Scrolling reverses direction

Value

Action

Text Behaviour

Loop

Scrolling loops round

Stop

Scroll then stop

Bounce

Scrolling reverses direction

Transition Type

Not implemented yet.