Archive of old VidSync blog posts

On January 1, 2025, I’m moving the VidSync website to a new platform (the standard WordPress, rather than a glitchy, overly complex one called Tiki-Wiki). I don’t see any use in re-creating the old blog updates one-by-one, so I’m just putting all their contents in this one post.

What’s new in VidSync 1.5 (March 4, 2014)

VidSync 1.5 is a major upgrade. It’s faster, more stable, and better-looking, and it adds some useful new controls. The underlying math, import/export formats, and general processes for doing things are the same, although a few buttons have moved around. The new version is backward-compatible with previously saved VidSync Document (.vsd) and auxiliary files.

The new version requires Mac OS X 10.9 (Mavericks) or later. Mavericks is a free upgrade and highly recommended. However, users restricted to older, 32-bit Macs can still download the old version of VidSync compatible with OS X 10.6 (Snow Leopard).

Major features:

The video playback controls have been revamped. Unsynchronized videos are controlled like any other video in Apple’s Quicktime Player. When two or more videos are synchronized, a new control bar opens up with more intuitive and easy-to-read buttons for all the advanced playback controls from the old version and a few new ones.
You can now snap “portraits” of objects and view them later within VidSync, either individually or as a list of portraits of all the objects in the project. For example, I save portraits of the juvenile Chinook salmon I’m analyzing, and when a fish swims off-screen and comes back I check its parr markings against its portrait to make sure it’s the same fish.
VidSync can now be used for 2-D measurements, using a single grid of points for calibration. These will naturally be less accurate than 3-D measurements from multiple cameras, but Vidsync lets you make them as good as they can get by tapping into the same distortion correction and linear transformation algorithms used for its 3-D measurements.

Major behind-the-scenes changes:

VidSync now uses Objective-C automatic reference counting (ARC) for memory management, which greatly reduces the potential for program crashes. This huge change to the code is only visible to users as improved stability and performance.
VidSync now uses AVFoundation instead of QTKit to handle video playback, image capture, and exporting. (In other words, it has moved from using outdated Quicktime 7 to modern Quicktime X behind-the-scenes.) This fixes several bugs with exporting, and makes videos start/stop and play more smoothly. However, some old video files are no longer compatible with VidSync without a conversion. The rule remains that VidSync can play any file Quicktime Player can play on the same computer, but Quicktime became much more picky about video codecs in Mavericks. If your files don’t work with VidSync anymore, you can convert them to a modern codec (.mov and .mp4 files using the H264 codec work well) using either Quicktime Player or a batch video converter such as Wondershare or Final Cut Compressor.

Minor features:

The visual markers for video overlays all have very subtle, non-offset drop shadows now. These make it much easier to see light-colored text and markers against light parts of a video.
You can copy an annotation from one video onto all the others using the new “Mirror Selected Annotation” button.
Advanced step controls allow choice of units, stepping by frames, minutes, or seconds.
There are shortcut keys for play-while-pressed at the regular rate and both advanced playback rates.
The program uses the masterclip’s native timescale for all timecodes recorded. It used to sometimes switch to strange intermediate numbers.
There are now more warnings/verifications to make it harder to accidentally mis-click and delete something you don’t want to.
Video overlays and the master time display now update live while the play-while-pressed buttons are in use.
You can now optionally seed the ((automatic plumbline detection)) algorithm with the first two starting points it needs, which makes it easier to find good settings to read your grid.

There are hundreds of other small improvements and bug fixes.

Minor update with Version 1.55 (February 2, 2015)

A new version of VidSync (1.55) is available with several minor bug fixes and user interface enhancements. The main changes since 1.5 include:

Added shortcut keys for regular advanced playback rates 1 and 2 (described in the tooltips for their buttons).
Fixed some bugs that prevented effective use of VidSync for 2-D calibrations (for people not trying to take 3-D measurements but wanting to record observations in terms of a 2-D grid).
Added the ability for annotations to include a running timer from the point the annotation was started (useful for having a “Begin analysis” annotation at a certain point in your video and being able to see how much time has elapsed since that point).
Made speed improvements so that files containing thousands of measurements should have playback just as responsive as files containing a few measurements.
Adjusted the color of the synced playback scrubber to show up well in Yosemite, since Apple inverted the colors of their sliders in the upgrade from Mavericks.

Updated to version 1.60 (March 9, 2016)

Version 1.60 of VidSync is now available. It fixes several minor glitches that came up in the last 1-2 versions of OS X. The new version 1.60 works well in El Capitan.

Several new features and minor bug fixes have been added since 1.55:

Added “instant replay” buttons to the advanced playback controls. The one for the standard playback rate goes backward 2 seconds, plays forward 2 seconds, and stops. You can customize the behavior for both advanced playback rate controls. These are great for re-watching animal behaviors you want to see a few times over to properly interpret.
All the different “play” buttons for various rates now work like “pause” buttons while the video is playing, so you can click once to start, again to stop. They don’t all change to show the pause icon while playing (that would be visually annoying), but they work that way.
Added the ability to automatically show speeds on connecting lines, in addition to distances. These speeds are also included in spreadsheet copy/paste exports.
Added a “Current observer” box on the Project tab. The observer is then recorded along with all measurements and annotations, which makes it possible to figure out if two people working on the same analysis might be interpreting things differently.
Added the ability to mute sound on each video individually and have this setting remembered for each project individually.
Added 27 new measurement overlay icons for event types, based on FontAwesome.
Added help buttons in several parts of the program that link directly to the relevant pages in this online user guide.
Added a button to sort the events list on the measurement tab chronologically based on the timecode of their earliest point.
The “Direct OpenCV output window” option from the automatic plumbline detection interface has been replaced by something better. Now, the detected chessboard corners all show up as yellow dots on the main video windows during this stage instead.
In configuring event types, you can now use length label multipliers < 1. For example, if your calibration units are in millimeters, you can use a multiplier of 0.1 to display measured lengths on the screen in centimeters.
Reorganized and enhanced the XML output. This includes adding project notes and all Annotations to the XML files. Instead of the object and videoclip elements being nested inside an “objects” element, the top-level element is now “project” (with some attributes including project description and name), under which are “objects” (containing only objects and their children, such as events) and “videoClips” (containing only videoClips and their children, such as annotations or calibration information). This means the XML files now contain pretty much any information from a VidSync file that you could possibly want to access. However, if you wrote code previously to import VidSync’s XML output into R or some other environment, you might (depending on your specific code) have to make some small, easy modifications for compatibility with the new and improved exports.
Fixed a bug that sometimes caused new portraits to overwrite old ones.
Fixed a bug that showed back face world residuals being way higher than they actually were.
Fixed many other minor glitches.

Comparison of VidSync with its mathematical predecessor (March 11, 2016)

For anyone curious about the difference in mathematical methods between VidSync and its predecessor, I’ve written up a short page graphically comparing VidSync’s method to the method of Hughes and Kelly (1996).

Quick update to 1.63 (March 23, 2016)

After making 1.60 public, I made some improvements worth releasing as a new version quickly. Here’s what’s new in 1.63:

Improved the distortion correction algorithm by adding four more high-order radial and one higher-order tangential term to the underlying model, which especially helps with extremely wide fisheye lenses but slightly improves accuracy across the board, and improved the cost function and numerical minimization algorithm that find the distortion parameters. The previous distortion correction was already pretty good, so there’s no rush to redo previous analyses, but there should be some slight improvements to accuracy, especially in highly distorted footage.
Added diagnostics for the distortion model, and a Distortion model page on this site describing the model and the meaning of the diagnostics, which are visible just below the distortion model parameters in the VidSync interface.
Added the ability to select whether to see all distortion lines on the screen (while on the distortion tab) or just the ones on the current timecode. This makes it manageable to gather plumblines from multiple different frames in the same video and maximize input to the distortion model. This is rarely if ever necessary, but it’s good to have the option.
Added an automatic calculation of “distance to the nearest camera” for all 3-D points, which shows up in the points list on the measurement tab as well as in the spreadsheet and XML data exports.
Added buttons to reset just the front face or back face of the calibration frame, not just both at once. This makes it possible to correct user mistakes during calibration (such as accidentally clicking on a bunch of the wrong points) by redoing the face that was messed up, without having to redo both of them.
Added a “tally” button to the measurement interface that pops up a running list of the number of events for each type under a given object (for example showing the number of length measurements and foraging maneuvers for a particular fish, etc).
Fixed a bug in the distortion correction display that was causing the final, straightened lines to always appear perfectly straight. Previously, it was actually just showing a straight line between the endpoints of each corrected plumbline. Now it shows both the actual corrected plumbline and a straight line between the endpoints as a reference to indicate how much distortion remains.
Updated the entire project to use the same permissive, open-source license (the MIT license) instead of a hodgepodge of outdated default copyright notices.

Estimating water velocity from tracers measured in VidSync (June 1, 2016)

VidSync is often used in rivers to study the behavior of fish from a stationary camera position, and it can be useful to characterize the water velocity in the region being observed — to measure which way is downstream, how fast it’s flowing, or even characterize the velocity in specific locations within the region. One way to do this with VidSync is to measure the motion of small, neutrally buoyant tracers, such as natural debris particles. On the Drift Model Project, we’ve found that well-soaked Israeli couscous thrown into the river several meters upstream produces a good number of highly visible, biodegradable tracers.

