Blackmagic ATEM Television Studio HD8 ISO

Blackmagic ATEM Television Studio HD User Manual Developer Information

Blackmagic ATEM Television Studio HD8 ISO

Blackmagic SDI Camera Control Protocol

Version 1.3

If you are a software developer you can use the SDI Camera Control Protocol to construct devices that integrate with our products. Here at Blackmagic Design our approach is to open up our protocols and we eagerly look forward to seeing what you come up with!

Overview

The Blackmagic SDI Camera Control Protocol is used by ATEM switchers, Blackmagic 3G-SDI Shield for Arduino and the Blackmagic Camera Control app to provide Camera Control functionality with supported Blackmagic Design cameras. Please refer to the ‘Understanding Studio Camera Control’ chapter section of this manual, or the ATEM Switchers Manual and SDK manual for more information. These can be downloaded at .

This document describes an extensible protocol for sending a uni directional stream of small control messages embedded in the non-active picture region of a digital video stream. The video stream containing the protocol stream may be broadcast to a number of devices. Device addressing is used to allow the sender to specify which device each message is directed to.

Assumptions

Alignment and padding constraints are explicitly described in the protocol document. Bit fields are packed from LSB first. Message groups, individual messages and command headers are defined as, and can be assumed to be, 32 bit aligned.

Blanking Encoding

A message group is encoded into a SMPTE 291M packet with DID/SDID x51/x53 in the active region of VANC line 16.

Message Grouping

Up to 32 messages may be concatenated and transmitted in one blanking packet up to a maximum of 255 bytes payload. Under most circumstances, this should allow all messages to be sent with a maximum of one frame latency.

If the transmitting device queues more bytes of message packets than can be sent in a single frame, it should use heuristics to determine which packets to prioritize and send immediately. Lower priority messages can be delayed to later frames, or dropped entirely as appropriate.

Abstract Message Packet Format

Every message packet consists of a three byte header followed by an optional variable length data block. The maximum packet size is 64 bytes.

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.

Receiving devices should use the destination device address and or the command identifier to determine which messages to process. The receiver should use the command length to skip irrelevant or unknown commands and should be careful to skip the implicit padding as well.

Defined Commands

Command 0 : change configuration

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.

Currently defined values are:

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.

Data types 6 through 127 are reserved.

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).

Data types 129 through 255 are available for device specific purposes.

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.

Operation types 2 through 127 are reserved.
Operation types 128 through 255 are available for device specific purposes.
Data (void)The data field is 0 or more bytes as determined by the data type and number of elements.

The category, parameter, data type and operation type partition a 24 bit operation space.

Group

ID

Parameter

Type

Index

Minimum

Maximum

Interpretation

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

Example Protocol Packets

Packet

Operation Length Byte

0

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

header command data

destination

length

command

reserved

category

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

Blackmagic Embedded Tally Control Protocol

Version 1.0 (30/04/14)

This section is for third party developers or users who may wish to add support for the Blackmagic Embedded Tally Control Protocol to their products or system. It describes the protocol for sending tally information embedded in the non-active picture region of a digital video stream.

Data Flow

A master device such as a broadcast switcher embeds tally information into its program feed which is broadcast to a number of slave devices such as cameras or camera controllers. The output from the slave devices is typically fed back to the master device, but may also be sent to a video monitor.

The primary flow of tally information is from the master device to the slaves. Each slave device may use its device id to extract and display the relevant tally information.

Slave devices pass through the tally packet on their output and update the monitor tally status, so that monitor devices connected to that individual output may display tally status without knowledge of the device id they are monitoring.

Assumptions

Any data alignment / padding is explicit in the protocol. Bit fields are packed from LSB first.

Blanking Encoding

One tally control packet may be sent per video frame. Packets are encoded as a SMPTE 291M packet with DID/SDID x51/x52 in the active region of VANC line 15. A tally control packet may contain up to 256 bytes of tally information.

Packet Format

Each tally status consists of 4 bits of information:

uint4

bit 0:

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

bit 1:

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

bit 2-3:

reserved (0x0)

The first byte of the tally packet contains the monitor device tally status and a version number.

Subsequent bytes of the tally packet contain tally status for pairs of slave devices. The master device sends tally status for the number of devices configured/supported, up to a maximum of 510.

struct tally

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)

Byte

7 MSB

6

5

4

3

2

1

0 LSB

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

...

Was this information helpful?