Creating your first quartz composition with Quartz Composer (for Mac)

Introduction

Serato Video allows you to display any compatible visual media file as the video part for your regular audio files.

On Mac OS systems, this includes Quartz Compositions.*

They are small visual programs which (usually) don't contain a video stream, but rather generate visuals. Quartz files can process information which they receive from the host application (Serato Video) and elsewhere like your webcam for example.

This article aims to get you started to create your own basic composition which will be compatible with Serato Video.

*Please note that Quartz technology is a core part of the Mac Operating System and is not available for Windows computers.

Step 1. Quartz Composer setup

This section will help you to set up your computer.

You can already play existing quartz files in Serato Video. If you don't plan on creating your own compositions you are already done. There are several user contributed examples on our forumSimply download them, import them into your Serato Library then drag them onto a video preview in Serato Video while an audio file is loaded to the virtual deck.

The really interesting part however is to create your own quartz compositions and to customize existing ones, so that you can show your own logo bouncing to the beat for example. To make and edit quartz files, you need to install the Xcode package, "Quartz Composer" in particular. It will install to /Developer/Applications/Quartz Composer.app. It is available for free, simply follow these instructions:

1. Go to the Apple Developer website here.

2. Sign in using your Apple ID. If you do not have a developer account, you will be taken through the process to sign up.

3. Once signed in, go to to the download section here.

4. Now select "Graphics Tools for Xcode" and download the .dmg file.

5. Run and install the Graphics Tools for Xcode package. 

6. Quartz Composer should now be available in Macintosh HD > Developers > Applications

Open up Quartz Composer. Select "Basic Composition" from the Template Chooser and hit "Choose". You are now ready to create your first quartz composition, but first we will cover the features in the main editing window.

 

Step 2. The Editor window

This section covers some basics to help you get familiar with the Quartz Composer workspace, the visual editor for quartz compositions.

The Header Menu

At the top of the window there is a header menu with several buttons:

  • Patch Library. Click to display your patch library browser. You can find existing patches in there, which you can simply drag into your composition for further use.
  • Zoom Levels. Use these to zoom in and out of the editor workspace.
  • Create Macro. A combined patch made up of multiple sub-patches. We'll go further into this in the advanced tutorial.
  • Edit Parent. Step out of a macro patch.
  • Add to Library. You can add/save a composition to your patch library so that it is available easily in future projects.
  • Parameters. Edit the input parameters of your composition on the fly. This is good for testing and modifying. We'll cover it in more detail later.
  • Patch Inspector. Click on a patch and select the patch inspector to edit it. Again, we will dive into this in the advanced tutorial.
  • Viewer. Toggles the output preview window. This viewer window lets you see your quartz composition in action. Usually you want to have both the editor window and the preview window open to see the changes made as you work on your composition.
The main Editor area

Underneath the header menu is your workspace, the main editor area. There are three types of patches that can be added to this space: Purple, black and blue patches.

  • Purple patches: "Provider". They feed information from somewhere into your Quartz composition.
  • Black patches: "Processor". They receive information from somewhere, do something with it, and feed it further down the processing path.
  • Blue patches: "Consumer". They receive information and display it to your screen in some way.

Data flows from left to right. At the right end of each path, there should usually be a blue patch, which will draw to the preview window in Quartz Composer.

Quartz files don't have pixel dimensions. Instead, all measures are relative. The visual area can be seen as three-dimensional space, where each dimension is infinite. The visible area on the X and Y axis goes from -1 to +1, so (0,0) is the center of the screen.

Connecting patches

You can connect patches with each other. A connection is represented by a yellow, orange or red line. Simply drag from a white dot on the right side of a patch to one on the left side of another patch. The color of the resulting line tells you if the outgoing data is what the consuming patch expects.

  • Yellow: The outgoing patch sends a data type which the consuming patch understands natively. An example would be if you provide the song title to a patch that expects text input. This is an acceptable link.
  • Orange: The consuming patch has to convert the data somehow, but likely understands it. An example would be providing the BPM of a song (a number) where ASCII text is expected. This is an acceptable link, but some other patch configurations might need to change in order for it to work.
  • Red: This will most likely not work. An example would be if you forward the song title but an image is expected. This is an unacceptable link.

One output can be fed to multiple inputs, but one input can always only receive one signal at a time.

Add a Composition to your Patch library

If you create lots of compositions, you may find certain patterns that you use regularly. You can save them as individual files and store them in your patch library with the "Add to Library" button in the header menu. They will then be available as part of your patch library for future projects.

Just make sure to publish the inputs and outputs that you would require for future compositions.

Step 3. Creating your first Quartz Composition

Lets get started creating your first Quartz Composition. If you haven’t already done so, open up Quartz Composer and select "Basic Composition" from the Template Chooser.
This will give you a blank workspace, and opens up the "Viewer" window. You will notice there is already one 'Consumer' patch in your workspace, called "Clear". This Clear patch gives you the 'black background' in your quartz composition. Click on that Clear patch (it will highlight with a yellow border) and select "Parameters" from the header menu; this will display the parameters for your selected patch. In the parameters bar, If you uncheck "enable" on this patch, you will notice that the black screen disappears and your viewer is now filled with grey and white checkers. This means that there is nothing outputting from Quartz Composer, as the checkers represent a transparent value (there is nothing to display).
Its good to have this Clear patch in your composition, as it acts as a background to your image allowing a nice blank canvas for you to design your composition on. So lets keep this enabled for now.

Video Input

Time to add an input. It is very easy to display the image of your computer's webcam in Quartz Composer. All you need to do is to connect a Video Input patch to a consumer patch.


Head up to the top left hand side of the header menu and select "Patch Library". This will open up the patch library browser menu. Since we know what we are looking for (Video Input) lets go ahead and enter in "Video Input" into the search bar. Click on Video Input and drag it into your workspace. As this is an Provider patch, you will notice it is purple in colour. A webcam (plus some image filters) can be a good source for random images, which play nicely with any music.
Alternatively you could use an Image provider patch to display an image file instead of the Video Input.

Outputting an Image

You will notice that the video input is not being displayed at this stage because we have not connected our Provider patch with a Consumer patch to get an output. So lets add a consumer patch.

Go back to your Patch Library and type in "Billboard" into the search box. A Billboard is the easiest way to display something. It is simply used to draw a given image to your screen. A billboard lets you:

  • Scale it by editing the width/height parameter.
  • Rotate it by editing the rotation value
  • Change the blending (what is visible from other visible objects on lower layers)
  • Move it (x and y position)
  • and more

Bring the Billboard patch into your workspace and connect the two. Click on the "Image" dot from the right-hand side of the Video Input patch, and connect it to "Image" on your Billboard patch. You will notice that this connection becomes yellow (a sign of a acceptable connection) and your Viewer outpurt window will now display your webcam input.

Congratulations you have now created your first quartz composition! Your webcam feed is now being fed through the quartz composition and outputting through the viewer. If you save this as a .qtz file and load it into your Serato Video preview window your webcam feed will now be displayed.
You may notice that the size of the video output stream is quite small. If you click on the Billboard patch and click on "Parameters", you can adjust the attributes of the output. Remember that the quartz pixels are square in shape, so any size adjustments you make will be relative.