Blackmagic ATEM Television Studio HD User Manual Developer Information

Destination device (uint8)

Device addresses are represented as an 8 bit unsigned integer. Individual devices are numbered 0 through 254 with the value 255 reserved to indicate a broadcast message to all devices.

Command length (uint8)

The command length is an 8 bit unsigned integer which specifies the length of the included command data. The length does NOT include the length of the header or any trailing padding bytes.

Command id (uint8)

The command id is an 8 bit unsigned integer which indicates the message type being sent. Receiving devices should ignore any commands that they do not understand. Commands 0 through 127 are reserved for commands that apply to multiple types of devices. Commands 128 through 255 are device specific.

Reserved (uint8)

This byte is reserved for alignment and expansion purposes. It should be set to zero.

Command data (uint8[])

The command data may contain between 0 and 60 bytes of data. The format of the data section is defined by the command itself.

Padding (uint8[])

Messages must be padded up to a 32 bit boundary with 0x0 bytes. Any padding bytes are NOT included in the command length.

Category (uint8)

The category number specifies one of up to 256 configuration categories available on the device.

Parameter (uint8)

The parameter number specifies one of 256 potential configuration parameters available on the device. Parameters 0 through 127 are device specific parameters. Parameters 128 though 255 are reserved for parameters that apply to multiple types of devices.

Data type (uint8)

The data type specifies the type of the remaining data. The packet length is used to determine the number of elements in the message. Each message must contain an integral number of data elements.

0: void / boolean

A void value is represented as a boolean array of length zero. The data field is a 8 bit value with 0 meaning false and all other values meaning true.

1: signed byte

Data elements are signed bytes

2: signed 16 bit integer

Data elements are signed 16 bit values

3: signed 32 bit integer

Data elements are signed 32 bit values

4: signed 64 bit integer

Data elements are signed 64 bit values

5: UTF-8 string

Data elements represent a UTF-8 string with no terminating character.

128: signed 5.11 fixed point

Data elements are signed 16 bit integers representing a real number with 5 bits for the integer component and 11 bits for the fractional componentThe fixed point representation is equal to the real value multiplied by 2^11. The representable range is from -16.0 to 15.9995 (15 + 2047/2048).

Operation type (uint8)

The operation type specifies what action to perform on the specified parameter. Currently defined values are:

0: assign value

The supplied values are assigned to the specified parameter. Each element will be clamped according to its valid range. A void parameter may only be 'assigned' an empty list of boolean type. This operation will trigger the action associated with that parameter. A boolean value may be assigned the value zero for false, and any other value for true.

1: offset / toggle value

Each value specifies signed offsets of the same type to be added to the current parameter values. The resulting parameter value will be clamped according to their valid range. It is not valid to apply an offset to a void value. Applying any offset other than zero to a boolean value will invert that value.

Lens

0.0

Focus

fixed16

–

0

1

0.0 = near, 1.0 = far

0.1

Instantaneous autofocus

void

–

–

–

trigger instantaneous autofocus

0.2

Aperture (f-stop)

fixed16

–

-1

16

Aperture Value (where fnumber = sqrt(2^AV))

0.3

Aperture (normalised)

fixed16

–

0

1

0.0 = smallest, 1.0 = largest

0.4

Aperture (ordinal)

int16

–

0

n

Steps through available aperture values from minimum (0) to maximum (n)

0.5

Instantaneous auto aperture

void

–

–

–

trigger instantaneous auto aperture

0.6

Optical image stabilisation

boolean

–

–

–

true = enabled, false = disabled

0.7

Set absolute zoom (mm)

int16

–

0

max

Move to specified focal length in mm, from minimum

(0) to maximum (max)

0.8

Set absolute zoom (normalised)

fixed16

–

0

1

Move to specified focal length: 0.0 = wide, 1.0 = tele

0.9

Set continuous zoom (speed)

fixed16

–

-1

+1.0

Start/stop zooming at specified rate: -1.0 = zoom wider fast, 0.0 = stop, +1 = zoom tele fast

Video

1.0

Video mode

int8

[0] = frame rate

–

–

24, 25, 30, 50, 60

[1] = M-rate

