This guide is the instruction manual for my motion-activated audio player software, Video Trigger.
(Click the link for screenshots, features, and latest download.)
Camera
You’ll need a stationary camera (tripod recommended). 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.
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.
Getting Started
On the left side 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 why this is handy! If your movie has audio, you can enable/disable it here.
Sound Settings…
Select your sound hardware here. We’ll assign zones to specific sound channels later…
Script Settings…
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 “simple_beep.scpt” to get things started. It just makes the default system alert sound whenever it runs. 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!
MIDI Settings…
Each zone can send a MIDI note whenever occupancy is detected. Use this to launch clips in Ableton Live, send a trigger to your DAW, or just make music notes with the MacOS built-in synth!
Select your MIDI Device on top, then choose channel number, MIDI note number, and velocity (0-127) for each zone. The duration of each note can be adjusted, or you can make it sustain until the zone is exited.
Note: In Ableton Live’s MIDI prefs, make sure the “Track” and “Remote” boxes are checked for the “from Video Trigger” MIDI device, otherwise your notes won’t show up in the MIDI Mapper!
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.
Setting Up A Zone
- First, memorize the background
- Click on the options panel for a zone. (It will turn green.) Then click and drag in the video window to draw a rectangle. Movement within that numbered zone will trigger playback of the corresponding file. Adjust the sensitivity to accommodate different lighting and contrast.
- Load a sound file for each zone. You can use most file formats (MP3, AAC, AIFF or WAVE). They can be mono, stereo, or up to 16 channels interleaved. 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).
- Use the checkbox to optionally loop the sound in each zone.
Route the sound file to your playback hardware 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. Bright dots indicate connections between the file and the hardware.- You can define the “logic” of the sound playback using the drop-down menus. There are separate options for entering and exiting the zones, so many behaviors are possible. You can even reverse the logic so the sound plays when nobody is in the zone, but stops when they enter it.
- The default 5 msec fade-in/fade-out will prevent clicks in your audio, but you can extend it much longer if you want.
Preferences & Auto-Starting
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).
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).
GPL License
Video Trigger 2008 – 2018 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 http://www.gnu.org/licenses/gpl-faq.html 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. http://cycling74.com/download/Share/JeremyBernstein/shellUB.zip License is unknown, but source files are included in the app package.
The software was developed in the (non-free) Max visual programming environment (http://www.cycling74.com) which is required if you want to edit the source code. My application contains the Max “Runtime” environment, which is not GPL, so my license pertains to my contributions only.
Change Log
2018-11-13 (November 13, 2018)
- Recompiled using Max 8 to make it more compatible with recent MacOS versions.
- Zones can now send MIDI notes, to launch clips in Ableton Live, etc.
2018-08-20 (August 20, 2018)
- Recompiled using Max 7 to make it more compatible with recent MacOS versions.
- No longer needs JAVA (hooray!)
- Now plays compressed formats (mp3, AAC)
- Added elapsed time counter for each zone’s audio player
- Minimum fade in/out time is now 5 msec (was 10)
- Enter/exit behavior can now be swapped (so playback can stop when zone is occupied, and continue when zone is exited)
- If using a movie as an input source, the audio can be optionally muted
- Fixed: output routing matrix is no longer cleared every time you load a soundfile (only clears when you load a file with a different number of channels than the last one)
- Fixed: script triggering was broken in recent OS versions
- Fixed: updated online docs URL for recent website redesign
- Lots of internal code cleanup to make patch easier to modify and update
- “simple_beep.scpt” Apple Script is included and ready to enable in the Script Settings
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…
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…
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.
