QTCoffee 1.2.5
Command Line Quicktime Utilities
by 3AM Coffee Software
January 21, 2008
http://www.3am.pair.com/QTCoffee.html
Introduction
These utilities allow you to manipulate QuickTime movies (and other QuickTime readable media such as MPEGs, AVIs, music, and images, and others with appropriate plug-ins such as Ogg and WMV files) via the command line.
For a quick introduction to the most commonly used capabilities of QTCoffee, please read the file “How To.rtf”.
The core functionality allows you to join (concatenate) movies one after the other, multiplex them (play simultaneously), and split them into pieces.
Along the way, you can modify movies by extracting tracks and chapters, scaling, rotating & translating tracks, changing playback rates, and cutting and pasting. The programs also convert, as best they can, the tags from AAC and protected AAC files into the output file. There is special support for joining AAC audio files into new AAC audio files (also works for MPEG-4 video). You can manipulate and create chapters.
Why would you want such a thing? Most of these things (as well as many others) can be done with QuickTime Pro. If you only happen to need these particular features, and don't want to pay $30 for Quicktime Pro, then this is for you! Certain things are easier with QTCoffee, and there a few things that QTCoffee can do that QuickTime Pro cannot. These utilities can also be used inside shell scripts and are therefore very useful for batch processing. We think of them more as complements to Quicktime Pro rather than replacements for it.
By default the output movie refers to data in the original files (so the output movies are usually very small). Make sure not to delete the original files until you have created a movie using the -self-contained or -mp4 options and verified that it works. Keep a backup of your originals, just in case.
If you find these utilities useful you may also want to investigate qt_tools by david van brink at http://omino.com/sw/qt_tools/ which provide a nice complement to our programs, including a utility to access QuickTime's export functions via the command line.
Installation
Double click the installer. This will put the binaries in /usr/local/bin, the manual pages in /usr/local/share/man, and this Read Me, the license, and the How To document into /usr/local/share/doc/QTCoffee. Be sure that /usr/local/bin is on your path (/usr/local/share/man should automatically be on in your manpath unless you've changed it). If you prefer another location (or if you don't have administrator privileges and want to install in your home directory), you can download the raw files from 3AM Coffee Software’s website and install them anywhere you like.
Compatibility
QTCoffee should work with the following software versions, although it has not been tested on all of them. Please notify us if it fails to work with one of these versions. It should also work with later versions.
Mac OS 10.3.9, 10.4–10.5.1
QuickTime 7.0–7.4
Cost
QTCoffee is donation-ware for personal and academic use. If the tools are useful to you you are encouraged to purchase a license or pay whatever amount of money you feel is appropriate. If you use it for commercial purposes (even if you don't make any money specifically off the project) you will need to purchase a license at US$10 per seat. Go to https://order.kagi.com/?QF8. Contact us directly for site-license information or if you wish to incorporate QTCoffee tools into another product. There is no need to purchase a QTCoffee license if you have already licensed iTunesJoin.
Contact
If you have suggestions, feel free to email. If you encounter any bugs, please send a full bug report. Please include the exact command line you used to trigger the bug. If possible, also enclose the movie or movies that you used or place them somewhere we can download them and give us a link. If you cannot make the movies available, please tell us as much as you can about them. You may wish to include the output from “qt_info” which comes with the above-mentioned qt_tools package.
Documentation
There are 5 command line utilities in QTCoffee: modmovie, catmovie & muxmovie, and chapcutmovie & splitmovie. Once QTCoffee is installed, typing man QTCoffee will bring-up general information, while man programname gives detailed information on programname. But most of the manual pages refer you back to this Read Me file for details.
modmovie is used to modify a single movie; it can extract tracks, rescale and translate tracks, rescale the entire movie, and extract chapters; the result can be saved in-place, as a small “pointer movie” (a movie which does not contain audio, video, or other data, but instead points to data in other movies), or as a new self-contained movie. catmovie concatenates movies together, one after the other. muxmovie multiplexes (plays at the same time) the tracks from movies. These two utilities can also do the same operations as modmovie on all or some of their arguments. chapcutmovie splits a movie into a bunch of movies, one for each chapter. splitmovie splits a movie into a bunch of movies at specific times, or into equal duration movies.
iTunes & iPod notes
QTCoffee tools can be used to manipulate iTunes audio files. You can join songs with catmovie, play songs simultaneously with muxmovie, or change the playback rate of songs with the -rate option. The resulting QuickTime movie files are fully supported by iTunes (aside from some imperfections in tag conversion). But they cannot be played by iPod. (They may be playable on Video iPods; we don't have one to test. Donations are, of course, welcome!)
If you wish to create files that are playable on iPod, here are some options:
1. QTCoffee has special support for joining AAC audio files. Try the -mp4 option to produce another AAC audio file as output (name the output file with a “.m4a” or “.m4b” extension). You may need to use the -force-same-tracks option in some cases (please check to make sure your new audio file works properly if you use this option). You will have to enter tags manually in iTunes. Also, iTunes 5.0 has a bug; we recommend using 6.0 or later if you must upgrade. You will need to use the -remove-output-edit-list option to make iTunes 5 compatible AAC files.
2. If you are joining MP3 files, search macupdate.com or versiontracker.com for MP3 joiners. Or convert the QTCoffee movie (see below).
3. If all your source files are Apple Lossless, convert the QTCoffee movie to another Apple Lossless file (see below).
4. If one or more of your source files are Protected AAC (purchased from the iTunes music store): you are out of luck. Apple prevents conversion of Protected AAC audio into other formats (even into new Protected AAC audio), so there is no (legal) way to make the processed file into something the iPod can play, but your files will play in iTunes on any authorized computer.
5. If you are using multiple file types in the same output file, or doing something other than just joining files, you will need to convert the movie (see below)
iTunes can be used to convert the movies QTCoffee produces into files that can be played on iPod (except protected AAC). If you are not willing to tolerate a reduction in quality, and are willing to tolerate large file sizes, set the Importing preferences to use the Apple Lossless Encoder. If you are willing to suffer a slight quality loss, choose MP3 or AAC. Then select the file in your iTunes Library and choose “Convert Selection” from the Advanced menu.
There are many issues with tag conversion. QuickTime 7 provides much better support for tags and a future version of QTCoffee will take advantage of these new features.
If you just want to join files, don't want to deal with all this complexity, and are willing to pay the shareware fee, you should investigate our “iTunesJoin” application for iTunes.
modmovie
catmovie
muxmovie
modmovie, catmovie, and muxmovie have similar arguments. modmovie only takes a single input file, while catmovie and muxmovie take multiple files (although they can also take only a single file, in which case they act just like modmovie). Only modmovie has the -save-in-place option.
catmovie will concatenate the movies you pass-in one after another, while muxmovie starts all the movies at the same time. catmovie can be used to join movies that have been split up into parts (such as downloaded movies that have been split or movies that you purposely split via chapcutmovie or splitmovie). muxmovie can be used to put an audio track together with a video track, or to place a mask over the video of a movie (for example, to add black bars to remove the annoying flickering lines that some video cameras place at the top and bottom of the frame or to add a watermark).
Typical usage:
modmovie [arguments] file -o outputFile
Modifies a movie based on [arguments] and saves a reference movie to outputFile.
modmovie [arguments] file -save-in-place
Modifies a movie based on [arguments] and then saves it in place, replacing the original movie. It is recommended that you use an output file first, to make absolutely sure modmovie is doing what you want, before using the -save-in-place option.
catmovie file1 file2 ... fileN -o outputFile
Will concatenate file1 through fileN in that order and place the result in outputFile.
muxmovie file1 file2 ... fileN -o outputFile
Will multiplex together file1 through fileN (the order matters if more than one file has a video track; the later video tracks will appear on top of the earlier ones).
In addition to Quicktime movies, you can pass in any file that Quicktime can read, such as MPEGs, AVIs, MP3s, AAC audio, as well as still image files like GIFs, PNGs, JPEGs, and Photoshop files. (Still images are especially useful with the -scale option to muxmovie.) 3rd party plug-ins allow use of WMV, OGG, and many other filetypes.
Finally, instead of an input file, you can use a URL with the -url option.
Options:
There are two kinds of options for catmovie and muxmovie (there is no distinction for muxmovie since it takes only one input movie). Some options are global. They affect either the output file or the general behavior the tool. These options can appear anywhere on the command line. Other options apply to individual movies. If one of these options appears before any movies are mentioned on the command-line, they apply to all the movies. If one appears after a movie is mentioned, it applies only to that movie. So:
catmovie -msscale 1/2 movie1.mov movie2.mov
would scale both movie1.mov and movie2.mov to half size, while
catmovie movie1.mov -msscale 1/2 movie2.mov
would scale only movie1.mov to half size.
Note that the input movies are never modified by catmovie and muxmovie and are only modified by modmovie when the -save-in-place option is used.
Input option:
-url
Global options:
-o, -mp4, -self-contained, -no-fast-start, -no-compressed-header, -add-no-save, -q, -names-from-stdin, -name-from-stdin, -, -unique-tracks, -force-same-tracks, -chapter-track, -auto-chapters, -auto-chapters-merge, -add-chapter, -chapter-tool-xml, -remove-output-edit-list, -set-auto-play, -unset-auto-play, -set-looping, -unset-looping.
Global or file-specific options:
-noresolve, -remove-no-save, -chapter-name, -chaplist, -nochaplist, -chapter, -nochapter, -sscale, -vscale, -hscale, -vtranslate, -htranslate, -rotate, -resetmatrix, -msscale, -mvscale, -mhscale, -mrotate, -resetmmatrix, -placeAt, -scale, -noscale, -rate, -trimToShortestTrack, -scaleToShortestTrack, -scaleToLongestTrack, -trimToLengthOf, -scaleToLengthOf, -trimToLengthOfMovie, -scaleToLengthOfMovie, -scaleMovieToLengthOfMovie, -startAt, -trimTo, -duration, -trimBy, -scaleTo, -scaleMovieTo, -no-convert-tags, -list, -nolist, -track, -notrack, -enable, -disable, -timescale, -fix-roundoff-error, -remove-edit-list, -transparency-mode.
File-specific options only:
-save-in-place, -use-settings.
Input option:
-url URLString
Instead of getting the movie from a file, it will be downloaded from the given URL. In conjunction with -self-contained, this can be used to download a movie over http or ftp (not rtsp).
Output options:
These options modify the output file or the way in which it is produced.
-o outputFileName
Send output to the specified file. If the file already exists, it is overwritten, so be careful. If no -o option is present, the file is sent to out.mov (or out.mp4) on the Desktop. This option has no effect when modmovie is used with the -save-in-place option.
-mp4
Normally, QTCoffee tools produce a QuickTime movie as output. If all the source files contain only AAC audio, MPEG-4 video, and/or H264 video, however, it is usually possible to create a new MPEG-4 output file without re-encoding by using this option. This is particularly useful for joining iTunes AAC audio files (which are simply MPEG-4 files that only contain audio), for multiplexing MPEG-4 or H264 video and MPEG-4 (aka AAC) audio together into an MPEG-4 file, and for simple modifications to MPEG-4 files (scaling, translating, and rotating the video, changing the playback rate, etc). In some cases, you may need to use the -force-same-tracks option. Files produced by this option are always self-contained, but certain features (chapters & tags in particular) are not available in MPEG-4 files. Chapters can be added by using the XML file produced by the option -chapter-tool-xml with Apple's ChapterTool.
-save-in-place [modmovie only]
Saves the changes made by the options below into the original movie file. Be careful using this option, since you can destroy your movie.
-self-contained
By default, the movie produced does not contain the actual audio, video, and other data, but instead points to the data in the original movies (or in some other movie, if the original also contained just pointers). With this option, however, the output movie will contain all the data it needs to play, and will not depend on the existence of any other files. This is useful if it will not be edited any further and will be directly distributed. It will also make the movie “fast start” meaning that the movie can be placed on a web site and the user will not have to wait for the entire movie to download before they can begin playing it. This option has no effect when modmovie is used with the -save-in-place option; in order to flatten a movie, you need to output to a new file.
-no-fast-start
When making a self-contained movie, don't make it fast start. This is faster and uses less disk space, but the resulting movie is unsuitable for use on the web.
-no-compressed-header
When making a self-contained movie, don't compress the header.
-add-no-save
Add a special flag to the output movie that prevents users from editing it. This is a basic form of copy-protection.
-set-auto-play
Sets the movie to automatically play when opened in QuickTime player.
-unset-auto-play
Sets the movie not to automatically play when opened in QuickTime player.
-set-looping
Sets the movie to loop (when it reaches the end, play starts again at the beginning).
-unset-looping
Makes the movie play once through, and not loop when it reaches the end.
-use-settings [muxmovie and catmovie only]
Normally muxmovie and catmovie copy the settings of the first file into the output file. (Settings include the movie matrix, auto-play, volume, time scale, tags or annotations, and other general movie properties.) When this option follows a file, then the settings of that file will be used instead.
Program behavior options:
These options change how the program behaves or how it treats input files.
-q
Be quiet. The programs don't print informational messages and warnings.
-names-from-stdin
-name-from-stdin
Instead of reading the filename(s) from the command line, they will be read from the standard input, one file per line. This is useful for filenames with special characters that are difficult or impossible to type in the shell. Also sometimes useful in shell scripts for files with spaces and other punctuation.
-
A single “-” indicates that argument processing is over and that the next arguments are the names of the input files. This is useful when the name of one or more input files begins with a “-” character.
-unique-tracks [catmovie only]
By default, catmovie will try to use as few tracks as possible by adding each movie's tracks to compatible tracks in the concatenated movie that has been constructed so far. Thus, for example, the video from all the files will most likely go into a single track. Sometimes this causes movies to “skip” at the junction point. This option sometimes helps to prevent skipping (but not always). This option destroys track reference information (things like Sprite Tracks and Chapter Tracks will not work correctly.)
-force-same-tracks [catmovie only]
Sometimes catmovie will unexpectedly create additional tracks. This sometimes causes the movie to “skip” at the junction point. It also prevents use of the “-mp4” option (which is very useful when creating AAC audio files for iTunes). Use this option to force catmovie to use as few tracks as possible. It is important to check that the resulting file plays properly, as this option can produce invalid movies. This option destroys track reference information (things like Sprite Tracks and Chapter Tracks will not work correctly.)
-noresolve
Don't try to resolve references to other files. This is useful if you need to work on a movie that refers to data in other movies that are unavailable. Especially useful when you'd like to extract the tracks that are still usable even without the files for other tracks.
-remove-no-save
QuickTime movies can be created with a special flag that prevents editing. This allows you to edit such movies. Note! This option requires very low-level manipulation of QuickTime files and is considered experimental, so check your output files carefully.
Options relating to chapters:
-chapter-track chapterTrackName
This makes the named track into a chapter track for the movie. The track must be a text track and is generally not enabled (although it can be).
-auto-chapters [catmovie only]
Automatically create one chapter for each input movie. The name of the chapter is the full name of the input movie, if it has one; otherwise the filename. The -chapter-name option can be used to assign a different name. The -add-chapter option can be used to add additional chapters.
-auto-chapters-merge [catmovie only]
For each input movie that does not have a chapter track, a chapter is added with name determined as by -auto-chapters. Pre-existing chapter tracks are merged into the final movie; no additional chapters are automatically added for input movies that already have chapter tracks.
-chapter-name name [catmovie only]
When used with the -auto-chapters options, names the automatically generated chapter “name” instead of basing the name on the annotations or filename.
-add-chapter name time
Adds a chapter with the given name at the given time. If the movie has no chapter track, one is created. If a chapter track already exists in the movie, a new chapter track is created merging the already existing chapters with the added chapters; the old one is disabled but not removed. Works in conjunction with -auto-chapters but not -chapter-track. time refers to time in the final output file and should be of the form hh:mm:ss.fractions. You can leave off the hours or hours and minutes if they are 0; the fractional seconds can also be left off. Note that fractional seconds are used rather than frames, as in many video editing applications.
-chapter-tool-xml filename
An XML file compatible with Apple's ChapterTool is output to the specified filename. This is useful for adding chapters to the files produced by the -mp4 option.
-chaplist
List the names of the chapters in a movie. Chapters with an asterisk (“*”) next to them will be used in the creation of the output movie.
-nochaplist
Cancels out a global -chaplist option for a particular movie.
-chapter chapterName
If you include one or more -chapter options, then only the chapters listed are included in the output. To find out chapter names, use the -chaplist option. It is possible for chapters to have duplicate names. If this is ever a problem, email us and we'll fix it.
-nochapter chapterName
If you include one or more -nochapter options then all but the listed chapters will be used in the output file. Additional information appears under -chapter above.
Scaling, rotation, and other matrix modification options
Track matrix options
-sscale number
(Spatial Scale). Scale the size of the visual tracks by a factor of number. See -msscale above for information on the format of number.
Usage example:
catmovie fullscreen.mov widescreen.mov -sscale 3/4 -o output.mov
Concatenates a fullscreen movie with a widescreen movie, which is letterboxed to fit in a 4x3 frame.
-vscale number
Scale the vertical size of the visual tracks by a factor of number. See -msscale above for information on the format of number.
-hscale number
Scale the horizontal size of the visual tracks by a factor of number. See -msscale above for information on the format of number.
-vtranslate pixels
Translate all the visual tracks vertically by a specific number of pixels, which can be an integer, a floating point value, or a fraction in the form “x/y”.
-htranslate pixels
Translate all the visual tracks horizontally by a specific number of pixels. See -vtranslate for information on the format of pixels.
Usage example
catmovie fullscreen.mov -htranslate 160/3 widescreen.mov
Concatenates a fullscreen 320x240 movie with a widescreen 427x240 movie, centering the fullscreen movie in the frame. The 160/3 comes from: 160/3=((16/9)*240 - 320) / 2; (16/9)*240 is the width of the widescreen movie, so we subtract from that the width of the fullscreen movie (320) and divide by two get the amount we need to translate in order to center it.
-rotate degrees
Rotate all the visual tracks by degrees degrees clockwise.
-about X Y
This option can follow -rotate, -sscale, -vscale, or -hscale and causes the rotation or scaling to be centered about the point (X,Y) instead of (0,0). This matters when combining two movies that have used different -about values..
-resetmatrix
Resets the transformation matrix of all visual tracks to the identity before applying translation and scaling options.
Movie matrix options:
-msscale number
(Movie Spatial Scale). Scale the size of the movie by of a factor of number. This is usually used only for such things as double sizing or half sizing a movie. The number can be an integer, a floating point number, or a fraction in the form x/y.
Usage example:
modmovie -msscale 1/2 input.mov -save-in-place
Sets a movie to play at half size.
-mvscale number
(Movie Vertical Scale). Scale the vertical size of a movie by a factor of number. See -msscale for more information.
-mhscale number
(Movie Horizontal Scale). Scale the horizontal size of a movie by a factor of number. See -msscale for more information.
-mrotate number
Rotate the movie by number degrees clockwise. Rarely used; use -rotate instead.
-about X Y
This option can follow -mrotate, -msscale, -mvscale, or -mhscale and causes the rotation or scaling to be centered about the point (X,Y) instead of (0,0). This rarely makes any difference; using it with the track scaling and rotation options is more useful.
-resetmmatrix
Resets the transformation matrix of the movie to the identity before applying scaling options.
Time and duration related options:
These options scale or trim the duration of tracks or control their placement in the movie’s timeline.
-placeAt time [muxmovie only]
Adds the movie being multiplexed to the current movie at the specified time, instead of at the beginning. When used as a global option, it does not apply to the first movie. time should be of the form hh:mm:ss.fractions. You can leave off the hours or hours and minutes if they are 0; the fractional seconds can also be left off. Note that fractional seconds are used rather than frames, as in many video editing applications.
-scale [muxmovie only]
Scales the length of movie being multiplexed in to be the same as the current movie so far. When used as a global option, it does not apply to the first movie. This can be useful for resolving audio synchronization problems. It is also useful when multiplexing still image files for use as video masks. E.g.
muxmovie -scale VideoMovie MaskMovie AudioMovie -o OutputMovie
will scale MaskMovie and AudioMovie to be the same length as VideoMovie and then multiplex them together, placing the output in OutputMovie.
-noscale [muxmovie only]
Cancels out a global “-scale” option for a particular movie.
-rate factor
Change the rate of playback by a factor of factor (which can be an integer, floating point value, or a fraction of the form "numerator/denominator").
Usage example:
modmovie -rate 160/180 song.m4a -mp4 -o song_slow.m4a
Changes a 180 BPM song to a 160 BPM song. (By the way, iTunes will not play back the resulting m4a file correctly, although QuickTime will; if you output a QuickTime movie instead of an MPEG-4, iTunes will be able to play it.)
Sometimes you will find or make a movie with tracks of different length. This can manifest itself as a few annoying white or blank frames at the end of the movie; this is especially annoying when concatenating movies. You can use the various "-trim" options to fix this problem. If the audio and video are out of sync as well, the "-scale" options may be helpful. The "-startAt" option allows you to remove material from the beginning of a movie. Note that the “-scale” options don't help with MPEG-1 and MPEG-2 movies because of limitations in the way QuickTime handles them, and the “-startAt” and “-trim” options will not be able to make file smaller. (MPEG-4 works fine on both accounts.)
-trimToShortestTrack
Trim the movie to the duration of its shortest track. Any tracks that are longer will be cut off at the end.
-scaleToShortestTrack
Long tracks are sped-up so that all tracks are the same duration as the shortest track. If audio and
-scaleToLongestTrack
Short tracks are slowed-down so that all tracks are the same duration as the longest track.
-trimToLengthOf name
Trim the movie to the duration of the track named name. Any tracks that are longer will be cut off at the end. Shorter tracks will not be affected.
-scaleToLengthOf name
Scale (speed up or slow down) all tracks so that they are the same length as the track named name.
-trimToLengthOfMovie name
Trim the movie to the be the same duration as the movie with the given name (if it is longer; if it is shorter, nothing happens).
-scaleToLengthOfMovie name
Scale each track of the movie to be the same duration as the movie with the given name. (Note: each track is scaled independently; this is probably not what you want; try -scaleMovieToLengthOfMovie.)
-scaleMovieToLengthOfMovie name
Scale the entire movie (speeding it up or slowing it down) so that it is the same length as the movie with the given name. All tracks are scaled by the same amount.
-trimTo duration
-duration duration
Trim the length of the movie to the specified duration. duration should be of the form hh:mm:ss.fractions. See the section “Times and Durations” for more information.
-scaleTo duration
Scale each track of the movie to the given duration. See -trimTo above for a description of the duration argument. (Note: each track is scaled independently; this is probably not what you want; try -scaleMovieTo.)
-scaleMovieTo duration
Scale the entire movie (speeding it up or slowing it down) to the given duration. See -trimTo above for a description of the duration argument.
-trimBy duration
Remove the specified duration from the end of the movie. See -trimTo above for a description of the duration argument.
-startAt time
Begin the movie at the specified time; alternatively you can think of this as trimming the specified duration from the beginning of the movie. See -trimTo above for a description of the duration argument. Note that “-startAt” is applied before -trim and -scale arguments (regardless of the order the arguments appear on the command line). So “modmovie in.mov -startAt 1:00 -trimTo 2:00” will do what you probably expect it to do, and extract a 2 minute segment of the movie beginning at 1:00; but this may not be what you want in conjunction with "-scaleTo," for example.
iTunes Tag Options
-no-convert-tags
iTunes uses a special format for the tags in AAC and protected AAC files that is not understood by QuickTime Player (nor iTunes if they appear in anything other than an AAC or protected AAC file). By default, when the program encounters such tags, it does its best to convert the tags into standard QuickTime tags. However, this format has limits. It cannot handle multilingual tags and you will also notice some missing tags, such as BPM, cover art, and disk number. Even worse, iTunes only recognizes tags that use Roman characters and QuickTime Player sometimes mangles non-Roman characters. We do our best to translate the tags. It is possible that the tag conversion will cause problems. Use this option to disable tag conversion. QuickTime 7 has greatly enhanced tag support and a future version of QTCoffee will certainly exploit it.
-remove-itunes-tags
By default the program will leave the old iTunes tags in the file, even after converting them. This means, however, that if you run the output file back through one of the programs, the tags will get converted again and any changes made since then will be lost. Use this option to remove the old tags.
Track manipulation options
Allow tracks to be removed or included, enabled or disabled.
-list
List the names of the tracks in a movie. Tracks with an asterisk ("*") next to them will be included in the output movie.
-nolist
Cancels out a global "-list" option for a particular movie.
-track trackName
If you include one or more -track options, then only the tracks listed are included in the output. To find out track names, use the "-list" option. It is possible in certain cases for tracks to have duplicate names. If this is ever a problem, email us and we'll fix it.
Usage examples:
catmovie -track "Video Track" -list file1 file2
Concatenate only the video tracks from file1 and file2 to the default output file. Also lists the names of the tracks in file1 and file2 and which are used.
muxmovie file1 -track "Video Track" -track "Chapter Track" file2 -track "Sound Track"
Multiplexes the video and chapter tracks from file1 with the sound track from file2
-notrack trackName
If you include one or more -notrack options then all but the listed tracks will be used in the output file. Additional information appears under "-track" above.
Usage examples:
catmovie -notrack "Sound Track" file1 file2
Concatenate all tracks except for the sound track of file1 and file2.
muxmovie file1 -notrack "Sound Track" -list file2 -track "Sound Track"
Multiplexes the sound track from file2 with everything but the sound track from file1. Also lists the tracks of file1 so we can make sure we got it right.
modmovie file -notrack "Sound Track" -save-in-place
Removes the audio from a file.
There's no telling what will happen if you use both "-track" and "-notrack" on the same movie (e.g. having a "-track" global option with a "-notrack" option on a specific file). It might work, it might not. We haven't really thought through what the results ought to be, so the program will just do whatever it happens to do in that case (nothing bad will happen; just not necessarily what you want to happen).
-disable trackName
Disables the named track. It will still be in the movie, but will not display video or text or play sound or whatever it is supposed to do. No warning is given if the track is not found. To find out track names, use the "-list" option.
-enable trackName
Enables the named track. No warning is given if the track is not found. To find out track names, use the "-list" option.
Miscellaneous options:
-timescale scale
Sets the time scale of the movie. Internally, QuickTime represents time as a fraction with the time scale as the denominator. Each track (technically, the media within the track) has its own time scale (which cannot be changed), the movie also has a time scale, which can be set with this option.
-timescale -sameAsTrack trackName
Sets the time scale of the movie to be the same as that of the named track (technically, set it to the time scale of the media within the named track). Usually it is best to choose the video track, since otherwise you may end up with blank or white frames at the end of the movie or at the joins.
-fix-roundoff-error
This is a somewhat technical option designed to allow joined AAC files to work with iTunes 5.0-5.0.1. It should be irrelevant for most other purposes. Each track in a QuickTime movie contains a media, which has its own time scale. For example, audio from a CD usually has a time scale of 44100. The movie itself also has a time scale, which is shared by its tracks. (See http://developer.apple.com/quicktime/qttutorial/movies.html for more information.) If that timescale is smaller than or incomensurate with the media time scale, then the track duration may be slightly shorter than the media duration. When the movie is concatenated to another movie, this causes an "edit" to be required–a small portion of the media is excluded from playback. This rarely causes any problem, but iTunes 5.0-5.0.1 only plays the first edit in an edit list in an AAC file. This option, in conjunction with the -timescale option, attempts to repair a track whose duration has been rounded off. Such tracks can then usually be joined without producing an edit. Sometimes the joined tracks still produce an edit. In that case you may need to trim other tracks or, in some cases, use the -remove-output-edit-list option.
-remove-edit-list
This option removes the edit list from all tracks in a movie. The media will play straight through from beginning to end. This can be used to modify previously joined files so that they work with iTunes 5.0-5.0.1.
-remove-output-edit-list
This option removes the edit list from the output file. The media will play straight through from beginning to end. This can be used to create joined files that work with iTunes 5.0-5.0.1.
-transparency-mode mode [muxmovie only]
If you wish to overlay one or more visual tracks with transparency (for example, for a semi-transparent watermark), use one of these options. Possible values of mode are
none No transparency. Usually used to cancel a global “-transparency-mode”.
straight-alpha Use the alpha channel that's in the movie or image.
transparent color The specified color is transparent. All others are opaque. “color” should be of the form red,green,blue where red, green, and blue are integers between 0 and 255. E.g.
muxmovie -scale Movie.mov Watermark.gif -transparency-mode transparent 0,0,0
will place a the image Watermark.gif in the upper-left corner, with any black pixels showing through to the background video.
transparent16 color The specified color is transparent. All others are opaque. “color” should be of the form red,green,blue where red, green, and blue are integers between 0 and 65535.
blend proportion Blend the two images using the specified proportions. propotion should be red-prop,green-prop,blue-prop where red-prop, green-prop, and blue-prop are real numbers between 0 and 1.
PNGs are a good choice for use with straight-alpha, but be careful using PNGs with transparent or transparent16 when the transparent color is neither black nor white. PNGs often store color maps and gamma values, which change the mapping between the colors values in the PNG and the color values that QuickTime sees, which can make specifying the transparent color very difficult. If you encounter this problem, try a less intelligent format like GIF or BMP, or use PNG's ability to handle true transparency and use straight-alpha.
Complex usage example:
In this example we will take some DV footage and scale it to a 4x3 aspect ratio, then concatenate it with some 16x9 footage. We will leave the vertical height of both pieces of footage the same and include black bars on the left and right sides of the 4x3 movie (letterboxing, but the reverse from how it is usually done). We will need a 720x480 entirely black picture (make this in Photoshop, Graphic Converter, etc.) called, say, BlackFrame.png.
We want to add the black background. muxmovie cannot apply the -scale option to the first argument, so we cannot use BlackFrame.png there. But if it is the second argument, it will cover up the video. So instead we use the rather wordily named -scaleMovieToLengthOfMovie option to make the black frame the correct duration. Meanwhile, we scale the 4x3 movie by 3/4 horizontally, so that it is correctly sized relative to the 16x9 movie. We also translate by (720 - 720*(3/4)) / 2 = 90 in order to center it.
muxmovie BlackFrame.png -scaleMovieToLengthOfMovie 4x3.dv 4x3.dv -hscale 3/4 -htranslate 90 -o 4x3_framed.mov
Now we concatenate with our 16x9 footage and scale the whole thing to the correct aspect ratio. Some background: DV footage comes as 720x480 frames. However, it is only the central 704x480 pixels that form the 4x3 or 16x9 frame (in analog systems, the 8 pixels on either side are not seen). A 4x3 image has those 704 pixels scaled to a size of 480*(4/3)=640. So we scale the frame by the factor of 640/704=10/11 for 4x3. 16x9 is 4/3 wider, so the scale factor is 40/33.
catmovie -hscale 40/33 4x3_framed.mov 16x9.dv -o output.mov
You can now use QuickTime Pro or qt_tools to export this movie to some compressed format.
chapcutmovie
splitmovie
chapcutmovie allows you to split a movie by chapters. This is useful, for example, for splitting up long iMovie projects into smaller pieces that can be individually compressed for presentation on the web. It's also useful if you want to perform some sort of editing on specific chapters. You can then concatenate the chapters back together again with catmovie. splitmovie splits a movie at times you specify or into equal duration pieces. Note that because of limitations in QuickTime, MPEG-1 and MPEG-2 input movies will not get any smaller when used with splitmovie -self-contained. (MPEG-4 files work as expected.)
Typical usage:
chapcutmovie filename -o outputFileName
The chapters of the movie are stored in files based on the name outputFileName. In particular, if your chapters are named "Introduction," "Middle," and "Credits", then
chapcutmovie "My Great Movie.mov" -o ~/Desktop/"My Great Movie Chapter.mov"
would produce files named
"My Great Movie Chapter-1 Introduction.mov", "My Great Movie Chapter-2 Middle.mov", and "My Great Movie Chapter-3 Credits.mov" and place them on the Desktop. The files are numbered so that they are ordered correctly in the Finder and in the shell. Thus you can concatenate them again using "catmovie *.mov".
splitmovie -duration 1:30 input.mov -o output.mov
will produce files named "output-1.mov", "output-2.mov", etc. Each file, except possibly for the last, will be 1 minute 30 seconds long.
splitmovie -numPieces 10 input.mov -o output.mov
will produce 10 files named “output-01.mov”, “output-02.mov”, …, “output-10.mov”. Each file will be the same duration.
splitmovie -splitAt 1:00 -splitAt 11:33.2 -splitAt 1:00:00 input.mov -o output.mov
will produce four files. "output-1.mov" will contain 0:00-1:00 of input.mov; "output-2.mov" will contain 1:00-11:33.2 (11 minutes, 33.2 seconds); "output-3.mov" will contain 11:33.2-1:00:00; and "output-4.mov" will contain from 1 hour to the end of the movie.
If you do not specify an output file name, the names are based on the name "out.mov" and the files are placed on the desktop.
Options:
-q
Be quiet. Don't print informational messages.
-mp4
Make an mp4 file, if the input is suitable. See the description under catmovie/muxmovie above.
-self-contained
Make self-contained movies, instead of the default pointer movies. See the description under catmovie/muxmovie above.
-no-fast-start
When making a self-contained movie, don't make it fast-start. See the description under catmovie/muxmovie above.
-no-compressed-header
When making a self-contained movie, don't compress the movie header. See the description under catmovie/muxmovie above.
-name-from-stdin
Take filenames from standard input instead of the command-line. See the description under catmovie/muxmovie above. Note the difference in spelling.
-
No more options follow; all remaining arguments are filenames. See the description under catmovie/muxmovie above.
splitmovie only options
-duration timevalue
Split the movie into equal duration pieces (except for the last piece, which may be shorter). "timevalue" is of the form "hh:mm:ss.fraction". See the section “Times and Durations” for more information on the format of duration.
-splitAt timevalue
Set a split point at the indicated time. See -duration for a description of timevalue. There are generally multiple -splitAt arguments. The movie is split at the split points.
chaptcutmovie only options
-no-chapter-names
When creating output files, don’t include the names of the chapters in the filenames. Only the numbers will be used.
Times and Durations
Times and durations are used by several arguments. They can be input in the form hh:mm:ss.fractions. You can leave off the hours, minutes, or fractional seconds if they are zero. If minutes or seconds is the first field, it can be bigger than 60. Please note that decimal fractions of a second are used; some video editing software uses "frames" for smaller-than-one-second divisions. Please be aware of this difference.
Examples:
01:10.4 1 minute, 10.4 seconds
1:10 1 minute, 10 seconds
3600 3600 seconds (1 hour)
100.45 100.45 seconds
61:10 61 minutes, 10 seconds
1:01:10 1 hour, 1 minute, 10 seconds (same as above)
48:00:00 48 hours.
Version History
1.2.5 Added -url option
Fixed some issues with -mp4 not working with some H.264 tracks.
Sometimes the first chapter does not start at the beginning of the movie; we handle this by calling the unchaptered part “<unnamed chapter>”.
Added -no-chapter-names option to chapcutmovie
1.2.4 Fixed regression in -timescale -sameAsTrack that was introduced in 1.2.3.
1.2.3 The -use-settings option now works with muxmovie
Some options that were “global” for catmovie & muxmovie did not work at all with modmovie. This has been fixed.
-timescale now works with explicit numbers, and not just with -sameAsTrack
New -numPieces option for splitmovie
1.2.2 Fixed the -chapter-track option
Fixed problems that could occur when using the -ssize, -hsize, and -vsize options with movies whose non-visual tracks have non-zero sizes.
1.2.1 QTCoffee tools are now universal binaries.
The -mp4 option can now pass-through H.264.
1.2 Moved man pages to a place that is searched by default.
Added -(un)set-auto-play and -(un)set-looping.
Installer package checks for Mac OS 10.3.9 or later.
Added many more -trim and -scale options, and -startAt.
Added -placeAt to muxmovie.
Added -transparency-mode.
No longer support Jaguar (Mac OS 10.2) and only support 10.3.9 for Panter.
Improved error message when file is not found.
Added -chapter-track, -auto-chapter, -auto-chapter-merge, and -add-chapter.
Added -enable and -disable options.
Added “How To” document so most people don't have to read the whole Read Me.
Fixed crash when -scale, -rotate, etc. were last on command line.
Fixed crashes that occurred when command-line options were erroneous
Fixed bug that could cause chapters to be in random order.
Added -add-no-save and -remove-no-save.
Fixed -no-compressed-header option.
Ability to output chapters to ChapterTool XML file.
Reorganized Read Me and man pages, so options are organized by theme.
Added -timescale option.
Added iTunes 5 helper options: -fix-roundoff-error, -remove-edit-list, and -remove-output-edit-list.
Fixed bug interpreting durations whose first field is > 60.
1.1.1 Fixed bug with -o option not working in splitmovie and chapcutmovie
1.1 Added information about concatenating AAC files to documentation
Improved iTunes tag conversion.
Added -force-same-tracks to catmovie for improved AAC joining
Added -trimToShortestTrack
Added -rotate option (ability to rotate tracks and movies)
Added -about option, allowing scaling & rotation about a specific point
Added splitmovie to split a movie at specifc times or into equal duration parts.
Added -mp4 option
Added -no-fast-start and -no-compressed-header option
1.0.2 Added warning when -self-contained is not used.
Added -q option to quiet the warning.
1.0.1 Fixed bug when using many files (hundreds) with catmovie or muxmovie.
1.0 First release