–

–

0 = regular, 1 = M-rate

[2] = dimensions

–

–

0 = NTSC, 1 = PAL,

2 = 720, 3 = 1080, 4 = 2k, 5 = 2k DCI,

6 = UHD

[3] = interlaced

–

–

0 = progressive, 1 = interlaced

[4] = Color space

–

–

0 = YUV

1.1

Gain

int8

1

16

1 = 100 ISO, 2 = 200 ISO, 4 = 400 ISO, 8 = 800 ISO, 16 = 1600 ISO

1.2

Manual White Balance

int16

[0] = color temp

2500

10000

Color temperature in K

int16

[1] = tint

-50

50

tint

1.3

Set auto WB

void

–

–

–

Calculate and set auto white balance

1.4

Restore auto WB

void

–

–

–

Use latest auto white balance setting

1.5

Exposure (us)

int32

1

42000

time in us

1.6

Exposure (ordinal)

int16

–

0

n

Steps through available exposure values from minimum (0) to maximum (n)

1.7

Dynamic Range Mode

int8 enum

–

0

1

0 = film, 1 = video,

1.8

Video sharpening level

int8 enum

–

0

3

0 = off, 1 = low, 2 = medium, 3 = high

• = file frame rate

• = sensor frame rate

• = frame width

Recording format

int16

• = frame height

• = flags

–

–

fps as integer (eg 24, 25, 30, 50, 60, 120)

–

–

fps as integer, valid when sensor-off-speed set (eg 24, 25, 30, 33, 48, 50, 60, 120), no change will be performed if this value is set to 0

–

–

in pixels

–

–

in pixels

–

–

[0] = file-M-rate

–

–

[1] = sensor-M-rate, valid when sensor-off-speed-set

–

–

[2] = sensor-off-speed

–

–

[3] = interlaced

–

–

[4] = windowed mode

1.10

Set auto exposure mode

int8

–

0

4

0 = Manual Trigger, 1 = Iris, 2 = Shutter, 3 = Iris + Shutter, 4 = Shutter + Iris

1.11

Shutter angle

int32

–

100

36000

Shutter angle in degrees, multiplied by 100

1.12

Shutter speed

int32

–

24

2000

Shutter speed value as a fraction of 1, so 50 for 1/50th of a second

1.13

Gain

int8

–

-128

127

Gain in decibel (dB)

1.14

ISO

int32

–

0

2147483647

ISO value

Audio

2.0

Mic level

fixed16

–

0

1

• = minimum,

• = maximum

2.1

Headphone level

fixed16

–

0

1

• = minimum,

• = maximum

2.2

Headphone program mix

fixed16

–

0

1

• = minimum,

• = maximum

2.3

Speaker level

fixed16

–

0

1

• = minimum,

• = maximum

2.4

Input type

int8

–

0

2

0 = internal mic, 1 = line level input, 2 = low mic level input, 3 = high mic level input

2.5

Input levels

fixed16

[0] ch0

0

1

0.0 = minimum, 1.0 = maximum

[1] ch1

0

1

0.0 = minimum, 1.0 = maximum

2.6

Phantom power

boolean

–

–

–

true = powered, false = not powered

Output

3.0

Overlay enables

uint16 bit field

–

–

–

bit flags:

• = display status,

• = display frame guides Some cameras don't allow separate control of frame guides and status overlays.

3.1

Frame guides style (Camera 3.x)

int8

[0] = frame guides style

0

8

0 = HDTV, 1 = 4:3, 2 = 2.4:1,

3 = 2.39:1, 4 = 2.35:1, 5 = 1.85:1, 6 = thirds

3.2

Frame guides opacity (Camera 3.x)

fixed16

[1] = frame guide opacity

0.1

1

0.0 = transparent, 1.0 = opaque

Overlays (replaces .1 and .2 above from Cameras 4.0)

3.3

int8

[0] = frame guides style

–

–

0 = off, 1 = 2.4:1, 2 = 2.39:1, 3 = 2.35:1, 4 = 1.85:1, 5 = 16:9, 6 = 14:9, 7 = 4:3

[1] = frame guide opacity

0

100

