atem-connection

Sofie: The Modern TV News Studio Automation System (ATEM connection library)

This library is used in the Sofie TV News Studio Automation System for connecting to Blackmagic Design ATEM devices.

Technology highlights

• Typescript
• Yarn
• Jest
• standard-version
• codecov

Installation

For usage by library consumers installation is as easy as:

yarn add atem-connection

For library developers installation steps are as following:

git clone https://github.com/nrkno/tv-automation-atem-connection
yarn
yarn build

If you want to make a contribution, feel free to open a PR.

Usage

const { Atem } = require('atem-connection')
const myAtem = new Atem({ externalLog: console.log })

myAtem.connect('192.168.168.240')

myAtem.on('connected', () => {
	myAtem.changeProgramInput(3).then((res) => {
		console.log(res)
		// ProgramInputCommand {
		// 	flag: 0,
		// 	rawName: 'PrgI',
		// 	mixEffect: 0,
		// 	properties: { source: 3 },
		// 	resolve: [Function],
		// 	reject: [Function] }
	})
	console.log(myAtem.state)
})

myAtem.on('stateChanged', function(err, state) {
  console.log(state); // catch the ATEM state.
});

Documentation

You can find the generated type docs here.

Events

• connected This event will be fired once we have connected with the ATEM.

• disconnected Whenever the connection to the ATEM fails and does not recover within 5 seconds this is called.

• stateChanged(state, path) Whenever a packet from the ATEM is received that changes the state, this event will be fired. The path parameter is a path into the state that represents the change, to allow for filtering of events. eg video.ME.0.programInput

Debug

Set debug=true config option in order to see raw packets. This is especially useful for library developers.

const myAtem = new Atem({ debug: true, externalLog: console.log })

SEND <Buffer 10 14 53 ab 00 00 00 00 00 3a 00 00 01 00 00 00 00 00 00 00>
SEND <Buffer 80 0c 53 ab 00 00 00 00 00 03 00 00>
SEND <Buffer 80 0c 53 ab 00 00 00 00 00 03 00 00>
SEND <Buffer 80 0c 80 0f 00 01 00 00 00 41 00 00>
RECV <Buffer 00 0c 90 60 5f 76 65 72 00 02 00 10>...

Test

This module run tests with jest.

$ yarn unit

There is a suite of generated serialization tests, using atem-connection-test-generator as the LibAtem project has tests to verify its serialization against the Blackmagic Atem SDK

Changelog

1.0.0 (2019-09-17)

Bug Fixes

• broken autoDownstreamKey function and mangled multiviewer window state (71c61f6)
• consistent API for super source methods (4327660)
• data transfer uses old command names (e6a6bd0)
• disable unsupported v8 tests (8bcafb5)
• dve value range (33784bc)
• exclude test helpers in build (041c37f)
• exit cleanly after running tests (c23a9f9)
• ignore failing tests (8cfcfaf)
• improve commandParser typings (1e26d6d)
• Make buffer use in serialize consistent. Remove setting command name in serialize. (40eec6e)
• More command test data mangling (8bd9009)
• multiviewer state initialization (2547af1)
• regenerate commands test data (fe619c4)
• restructure all command tests to use new structure (957ed76)
• some broken cases (9ebde2e)
• some more command serialization (cf66953)
• some tests (3f14715)
• AudioMixerInputCommand: sign in deserialization (d9a3865)
• MediaPlayerSourceCommand: order of serialization (a0a89f3)
• MixEffectFlyKeyFrameGetCommand: correct validators (a1648c1)
• tidy up some commented out code (f1a1252)
• topology command (e5812d9)

Features

• 8.0.1 support (eaa1e72)
• Add test for api methods which change command based on version (7208ee4)
• add test to verify that all commands have serialization test cases (3cb9ae7)
• Enable and fix v8 command tests (3a7d23d)
• enable running tests in circleci (662638d)
• expect commands to be split to be a serialize or deserialize (unless they use the same name for both) (e9704f2)
• FadeToBlack control (660e8dc)
• initial multi-version support (fedc690)
• prototype serialize command (010fff2)
• prototype what separate command converter structures would look like (378be83)
• restructure some core buffer usage, and move command header (length + name) writing into common command serialization code (3c8b062)
• split some commands (beae1c4)
• stateChanged events report a path instead of the Command (845909f)