User Tools

Site Tools


layer_protocol_for_boinxtv_layers

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.

If you want to learn how to create custom layers with Quartz Composer, please read Creating Custom Layers for BoinxTV.

Properties

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

Name Required Type Sample Value
category String
copyright String © 2013 My software company
description String Plays a fullscreen input
name yes String Fullscreen Player
protocols yes Array com.boinxtv.protocol.layer
tv_Categories yes String Backdrop,Fullscreen
tv_Debug Boolean
tv_FileData_<protocol input name> Data
tv_FileName_<protocol input name> String
tv_InputLabel_<protocol input name> String Video Input
tv_LayerIdentifier yes String com.example.layer.mylayer
tv_LayerVersion yes Number (real) 1.01
tv_LayerPreview Data
tv_LayerProtocolVersion yes Number 1
tv_SortKey String
tv_StepSize_<protocol input name> Number (real) 0.1
tv_Tagline yes String Plays a fullscreen input
tv_UseAudioFromSource String A
tv_UnitLabel_<protocol input name> String pixel

category

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

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.

  • 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. WeatherMap? , 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_<protocol input name>

A data blob that will be created and written into the document for a file input on layer creation.

tv_FileName_<protocol input name>

The corresponding filename to the tv_FileData_<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.

Inputs

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_AccountTwitterConsumerSecret

tvIn_AccountTwitterTokenKey

tvIn_AccountTwitterTokenSecret

tvIn_CalculateSuggestions

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_InTransitionDirection

A direction in which the tvIn_InTransitionType will be performed. Also see Transition Direction.

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.

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

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_TransitionDirection

A direction in which the tvIn_TransitionDirection will be performed. Also see Transition Direction.

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.

tvIn_VideoSourceAImage

A layer can have up to three dynamic image inputs: A, B and C. If this input is present an input will be available.

tvIn_VideoSourceAType

A value of source type.

tvIn_VideoSourceAName

A human readable string of the tvIn_VideoSourceAImage. Might be a source name or a file name.

tvIn_VideoSourceARemainingTime

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

tvIn_VideoSourceBImage

A layer can have up to three dynamic image inputs: A, B and C. If this input is present an input will be available.

tvIn_VideoSourceBType

A value of source type.

tvIn_VideoSourceBName

A human readable string of the tvIn_VideoSourceBImage. Might be a source name or a file name.

tvIn_VideoSourceBRemainingTime

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

tvIn_VideoSourceCImage

A layer can have up to three dynamic image inputs: A, B and C. If this input is present an input will be available.

tvIn_VideoSourceCType

A value of source type.

tvIn_VideoSourceCName

A human readable string of the tvIn_VideoSourceCImage. Might be a source name or a file name.

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.

Outputs

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.

tvOut_hide_<protocol input name>

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

Type Definitions (aka. Naming Conventions)

Key Type Description
*_TypeFilePath String Resulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeDirectoryPath String Resulting in a “Choose…” button in the UI, maybe also displaying a path control
*_TypeFontName String Will result in a font chooser, will combine _TypeFontColor and _TypeFontSize into it if there with the same label
*_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
*_TypeDuration Number Time in seconds - will be displayed in minutes:seconds and can get a custom UI
*_TypeSignal Boolean A single frame pulsed signal, use the Pulse or Watcher patches
*_TypeMultiline String A mutliline text field that permits entering of return
*_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
*_TypePassword String Displays a password-text-box. The Password itself stays readable in the document! New in BoinxTV 1.2

Filter Templates

Those inputs and Properties are specific for if you are creating a Quartz Composition to use it as a image filter in BoinxTV.

Inputs

Name Type Comment
_protocolInputPreviewMode | Boolean | Can be used to tell the composition that it is in preview mode | | _protocolInputX Number Will be hidden from the user and gives the posibility to click into the image to set this, in Quartz Comoposer Coordinates
_protocolInput_Y Number Will be hidden from the user and gives the posibility to click into the image to set this, in Quartz Comoposer Coordinates

Properties

Name Type Sample Value Comment
tvFilterIdentifier | String | com.boinx.boinxtv.layer.singlevideo | For identifying Boinx shipped compositions and sorting different versions | | tvFilterVersion 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 (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.

  • Dissolve
  • Wipe
layer_protocol_for_boinxtv_layers.txt · Last modified: 2015/09/19 08:00 by achim