0 = transparent, 100 = opaque

[2] = safe area percentage

0

100

percentage of full frame used by safe area guide (0 means off)

[3] = grid style

–

–

bit flags: [0] = display thirds,

• = display cross hairs,

• = display center dot

Display

4.0

Brightness

fixed16

–

0

1

0.0 = minimum, 1.0 = maximum

4.1

Overlay enables

int16 bit field

–

–

–

0x4 = zebra

0x8 = peaking

4.2

Zebra level

fixed16

–

0

1

• = minimum,

• = maximum

4.3

Peaking level

fixed16

–

0

1

• = minimum,

• = maximum

4.4

Color bars display time (seconds)

int8

–

0

30

0 = disable bars, 1-30 = enable bars with timeout (s)

4.5

Focus Assist

int8

[0] = focus assist method

–

–

0 = Peak, 1 = Colored lines

[1] = focus line color

–

–

0 = Red, 1 = Green, 2 = Blue, 3 = White, 4 = Black

Tally

5.0

Tally brightness

fixed16

–

0

1

Sets the tally front and tally rear brightness to the same level. 0.0 = minimum,

1.0 = maximum

5.1

Front tally brightness

fixed16

–

0

1

Sets the tally front brightness. 0.0 = minimum,

1.0 = maximum

5.2

Rear tally brightness

fixed16

–

0

1

Sets the tally rear brightness.

• = minimum,

• = maximum Tally rear brightness cannot be turned off

Reference

6.0

Source

int8 enum

–

0

2

0 = internal, 1 = program, 2 = external

6.1

Offset

int32

–

–

–

+/- offset in pixels

Configuration

7.0

Real Time Clock

int32

[0] time

_

_

BCD - HHMMSSFF (UCT)

[1] date

_

_

BCD - YYYYMMDD

7.1

System language

string

_

_

_

ISO-639-1 two character language code

7.2

Timezone

int32

_

_

_

Minutes offset from UTC

7.3

Location

int64

[0] latitude

_

_

BCD - s0DDdddddddddddd where s is the sign: 0 = north (+), 1 = south (-); DD degrees, dddddddddddd decimal degrees

[1] longitude

_

_

BCD - sDDDdddddddddddd where s is the sign: 0 = west (-), 1 = east (+); DDD degrees, dddddddddddd decimal degrees

Color Correction

8.0

Lift Adjust

fixed16

[0] red

-2

2

default 0.0

[1] green

-2

2

default 0.0

[2] blue

-2

2

default 0.0

[3] luma

-2

2

default 0.0

8.1

Gamma Adjust

fixed16

[0] red

-4

4

default 0.0

[1] green

-4

4

default 0.0

[2] blue

-4

4

default 0.0

[3] luma

-4

4

default 0.0

8.2

Gain Adjust

fixed16

[0] red

0

16

default 1.0

[1] green

0

16

default 1.0

[2] blue

0

16

default 1.0

[3] luma

0

16

default 1.0

8.3

Offset Adjust

fixed16

[0] red

-8

8

default 0.0

[1] green

-8

8

default 0.0

[2] blue

-8

8

default 0.0

[3] luma

-8

8

default 0.0

8.4

Contrast Adjust

fixed16

[0] pivot

0

1

default 0.5

[1] adj

0

2

default 1.0

8.5

Luma mix

fixed16

–

0

1

default 1.0

8.6

Color Adjust

fixed16

[0] hue

-1

1

default 0.0

[1] sat

0

2

default 1.0

8.7

Correction Reset Default

void

–

–

–

reset to defaults

Media

10.0

Codec

[0] = basic codec

–

–

0 = RAW,

1 = DNxHD, 2 = ProRes, 3 = Blackmagic RAW

–

–

RAW:

0 = Uncompressed, 1 = lossy 3:1, 2 = lossy 4:1

int8 enum

[1] = codec variant

–

–

ProRes:

0 = HQ,

1 = 422, 2 = LT, 3 = Proxy,

4 = 444, 5 = 444XQ

–

–

Blackmagic RAW:

0 = Q0, 1 = Q5,

2 = 3:1, 3 = 5:1, 4 = 8:1, 5 = 12:1