But how many of these tracers do we need to accurately characterize the velocity at a site? Using data from the above project in which we digitized trajectories of 100 particles in each of three sites on three different rivers, I ran some randomization tests to see how many tracers we needed to approximate the “true” velocity, which was assumed to be the mean velocity of all 100 tracers. Of course, there is no single true velocity: the current at each site really does vary constantly, both over time and at different locations within the observation region. But it is nevertheless useful to figure out how many tracers are required to get an estimate that characterizes the habitat fairly well. This characterization includes both the magnitude (current speed) and direction of the mean velocity vector.

The randomization tests involved drawing a number of tracer vectors from the full set of 100 vectors with replacement, averaging them, and comparing them to the overall average of the original 100. The results below show the “error” (absolute difference between the randomized measurement and the “real” 100-tracer measurement) in both current speed (left column) and angle (right column) for random samples ranging from 5 to 100 tracers at three sites in different streams. The black line is the mean error and the 95% confidence band is shaded in gray.

For this study, we decided to go with 40 tracers per site, which can be digitized pretty quickly and are adequate to stabilize our estimates at values very close to the larger-sample average of 100 tracers.

Tiny update to 1.64 (March 23, 2016)

This update includes just minor but useful bug fixes. The annoying starting position of the floating synced-playback control panel has been fixed (it should now start in the top left corner of the screen as intended). More importantly, a recently introduced bug that was causing the program to hang for 2 to 15 seconds or so during certain tasks in certain videos has been fixed. These include resizing videos, calculating calibrations, and sometimes measuring points.

Another small update to 1.66 (June 26, 2016)

VidSync user Neil Wi has posted a nice timelapse of measuring a bunch of marine fish lengths in VidSync. You can watch it on his Vimeo channel.

Manuscript describing VidSync and testing its accuracy published (November 17, 2016)

This past summer, the Canadian Journal of Fisheries and Aquatic Sciences published an article describing the mathematical methods underlying VidSync, testing its accuracy, and demonstrating an application to juvenile Chinook salmon research.

See the How to Cite page for details on the article, including how to obtain a copy.

Just a quick update, since things have been stable for a while (May 24, 2020)

I know that when I’m looking into a new piece of software, I see a blog that hasn’t been updated in a few years and wonder, “Does it still work?”

I’m updating this just to let people know that VidSync is still working just fine, as of macOS version 10.15.1 (Catalina) in mid-2020, and there’s nothing on the horizon to suggest that will change. I am still checking it with each new OS version, and if something breaks I’ll be quick to fix it.

There haven’t been any updates to the program in four years because nothing has broken that would require an urgent update. I have collected a list of minor new feature requests and improvements to be made at some point, but I’m not sure how soon that will happen.

I am still happy to hear about projects for which you’re using VidSync (or might plan to use it), and to answer any questions potential or current users might have about the program.

MacOS Big Sur incompatibility (working on a fix) (January 28, 2021)

I’m just posting quickly to let people know that VidSync does NOT work yet on MacOS 11 (Big Sur). Apple made some major changes under the hood, breaking some of the underlying technologies VidSync relied on.

There are new and improved versions of all of these deprecated tools, and I’m working on implementing them in VidSync. When I’m done (hopefully early February 2021), I’ll post a new version of VidSync that should be compatible going forward with the next several versions of MacOS and with the brand new Macs using Apple Silicon chips.

In the meantime, anyone actively using VidSync should hold off on upgrading to Big Sur.

New version compatible with MacOS Big Sur, Monterey, and beyond (May 6, 2022)

I’ve been gradually making small improvements to a new version of VidSync that works with both Intel and the new Apple M1 processors, and with the latest versions of MacOS (Big Sur and Monterey).

The only feature missing from the new version is “portraits,” the ability to save screenshots of particular subjects (like the markings of a fish) within a VidSync file, e.g., for keeping better track of individual animals if they go off-screen and come back. I don’t know of anybody actively using that feature right now. I plan to add it back in to the new version, but Apple completely removed the under-the-hood technology I was using to create it, so I’ll have to rebuild it from scratch with all new code. I’m not sure when I’ll have time to do that.

There are still a handful of minor bugs to be worked out, but most users won’t encounter them, and none of them affect measurement accuracy or make the program unusable. I’ve used the new version extensively myself and have sent it by email to about half a dozen people who requested it, and nobody has reported back with any major bugs. So it’s not as polished as the old version, but at least it works with newer Macs.

Head on over to the Downloads page to get the new version if you need it.