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