Custom Layer API

Protocol Version 1.2

Introduction

mimoLive uses Apple’s Quartz Composer technology and its documents for the layers. Because mimoLive needs to tell the Quartz Composer document some environmental parameters as well as reading results from them, we designed a protocol that you have to follow in order to take advantage of all the features mimoLive has to offer. In the following, you find all the technical information about this protocol.

If you want to learn how to create custom layers with Quartz Composer, please read “Creating Customer Layers for mimoLive”:en:pro:custom_layer:creating_custom_layers.

Properties

You can edit the protocol in Quartz Composer by selecting Editor ⇢ Edit information (⌥⌘I)

Name	Required	Type	Sample Value
category		String
copyright		String	© 2016 MySoftwareCompany
description		String	Plays a fullscreen input
name	yes	String	Fullscreen Player
DEPRECATED tv_Categories		String	Backdrop,Fullscreen
tv_Debug		Boolean
tv_FileData_ input name-		Data	(imported XML file)
tv_FileName_ input name-		String	Standings.xml
tv_HelpURL		String
tv_HiddenInputKeys		Array of Strings
tv_InputLabel_ input name-		String	Video Input
tv_LayerIdentifier	yes	String	com.example.layer.mylayer
tv_LayerVersion	yes	Number (real)	1.01
tv_LayerPreview		Data	(imported PNG file)
tv_LayerProtocolVersion	yes	Number (real)	1
tv_SortKey		String
tv_StepSize_ input name-		Number (real)	0.1
DEPRECATED tv_Tagline		String	Plays a fullscreen input
tv_UseAudioFromSource		String	tvIn_VideoSourceA
tv_UnitLabel_ input name-		String

category

The category is usually set by Quartz composer and is not needed for mimoLive layers. For mimoLive categories see tv_Categories instead.

copyright

The copyright is usually set by Quartz composer and is not needed for mimoLive layers.

description

Quartz Composer standard – keep it about 3 lines long so it fits well in the preview.

name

The name is displayed inside of mimoLive. Use a short and unique name to find your layer quickly.

protocols

This array is usually set by Quartz composer and is not needed for mimoLive layers.

tv_Categories

DEPRECATED

The categories were used to group and filter the layers. Currently, they are ignored, but it may be activated again. Use a comma-separated list of the following predefined categories or define your own.

– “Audio” – Layers that provide the possibility to use an audio source
– “Overlay” – Layers that overlay data or images: Lower Thirds, Title, Logo, …
– “Fullscreen” – Layers that at least via default settings provide a full screen – e.g. Animations, Single Video, Weather Map
– “Backdrop” – Layers that work as a backdrop/background for other things on top.
– “Text” – Layers that provide some kind of text display, e.g. Credits, Lower Thirds, Heading
– “Data” – Layers that display Data, e.g. stock tickers, basketball scores, etc.
– “Image” – Layers that provide a means of displaying using a static image input
– “Multivideo” – Layers that combine at least two sources, either by adding at least one source in addition to the layers below or using two or more sources.
– “3D” – Layers that provide some kind 3d positioning of elements, e.g. Presenter
– “Segment” – Layers that provide a timed animation to separate segments, e.g. Digital Upgrade Beitrag
– “Effect” – Layers that provide some overlay Effects, e.g. Magnifier, Spotlight, Zoom…
– “Demo” – Layers that are mostly meant for demonstrating capabilities rather than providing generic useful functionality, e.g. Weather Map, which just shows a map of Germany.
– “Consumer” – Layers that use the compositedlayersimage, e.g. Video Switcher, Zoom, Presenter
– “Generator” – Layers that provide some sort of generated output, e.g. Animations
– “Debug” – Layers useful for debugging that are not visible in the end product

tv_Debug

Telling the application that this composition should only be used in a debugging environment.

tv_FileData_

A data blob that will be created and written into the document for a file input on layer creation. This works for text files that will be provided in a _TypeFilePath or .mov files for image inputs. See tv_FileName_ .

tv_FileName_

The corresponding filename to the tv_FileData_ . Required if a tv_FileData_* input is existing.

tv_HelpURL

This string can store an URL with helpful information on how to use this layer. mimoLive will present a “?” button in the information popover for each layer. If the user clicks this button the URL will be opened by the system’s default internet browser.

tv_HiddenInputKeys

In this array, the composition holds input keys that should be hidden from the user interface.

tv_InputLabel_

Can be used to provide an alternate name label for the given input key in the parameter view. Empty strings for no labels are also possible. Works like the tv_hide_ouput , e.g. the protocol input name must be complete (e.g. “tv_InputLabel_tvIn_VideoSourceAImage”).

