Thumbfixer

Thumbfixer is a utility for automatically editing iMovie project files, primarily to avoid the scrambled thumbnail bug.

I have not tested this with iMovie 3, and in fact I hope iMovie 3 has fixed this bug, so this utility should no longer be needed.

Please read all directions, particularly the caveats, or you edit your projects at your own risk.

Thumbfixer fixes a couple of limitations of iMovie 2 (as of version 2.1.1):

iMovie sometimes corrupts the thumbnail displayed. (The original clip is unaffected, but the thumbnail appears as static or distortion.) I am unsure of the exact reason why this happens, but it seems to occur most often during an undo of a split.
You cannot specify which frame of a clip should be displayed as its thumbnail. iMovie always displays frame 0, which may not be the best representation of your clip.

Thumbfixer corrects these issues by allowing you to specify the frame number of the clip you want to use as the thumbnail.

Note: Apple posted a workaround to this problem in Knowledge Base Article 61555, but I do not recommend their solution because it suggests that you process your clip with an effect (such as brightness/contrast) in order to create a new thumbnail. This is a bad recommendation because it is time consuming, and more importantly it can permanently alter your clip (even if you set the effect to "neutral" it can change your data).

Sample Output

This example shows how the first clip of MyMovie can be changed from the default thumbnail of frame 0 to frame 1, avoiding its scrambled thumbnail:

> thumbfixer MyMovie 
Shelf: Clip 02
  Duration:  00:06.16 (196 frames)
  Thumbnail: 00:00.00 (frame 0)
Change? [0] 1
  Thumbnail: 00:00.01 (frame 1)

project file 'MyMovie' updated successfully

In the next example, the thumbnail is set to the frame at the 3 second mark. This is handy if the clip is a fade in -- now the representative thumbnail is from the middle of the clip rather than the beginning, which is black because it is fading in.

> thumbfixer MyMovie
Shelf: Clip 02
  Duration:  00:06.16 (196 frames)
  Thumbnail: 00:00.00 (frame 0)
Change? [0] 3:00
  Thumbnail: 00:03.00 (frame 90)

project file 'MyMovie' updated successfully

In the next example, the project file is reverted to the backup:

> thumbfixer -s MyMovie 
Swap 'MyMovie' with 'MyMovie.backup'? [y] y
Backup file successfully swapped with project file.

How To Install

I presume you have a basic knowledge of Unix and the Terminal. From within Terminal, install this program in an application directory in your path, such as /usr/local/bin. Make sure it is executable (chmod 755 thumbfixer). Log out and back in (or use the rehash command if it is supported by your shell).

How To Use It

Open up a Terminal. cd to the directory where your movie is (such as ~/Movies/MyMovie/). Type thumbfixer MyMovie and you will be prompted to enter a new thumbnail for each clip.

To fix corrupted thumbnails, just change them to a different value. You can do this quickly to all clips by just hitting 1 <return> repeatedly.

To specify customized thumbnails, type the frame as a number or a time relative to the start of the clip (not relative to all clips, which is the way the movie track displays the times). This allows you to specify a thumbnail that is more representative of the clip -- for example after a fade in or after action has focused on the main subject. The first frame is 0, the last is the total number of frames in the clip. See below for options and flexibility in how you enter the numbers.

There are two command line options you may also specify:

-c: compress shelf (removing empty spaces on shelf). This does not compress the clips themselves; it just fills in the empty spaces with clips from farther down the shelf. It does not sort them in any special order, just the order it encounters them in the project file.
-s: swap backup file with current project file. This allows you to restore the previous version if (in the unlikely event) something gets corrupted. Only one backup is made, so if you run Thumbfixer more than once you won't be able to restore the original backup, only the most recent one. You can, however, copy any backup file you make for more permanent backup. See more on this command below.

How It Works

Thumbfixer does not alter your movie clips. It only edits your iMovie project file, which is a text file. For example, the line that indicates which thumbnail to use looks like this:

: Frames: 760 In:382 Out:1142 Thumb:0

Thumbfixer only changes the value of the field Thumb. iMovie only sets Thumb to display frame 0, but when it is changed to another number, iMovie (at least version 2.1.1) will display the corresponding frame as the thumbnail in the shelf and movie track views. You could do this editing by hand, but Thumbfixer automates the process so you won't create problems such as:

entering an invalid frame number
inadvertently altering the format of the file
changing the type/creator of the file

Thumbfixer also provides a couple of handy features:

You can enter the thumbnail as a frame number, or, to match what you see in iMovie, as a time. The time, as minutes/seconds/frames, can be written in several ways, interpreted as follows:
- three numbers, two delimiters (1:03:10 or 1:03.10) = min:sec:frames
- two numbers, two delimiters (1:03: or 1:03.) = min:sec
- two numbers, one delimiter (3:10 or 3.10) = sec:frames
- one number, one delimiter (3: or 3.) = sec
- one number only (3 or 90 or 1800) = frames
This gives you shorthand alternates for numbers. For example, the following are equivalent: 90 or 3. or 3:00 or 00:03:00. Also note that either : or . can be the final delimiter.
You can provide the thumbnail as an offset, such as 49:21 - 2:15 or 1:03.02 + 100. This makes it easy to calculate frames that are in clips in the movie track, since the times given are relative to the beginning of all the clips. For example, note the beginning of the clip (time A) and find the frame you want (time B). In Thumbfixer enter B - A and the relative thumbnail will be calculated for you.

If you have any suggestions or observations, don't hesitate to contact me.

Caveats

I have not yet tested Thumbfixer extensively with files containing a lot audio or effects, so it is possible that those project files will not be edited correctly because it contains formatting I have not anticipated.

iMovie must not be running when you run Thumbfixer. This is to prevent Thumbfixer from changing an open file. Thumbfixer checks once when it starts up, so wait to open iMovie until it finishes.

The main inconvenience is that if you want to pick and choose certain frames (rather than just taking the 1st or 10th or same frame for all your clips) you have to remember all the frame numbers by writing them down.

I have tried to make the user's input and the file writing as robust and error-avoidable as possible, but it is conceivable that someone could cause the program to create a project file that is corrupted. If this happens, you can use the -s command to swap the project file with its backup file. Please let me know your error and any input you might have been providing.

Only the last backup file is saved, so if you run Thumbfixer more than once before checking your work in iMovie, you may not be able to recover from other than the most recent changes.

If you need to rename or move project files around, do so in the Finder, not in Terminal, to preserve the type/creator codes (required for iMovie to find them).

Why Perl?

Because the iMovie project file is a text file, and Perl is great for processing text files. And it is fast to program in. And I know it better than Objective-C.

Future

There are two tracks future development could take:

For Thumbfixer, all this Perl logic could be converted into a native Mac app which would allow you to visually select a frame and not worry about frame numbers and times. This would be neat but I'm not sure I have the time. Besides...
For iMovie, future relases (a) could avoid the thumbnail corruption and (b) could provide a mechanism internally so you can specify any frame to be the thumbnail (perhaps in File / Get Clip Info). If this happens, the need for Thumbfixer will go away.

So I hope #2 happens soon...

- jfw, 5 Mar 2002
John F. Whitehead - http://www.well.com/~jfw/

Download

Revisions

Version 1.0, 3 Feb 2002. Initial release.

Trademarks

iMovie is a trademark of Apple Computer, Inc. Thumbfixer is not written by or endorsed by Apple Computer.