Table of Contents

Layer Protocol for BoinxTV layers

Protocol Version 1.2

Introduction

BoinxTV uses Apple's Quartz Composer technology and it's documents for the layers. Because BoinxTV 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 BoinxTV has to offer. In the following you find all the technical information of this protocol.

category

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

copyright

The copyright is usually set by Quartz composer and is not needed for BoinxTV 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 BoinxTV. Use a short und uniquie name to find your layer quickly.

protocols

This array must contain com.boinxtv.protocol.layer. If you started with a blank composition you need to use a property list editor to edit this key. If you export a layer from BoinxTV this value will be set.

tv_Categories

The categories are used to group and filter the layers. Use a comma separated list of the following predefined categories.

tv_FileData_<protocol input name>

tv_FileName_<protocol input name>

tv_InputLabel_<protocol input name>

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. tvInputLabeltvIn_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. 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_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 174 × 98 pixels.

tv_LayerProtocolVersion

For future backwards compatibility if BoinxTV changes the protocol significantly. Currently must be set to 1.

tv_SortKey

Defines the sorting of the collection view. So you can sort the filters by probability of use. Currently a scheme of 2 uppercase letters is used, eg. BM, DE, DM, etc.

tv_StepSize_<protocol input name>

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

One line string that will be displayed beneath the name in the layer template list.

tv_UseAudioFromSource

Use either A, B, C or leave empty. If not provided BoinxTV assumes that no audio will be used with this layer.

tv_UnitLabel_<protocol input name>

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.

tvIn_AccountTwitterConsumerKey

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

tvIn_InTransitionDirection

tvIn_InTransitionDuration

tvIn_InTransitionType

If useful for a layer which lets the user choose the type of ingoing transition. Also see Transition Type.

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_OutTransitionDuration

tvIn_OutTransitionType

If useful for a layer which lets the user choose the type of ingoing transition. Also see Transition 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 BoinxTV.

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 is set instead to maintain compatibility with older layers.

tvIn_VideoSourceCType

tvIn_VideoSourceCName

tvIn_VideoSourceCRemainingTime

Remaining time in seconds if tvIn_VideoSourceCType is Movie. Most provided compositions send the done signal if a remaining time reaches 0.0.

<ImageInputKey>Name

Every Image input get an additional input of inputs of <ImageInputKey>Name that will give the filename of that input for use in the composition (e.g. as Setting Name Output).

Grouping Inputs

Grouping is provided in the user interface - for that the prefix of the input is relevant. Syntax works like tvGroup_<groupname>__<your input name>. A special group is defined for inputs that should always be hidden: tvGroup_Hidden_Inputs__<your input name> This group can be made visible by switching BoinxTV into debug mode in the Debug Preferences.

Hide Inputs Dynamically

Every Protocol Input is hidden if the tvOuthide<protocol input name> Output is set to true. This is observed in the application and can be changed dynamically. Note that you need to set the full input name, including tvIn, otherwise non protocol inputs could not be hidden. E.g.: use the output tvOuthidetvInText for the input tvInText.

tvOut_CalculatingSuggestions

True while calculating suggestions, false when values are ready to be read.

tvOut_Done

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

tvOut_IgnoresCompositedLayersImage

Tells app to ignore composited layers image input.
Used for optimizing performance when using layers below with transitions etc. Only drawing optimization, all media will be rolled nevertheless. Only used if tvIn_CompositedLayersImage is present.

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_RollVideoSourceA

Composition needs images on video source. Default true.

tvOut_RollVideoSourceB

Composition needs images on video source. Default true.

tvOut_RollVideoSourceC

Composition needs images on video source. Default true.

tvOut_SettingName

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

tvOut_Suggest_

Compositions can suggest useful input values depending on the input values. These should be calculated when tvIn_CalculateSuggestions is set to true, and when finished calculating the tvOut_CalculatingSuggestions should be set to false.

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.

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 (was: com.boinx.boinxtv.filter.hasAlpha)

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.