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

Download Layer Template v1.0

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.

  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 mimoLive and will be presented in the parameters view on the left when the layer is selected in mimoLive.
  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.
  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 mimoLive, don’t create a document yet.
  18. 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.
  19. Now create a new mimoLive document with File ⇢ New…. The mimoLive Template Chooser will show up.
  20. 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.
  21. Open the Layer Repository by clicking on the “+” button in the top right corner of the Layers column.
  22. 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.
  23. Find your self defined input called My Text and change the text of the input field.
  24. 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 by 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 by 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 thought, because QuartzCompose won’t open the file anymore 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.

Importing a layer by AppleScript Droplet

installqtz.zip
Because it is tedious to manually import your Quartz Composer Composition into mimoLive 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 mimoLive.

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:

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Post Comment