BoinxTV can be customized by adding new layers. The real power of layers lies in the fact that they are actually made with a MacOS X technology called Quartz Composer. Almost anything is possible with Quartz Compositions. You can create interactive TV shows where your audience can send in SMS or twitter messages which are displayed on screen. Create stock charts from online data. Keep scores in a sports match. Play games on screen. You may find inspiration in some of the layers included with BoinxTV. To work with BoinxTV, the Quartz Compositions must contain certain elements so that BoinxTV and the layer can talk to each other and that the layer can display the media files BoinxTV sends to it. In theory, anyone can make their own layers. This page describes on a technical level how to create layers using Quartz Composer.

If you do not want to dig into Quartz Composer yourself, let us do it for you. We have extensive experience creating layers for BoinxTV, including data visualization such as stock charts, which you can leverage to create just the right layer for you. See the BoinxTV web pages for details.

There are some pre-requisitions before you can start developing layers for BoinxTV:

• You need to have a valide BoinxTV license (either Home or regular) to test and run your layers in BoinxTV.
• You need to have the Quartz Composer application by Apple. It's a free development tool you can download at the developer website of Apple. However you will need to register as a Mac Developer first (http://developer.apple.com). Here you can find The Quartz Composer User Guide by Apple.
• Lua Patch – You'll need the Lua patch to open BoinxTV Layers in Quartz Composer starting with BoinxTV 1.9. It is open source and available from GitHub. We use this patch as a replacement for the QuartzComposer JavaScript patch because it doesn't run stable in BoinxTV.

As a first and easy example we are going to create a basic Quartz Composition and use it as a layer in BoinxTV.

1. Start Quartz Composer application
2. Choose File ⇢ New Blank in the menu bar. You will get a new empty Quartz Composer document.
3. Open the Patch Library with the button in the top left corner. A little window will popup with a list of all the Quartz Composer patches.
4. In the Patch Library find the Patch named Billboard. You can do so quickly by typing in some leading letters of the patch name in the search field at the bottom of the Patch Library window. This is a Render Patch. It draws an image flat on the output screen.
5. Drag the patch from the library to your blank editor window. The patch will stick there where you drop it. You are able to move it around by click-dragging it. Please note: The patch has several inputs that are marked with a connection dot on the left side of each value.
6. Now find the Image with String patch in the Patch Library and drag this over to your editor window. Position it on the right side of the Billboard patch. The Image with String patch is a Generator patch that will generate an image containing a text you can specify with the input value String.
7. Connect the Image output of the Image with String patch with the Image input of the Billboard patch.
8. If the Quartz Composer Viewer isn't visible right now, click on the Viewer button in the top right corner. You should see a window with a checkerboard in the background and “Hello World!” in white letters above it.
9. Head back to the Editor window and right-click on the Image with String patch to reveal a context menu for it.
10. Select Insert Input Splitter ⇢ String of that context menu. A new patch of type Input Splitter will appear on the document which is connected by its output to the input String of the Image With String patch.
11. Again right click on this newly created input splitter and select Publish Inputs ⇢ Input. A text box is popping up and asking for name for this published input. Change it to My Text. Please note that this published input is visible to BoinxTV and will be presented in the parameters view on the left when the layer is selected in BoinxTV.
12. Open the Composition Information Sheet by selecting Editor ⇢ Edit Information…. You will get a sheet with a list of key value pairs.
13. Add a new key by clicking the + button at the bottom left. A new line will appear in the list asking for a key name.
14. Enter tv_LayerProtocolVersion as the Property, switch the Class option from String to Number and put a 1 into the Value column. (Please read Minimal Implementation down below for more information about this entry)
15. Click the Done button in the lower left corner to close the sheet.
16. Save this composition to your Desktop with the name Hello World.qtz
17. Start BoinxTV, don't create a document yet.
18. Select File ⇢ Import Layer Compositions… from the menu bar. The Layer Composition Importer window will pop up.
19. Skip the steps 1 and 2 and click on the Choose Compositions… button of step 3. You will be prompted by a File chooser dialog. Please select the Hello World.qtz file previously saved to the Desktop.
20. The Importer will show you some warnings in orange in its import log at the bottom of the window but should indicate the successfully imported by a green line reading Imported Hello World.qtz
21. Now create a new BoinxTV document with File ⇢ New with Template…. The BoinxTV Template Chooser will show up.
22. Select the Blank template and hit the Choose button in the lower right corner. A new BoinxTV Document window will show up containing a single Placer layer rendering yourself sitting in front of your computer.
23. Open the Layer Repository by clicking on the Layers button in the lower left corner.
24. Find the Hello World layer you just imported and drag an instance to the top of the layer stack in the middle of the document.
25. Find your self defined input called My Text and change the text of the input field.
26. After clicking the Live button of that layer your text will appear over the video.

