Protocol Version 1.2

Introduction

mimoLive uses Apple’s Quartz Composer technology and it’s 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 which 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 of 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 EditorEdit 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.

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 und 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 maybe 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 an 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 menat 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 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 be used to store an URL with help information 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 systems 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 identifying boinx shipped compositions and sorting 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 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 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, that 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 better experience than the default quicklook preview. Preview image should be 256 × 256 pixels.

tv\_LayerProtocolVersion

For future backwards 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 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 an 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]] and [[OAuth Patch in order to read data from 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 to high the frame count will jump over those dropped frame numbers.

tvIn\_FrameDuration

The frame duration is the time interval between each renderings 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 which lets the user choose the type of ingoing 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 refere 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 don’t need to render any output because a layer above will obscure it anyways by drawing full screen. This can be used to avoid heavy drawing by layers that aren’t visible but set to be live. (E.g. in 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 the tvIn\_OutTransitionType will be performed. Also see Transition Direction .

tvIn\_OutTransitionDuration

A value in seconds the tvIn\_OutTransitionType will be performed.

tvIn\_OutTransitionType

If useful for a layer which lets the user choose the type of ingoing 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 the tvIn\_InTransitionType will be performed.

tvIn\_TransitionType

If useful for a layer which lets the user choose the type of ingoing 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 guide lines 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 guide lines 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 meta data of the source. Current 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 preview or to calculating the default name for the layer variant. See tvOut_SettingName .
RemainingTime Number In seconds. Will be provided for movie sources. -1 if 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”. //Note: remove postfix “_Cursor” or “Cursor” from the 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 app that the layer currently needs the composited layers image input. mimoLive will put in the layers below composited image in the next render cycle. If “tvOut_UseCompositedLayersImage” isn’t present mimoLive assumes that the layers below 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 this output the 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 transfere 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 want 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 it self. The data is stored by mimolive by its sharing key until 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 story any QuartzComposer data type however a struct is recommended because the 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 contains audio (e.g. Movie sources, Video sources or Audio Only soruces). The layer will get control over this source (in the future) as well as the audio volume values for left and right channel 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 full screen height), replaced _TypeFontSize, which still works but is drawn with orange text
*_TypeFontColor String See above
*_TypeFontName String Will result in a font chooser, will combine _TypeFontColor and _TypeFontSize into it if there with the same label
*_TypeMultiline String A mutliline text field that permits entering of return
*_TypePassword String Displays a password-text-box. Important: The Password itself is stored plain text and readable in the document!
*_TypeSignal Boolean A single frame pulsed signal, use the Pulse or Watcher patches

Filter Templates

Those inputs and properties are specific for if you are creating a Quartz Composition to use it as a image filter in mimoLive. Most of the previously 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 identifying Boinx shipped compositions and sorting different versions
tv_FilterVersion Number (double) 1 For matching different versions of a composition in 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, that 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 opqaue. 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

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Please do not use this for support questions.
mimoLive Support

Post Comment