mimoLive 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 mimoLive. To work with mimoLive, the Quartz Compositions must contain certain elements so that mimoLive and the layer can talk to each other and that the layer can display the media files mimoLive 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.
Purchasing a custom layer
If you do not want to dig into Quartz Composer yourself, let us do it for you. We have extensive experience creating layers for mimoLive, including data visualization such as stock charts, which you can leverage to create just the right layer for you. Please contact the sales department for details.
Creating a Custom Layer – Getting Started
Masterclass Coding layers for mimoLive
Pre-Requisitions
There are some pre-requisitions before you can start developing layers for mimoLive:
- You need to have a valid mimoLive license to test and run your layers in mimoLive.
- You need to have the Quartz Composer application by Apple installed. 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 mimoLive Layers in Quartz Composer starting with mimoLive 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 mimoLive. (Download the patch from here:[https://github.com/boinx/QCLua/releases )
- JSON Patch and OAuth Patch – There are two more custom patches that are currently only used in the Twitter layer. When customizing the Twitter layer you will need to download and install the patches before start editing.
Blank Layer Template
You can use our free Quartz Composition file as a starting point for your custom layers. It contains a basic set of inputs and outputs and the required properties you need to change in the “Edit Information” Dialog of Quartz Composer.
The Hello-World Example
As a first and easy example we are going to create a basic Quartz Composition and use it as a layer in mimoLive.
- Start Quartz Composer application
- Choose File ⇢ New Blank in the menu bar. You will get a new empty Quartz Composer document.
- 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.
- 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.
- 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.
- 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.
- Connect the Image output of the Image with String patch with the Image input of the Billboard patch.
- 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.
- Head back to the Editor window and right-click on the Image with String patch to reveal a context menu for it.
- 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.
- 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 mimoLive and will be presented in the parameters view on the left when the layer is selected in mimoLive.
- Open the Composition Information Sheet by selecting Editor ⇢ Edit Information…. You will get a sheet with a list of key value pairs.
- 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.
- Enter tv_LayerProtocolVersion as the Property, switch the Class option from ‘‘String’‘ to ‘‘Number’‘ and put a ‘‘1’‘ into the Value column.
- Click the Done button in the lower left corner to close the sheet.
- Save this composition to your Desktop with the name Hello World.qtz
- Start mimoLive, don’t create a document yet.
- Select File ⇢ Import Layer Compositions… from the menu bar. You will be prompted by a File chooser dialog. Please select the Hello World.qtz file previously saved to the Desktop.
- Now create a new mimoLive document with File ⇢ New…. The mimoLive Template Chooser will show up.
- Select the Blank template and hit the Choose button in the lower right corner. A new mimoLive Document window will show up containing a single Placer layer rendering yourself sitting in front of your computer.
- Open the Layer Repository by clicking on the “+” button in the top right corner of the Layers column.
- 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.
- Find your self defined input called My Text and change the text of the input field.
- After clicking the Live button of that layer your text will appear over the video.
Congratulations! You just created a new mimoLive layer! In the following sections we want to go into the details whats necessary to be a good mimoLive 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.
Handling layers in mimoLive
Exporting a layer from mimoLive
If want to change a build-in mimoLive layer you can export that layer in mimoLive by the following steps:
- Open the layer repository with the “+” button at the top right corner of the Layers column.
- Find and select the layer you want to use as a base for your new layer.
- Open the context menu by right-clicking on that layer.
- Select Export Layer Composition… in that context menu.
- You will be asked to enter a file name and to set a location where to save the layer.
Importing a layer in mimoLive
Once you are done editing or creating your custom layer you have to import your layer into mimoLive. There are several ways of importing a layer into mimoLive:
Importing a layer using the File menu
- Select File ⇢ Import Layer Compositions….
- You will be prompted by a File chooser dialog.
- Please select you QuartzComposition file and hit “Import”
Importing a layer using the file name extension “.tvlayer”
This technique is useful when sending out custom layers to other mimoLive users (e.g. your clients) who are not familiar with manually importing custom layers. It isn’t very handy while in development though, because QuartzComposer won’t open the file when changing the extension of it.
- Find your composition in Finder.
- Click on the file name once to change the name of the file. A box around the filename indicates that you about to change it.
- 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.
- Double click the composition file. Now mimoLive will open and import the file as new layer automatically. It will notify you with a alert upon success.
Custom Layer API
mimoLive expect the Quartz Compositions to adopt the Custom Layer API. In this section you will learn the minimal implementation.
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).
Name | Type | Sample Value |
---|---|---|
tv_LayerProtocolVersion | Number (real) | 1.2 |
tv_LayerIdentifier | String | com.example.layer.mylayer |
tv_LayerVersion | Number (real) | 1.01 |
It is important to know how those values are used by mimoLive so that mimoLive 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 mimoLive versions are able to tell the user if a layer is used (e.g. stored in a mimoLive document) that has a newer protocol version and therefore may not treated correctly by mimoLive.
- tv_LayerIdentifier: This value should be a unique value to each of your layers. Our layers have the prefix com.boinx.layer.*. Please use your own scheme in order to have unique identifiers all over the world. Please note that mimoLive don’t use the file name to compare layers!
- tv_LayerVersion: If mimoLive 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 mimoLive will treat the layer as an incompatible replacement and won’t update the document layer!
Common Property additions
- copyright:
- description:
- name:
- tv_Tagline: