This guide is the instruction manual for my multi-channel video player software, MultiScreener.
(Click the link for screenshots, features, and latest download.)
How it Works:
There are two applications: MultiScreener Server and MultiScreener Client. The server broadcasts its current frame position over the network using multicast udp packets, so no knowledge of server/client IP addresses are required. Normally, the client will adjust its playback rate by tiny increments, smoothed over time to avoid audible pitch changes. If the server suddenly jumps to an unexpected frame (like when a loop occurs, or you manually scrub the server to a new frame), the client changes sync strategies: It immediately jumps to the server’s frame position and triggers the “Finding Frame” indicator. Afterwards, the client resumes the normal syncing method. If the Server pauses on a frame, the client will “hover” around that frame waiting to continue. If the server disappears, or the network breaks, the client will keep playing for a moment and then pause. When the server reappears, the client will re-sync to it immediately. (So clients and the server can be launched in any order, added and removed at will. It will just work.)
Installation:
Open the disk image, drag the MultiScreener folder into your Applications folder, and run the apps.
Permissions WARNING: In OS X, only the Administrator users can modify the Applications folder. This could cause a problem with MultiScreener: An admin user might install MultiScreener in the apps folder, but a non-admin user logs-in later and runs the apps. They would appear to work but they can’t save their preferences (because the prefs file lives in the same folder as the app). To prevent problems, I recommend running MultiScreener as an admin user, or putting it in a shared folder or the Desktop of the non-admin user who intends to run it.
Basic Usage:
This describes how to sync 2 videos using 2 computers. Other setups are described later.
Make sure your computers are on the same network. (Wired ethernet recommended, but wireless will generally work. Internet access is not required.) If you connect the computers to a router then it will probably provide IP addresses automatically so no extra setup will be required.- For reliability and simplicity it’s best to connect the computers directly (for 2 machines), or via a network hub or switch (for 3 or more machines). In these cases you should open the Network preference pane in System Preferences and set the following:
Configure: Manually
IP address: 192.168.0.x (replace x with a unique number for each computer on the network)
Subnet Mask: 255.255.255.0
Router: 192.168.0.1
DNS Server: 192.168.0.1 (I think you can leave this blank, but it doesn’t hurt!) - Make sure the firewalls on both machines are off (or allow UDP traffic on port 7474)
- Put the MultiScreener folder on each computer. Put a QuickTime movie file on each computer.
- On the first computer, launch MultiScreener Server and choose a movie. Start playback and be sure that “Transmit to Clients” is checked.
- On the second computer, launch MultiScreener Client and choose a movie. It should start playing in sync with the Server computer.
- You’re done. Now read the rest of this guide to find out the specifics!
Client Offset and decoder delays:
In rare cases the sync meter can be inaccurate if Quicktime takes significant time to decompress the frames of the movie. In this case, MultiScreener delivers each frame to the decoder but the whole Quicktime architecture seems to be lagging a bit. There is no way for MultiScreener to be made aware of the this delay, so there is a “Client Offset” adjustment instead. Usually it should be set to zero.
While viewing in fullscreen mode, use the left and right arrow keys to adjust the offset in 1/4-frame increments. (Positive numbers make the client early, negative makes it late.)
Fullscreen and External Video:
Typically, MultiScreener users play their movies fullscreen, so any data projector or computer monitor can be used for presentation. All frame-rates and dimensions are supported (including NTSC, PAL, HD formats) with no unnecessary scaling, up to the limits of your hardware and Quicktime capabilities. The graphics card does the scaling directly from the movie to the screen via openGL. (The software has no “native” format, although the small video preview window is locked at 320 x 240.) Since computer displays are inherently progressive-scan devices, MultiScreener can de-interlace your movie too (see the Movie Preparation for more info.)
For long-extinct formats like DV, MultiScreener can send the video directly to special hardware for better decompression. If you attach a DV camera, deck, or converter box to your Firewire port (remember those?), MultiScreener will let you choose it as an output instead of the computer screen. This provides the best quality and lowest CPU load for DV footage. Note: DV devices introduce a noticeable video delay (about 4 frames), so you shouldn’t mix DV decks and Computer Screens in the same project. Your movie must be encoded in the format that your external hardware expects.
Movie Preparation:
Movies should be prepped to match your output device (computer screen, DV over firewire), because MultiScreener will scale the image to fill the screen. That means that 16:9 movies will look wrong on 4:3 monitors, and 4:3 movies will look wrong on widescreen monitors. Try setting your monitor resolution to a ratio that matches your movie instead of your display. For example: You can play 4:3 movies on a widescreen iMac or laptop by choosing a 4:3 display resolution that is not “stretched”. The computer will insert black “pillar box” bars on the sides of the screen, and you won’t need to change the dimensions your original movie.
Your server and client movies should be compressed in the same format. All of the math is based on the Quicktime “timescale” of the movies. The timescale defines how many subdivisions of each second are stored in the movie file. It is not the frame-rate. A DV NTSC movie from Final Cut Pro will have a timescale of 2997 but Quicktime Pro will export the same movie with a timescale of 600. It is crucial that you have matching timescales on your movies to ensure that the server and client speak the same language. (MultiScreener displays the timescale of the current movie, so you can easily check.)
MultiScreener can de-interlace your movie, but it uses the Quicktime scaler which isn’t as good as some advanced de-interlacers. If your movie came from an interlaced source and you want the best quality on a progressive display then you might want to de-interlace first.
You should consider the compression “codec” when exporting your movie for MultiScreener. Most modern codecs (like H.264, MPEG4) use temporal compression, so only certain frames are recorded in their entirety. Do not use temporal compression for MultiScreener. Those codecs require more processor power and they introduce decompression delays which make sync unreliable. Restrict yourself to spatial compression instead (like Apple ProRes). These formats require more disk space (and disk performance) but MultiScreener can keep them in sync.
H.264 = BAD … Apple ProRes 422 = GOOD
(If you throw all caution to the wind and use H264, at least uncheck “frame reordering” in the compression settings during export. Frame-reordering will cause trippy forwards-backwards stuttering whenever MultiScreener tries to update the speed!)
Performance:
MultiScreener was made with a cross-platform graphical programming language, not native Mac OS code. HD playback is not as smooth as Quicktime Player. Quicktime player might play your 1080p files perfectly on an older machine, but MultiScreener requires more horsepower.
If you are having trouble getting adequate HD performance, try slowing the server’s “transmit_interval” to 500ms (see Preferences below). That might give the clients some breathing room. Also experiment with the “overdrive” preference.
Preferences:
All settings are saved automatically to an xml preferences file, as soon as you make the change (so if the computer crashes, your settings will not be lost). When the application starts, it automatically loads your movie, recalls your settings, and (optionally) goes into fullscreen mode. Great for unattended exhibitions. You can edit the xml with any text editor. MultiScreener will read the file on the next launch (but don’t mess with the xml while MultiScreener is running).
Hidden Preferences:
(not exposed in the main user-interface)
- “overdrive” options: 0, 1 [default 1] — Sets the MAX/MSP scheduler to operate in “overdrive” mode. In this mode, internal timing is less susceptible to interference from drawing the screen, moving the mouse, etc. But it may have a negative effect on stability in some cases.
- “interrupt” options: 0, 1 [default 0] — (Requires overdrive: 1) Sets the MAX/MSP scheduler to operate at audio interrupt – may help solidify timing on slow computers, may not.
- “transmit_interval(ms)” options: number of milliseconds [default 100] — How often the server sends its position over the network. The default works fine but slower values might be better for slower computers/networks
- “window_coords_x” pixels — The horizontal position of the top-left corner of the window (multiple monitors may have negative numbers)
- “window_coords_y” pixels — The vertical position of the top-left corner of the window (multiple monitors may have negative numbers)
- “frame_offset” (client only) — This isn’t hidden, it’s in the user-interface. But you should know that frame_offset values are stored in Quicktime time-units, not the 1/4-frame increments reported onscreen.
- “debugmode” options: 0, 1 [default 1] — If 1, any errors are printed to the “max window” (reveal it via the Window menu)
Server and Client on the same computer:
Multiscreener was originally designed with the implication that each Server or Client application would run on its own computer. There was interest in multiple monitor support, so now you can run two channels of video on the same computer. The apps recognize which monitor they were occupying before you triggered fullscreen, and they go to fullscreen on that monitor only. (This should work with a single dual-head graphics card, or multiple single-head cards, or a laptop.) The window position is saved and restored through the preferences, so the apps will remember which monitor to occupy when relaunched. When the first app enters fullscreen mode, you can elect to keep the mouse visible by un-checking “Hide Mouse in F-S”. That way you can launch the other apps. I also provide an Applescript to automate the process:
To launch the Client and Server using multiple monitors:
1) Be sure the applications are in your Applications folder. (Yes, it matters)
2) Open each app individually and do the following:
a) Choose the movie and define your options. Be sure to select AUTO FULL SCREEN.
b) Drag the app to whichever monitor you want it to occupy.
c) Close it.
3) Locate the MultiScreener Launcher (Dual Head).app Applescript
(This programmatically opens the 2 apps, one after the other.)
4) Run the Applescript (or put it into your “Login Items” in “System Preferences… / Accounts” so it runs whenever the computer starts.)
To quit when using multiple monitors:
1) Quit one app with Command-Q
2) Switch apps using Command-Tab
3) Quit the other app with Command-Q
Server and Multiple Clients on the same computer:
I have discovered a technique to run a Server and multiple Clients simultaneously, with each app feeding a different monitor. It involves copying the clients, then triggering them to run via Applescript so they can all live happily in fullscreen mode on separate monitors. There are much more elegant ways of doing multi-channel video playback on a single computer, but MultiScreener “accidentally” works in this context. (You will need a pretty fast computer to handle all of that video, though!)
To prepare a new Client: (instructions updated in 2013)
1) Inside your MultiScreener folder, make a new folder with a name like “MultiScreener Client 2 folder”
2) Copy the Client application and its preferences into the new folder. (Select them and drag them while holding the option key.)
3) Rename the copied app to “MultiScreener Client 2”
4) Right-click on the copied app and choose “Show Package Contents”.
5) Inside the “Contents” folder you will find “MultiScreener Client.mxf” Rename it to “MultiScreener Client 2.mxf”
6) You will also see a file called “Info.plist”. Open it in TextEdit and search for a key called “CFBundleExecutable”. Rename the string below it, so it reads <string>MultiScreener Client 2</string>.
7) Find the subfolder called MacOS and rename “MultiScreener Client” to “MultiScreener Client 2”.
Repeat these steps to prepare as many clients as you need.
To use them:
1) Basically just follow the Server and One Client instructions, but modify the Applescript to reflect your new clients. (So, tell Server to activate, then “MultiScreener Client”, then “MultiScreener Client 2” etc…)
Fullscreen and “Tearing”
Some graphics cards exhibit a phenomenon known as “tearing”, where horizontal strips of the previous frame will appear on the display. This is caused by the graphics-card buffers being improperly synced to the vertical refresh rate of the monitor. MultiScreener tries to alleviate this by enabling “VBL sync” on the graphics card, but some cards can’t manage to do it. This problem is more likely when using multiple monitors.
If you experience “tearing”, make sure your system software (and therefore your graphics drivers) are up to date. Also, try adjusting the refresh-rate of your monitor in “System Preferences… / Displays”. Some codecs tend to tear more than others.
Applescripts:
There are several Applescripts included to help launch the MultiScreener apps in unattended installations. Typically I would just add the app to the “Login Items” in “System Preferences… / Accounts” but on slower machines, startup apps won’t launch properly because they get triggered before the computer is finished starting. Before using these scripts, be sure the MultiScreener applications are in your Applications folder.
- MultiScreener Launcher (Server).app
- MultiScreener Launcher (Client).app
Drop one of these into your “Login Items” instead of the app itself. These scripts wait 10 seconds before launching their accompanying Multiscreener app. That should be enough time to ensure success.
- MultiScreener Launcher (Dual Head).app
This script is similar to the others, but it launches the Server and Client on the same machine. (See Server and Client… above.)
NOTE: These Applescripts have been compiled as Applications, but you can edit them too: If you launch Applescript Editor first, then use file menu / open to open one of the script “.app” files, you can edit the source.
GPL License:
MultiScreener is Copyright 2008, 2009 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.)
There is a caveat: MultiScreener was developed in the (non-free) MAX5 visual programming environment ( http://www.cycling74.com ) which is required if you want to edit the source code. The MultiScreener application contains the MAX5 “Runtime” environment, which is not GPL, so my license pertains to my contributions only.
(Former versions were distributed under a Creative Commons by-nc-sa license, which was a little too vague and restrictive with respect to commercial use of the software. The GPL provides more freedom to use the software commercially.)
Change Log & Known Bugs:
Version 0.95 (Feb 03, 2009)
Changes in this version:
- Changed to GPL 3.0 license
- Recompiled with MAX5
- Tested HD playback
- Fixed: Fixed error in client timing comparison. (improved sync accuracy).
- Fixed: Fixed occasional loss or overwrite of xml preferences file
- Fixed: client sync meter was sometimes inaccurate
- Fixed: Simplified and optimized speed-control math
- Fixed: Simplified window-position save/recall at startup
- Fixed: Counters sometimes displayed wrong times
- Fixed: Now uses more conservative timing when entering/exiting fullscreen
- Fixed: Changed size of filename display to accommodate long filenames
- Fixed: changed “Way Off!” indicator into “Finding Frame” indicator
- Added: “Mute Sound” button added
- Added: “Hide Mouse in Full-Screen” button added
- Added: Client now indicates playback speed
- Added: Client now has user-settable frame offset
Known Bugs in this version:
- If you launch MultiScreener via Applescript, it sometimes fails to load preferences. This is a vexing problem that only happens on certain machines under certain conditions. I’m investigating solutions for the next release.
- If you put the computer to sleep while MultiScreener is running in fullscreen mode, it wakes up OK but the mouse pointer becomes visible. A fix is in the works.
- One user reported red flashes in full screen mode and frequent crashes (MultiScreener Client, OS 10.6.6 and 10.6.7). He disabled Apple Remote Desktop and the problem disappeared. When running OS 10.6.2, ARD and MultiScreener coexisted peacefully.
Version 0.93b (May 23, 2008)
- Added: Updated the README file to reveal a way to run multiple clients on the same computer.
(There are no code changes!)
Version 0.93 (May 20, 2008)
- Added: Now supports multiple monitors (2 fullscreen movies on one machine)
- Added: Apps now remember their monitor position
- Added: Expanded README file with lots of new info
- Added: Applescripts are now included for unattended launching and multiple monitors
- Added: Movie timescale data is now displayed
- Fixed: Changed fullscreen startup delay to 5 seconds to help with slower machines
- Fixed: Settings are now saved immediately, not when app closes
- Version 0.92 (May 09, 2008)
- Fixed: reduced CPU load on client and server by limiting GUI updates and slowing down non-critical math
- Fixed: The window in which normal tracking operates is now (+/-) 1/4 second, regardless of movie frame-rate or Quicktime time-units/second. If the sync falls outside this window then we switch to emergency mode and jump directly to the server’s frame (triggering the new “Way Off!” indicator on the way).
- Added: de-interlacing (uses same method as Quicktime player – nothing fancy).
- Added: “Way Off!” indicator to indicate when the client switches from normal to emergency sync mode
- Added: numerous advanced options are now acessible via XML prefs
- Added: software license (Creative Commons Attribution-Noncommercial-Share Alike)
Versions 0.8 – 0.91 (May, 2008)
- Internal test versions
Version 0.7b (April 9, 2008)
- Fixed: problem with client not entering fullscreen.
Version 0.7 (April 8, 2008)
- First release