10.1

Transport mode

int8

[0] = mode

–

–

0 = Preview, 1 = Play, 2 = Record

[1] = speed

–

–

-ve = multiple speeds backwards, 0 = pause, +ve = multiple speeds forwards

[2] = flags

–

–

1<<0 = loop, 1<<1 = play all, 1<<5 = disk1 active, 1<<6 = disk2 active, 1<<7 = time-lapse recording

[3] = active storage medium

–

–

0 = CFast card,

1 = SD

PTZ

Control

11.0

Pan/Tilt Velocity

fixed 16

[0] = pan velocity

-1.0

1.0

-1.0 = full speed left,

1.0 = full speed right

[1] = tilt velocity

-1.0

1.0

-1.0 = full speed down,

1.0 = full speed up

11.1

Memory Preset

int8 enum

[0] = preset command

–

–

0 = reset, 1 = store location, 2 = recall location

int8

[1] = preset slot

0

5

–

Packet

Operation Length Byte

0

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

destination

command

reserved

parameter

type

operation

trigger instantaneous auto focus on camera 4

8

4

4

0

0

0

1

0

0

turn on OIS on all cameras

12

255

5

0

0

0

6

0

0

1

0

0

0

set exposure to 10 ms on camera 4 (10 ms = 10000 us = 0x00002710)

12

4

8

0

0

1

5

3

0

0x10

0x27

0x00

0x00

add 15% to zebra level (15 % = 0.15 f = 0x0133 fp)

12

4

6

0

0

4

2

128

1

0x33

0x01

0

0

select 1080p 23.98 mode on all cameras

16

255

9

0

0

1

0

1

0

24

1

3

0

0

0

0

0

subtract 0.3 from gamma adjust for green & blue (-0.3 ~= 0xfd9a fp)

16

4

12

0

0

8

1

128

1

0

0

0x9a

0xfd

0x9a

0xfd

0

0

all operations combined

76

4

4

0

0

0

1

0

0

255

5

0

0

0

6

0

0

1

0

0

0

4

8

0

0

1

5

3

0

0x10

0x27

0x00

0x00

4

6

0

0

4

2

128

1

0x33

0x01

0

0

255

9

0

0

1

0

1

0

24

1

3

0

0

0

0

0

4

12

0

0

8

1

128

1

0

0

0x9a

0xfd

0x9a

0xfd

0

0

uint4

bit 0:

program tally status (0=off, 1=on)

bit 1:

preview tally status (0=off, 1=on)

bit 2-3:

reserved (0x0)

uint8

bit 0:

monitor device program tally status (0=off, 1=on)

bit 1:

monitor device preview tally status (0=off, 1=on)

bit 2-3:

reserved (0b00)

bit 4-7:

protocol version (0b0000)

uint8[0]

bit 0:

slave device 1 program tally status (0=off, 1=on)

bit 1:

slave device 1 device preview tally status (0=off, 1=on)

bit 2-3:

reserved (0b00)

bit 4:

slave device 2 program tally status (0=off, 1=on)

bit 5:

slave device 2 preview tally status (0=off, 1=on)

bit 6-7:

reserved (0b00)

uint8[1]

bit 0:

slave device 3 program tally status (0=off, 1=on)

bit 1:

slave device 3 device preview tally status (0=off, 1=on)

bit 2-3:

reserved (0b00)

bit 4:

slave device 4 program tally status (0=off, 1=on)

bit 5:

slave device 4 preview tally status (0=off, 1=on)

bit 6-7: . . .

reserved (0b00)

0

Version (0b0)

Version (0b0)

Version (0b0)

Version (0b0)

Reserved (0b0)

Reserved (0b0)

Monitor Preview

Monitor Program

1

Reserved (0b0)

Reserved (0b0)

Slave 1 Preview

Slave 1 Program

Reserved (0b0)

Reserved (0b0)

Slave 0 Preview

Slave 0 Program

2

Reserved (0b0)

Reserved (0b0)

Slave 3 Preview

Slave 3 Program

Reserved (0b0)

Reserved (0b0)

Slave 2 Preview

Slave 2 Program

3

...