tv_LayerIdentifier

For identification, Boinx shipped compositions and sorted different versions. Must be unique. A reverse-notated domain is recommended. Example: com.mysoftware.layers.videofullscreen

tv_LayerVersion

For matching different versions of a composition in a document/application. Major version numbers denote incompatibility and don’t match with other major versions (e.g. you need to increase the major version if the input keys name changes). Minor version numbers must be upwards compatible and can be incremented by 0.001 for each iteration. E.g. it must be ensured that loading settings from a 1.0 layer for a 1.013 must look exactly the same, which means new keys if present need to have a default value that does not show them or equals the look of the previous version.

tv_LayerPreview

Image data to be used for previewing a layer inside the layers list. This can deliver a better experience than the default quick-look preview. The preview image should be 256 × 256 pixels.

tv_LayerProtocolVersion

For future backward compatibility if mimoLive changes the protocol significantly. Currently must be set to 1.

tv_SortKey

Defines the sorting of the layers in mimoLive. So you can sort the filters by the probability of use. Currently, a scheme of 2 uppercase letters is used, eg. “BM”, “DE”, “DM”, etc. NOTE: Currently this feature isn’t used but will in the future.

tv_StepSize_

Can be used to provide a custom StepSize for the jog wheels – one-pixel mouse movement then corresponds to this amount of change (also +/- click).

tv_Tagline

DEPRECATED
One line string that will be displayed in the info popover in the layer repository.

tv_UseAudioFromSource