Congratulations! You just created a new BoinxTV layer! In the following sections we want to go into the details whats necessary to be a good BoinxTV citizen.

Please note, that we can't explain how to use Quartz Composer Editor in all details in this documentation. If you want to learn more about Quartz Composer please read The Quartz Composer User Guide at the Apple Developer website.

If want to change a build-in BoinxTV layer you can export that layer in BoinxTV by the following steps:

1. Open the layer repository with the Layer button in the lower left corner.
2. Find and select the layer you want to use as a base for your new layer.
3. Open the context menu by right-clicking on that layer.
4. Select Export Layer Composition… in that context menu.
5. You will be asked to enter a file name and to set a location where to save the layer.

Now that you exported a BoinxTV layer you are able to modify it with the Quartz Composer app by Apple.

Once you are done editing or creating your custom layer you have to import your layer into BoinxTV. There are several ways of importing a layer into BoinxTV:

1. Select File ⇢ Import Layer Compositions…. The BoinxTV Layer Composition Importer window will show up.
2. In the Step 1 you can choose wehter the layer should be available only for this user (then the layer will be installed into the users folder) or for all user on this computer (then the layer will be installed into the system folder).
3. The Step 2 let you add categories to your composition. If you had already set the categories within the composition with the tv_categories property you don't need to add them here again.
4. Now you can either drag&drop the file to the drop zone in Step 3 or select the Choose Compositions… button (you have to select you file in the file chooser). The import will start right away.

At the bottom of the window you will see an Import Log which tells you if anything worked out or if BoinxTV is missing something from the layer protocol. Warnings are marked in orange. Failure is show in red. Success is green.

Please restart BoinxTV in order to make the imported layer appear in the layers repository.

This technique is useful when sending out custom layers to other BoinxTV users (e.g. your clients) who are not familiar with manually importing custom layers. It isn't very handy while in development thought, because QuartzCompose won't open the file anymore.

1. Find your composition in Finder.
2. Click on the file name once to change the name of the file. A box around the filename indicates that you can change it.
3. Add the extension .tvlayer at the end and hit Return. The Finder will ask you if you really want to change the extension. Please accept.
4. Double click the composition file. Now BoinxTV will open and import the file as new layer. It will notify you with a alert upon success.

Please restart BoinxTV in order to make the imported layer appear in the layers repository.

installqtz.zip

Because it is tedious to manually import your Quartz Composer Composition into BoinxTV to test it we developed a small AppleScript Droplet which copies the composition to the temp folder, renames it with the .tvlayer extension and installs it by opening it with BoinxTV.

Please restart BoinxTV in order to make the imported layer appear in the layers repository.

(Work in progress)

BoinxTV expect the Quartz Compositions to adopt to the Layer Protocol for BoinxTV layers. In this section you will learn the minimal implementation.

The minimal implementation of the Layer Protocol involves only Quartz Composition Properties which can be edited in the Quartz Composer editor by selecting Editor ⇢ Edit information (⌥⌘I).

You only have to add these keys to the property list:

It is important to know how those values are used by BoinxTV so that BoinxTV can handle layer version conflicts.

• tv_LayerProtocolVersion: When ever we change the Layer Protocol we are going to increase the layer protocol version. With this older BoinxTV versions are able to tell the user if a layer is used (e.g. stored in a BoinxTV document) that has a newer protocol version and therefore may not treated correctly by BoinxTV.
• tv_LayerIdentifier: This value should be a unique value to each of your layers. Our layers ha the prefix com.boinx.layer.*. Please use your own scheme in order to have unique identifiers all over the world. Please note that BoinxTV don't use the file name to compare layers!
• tv_LayerVersion: If BoinxTV is finding the layer version differently for a layer that is stored in a document to the layer that is installed in the layers repository it uses the following rules to decide what to do:
  • If the document layer version is more than the repository: keep the document version
  • If the document layer version is less than the repository, but the same major number (e.g. 2.4 vs 2.6) then replace the document layer with the new one.
  • If the layer version major number is differently then BoinxTV will treat the layer as an incompatible replacement and won't update the document layer!

• copyright:
• description:
• name:
• tv_Categories:
• tv_SortKey:
• tv_Tagline: