Video Trigger Guide

Before You Begin… You Need:

Camera & Tripod

See the camera compatibility page for supported cameras and video input devices. You must use manual exposure if you want Video Trigger to be reliable! It will work with auto exposure, but if something bright enters the frame then the camera will automatically darken the image. Then all of your motion-detector zones will trigger and you will be unhappy.


The software was developed on Mac OS 10.6, but will probably work fine on other Mac OS versions. The slowest machine that I have tested is a Mac Mini with a single 1.8GHz processor. Keep in mind that multichannel sound requires a lot of disk access though.

Steady Lighting

Performance is only as reliable as your lighting. If you turn off all the lights then you will trigger all of your zones. However, there is an “adaptive background” mode that compensates for slowly-changing lighting. See “Background Image Settings” below. If you absolutely can’t control your lighting, consider using infrared. Some webcams can be modified to respond to IR instead of visible light. Then you can illuminate your area with IR LEDs and thus control your lighting.

Sound Files

AIFF or WAVE format, NOT MP3. These files can be mono, stereo, or up to 16 channels interleaved. VideoTrigger will give you the opportunity to map any channel of each sound file to any output on your sound hardware. If you’re wondering how to get 3 or more channels packed into one AIFF file, I’ve had great luck with SoundFilesMerger from Emmanuel Jordan (free, but you should donate if you like it).

How to Use Video Trigger

Basically, you memorize the background and draw “zones” over the live video from the camera. Each zone has an options panel where you load a sound file, choose your outputs, and define the logic of the playback. (When somebody enters the zone should the sound play from the beginning, resume from pause, etc.) There are separate options for entering and exiting the zones, so many behaviors are possible. I think the basic options are self-explanatory, but here are some important details…

Preliminary Setup… In the lower left corner you’ll see buttons for Video, Sound, and Script settings.

Video Settings…

Image Resolution: Use the lowest resolution that is practical for your project because larger sizes result in slower performance. I usually use 160 x 120 or 320 x 240.

Input Source: Choose Camera, Syphon, or Movie.

Camera: The first camera connected to your system is usually selected by default, and you can select other cameras using the drop-down menus.

Syphon: Syphon is a framework that enables realtime sharing of video data between compatible applications. You can choose a feed from any Syphon server using the drop-down menus.

Movie: You can record the current video input to a file and play it back later while you adjust the Video Trigger settings. If you’ve ever set up an interactive installation by yourself, you know what this means!

Sound Settings…

Select your sound hardware here. Then you can assign zones to specific sound channels using the “Choose Outputs…” button in each zone options panel. This opens a pop-up  “matrix” that shows the channels in the sound file horizontally, and the outputs of your audio hardware vertically. Red dots indicate connections which you can arrange to route the channels of your sound file to any or all of the hardware outputs.

Script Settings…

Video Trigger was designed to trigger sounds, but I’m slowly making it more universal. In this window you can define terminal commands and attach them to zones. Whenever a zone is entered or exited, your command will run in the UNIX shell. You can trigger an Apple Script or shell script, launch an application, open a file, etc.

To run an Apple Script, type: osascript /path/to/script.scpt

To open a file, type: open /path/to/your/file.txt

You can include spaces in the path names if you surround them with quotes, but you MUST put a forward-slash in front of each quote too:

open \”/path/to/your/file with spaces.txt\”

I included a few Apple Scripts to get you started: “simple_beep.scpt” just makes the default system alert sound whenever it runs. “play_a_movie.scpt” plays a movie of your choice in Quicktime Player whenever it runs, optionally returning to the beginning if the movie is already playing. Open these files in your Mac’s Script Editor to make changes. Search the web for more things you can do with the Apple Script or the terminal, but be careful because some terminal commands can delete things or cause other damage!

Background Image Settings

Video Trigger detects motion by comparing each live video frame with a stored background image. If they match then nothing gets triggered. If they mismatch enough then a zone gets triggered.

Use “Manual” mode if your lighting is very controlled. Clear the area in front of your camera and press “Memorize Now”. The background image is now stored, and Video Trigger is comparing the video input to the image, looking for differences.

Use “Adaptive” mode if your lighting will change (as day turns to night, clouds block the sun, etc.) In this mode, frames from the live video input are averaged together to form a slowly changing background image which is tolerant of changes in lighting. Theoretically, if somebody occupies a zone for a few minutes they will become part of the background image, but adaptation is bypassed whenever a zone is occupied, so it shouldn’t be a problem.

Panic Button!

If you want the whole thing to shut up, press the green “Triggers ENABLED” button on the screen, or press the Esc key. None of your settings will be effected, but all sounds will stop and zones won’t trigger until the button is pushed again.


Video Trigger is designed for gallery installations where the computer will run all the time, or be turned-on daily. It makes sense to start Video Trigger from the Login Items panel in System Preferences/Accounts/(your username). However, I’ve noticed that the OS launches login items before it is finished booting, so the app might initialize strangely. Launch the included Applescript instead, which will launch Video Trigger after a delay.


All settings are saved automatically to an xml preferences file as soon as you make changes. If you want to get really nerdy, you can edit the xml with any text editor (but Video Trigger doesn’t monitor changes in the xml while it’s running).

GPL License

Video Trigger 2008 – 2012 by Zach Poff. It is Free Software, released under a GPL 3.0 license. You are free to copy it, modify it, and redistribute your changes provided that all derivative products remain GPL licensed. The source files are included in the download. (See for details about this license.)

It contains Syphon external objects which have a separate BSD license (full details included in download). It also contains the “Shell” external object originally created by Bill Orcutt, later updated by Jeremy Bernstein. License is unknown, but source files are included in the download.

The software was developed in the (non-free) MAX6 visual programming environment ( which is required if you want to edit the source code. My application contains the MAX6 “Runtime” environment, which is not GPL, so my license pertains to my contributions only.

Change Log

Version 2013-03-28 (March 28, 2013)


  • Fixed a nasty bug that was preventing users from selecting any audio devices except “built-in audio”. Oops!

Known Bugs:

  • preferences problem for output channel routing: The first 2 channels of any audio interface will behave as expected (zones routed to these channels will still be routed there when the app is restarted). But, zones routed to channels 3 and higher will “forget” their routing when the application is restarted.
  • Same bugs as version below…

Version 2012-08-11 (August 11, 2012)


  • dropped support for PPC machines, now Intel-only
  • new capture resolution options
  • added master disable (panic button) which stops all triggers
  • added adaptive background option for environments with changing lighting conditions
  • optimized code for greater efficiency
  • changed user-interface a bit
  • added link to (this) online documentation
  • added syphon support
  • zones can now trigger Applescripts, open files, or anything else you can invoke from the Terminal (samples included)
  • fixed problem where zone 1 was always enabled at startup, even if prefs said it should be off
  • changed license to GPL3

Known Bugs:

  • Same bugs as version below…

Version 2009-01-10 (Jan 11, 2009) (First Release)

Known Bugs:

  • When you load a new sound file, the “Choose Outputs” screen will show no connections, but sometimes the old connections are still active. Choose new connections to override the old ones.
  • Sometimes if you choose the “Resume Playing” option while a sound is playing, it might not resume properly on the next trigger. Choose “Start Playing” and trigger it once. Then you can choose “Resume Playing” when it’s done.
  • “Video Hardware Settings” might show irrelevant information, but it will still work.