mimoLive currently can show one audio control in the user interface only. This property tells it what input key is the one to be controlled. Fill in the complete corresponding input key. (For backward compatibility this field also accepts “A”, “B” or “C” which is translated to the key tvIn_VideoSourceAImage, tvIn_VideoSourceBImage or tvIn_VideoSourceCImage. If not provided mimoLive assumes that no audio will be used with this layer.

tv_UnitLabel_

Can be used to provide a unit label, e.g. “pt” for the given input key in the parameter view. Keep as short as possible. Help to communicate what input means. Boinx unit inputs will get automatic “px” labels.

Inputs

Name	Type
tvIn_AccountTwitterConsumerKey	String
tvIn_AccountTwitterConsumerSecret	String
tvIn_AccountTwitterTokenKey	String
tvIn_AccountTwitterTokenSecret	String
tvIn_CompositedLayersImage	Image
tvIn_FrameCount	Index
tvIn_FrameDuration	Number
tvIn_CompositedLayersImage	Image
tvIn_InTransitionDirection	Index Transition Direction Direction
tvIn_InTransitionDuration	Number
tvIn_InTransitionType	Index Transition Type Type
tvIn_KeyboardModifierAlt	Boolean
tvIn_KeyboardModifierCommand	Boolean
tvIn_KeyboardModifierControl	Boolean
tvIn_KeyboardModifierFunction	Boolean
tvIn_KeyboardModifierShift	Boolean
tvIn_Obscured	Boolean
tvIn_OnAir	Boolean
tvIn_OSVersion	String
tvIn_OutTransitionDirection	Index Transition Direction Direction
tvIn_OutTransitionDuration	Number
tvIn_OutTransitionType	Index Transition Type Type
tvIn_PreviewMode	Boolean
tvIn_Reset	Boolean (Signal)
tvIn_RuntimeIdentifier	String
tvIn_Shared_	any value type
tvIn_ShowDuration	Number
tvIn_ShowTimer	Number
tvIn_Switch	Boolean (Signal)
tvIn_TransitionDirection	Index Transition Direction Direction
tvIn_TransitionDuration	Number
tvIn_TransitionType	Index Transition Type Type
tvIn_UISnapColor	Color
tvIn_VideoSourceA B C D	Image

tvIn_AccountTwitterConsumerKey

tvIn_AccountTwitterConsumerSecret

tvIn_AccountTwitterTokenKey

tvIn_AccountTwitterTokenSecret

Those four AccountTwitter inputs are used to feed the login data from mimoLive Twitter Account Preferences into the composition. The values are used with the JSON Patch and OAuth Patch Patch in order to read data from the Twitter service.

tvIn_CompositedLayersImage

If this input is present in a composition and there is content from the layers below, the result of the drawing of those layers below will be fed into this input.

tvIn_FrameCount

This input will get the total rendered frame count after starting mimoLive. If frames were dropped because the render load is too high the frame count will jump over those dropped frame numbers.

tvIn_FrameDuration

The frame duration is the time interval between each rendering in seconds.

tvIn_InTransitionDirection

A direction in which the Transition Direction will be performed.

tvIn_InTransitionDuration

A value in seconds the tvIn_InTransitionType will be performed.

tvIn_InTransitionType

If useful for a layer that lets the user choose the type of ongoing transition. Also, see Transition Type Type.

tvIn_KeyboardModifierAlt

tvIn_KeyboardModifierCommand

tvIn_KeyboardModifierControl

tvIn_KeyboardModifierFunction

tvIn_KeyboardModifierShift

Those boolean input fields will be set to true while the user presses the accordingly modifier key on the keyboard. This feature is mainly used for the direct manipulation feature. Please refer to the Apple Human User Guide Lines to see which modifier key should be used for which function in the UI.

tvIn_Obscured

This input is set to true if the layer doesn’t need to render any output because a layer above will obscure it anyways by drawing the full screen. This can be used to avoid heavy drawing by layers that aren’t visible but are set to be live. (E.g. in the case of the Twitter layer the layer still gets called even when obscured by another layer above and gets the chance to keep up the internet connection to the Twitter service.)

tvIn_OnAir

This input starts with a value of “true”. Once the input goes to “false” the composition should do any outgoing transition, then set its Done output when that’s finished. The composition will then be deactivated. It may happen that the application switches off a layer without waiting for the done flag.

tvIn_OSVersion

This string input will be set to the current OS X version (e.g. “Version 10.11.2 (Build 265341)”).

tvIn_OutTransitionDirection

A value in seconds of the tvIn_OutTransitionType will be performed. Also, see Transition Direction.

tvIn_OutTransitionDuration

A value in seconds of the tvIn_OutTransitionType will be performed.

tvIn_OutTransitionType

If useful for a layer that lets the user choose the type of ongoing transition. Also, see Transition Type Type.

tvIn_PreviewMode

Can be used to tell the composition that it is in preview mode.

tvIn_Reset

Useful for reseting the Logic of the Composition. This flag is set when a layer is switched to live from off or when switching between settings and no tvIn_Switch input is available.

tvIn_RuntimeIdentifier

Helps layers to communicate between preview and live instance. Set dynamically by mimoLive.

tvIn_Shared_

See Sharing Values between Layers Values between Layers.

tvIn_ShowDuration

If the user filled out the show duration in the Show Settings this input will have the value in seconds.

tvIn_ShowTimer

The show timer will reflect the Show Timer display of the mimoLive document in seconds.

tvIn_Switch

This flag is set instead of tvIn_Reset]] when a layer is switched from one setting to another without disabling the layer. In case this input does not exist, the [[#tvIn_Reset when a layer is switched from one setting to another without disabling the layer. In case this input does not exist, the [[#tvIn_Reset is set instead to maintain compatibility with older layers.

tvIn_TransitionDirection

A direction in which the Transition Direction will be performed.

tvIn_TransitionDuration

A value in seconds of the tvIn_InTransitionType will be performed.

tvIn_TransitionType

If useful for a layer that lets the user choose the type of ongoing transition. Also, see Transition Type Type.

tvIn_UISnapColor

In order to keep the UI consistent mimoLive provides a “snap color” in which to draw the guidelines in the preview whenever the UI is snapping to a certain value (e.g. hold down the “shift” key while rotating a Placer layer in custom display mode, then the guidelines will be drawn in that color when the rotation angle snaps to 0, 45 or 90 degrees)

tvIn_VideoSource

A layer can have up to 8 dynamic video source inputs: “A”, “B”, “C” and so on. They will be represented by a drop zone if the user drags a video source from the source repository to the layer stack. //Note: For backward compatibility, the extension “Image” on those inputs is ignored.//

Input Options

Corresponding Input Keys

If a video input key is present the following input keys will also be filled with information accordingly:

(e.g. “tvIn_VideoSourceA” -> “tvIn_VideoSourceAName”)

Key	Type	Description
AudioGain	Number	TBD
AudioLevel0	Number	Left audio channel level in db after gain control
AudioLevel1	Number	Right audio channel level in db after gain control
AudioLevel0Raw	Number	Left audio channel level in db before gain control
AudioLevel1Raw	Number	Right audio channel level in db before gain control
AudioPanning	Number	TBD
AudioVolume	Number	TBD
Data	Struct	A dictionary of metadata of the source. Currently, implemented keys are: “index” “duration” “title” “titleFallback” “artist” “album” “year” “fileReferenceIdentifier”
Name	String	Name of the associated image source. Can be used for displaying its name in the preview or to calculate the default name for the layer variant. See tvOut_SettingName .
RemainingTime	Number	In seconds. Will be provided for movie sources. -1 if the movie source is looped (or any other source).
TallyState	Index	Tally State of the connected source, see Tally States States
Type	Index	Value of source type type

Grouping Inputs

Grouping is provided in the user interface – for that the prefix of the input is relevant. Syntax works like tvGroup___. Please note the double underscore _ _ after the group name as a separator to the input name.

A special group is defined for inputs that should always be hidden: tvGroup_Hidden_Inputs__ This group can be made visible by switching mimoLive into debug mode in the debug|Debug Preferences|Debug Preferences. Some layers are using those hidden fields to communicate between the “Preview instance” and the “Live instance” (e.g. the Video Switcher layer is telling the Preview instance which video source is currently live).

Hide Inputs Dynamically

Every Protocol Input will be hidden in the UI if the tvOut_hide_ Output is set to “true”. This value is observed by the application and can be changed dynamically. Note that you need to use the full input name, including “tvIn” (e.g. use the output tvOut_hide_tvIn_Text_TypeMultiline for the input tvIn_Text_TypeMultiline).

Outputs

Name	Type
tvOut_Cursor	String
tvOut_Done	Boolean (Signal)
tvOut_hide_	Boolean
tvOut_Opaque	Boolean
tvOut_SettingName	String
tvOut_Share_	any type
tvOut_TimeRemaining	Number
tvOut_UseCompositedLayersImage	Boolean
tvOut_TallyState	Index of Tally States States
tvSet_	Type of input to be set
tvSetSignal_	Boolean
tvSetAudioVolume_	Number
tvSetAudioVolumeSignal_	Boolean

tvOut_Cursor

This output specifies the look of the mouse cursor if the mouse pointer is over either the preview or the program output view. Please refer to Apples NSCursor Class documentation) for valid values. Additional mouse cursors provided by mimoLive are “minus” and “plus”.

*Remove postfix “_Cursor” or “Cursor” from Apple’s NSCursor constants (e.g. use “openHand” to get an open-hand mouse cursor).

tvOut_Done

Used to tell the next layer that this layer is done. See tvIn_OnAir for documentation.

tvOut_hide_

Can be used to dynamically hide input values in the parameter view. See Hide Inputs Dynamically .

tvOut_Opaque

Used to tell the application that layers below this one do not have to be drawn. Default “false”. This value is overridden any connected source that contains alpha.

tvOut_SettingName

Compositions can suggest a useful name for a setting based on some input(s).

tvOut_Share_

See Sharing Values between Layers .

tvOut_TimeRemaining

Allows the application to display some large timer countdown (e.g. 5 seconds until a movie is done). Currently using “-1” to indicate there is no information about remaining time or “-2” if it is a looping movie.

tvOut_UseCompositedLayersImage

Used for optimizing performance when using layers below with transitions etc. It tells the app that the layer currently needs the composited layers image input. mimoLive will put in the layers below the composited image in the next render cycle. If “tvOut_UseCompositedLayersImage” isn’t present mimoLive assumes that the layers below the image should always be put in. Only drawing optimization, all media will be rolled nevertheless. Only used if tvIn_CompositedLayersImage is present.

tvOut_TallyState

This output layer can overwrite the automatic tally state of the source that is currently connected to that input. This is useful for transitions or if the source isn’t used for output the tally state can be switched off (e.g. the Video Switcher uses 3 cameras but only shows one at a time so it needs to set the tally state for unused sources to “TVTallyStateOff”). Please see Tally States for the list of tally states.

tvSet_

In mimoLive, a layer or filter can manipulate its own parameters. This is mainly to implement the direct manipulation feature in the preview of the layer variant (e.g. if the user drags the Analog Clock in the preview, the layer tells mimoLive which input keys should be changed to which value. However, this feature is also used to transfer live data from the program out instance to the preview instance and vis versa (e.g. in the Video Switcher layer the program out instance tells the preview instance which video source is currently live and the preview instance can tell the program out instance which video source the user selected on screen).

To make use of this feature you need two outputs that correspond to the input field you want to manipulate: In ‘tvSet_’ you output the new value you want to set and with ‘tvSetSignal_’ you signal when the value is valid and to be stored.

tvSetSignal_

See tvSet_ .

tvSetAudioVolume_

This output controls the volume of its associated audio source (or audio of a video source). Valid values are 0=silent to 1=full. the composition has to set the corresponding “tvSetAudioVolumeSignal_” each time it wants to change the audio volume level. E.g. this is useful if the layer has a fade in transition and wants to fade in audio as well.

tvSetAudioVolumeSignal_

See tvSetAudioVolume_ .

Sharing Values between Layers

A layer can send data to other layers in the layer stack which are above itself. The data is stored by mimolive by its sharing key until the next render cycle. If a layer is used multiple times (or the same sharing key is used in different layers) the data is overwritten by the layer above. To set this sharing data use a “tvOut_Share_” output. You can store any QuartzComposer data type however a struct is recommended because you just need one output for multiple values. On the receiving layer side, you will need a corresponding “tvIn_Shared_” input with the very same data type. Please note the receiving layer needs to be on top of the sending layer in the layer stack.

The sharing of values is useful if you need the same data in multiple layers (e.g. the name of the Home and Guest opponents in a game).

Type Definitions (aka. Naming Conventions)

Key	Type	Description
*_TypeAudio	Image	This is a very special case: A _TypeAudio can only assign sources that contain audio (e.g. Movie sources, Video sources or Audio Only sources). The layer will get control over this source (in the future) as well as the audio volume values for the left and right channels via the “_TypeAudioAudioLevel0” and “_TypeAudioAudioLevel1” inputs.
*_TypeBoinxX	Number	A number input in Boinx X Coordinates – e.g. -1 is the first pixel, 1 is the last pixel of the current screen dimensions. will be presented to the user in pixels
*_TypeBoinxY	Number	A number input in Boinx Y Coordinates – e.g. -1 is the bottom pixel, 1 is the topmost pixel of the current screen dimensions. will be presented to the user in pixels
*_TypeDirectoryPath	String	Resulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeDuration	Number	Time in seconds – will be displayed in minutes:seconds and can get a custom UI
*_TypeFilePath	String	Resulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeFontBoinxSize	String	Font size in Boinx Y Coordinates (e.g. 2 is the full-screen height), see note below
*_TypeFontColor	Color	Regular color input to specify a text color, see note below
*_TypeFontName	String	This will result in a font chooser, see note below
*_TypeMultiline	String	A multiline text field that permits entering of return
*_TypePassword	String	Displays a password-text-box. Important: The Password itself is stored in plain text and readable in the document!
*_TypeSignal	Boolean	For a single-frame pulsed signal, use the Pulse or Watcher patches

*The _TypeFontName, the _TypeFontBoinxSize and the _TypeFontColor field are combined into one Font Chooser UI element in the layers parameter view if they have the same base label.

Filter Templates

Those inputs and properties are specific for if you are creating a Quartz Composition to use as an image filter in mimoLive. Most of the previous definitions apply to filters also.

Filter Inputs

The following input fields are required by Quartz Composer for a filter composition:

Name	Type	Description
_protocolInput_PreviewMode	Bool	Can be used to tell the composition that it is in preview mode
_protocolInput_X	Number	Is always 0.
_protocolInput_Y	Number	Is always 0.

Filter Properties

The following properties are defined by mimoLive. tv_FilterIdentifier and tv_FilterVersion are required to handle the filter and its update path with newer versions:

Name	Type	Sample Value	Description
tv_FilterIdentifier	String	com.boinx.mimoLive.layer.placer	For identification, Boinx shipped compositions and sorted different versions
tv_FilterVersion	Number (double)	1	For matching different versions of a composition in a document/application. Major version numbers denote incompatibility and don’t match with other major versions. Minor version numbers must be upwards compatible and increment by 0.001 each iteration. E.g. it must be ensured that loading settings from a 1.0 layer for a 1.013 must look exactly the same, which means new keys if present need to have a default that does not show them or equals the look of the previous version.
tv_FilterOutputIsOpaque	BOOL		Determines if a filter output is opaque. Default is NO

Enumerations

The Quartz Composer type Index allows for named indices. They can be edited in the Quartz Composer Editor by adding an input splitter in index mode.

Source Type

The source will be one of the following values

– 0 – Image
– 1 – Movie, a movie will have a remaining time
– 2 – Camera, also might be a composition

Transition Direction

You can define your own directions. The shipped layers are using the following values.

– None
– Left
– Right
– Up
– Down

Transition Type

You can define your own transition types. Here are some useful example values.

– Dissolve
– Wipe

Tally States

There are several Tally States for video sources defined which will be represented in the UI and the Tally Light companion app.

– 0 = TVTallyStateOff
– 10 = TVTallyStateInUse
– 20 = TVTallyStatePreview
– 30 = TVTallyStateEffect
– 40 = TVTallyStateProgram