mimoLive® - User Manual

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors

Manual – Table of Content

Custom Layer API

Table of Contents

Protocol Version 1.2


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.


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

NameRequiredTypeSample Value
copyrightString© 2016 MySoftwareCompany
descriptionStringPlays a fullscreen input
nameyesStringFullscreen Player
DEPRECATED tv_CategoriesStringBackdrop,Fullscreen
tv_FileData_ input name-Data(imported XML file)
tv_FileName_ input name-StringStandings.xml
tv_HiddenInputKeysArray of Strings
tv_InputLabel_ input name-StringVideo Input
tv_LayerVersionyesNumber (real)1.01
tv_LayerPreviewData(imported PNG file)
tv_LayerProtocolVersionyesNumber (real)1
tv_StepSize_ input name-Number (real)0.1
DEPRECATED tv_TaglineStringPlays a fullscreen input
tv_UnitLabel_ input name-String


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.


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


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


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



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


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


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


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


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.


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


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


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


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.


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.


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


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.


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


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


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.


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.


tvIn_InTransitionDirectionIndex Transition Direction Direction
tvIn_InTransitionTypeIndex Transition Type Type
tvIn_OutTransitionDirectionIndex Transition Direction Direction
tvIn_OutTransitionTypeIndex Transition Type Type
tvIn_ResetBoolean (Signal)
tvIn_Shared_any value type
tvIn_SwitchBoolean (Signal)
tvIn_TransitionDirectionIndex Transition Direction Direction
tvIn_TransitionTypeIndex Transition Type Type
tvIn_VideoSourceA B C DImage





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.


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.


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.


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


A direction in which the Transition Direction will be performed.


A value in seconds the tvIn_InTransitionType will be performed.


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






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.


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


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.


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


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


A value in seconds of the tvIn_OutTransitionType will be performed.


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


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


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.


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


See Sharing Values between Layers Values between Layers.


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


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


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.


A direction in which the Transition Direction will be performed.


A value in seconds of the tvIn_InTransitionType will be performed.


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


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)


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

AudioLevel0NumberLeft audio channel level in db after gain control
AudioLevel1NumberRight audio channel level in db after gain control
AudioLevel0RawNumberLeft audio channel level in db before gain control
AudioLevel1RawNumberRight audio channel level in db before gain control
DataStructA dictionary of metadata of the source. Currently, implemented keys are: “index” “duration” “title” “titleFallback” “artist” “album” “year” “fileReferenceIdentifier”
NameStringName 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 .
RemainingTimeNumberIn seconds. Will be provided for movie sources. -1 if the movie source is looped (or any other source).
TallyStateIndexTally State of the connected source, see Tally States States
TypeIndexValue 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).


tvOut_DoneBoolean (Signal)
tvOut_Share_any type
tvOut_TallyStateIndex of Tally States States
tvSet_Type of input to be set


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


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


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


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.


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


See Sharing Values between Layers .


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.


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.


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.


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.


See tvSet_ .


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.


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)

*_TypeAudioImageThis 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.
*_TypeBoinxXNumberA 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
*_TypeBoinxYNumberA 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
*_TypeDirectoryPathStringResulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeDurationNumberTime in seconds – will be displayed in minutes:seconds and can get a custom UI
*_TypeFilePathStringResulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeFontBoinxSizeStringFont size in Boinx Y Coordinates (e.g. 2 is the full-screen height), see note below
*_TypeFontColorColorRegular color input to specify a text color, see note below
*_TypeFontNameStringThis will result in a font chooser, see note below
*_TypeMultilineStringA multiline text field that permits entering of return
*_TypePasswordStringDisplays a password-text-box. Important: The Password itself is stored in plain text and readable in the document!
*_TypeSignalBooleanFor 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:

_protocolInput_PreviewModeBoolCan be used to tell the composition that it is in preview mode
_protocolInput_XNumberIs always 0.
_protocolInput_YNumberIs 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:

NameTypeSample ValueDescription
tv_FilterIdentifierStringcom.boinx.mimoLive.layer.placerFor identification, Boinx shipped compositions and sorted different versions
tv_FilterVersionNumber (double)1For 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_FilterOutputIsOpaqueBOOLDetermines if a filter output is opaque. Default is NO


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

Your Feedback

How would you rate your experience with this feature of mimoLive®?

Email Newsletter


Join the 24/7 Live Zoom® Demo


You need to load content from reCAPTCHA to submit the form. Please note that doing so will share data with third-party providers.

More Information