Users Guide

Creating a Project

The first thing to do when you fire up SUFFERvision is select File|New Project to create a project that links your video and telemetry files and stores various settings.  To begin, your video and telemetry files must be in the same directory.  Select the video file first.  This will automatically select the telemetry file (if a matching name is found) and the project file.  You can override these default selections if desired.

SUFFERvision can handle any video file format supported by FFmpeg, which  includes anything you're likely to encounter.

SUFFERvision can handle .tcx, .fit, and .gc (GoldenCheetah) files for telemetry data.  If your data is not in one of these forms you may be able to use the excellent GoldenCheetah to convert it.  Additionally, SUFFERvision has its own .csv telemetry input format.  SUFFERvision .csv files contain comma or tab-delimited lines with these fields: Seconds(Integer), Power(W), HeartRate, Cadence(RPM), Distance(M), Elevation(M), Latitude(Deg), Longitude(Deg).  No header row is expected.  All fields must be present.  If you don't have a certain kind of data, fill with zeroes.

Synchronizing Telemetry

Once you've created your project a new window will appear and your video will start to play in it.  The control window will appear as shown to the right.

Your first task is to align the telemetry with your video.

First use the slider and the controls underneath it to move to a point in the video that you think you can identify easily in the telemetry via  pauses/restarts in the data or characteristic patterns in power or GPS.  Good candidates include the start or finish of a race, sprints, and sharp corners.  A start can be especially helpful if there is an audible beep in the video when your computer starts recording.

Now use the <<, <, >, >> arrows to shift the telemetry until it is aligned.  The single arrows move by 0.5 seconds at at time, while the double arrows move by ten seconds at a time.  The direction of the arrow corresponds to the direction the time series will shift on the screen, so << is effectively fast-forwarding through the telemetry.

Sometimes you can't be certain you've got the alignment right from looking at a single point, so review the alignment while the video is playing and check it at a few different points until you're happy.

Marking Start and Finish Lines

Once the telemetry is aligned, you may wish to mark start and finish lines.

The start line mark is used to compute elapsed time and distance.  By default, the start line is the beginning of your telemetry data.  You may click Mark Start at another point in the video if, for example, you wish to exclude warmup that appears in your data before the start of your race.

The finish line mark is used to compute lap counts and distance remaining.  The finish line also displayed on the map as a short blue line perpendicular to the course.  Normally you'll click Mark Line at the point in the video where you cross the finish line at the end of the race.  However, if you were shelled like a Narragansett quahog and didn't finish the race you may mark the line on a different lap and use the Laps at line field to tell SUFFERvision how to adjust the lap counts accordingly.

The other options on this screen are pretty self-explanatory, with the exception of the Criterium checkbox.  If criterium is checked then SUFFERvision will search for a lap ending at the marked finish line and update the map to show just the shape of the course rather than any additional warmup or warmdown you may have done with your computer on.

Choosing what to Display

The second tab of the control window governs which fields are displayed at the bottom left of your video.

The list on the left shows the fields to display.  The list on the right shows the menu of fields you can choose from.

Use the left and right arrows to move an item from one list to the other.  Use the up and down arrows to order displayed fields to suit your tastes.

Captions and Video Timeline

The third tab of the control window provides a freeform text editor where you can maintain a list of timeline entries representing captions and video editing commands.

Timeline entries should be specified in a 3-column tab-delimited format:
  1. video timestamp
  2. seconds duration (used for captions or fades)
  3. caption or command
For example:

0:00:30.0    0.0     [START]
0:00:31.0    10.0    2011 Spring Horsepower Festival
0:00:50.0    1.0     [FADEOUT]
0:50:00.0    1.0     [FADEIN]
0:50:01.0    10.0    Skipping to the finish
0:52:00.0    0.0     [STOP]

To facilitate maintenance of this table, hitting the tab key at the beginning of a line will insert the current video timestamp.  Hitting an opening square bracket '[' will insert a [START] command.  Hitting the tab key after this will cycle through the other possible commands (i.e., [FADEOUT] [FADEIN] [STOP]).

A pipe '|' can be used to delimit multi-line captions.

For captions the duration field determines how long the caption is visible.  Obviously, a caption must have a nonzero duration to be shown.  Duration is ignored for START and STOP commands.  For fades the duration determines how many seconds it takes to fade to/from black.

For handy navigation, double clicking a timeline entry will make the video seek to the corresponding point in the video.

Strava Integration

If you are a Strava user and you've already uploaded your ride, you can have SUFFERvision look up the segments traversed during your ride and display progress bars in your video as you traverse them.  Go to Tools|Strava to display the dialog shown to the right.  Enter your Athlete ID, which you can find by looking at the URL of your profile page.  Load and select segment efforts as desired.

Encoding your Video

Once you've synchronized your data, marked your finish, tweaked your options, and added your commentary and video editing commands, all that's left is to encode your video.  Select File|Encode and provide an output filename.  Note: the only supported output format is .mov.  A dialog will pop up to show encoding progress and will go away when encoding is done.

That's it!  Post your video so we can all enjoy!

Training Mode

Want to watch and reproduce efforts from last season's races while you're on the trainer?  SUFFERvision's training mode will do the trick. To get this working you will need:
  1. An Ant+ power meter and heart rate monitor.
  2. An Ant+ USB stick and associated drivers.
  3. Quarqd.(
It's beyond the scope of this document to describe how to get these working together.  However, once you have them working together it's easy to display the data in SUFFERvision.

In the training tab point SUFFERvision at the host and port where you have Quarqd running (probably localhost/8168) and click Connect.

If you select "display live telemetry" then the live data from your trainer session will be displayed on top of the recorded data from your past ride or race.

If you select "live power drives frame rate" then SUFFERvision will adjust the video frame rate based on a physical model of power, weight, momentum, grade, and wind resistance.