Docbook2Wiki: Initial conversion from Docbook

2008-03-06T23:50:56Z

Initial conversion from Docbook

New page

{{QuickTime for Java: A Developer's Notebook/TOC}}
Playback is nice, but you have nothing to play if you lack tools to create media, and the most critical of these are editing tools. If you've ever used iMovie with your home movies, you know what I'm talking about: there's a huge difference between watching a cute collection of scenes of your kids playing, set to music, and watching the two hours of unedited raw footage you started with. Sometimes, less ''is'' more.

== Copying and Pasting ==

The most familiar form of editing is copy-and-paste, which many users already are familiar with from the "pro" version of QuickTime Player. The metaphor is identical to how copy-and-paste works in nonmedia applications such as text editors and spreadsheets: select some source material of interest, do a "copy" to put it on the system clipboard, select an insertion point in this or another document, and do a "paste" to put the contents of the clipboard into that target.

In the simplest form of a QuickTime copy-and-paste, the controller bar (from <tt>MovieController</tt>) is used to indicate where copies and pastes should occur. By shift-clicking, a user can select a time-range from the current time (indicated by the play head) to wherever the user shift-clicks (or, if he is dragging, wherever the mouse is released).

<div class="note">
'''Note'''

''QuickTime Pro costs money ($29.99 as of this writing), but it allows you to exercise much of the QuickTime API from QuickTime Player, which can be a useful debugging tool''.
</div>

=== How do I do that? ===

<tt>BasicQTEditor</tt>, shown in [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-EX-1|Example 3-1]], will be the basis for the examples in this chapter. It offers a single empty movie window (with the ability to open movies from disk in new windows or to create new empty movie windows), and an Edit menu with cut, copy, and paste options.

<div id="quicktimejvaadn-CHP-3-EX-1">
'''Example 3-1. A copy-and-paste movie editor'''

package com.oreilly.qtjnotebook.ch03;

import quicktime.*;
import quicktime.qd.QDRect;
import quicktime.std.*;
import quicktime.std.movies.*;
import quicktime.app.view.*;
import quicktime.io.*;

import java.awt.*;
import java.awt.event.*;

import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

public class BasicQTEditor extends Frame
implements ActionListener {

Component comp;

Movie movie;
MovieController controller;
Menu fileMenu, editMenu;
MenuItem openItem, closeItem, newItem, quitItem;
MenuItem copyItem, cutItem, pasteItem;
static int newFrameX = -1;
static int newFrameY = -1;
static int windowCount = 0;

/** no-arg constructor for "new" movie
*/
public BasicQTEditor ( ) throws QTException {
super ("BasicQTEditor");
setLayout (new BorderLayout( ));
QTSessionCheck.check( );
movie = new Movie(StdQTConstants.newMovieActive);
controller = new MovieController (movie);
controller.enableEditing(true);
doMyLayout( );
}

/** file-based constructor for opening movies
*/
public BasicQTEditor (QTFile file) throws QTException {
super ("BasicQTEditor");
setLayout (new BorderLayout( ));
QTSessionCheck.check( );
OpenMovieFile omf = OpenMovieFile.asRead (file);
movie = Movie.fromFile (omf);
controller = new MovieController (movie);
controller.enableEditing(true);
doMyLayout( );
}
/** gets component from controller, makes menus
*/
private void doMyLayout( ) throws QTException {
// add movie component
QTComponent qtc =
QTFactory.makeQTComponent (controller);
comp = qtc.asComponent( );
add (comp, BorderLayout.CENTER);
// file menu
fileMenu = new Menu ("File");
newItem = new MenuItem ("New Movie");
newItem.addActionListener (this);
fileMenu.add (newItem);
openItem = new MenuItem ("Open Movie...");
openItem.addActionListener (this);
fileMenu.add (openItem);
closeItem = new MenuItem ("Close");
closeItem.addActionListener (this);
fileMenu.add (closeItem);
fileMenu.addSeparator( );
quitItem = new MenuItem ("Quit");
quitItem.addActionListener (this);
fileMenu.add(quitItem);
// edit menu
editMenu = new Menu ("Edit");
copyItem = new MenuItem ("Copy");
copyItem.addActionListener(this);
editMenu.add(copyItem);
cutItem = new MenuItem ("Cut");
cutItem.addActionListener(this);
editMenu.add(cutItem);
pasteItem = new MenuItem ("Paste");
pasteItem.addActionListener(this);
editMenu.add(pasteItem);
// make menu bar
MenuBar bar = new MenuBar( );
bar.add (fileMenu);
bar.add (editMenu);
setMenuBar (bar);
// add close-button handling
addWindowListener (new WindowAdapter( ) {
public void windowClosing (WindowEvent e) {
doClose( );
}
});
}

/** handles menu actions
*/
public void actionPerformed (ActionEvent e) {
Object source = e.getSource( );
try {
if (source = = quitItem) doQuit( );
else if (source = = openItem) doOpen( );
else if (source = = closeItem) doClose( );
else if (source = = newItem) doNew( );
else if (source = = copyItem) doCopy( );
else if (source = = cutItem) doCut( );
else if (source = = pasteItem) doPaste( );
} catch (QTException qte) {
qte.printStackTrace( );
}
}

public void doQuit( ) {
System.exit(0);
}

public void doNew( ) throws QTException {
makeNewAndShow( );
}

public void doOpen( ) throws QTException {
QTFile file =
QTFile.standardGetFilePreview (QTFile.kStandardQTFileTypes);
Frame f = new BasicQTEditor (file);
f.pack( );
if (newFrameX >= 0)
f.setLocation (newFrameX+=16, newFrameY+=16);
f.setVisible(true);
windowCount++;
}

public void doClose( ) {
setVisible(false);
dispose( );
// quit if no windows now showing
if (--windowCount = = 0)
doQuit( );
}

public void doCopy( ) throws QTException {
Movie copied = controller.copy( );
copied.putOnScrap(0);
}

public void doCut( ) throws QTException {
Movie cut = controller.cut( );
cut.putOnScrap(0);
}

public void doPaste( ) throws QTException {
controller.paste( );
pack( );
}

/** Force frame's size to respect movie size
*/
public Dimension getPreferredSize( ) {
System.out.println ("getPreferredSize");
if (controller = = null)
return new Dimension (0,0);
try {
QDRect contRect = controller.getBounds( );
Dimension compDim = comp.getPreferredSize( );
if (contRect.getHeight( ) > compDim.height) {
return new Dimension (contRect.getWidth( ) +
getInsets( ).left +
getInsets( ).right,
contRect.getHeight( ) +
getInsets( ).top +
getInsets( ).bottom);

} else {
return new Dimension (compDim.width +
getInsets( ).left +
getInsets( ).right,
compDim.height +
getInsets( ).top +
getInsets( ).bottom);

}
} catch (QTException qte) {
return new Dimension (0,0);
}
}

/** opens a single new movie window
*/
public static void main (String[ ] args) {
try {
Frame f = makeNewAndShow( );
// note its x, y for future calls
newFrameX = f.getLocation( ).x;
newFrameY = f.getLocation( ).y;
} catch (Exception e) {
e.printStackTrace( );
}
}

/** creates "new" movie frame, packs and shows.
used by main( ) and "new"
*/
private static Frame makeNewAndShow( )
throws QTException {
Frame f = new BasicQTEditor( );
f.pack( );
if (newFrameX >= 0)
f.setLocation (newFrameX+=16, newFrameY+=16);
f.setVisible(true);
windowCount++;
return f;
}
}
</div>

<div class="note">
'''Note'''

''With the downloaded book code, compile and run this with ant run-ch03-basicqteditor''.
</div>

[[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-1|Figure 3-1]] shows the <tt>BasicQTEditor</tt> class in action, with two windows open. The window on the left is the original empty movie window, with the user about to paste in some contents. The window on the right is a movie that was opened from a file. Note the small stretch of darker gray in the timeline, under the play head, which indicates the selected segment that was copied from the movie to the system clipboard.

<div id="quicktimejvaadn-CHP-3-FIG-1">
'''Figure 3-1. BasicQTEditor with two movies open'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt39.png|BasicQTEditor with two movies open]]
</div>

Also note that when running in Windows, as pictured here, the menus are inside the windows. On Mac OS X, the usage of AWT means the File and Edit menus will be at the top of the screen in the Mac's "One True Menu Bar."

One usability note: for simplicity, I haven't tried to make this particularly smart about what the user "really wants," and that can be bad on the paste . The paste will replace whatever is selected in the target movie, and if there is no selection, it will paste to the beginning of the movie. It's probably more typical to add clips either to the end of the movie, or to the current time as indicated by the play head (i.e., to behave as if a lack of a selection should be interpreted as a zero-length selection beginning and ending at the movie's current time). It's simple enough to add this kind of intelligence to <tt>doPaste()</tt> and find a behavior that feels better.

=== What just happened? ===

This is a big example, so here's an overview.

The no-arg constructor, <tt>BasicQTEditor( )</tt>, initializes QuickTime with [[QuickTime for Java: A Developer's Notebook/Getting Up and Running with QuickTime for Java|Chapter 1]]s <tt>QTSessionCheck</tt>, then creates a new empty <tt>Movie</tt>, gets a <tt>MovieController</tt> for it, and calls <tt>doMyLayout</tt>. A second constructor, <tt>BasicQTEditor (QTFile)</tt>, is essentially identical, except that instead of creating an empty movie, it gets a movie from the provided <tt>QTFile</tt>. The <tt>movie</tt> and the <tt>controller</tt> instance variables are used by many methods throughout the application.

The <tt>doMyLayout( )</tt> method sets up the menus and their <tt>ActionListeners</tt> and reminds us that building GUIs in code is a pain.

<tt>actionPerformed (ActionEvent)</tt> is used to farm out method calls from clicks on the various menu items.

<tt>doQuit( )</tt> is a trivial call to <tt>System.exit(0)</tt>. Remember that the <tt>QTSessionCheck</tt> call has set up a shutdown handler to close QuickTime when Java goes away.

<tt>doNew( )</tt> trivially calls <tt>makeNewAndShow()</tt>, which is a convenience method to call the no-arg constructor (which creates an empty <tt>Movie</tt>), pack the frame, and move it down and to the right 16 pixels from the last place a new window was created.

<div class="tip">
'''Tip'''

Note that there's nothing here to keep new windows from going off-screen if the user creates enough of them. In a more polished application, you'd check the proposed x and y against the screen size reported by the AWT's <tt>Toolkit.getScreenSize()</tt> .
</div>

<tt>doOpen( )</tt> brings up a file-open dialog and calls the file-aware constructor. It then <tt>pack( )</tt> s the window and positions it in the same way <tt>makeNewAndShow()</tt> does.

<tt>doClose( )</tt> closes the frame and, if it is the last open window, quits the application via <tt>doQuit( )</tt> (yes, this is Windows-like behavior, as opposed to the typical Mac application which can hang around with no open windows).

<tt>doCopy( )</tt> and <tt>doCut( )</tt> are practically identical, and each needs only two lines to do its thing. They make a call to the <tt>MovieController</tt> to cut or copy the current selection and return the result as a new <tt>Movie</tt>. Then they put this movie on the system clipboard with the movie's <tt>putOnScrap( )</tt> call.

<tt>doPaste( )</tt> is even simpler: it just calls the controller's <tt>paste( )</tt> method and then re-<tt>pack( )</tt>s the window.

The <tt>getPreferredSize()</tt> method overrides the default by indicating that the window needs to be large enough to contain the movie, its control bar, and any insets that might be set. This is why you should <tt>pack( )</tt> after each paste: the original empty movie has no size other than its control bar, so when you paste into it, the size of the movie (and thus its controller) changes to accommodate the pasted contents, and you need the frame to adjust to that.

<div class="warning">
'''Warning'''

This really should be taken care of automatically in Java, because the use of a <tt>BorderLayout</tt> should allow the contents to achieve their preferred size on a <tt>pack( )</tt>. Unfortunately, on Mac OS X, the <tt>QTComponent</tt> exhibits a bizarre behavior where its preferred size is set ''once'', when it's packed, and never again. So, a component built from an empty movie always thinks it's supposed to be zero pixels high by 160 pixels wide, even if you paste in contents much larger than that. Fixing this reveals the opposite problem on Windows: sometimes there's a good preferred size and a zero-height controller bound. The version here prefers whichever set of bounds has a greater height.
</div>

=== What about... ===

...that weird play head? That is odd, isn't it? The call to <tt>enableEditing(true)</tt> has changed the play head ball to an hourglass shape. [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-2|Figure 3-2]] shows it at an enlarged size.

<div id="quicktimejvaadn-CHP-3-FIG-2">
'''Figure 3-2. MovieController scrubber bar with editing enabled'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt40.png|MovieController scrubber bar with editing enabled]]
</div>

My guess is that the shape is supposed to help you select the exact point for making a selection, instead of burying it under the center of the ball. That said, there's a reason you don't see this elsewhere: this default widget isn't terribly well-suited to editing. The QuickTime Player application that comes with QuickTime has a custom controller widget with two little triangles under the timeline to mark in and out points. But that control, like this one, shares the flaw that the accuracy of your edit is limited by the on-screen size of your movie. More serious editing applications, like Premiere and Final Cut Pro, have custom GUI components for editing, usually based on a timeline that can be "zoomed" to an arbitrary accuracy. Of course, one could do the same with AWT or Swing, tracking <tt>MouseEvent</tt>s, <tt>paint()</tt>ing as necessary, and making programmatic calls to QTJ to perform actions.

== Performing "Low-Level" Edits ==

Low-level edits are a separate set of editing calls that don't involve the clipboard or selection metaphors. They're called "low level" because instead of operating at the conceptual level of "paste the contents of the clipboard into the user's current selection," they work at the level of "insert a segment from movie M1, ranging from time A to time B, into movie M2 at time C."

<div class="note">
'''Note'''

''By way of comparison, although QuickTime has two sets of editing functions, Sun's Java Media Framework has no editing API at all''.
</div>

=== How do I do that? ===

This version reimplements <tt>doCopy( )</tt>, <tt>doCut( )</tt>, and <tt>doPaste( )</tt> to use low-level editing calls on the <tt>Movie</tt> instead of cut/copy/paste-type calls on the <tt>MovieController</tt>.

First, <tt>LowLevelQTEditor</tt> needs a static <tt>Movie</tt>, called <tt>copiedMovie</tt>, to keep track of what's on its virtual "clipboard" so that it can be shared across the new <tt>doCopy( )</tt>, <tt>doCut()</tt>, and <tt>doPaste( )</tt> methods:

public void doCopy( ) throws QTException {
copiedMovie = new Movie( );
TimeInfo selection = movie.getSelection( );
movie.insertSegment (copiedMovie,
selection.time,
selection.duration,
0);
}

public void doCut( ) throws QTException {
copiedMovie = new Movie( );
TimeInfo selection = movie.getSelection( );
movie.insertSegment (copiedMovie,
selection.time,
selection.duration,
0);
movie.deleteSegment (selection.time,
selection.duration);
controller.movieChanged( );
}

public void doPaste( ) throws QTException {
if (copiedMovie = = null)
return;
copiedMovie.insertSegment (movie,
0,
copiedMovie.getDuration( ),
movie.getSelection( ).time);
controller.movieChanged( );
pack( );
}

<div class="note">
'''Note'''

''You can make ant compile and run this example with ant run-ch03-lowlevelqteditor''.
</div>

The only thing the user might see as being different or odd in this example is that the cut or copied clip does not get put on the system clipboard because low-level edits don't touch the clipboard.

<div class="tip">
'''Tip'''

For what it's worth, this example was intended originally to be a drag-and-drop demo, for which these low-level, segment-oriented calls are particularly well-suited. Unfortunately, the QTComponent won't generate an AWT "drag gesture." I suppose it would be a little unnatural to drag the current image as a metaphor for copying a segment of a movie. Anyway, if you decide to do your own controller GUI, you can use this low-level stuff for your drag-and-drop.
</div>

=== What just happened? ===

The <tt>doCut( )</tt>, <tt>doCopy( )</tt>, and <tt>doPaste( )</tt> methods all call <tt>Movie.insertSegment()</tt> ; either to put some part of a source movie into the clipboard-like <tt>copiedMovie</tt> or to put the <tt>copiedMovie</tt> into the target movie. This method takes four arguments:

* The <tt>Movie</tt> to insert into
* The start time of the segment, in the movie's time scale
* The end time of the segment, in the movie's time scale
* The time in the target movie when the segment should be inserted

In the case of a cut, the <tt>deleteSegment()</tt> call removes the segment that was just copied out. This method simply takes the beginning and end times of the segment to delete.

<div class="note">
'''Note'''

''Time scales are covered in [[QuickTime for Java: A Developer's Notebook/Playing Movies|Chapter 2]], in the section [[QuickTime for Java: A Developer's Notebook/Playing Movies#Showing a Movie's Current Time|Section 2.5]].''"
</div>

In the <tt>doPaste( )</tt> and <tt>doCut( )</tt> methods, a call to <tt>MovieController.movieChanged( )</tt> lets the controller know that the movie was changed in a way that didn't involve a method call on the controller, and that the controller now needs to update itself to adjust to the changed duration, current time, etc.

=== What about... ===

...any other low-level calls? There is an interesting method in the <tt>Movie</tt> class, called <tt>scaleSegment()</tt> , which changes the duration of a segment, meaning it either slows it down or speeds it up to suit the specified duration. This could be handy for creating a " slow-motion" or "fast-motion" effect from a normal-speed source, or stretching it out to fit a piece of audio.

== Undoing an Edit ==

Critical to any kind of editing is the ability to back out of a change that had unintended or undesirable effects. Fortunately, controller-based cuts and pastes can be undone with some fairly simple calls.

=== How do I do that? ===

<tt>UndoableQTEditor</tt> builds on the original <tt>BasicQTEditor</tt> by adding an "undo" menu item. The <tt>doUndo( )</tt> method it calls has an utterly trivial implementation:

public void doUndo( ) throws QTException {
controller.undo( );
}

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-undoableqteditor''.
</div>

=== What just happened? ===

With a simple call to <tt>MovieController.undo()</tt> , the program gained the ability to undo a cut or paste, or any other destructive change made through the controller.

=== What about... ===

...multiple undoes? Or redoes? Ah, there's the rub. Hit undo again and the cut or paste is redone, in effect undoing the undo.

Sadly, this is your dad's "undo"...the undo from back in 1990, when a single level of undo was a pretty cool thing. Today, when users expect to perform multiple destructive actions with impunity, it's not too impressive.

== Undoing and Redoing Multiple Edits ==

Fortunately, QTJ offers a unique opportunity to combine Swing's thoughtfully designed undo API, <tt>javax.swing.undo</tt>, with QuickTime's support for reverting a movie to a previous state. Combined, these features provide the ability to support a long trail of undoes and redoes.

=== How do I do that? ===

<tt>RedoableQTEditor</tt> again builds on <tt>BasicQTEditor</tt>, adding a Swing <tt>UndoManager</tt> that is used by both the <tt>doUndo( )</tt> and <tt>doRedo( )</tt> methods:

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-redoableqteditor''.
</div>

public void doUndo( ) throws QTException {
if (! undoanager.canUndo( )) {
System.out.println ("can't undo");
return;
}
undoManager.undo( );
}

public void doRedo( ) throws QTException {
if (! undoManager.canRedo( )) {
System.out.println ("can't redo");
return;
}
undoManager.redo( );
}

The information about a destructive edit is encapsulated by an inner class called <tt>QTEdit</tt> :

class QTEdit extends AbstractUndoableEdit {
MovieEditState previousState;
MovieEditState newState;
String name;
public QTEdit (MovieEditState pState,
MovieEditState nState,
String n) {
previousState = pState;
newState = nState;
this.name = n;
}
public String getPresentationName( ) {
return name;
}
public void redo( ) throws CannotRedoException {
super.redo( );
try {
movie.useEditState (newState);
controller.movieChanged( );
} catch (QTException qte) {
qte.printStackTrace( );
}
}
public void undo ( ) throws CannotUndoException {
super.undo( );
try {
movie.useEditState (previousState);
controller.movieChanged( );
} catch (QTException qte) {
qte.printStackTrace( );
}
}
public void die( ) {
previousState = null;
newState = null;
}
}

Finally, <tt>doCut( )</tt> and <tt>doPaste()</tt> are amended to create suitable <tt>QTEdit</tt>s and hand them to the <tt>UndoManager</tt>:

public void doCut( ) throws QTException {
MovieEditState oldState = movie.newEditState( );
Movie cut = movie.cutSelection( );
MovieEditState newState = movie.newEditState( );
QTEdit edit = new QTEdit (oldState, newState, "Cut");
undoManager.addEdit (edit);
cut.putOnScrap(0);
controller.movieChanged( );
}

public void doPaste( ) throws QTException {
MovieEditState oldState = movie.newEditState( );
Movie pasted = Movie.fromScrap(0);
movie.pasteSelection (pasted);
MovieEditState newState = movie.newEditState( );
QTEdit edit = new QTEdit (oldState, newState, "Paste");
undoManager.addEdit (edit);
controller.movieChanged( );
pack( );
}

When clicked, the Undo menu item now undoes a cut or paste. Redo redoes the edit, while a second "undo" will undo the previous edit, etc.

=== What just happened? ===

Obviously, the fun parts involve the destructive actions and how they save enough information to be undoable and redoable. In each case, they call <tt>Movie.newEditState()</tt> to create a <tt>MovieEditState</tt> , a QuickTime object that contains the information needed to revert the movie to the current state at some point in the future. Then they do the destructive action and create another <tt>MovieEditState</tt> to represent the post-edit state. These objects are passed to the <tt>QTEdit</tt>, which is then sent to the <tt>UndoManager</tt> to join its stack of edits.

<div class="note">
'''Note'''

.
</div>

When the <tt>UndoManager.undo()</tt> method is called, it takes the first undoable edit, if there is one, and calls its <tt>undo( )</tt> method. In this case, that means the manager is calling the <tt>QTEdit.undo( )</tt> method, which takes the pre-edit <tt>MovieEditState</tt> and passes it to <tt>Movie.useEditState( )</tt> to return the movie to that state. Similarly, a post-undo call to <tt>QTEdit.redo( )</tt> also uses <tt>useEditState( )</tt> to get to the post-edit state.

== Saving a Movie to a File ==

Once a user has performed a number of edits and has a finished project, she presumably needs to save the movie to disk. In QuickTime, many different actions can be thought of as "saving" a movie. Perhaps the simplest and most flexible option is to let the user decide.

=== How do I do that? ===

The <tt>SaveableQTEditor</tt> uses a <tt>QTFile</tt> to keep track of where a movie was loaded from (<tt>null</tt> in the case of a new movie). This is used by the <tt>doSave( )</tt> method to indicate where the saved file goes:

public void doSave( ) throws QTException {
// if no existing file, then prompt for one
if (file = = null) {
file = new QTFile (new File ("simplemovie.mov"));
}
int flags = StdQTConstants.createMovieFileDeleteCurFile |
StdQTConstants.createMovieFileDontCreateResFile |
StdQTConstants.showUserSettingsDialog;
movie.convertToFile (file, // file
StdQTConstants.kQTFileTypeMovie, // filetype,
StdQTConstants.kMoviePlayer, // creator
IOConstants.smSystemScript, // scriptTag
flags);
}

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-saveableqteditor''.
</div>

When the user hits the Save menu item, she'll see the QuickTime Save As dialog as shown in [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-3|Figure 3-3]].

<div id="quicktimejvaadn-CHP-3-FIG-3">
'''Figure 3-3. QuickTime Save As dialog'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt47.png|QuickTime Save As dialog]]
</div>

This dialog's Export selector gives the user four choices:

;Movie
: Saves a QuickTime ''reference movie'' , a tiny (typically 4 or 8 KB) file that contains just references (pointers) to the media in their original locations
;Movie, self-contained
: Copies all the media, in their original encodings, into a new QuickTime movie file
;Movie to Hinted Movie
: Creates a self-contained movie but lets the user adjust the hinting settings for use in a streaming server
;Movie to QuickTime Movie
: Creates a self-contained movie, but lets the user choose different compressors and settings to re-encode the audio and video

Some of these options give the user additional choices. Saving a "self-contained" movie presents an Options... button that lets the user specify the audio and video codecs to be used in the saved movie, their quality and bitrate settings, etc. A "Use" pop up contains canned settings with appropriate choices for distributing the movie on CD-ROM, over dial-up, etc.

Once the user clicks Save, the program saves the movie to disk. This is a very fast operation for the reference movie option and a potentially slow operation for the other options because the media might be re-encoded into a new format as part of the save.

=== What just happened? ===

The key is the <tt>Movie.convertToFile()</tt> method. The version shown here takes five parameters:

* The <tt>QTFile</tt> to save to.
* An <tt>int</tt> to represent the old Mac OS file "type." Use the constant <tt>kQTFileTypeMovie</tt> , which gives it the QuickTime movie type <tt>moov</tt>.
* An <tt>int</tt> to represent the old Mac OS file "creator." The boilerplate option is <tt>kMoviePlayer</tt> , which associates it with the default QuickTime Player application.
* An <tt>int</tt> to represent the old Mac OS "scriptTag," which indicates what kind of "script system" (character encoding, writing direction, etc.) is to be used. Common practice is to use the constant <tt>smSystemScript</tt> to use whatever the operating system's current script is.
* Behavior flags to affect the save operation, logically <tt>OR</tt>ed together. The most important flag for this example is the <tt>showUserSettingsDialog</tt> ; without it, the program would silently save the file with Apple's ancient "Video" codec and uncompressed sound. This example also uses the flag <tt>createMovieFileDeleteCurFile</tt> to delete any file already at the target location and <tt>createMovieFileDontCreateResFile</tt> to force the file to exist in a single data "fork," instead of using the old Mac OS' "resource" fork. This is required for making QuickTime movies that run on multiple platforms.

<div class="note">
'''Note'''

''Most of the time, it's appropriate to use boilerplate code for things like type, creator, and system script, and not to have to read some ''Inside Macintosh'' book from 10 years ago''.
</div>

=== What about... ===

...other interesting behavior flags? The docs for the native <tt>ConvertMovieToFile</tt> function offer two that aren't shown here because they seem to indicate behavior that is already the default:

* <tt>movieFileSpecValid</tt> indicates that the file passed in actually exists and should be shown as the default save location.
* <tt>movieToFileOnlyExport</tt> restricts the dialog to showing only the data export components that are actually present.

Can anything be done about the interminable wait when saving "Movie to QuickTime Movie"? One thing that helps is to provide a "progress function," which provides a visual representation of the progress being made on the long save operation. You can set up the default progress function with a one-line call right before <tt>convertToFile()</tt>:

movie.setProgressProc( )

This will bring up a progress dialog like the one shown in [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-4|Figure 3-4]].

<div id="quicktimejvaadn-CHP-3-FIG-4">
'''Figure 3-4. Default QuickTime progress dialog'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt49.png|Default QuickTime progress dialog]]
</div>

The <tt>Movie</tt> class also has a <tt>setProgressProc( )</tt> method that takes a <tt>MovieProgress</tt> object as a parameter. The idea here is that of a typical callback arrangement—during a long save, <tt>MovieProgress.execute()</tt> is called repeatedly with four parameters: the movie being monitored, a "message" <tt>int</tt>, a "what operation" <tt>int</tt>, and a <tt>float</tt> that represents the percentage done on a scale from 0.0 to 1.0. Unfortunately, this interface has a couple of problems. First, the constants for the "message" aren't defined in QTJ (a few <tt>println</tt>s here and there show that the values are <tt>0</tt> for start, <tt>1</tt> for update, and <tt>2</tt> for done). More importantly, using this callback seems extremely unstable in QTJ 6.1—I find I often get an exception with an "Unknown Error Code," and the movie doesn't save. So, maybe the default behavior is the safe choice for now.

== Flattening a Movie ==

Saving a movie can mean different things in QuickTime: saving a reference movie, saving a self-contained movie, or exporting to a different format. Typically, though, the idea of creating a self-contained movie is what users think of as "saving"—they want a single file that doesn't depend on any others, so they can put it on a server, email it to mom, etc. This process is called "flattening."

<div class="note">
'''Note'''

"''Flattening" is also an old Mac OS term for turning a file with both a resource fork and a data fork into a single-fork file, suitable for use on non-Mac disk formats. In this book, we use "flatten" only in its QuickTime sense''.
</div>

=== How do I do that? ===

The <tt>FlattenableQTEditor</tt> is similar to the <tt>SaveableQTEditor</tt>, adding the menu item and its typical GUI and action-handling support. The flattening is done in a <tt>doFlatten( )</tt> method:

public void doFlatten( ) throws QTException {
// always attempts to save to a new location,
// so prompt for filename
FileDialog fd = new FileDialog (this,
"Flatten...",
FileDialog.SAVE);
fd.setVisible(true); // blocks
if ((fd.getDirectory( ) = = null) ||
(fd.getFile( ) = = null))
return;
QTFile flatFile =
new QTFile (new File (fd.getDirectory( ),
fd.getFile( )));
if (flatFile.exists( )) {
// JOptionPane is a bit of cheat-for-clarity here,
// building a working AWT dialog would be punitive
int choice =
JOptionPane.showConfirmDialog (this,
"Overwrite " +
flatFile.getName( ) + "?",
"Flatten",
JOptionPane.OK_CANCEL_OPTION);
if (choice != JOptionPane.OK_OPTION)
return;
}
movie.flatten(StdQTConstants.flattenAddMovieToDataFork |
StdQTConstants.flattenForceMovieResourceBeforeMovieData,
flatFile, // fileOut
StdQTConstants.kMoviePlayer, // creator
IOConstants.smSystemScript, // scriptTag
StdQTConstants.createMovieFileDeleteCurFile,
StdQTConstants.movieInDataForkResID, // resID
null); // resName
}

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-flattenableqt-editor''.
</div>

When run, this creates a self-contained QuickTime movie file at the specified location, using whatever video and audio encoding was used in the original sources. This can result in some playback jitters if the user has mixed in different kinds of codecs—for example, pasting in some MPEG-4 video with some Sorenson 3 video. Flattening doesn't change encoding; it just resolves references and puts all the media into one file.

=== What just happened? ===

The <tt>Movie.flatten( )</tt> call creates the self-contained movie file, taking seven parameters to control its behavior:

<div class="note">
'''Note'''

''Many of these are the same parameters used by Movie.convertToFile( ), covered in the previous lab''.
</div>

* Behavior flags for the flatten operation, logically <tt>OR</tt>ed together. This example uses <tt>flattenAddMovieToDataFork</tt> to create a single-fork movie that is more suitable for non-Mac operating systems. Using <tt>flattenForceMovieResourceBeforeMovieData</tt> creates a "quick start" movie, so named because all its metadata comes before its media samples, which allows QuickTime to start playing the movie from a stream, even an http://-style URL, before all the data is loaded, because all the information QuickTime needs (what tracks are present, what size the video is, how loud the audio is, etc.) is loaded first.
* The file to flatten to.
* The Mac OS "creator," typically <tt>kMoviePlayer</tt>.
* The Mac OS script tag, typically <tt>smSystemScript</tt>.
* The behavior flags that are used for the create file operation. <tt>createMovieFileDeleteCurFile</tt> is used here to delete any file already at the target file location.
* Resource ID. For cross-platform reasons, it's usually best to use <tt>movieInDataForkResID</tt> instead of old Mac OS-style resources.
* Resource name. Irrelevant here, so <tt>null</tt> will do.

=== What about... ===

...behavior flags for the flatten operation? The native docs for <tt>FlattenMovie</tt> define a bunch, but the ones not used here are largely esoteric.

;<tt>flattenDontInterleaveFlatten</tt>
: Turns off "interleaving," an optimization that mixes audio and video samples together so that they're easier to read at playback time (if a movie had a couple of megabytes' worth of video samples, followed by a couple of megabytes' worth of audio samples, the hard drive would have a difficult time zipping back and forth between the two; interleaving puts the samples for the same time period in the same place so that they can be read together). The default behavior is ''a good thing'', so this constant isn't used often.
;<tt>flattenActiveTracksOnly</tt>
: Doesn't include disabled tracks from the movie in the flattened file.
;<tt>flattenCompressMovieResource</tt>
: Compresses the movie's resource, and its organizational and metadata structure, if stored in the data fork. Like you care.
;<tt>flattenFSSpecPtrIsDataRefRecordPtr</tt>
: This is meaningless in QTJ.

== Saving a Movie with Dependencies ==

The opposite of flattening is saving a movie with dependencies. In this type of a save, the resulting file just contains pointers to the sources of the media in each track. The file typically is tiny, usually just 8 KB or less.

=== How do I do that? ===

The <tt>RefSaveableQTEditor</tt> example extends the <tt>FlattenableQTEditor</tt> with a "Save w/Refs" menu item that calls <tt>doRefSave()</tt>:

public void doRefSave( ) throws QTException {
// if no home file, then prompt for one
if (file = = null) {
FileDialog fd = new FileDialog (this,
"Save...",
FileDialog.SAVE);
fd.setVisible(true); // blocks
if ((fd.getDirectory( ) = = null) ||
(fd.getFile( ) = = null))
return;
file = new QTFile (new File (fd.getDirectory( ),
fd.getFile( )));
}
// save ref movie to file
if (! file.exists( )) {
file.createMovieFile(StdQTConstants.kMoviePlayer,
StdQTConstants.createMovieFileDontCreateResFile);
}
OpenMovieFile outFile =
OpenMovieFile.asWrite(file);
movie.updateResource (outFile,
StdQTConstants.movieInDataForkResID,
null);
}

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-refsaveableqt-editor''.
</div>

When run, this creates a movie file that, despite its tiny size, behaves exactly like any other movie file. Double-click it and it will open in QuickTime Player, just like a self-contained movie. QuickTime completely isolates the user from the fact that the file contains nothing more than metadata and pointers to the source media files.

Of course, there are limits to what QuickTime can do if those pointers cease to be valid. A user can move the source files and the movie still will play, but if the source movies are deleted, or if the reference movie is transferred to another system, QuickTime won't be able to resolve the references. This typically will result in a "searching..." dialog, followed by a dialog asking the user to locate the missing media, as shown in [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-5|Figure 3-5]].

<div id="quicktimejvaadn-CHP-3-FIG-5">
'''Figure 3-5. Unresolvable media reference dialog'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt52.png|Unresolvable media reference dialog]]
</div>

=== What just happened? ===

First, a call to <tt>QTFile.createMovieFile()</tt> creates the file on disk, if it doesn't exist already. This method takes two parameters:

* A Mac OS "creator," for which <tt>StdQTConstants.kMoviePlayer</tt> is the typical boilerplate value.
* Behavior flags. The constant <tt>createMovieFileDontCreateResFile</tt> commonly is used to create cross-platform, single-fork files.

With the file created, the reference movie data can be put into the file with the <tt>updateResource()</tt> method. This method takes three parameters:

<div class="note">
'''Note'''

''The name updateResource( ) seems to be another Classic Mac OS legacy that doesn't make much sense today''.
</div>

* An <tt>OpenMovieFile</tt>, opened for writing.
* A resource ID, for which the appropriately cross-platform, no-resource-fork value is <tt>movieInDataForkResId</tt>.
* An updated name for the resource; <tt>null</tt> is appropriate here.

=== What about... ===

...the fragility of reference movies? Because a reference movie is fragile, why would anyone ever create one? This technique is very handy for the saving state in editing applications because it allows the user to quickly save his edited movie without the I/O grinding of flattening. Editing, after all, can be seen as a process of arranging pointers to source materials; in the professional realm, a document called an ''Edit Decision List'' (EDL) is a simple list of "in" and "out" points from source media that you can use to produce the edited media. The reference movie is equivalent to the EDL: it's just a collection of pointers, with the nice advantage that it continues to behave as a normal QuickTime movie. So, the reference movie can be used to save the progress of the user's editing work, and when finished, a final self-contained movie can be generated via flattening or exporting (see [[QuickTime for Java: A Developer's Notebook/Working with Components|Chapter 4]]).

== Editing Tracks ==

Often, it makes sense to perform edits on all tracks of a movie. But for serious editing applications, sometimes you need to work at the track level, to add and remove tracks, or to work on just one track in isolation from the others. This task will provide a taste of that by adding a second audio track to a movie.

=== How do I do that? ===

The <tt>AddAudioTrackQTEditor</tt> builds on <tt>FlattenableQTEditor</tt> by adding another Add Audio Track... menu item, calling the <tt>doAddAudioTrack( )</tt> method:

<nowiki>public void doAddAudioTrack( ) throws QTException {
// ask for an audio file
QTFile audioFile =
QTFile.standardGetFilePreview (QTFile.kStandardQTFileTypes);
OpenMovieFile omf = OpenMovieFile.asRead (audioFile);
Movie audioMovie = Movie.fromFile (omf);
// find the audio track, if any
Track audioTrack =
audioMovie.getIndTrackType (1,
StdQTConstants.audioMediaCharacteristic,
StdQTConstants.movieTrackCharacteristic);
if (audioTrack = = null) {
JOptionPane.showMessageDialog (this,
"Didn't find audio track",
"Error",
JOptionPane.ERROR_MESSAGE);
return;
}
// now make new audio track and insert segment
// from the loaded track
Track newTrack =
movie.newTrack (0.0f, // width
0.0f, // height
audioTrack.getVolume( ));
// ick, need a dataref for our "new" media
// http://developer.apple.com/qa/qtmtb/qtmtb58.html
SoundMedia newMedia =
new SoundMedia (newTrack,
audioTrack.getMedia( ).getTimeScale( ),
new DataRef (new QTHandle( )));
newTrack.getMedia( ).beginEdits( );
audioTrack.insertSegment (newTrack,
0,
audioTrack.getDuration( ),
0);
controller.movieChanged( );
}</nowiki>

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch03-addaudiotrackqteditor''.
</div>

This method is admittedly contrived—it prompts the user to open another file, and if an audio track can be found in the file, the program adds that track to the movie, starting at time 0. If the user has done only a few short pastes and then adds an audio track from a typical iTunes MP3 or AAC, the result probably will be a movie in which the new soundtrack is much longer than the pasted contents.

Also, QuickTime will eat more CPU cycles playing this movie, because it has to decode two compressed soundtracks at once. Like I said, it's a contrived example, but it covers some interesting ground.

=== What just happened? ===

The program tries to find an audio track with <tt>Movie.getIndTrackType( )</tt> , passing <tt>audioMediaCharacteristic</tt> as the search criterion. Assuming an audio track is found in this movie, the program needs to create a new track in the movie being edited. <tt>Movie.newTrack( )</tt> creates the new track, taking as parameters the width, height, and volume of the new track.

This new track is useless without a <tt>Media</tt> object to hold the actual sound data, so the next step is to construct a new <tt>SoundMedia</tt> object. The constructor takes the track that the media is to be associated with, a time scale, and a <tt>DataRef</tt> to indicate where media samples can be stored.

Interestingly, although the edit methods this program uses are in the <tt>Track</tt> class, first I have to call <tt>Media.beginEdits( )</tt> to inform the track's underlying media that it's about to get edited. Having done this, the program then can call <tt>Track.insertSegment()</tt> , which is identical to its low-level-editing <tt>Movie</tt> equivalent, taking a target track, source in and out times, and a destination-in time. Following this, the program calls <tt>movieChanged( )</tt> on the movie controller to let it know that a change was made to the movie behind the controller's back.

The result is an additional audio track in the movie. If the user then flattens the movie and opens it up with QuickTime Player, a "Get Info" shows the extra audio track, as seen in [[QuickTime for Java: A Developer's Notebook/Editing Movies#quicktimejvaadn-CHP-3-FIG-6|Figure 3-6]]. In this case, I imported clips from an MPEG-4 file and added an MP3 soundtrack.

<div class="note">
'''Note'''

''No, I'm not swearing in this filename. I combined a video of my son in an inflatable boat with an MP3 of a song called "Dam Dariram" from the video game "Dance Dance Revolution"; thus, "dam-boat.mov"''.
</div>

<div id="quicktimejvaadn-CHP-3-FIG-6">
'''Figure 3-6. QuickTime Player "Get Info" for movie with multiple audio tracks'''

[[Image:QuickTime for Java: A Developer's Notebook_I_3_tt54.png|QuickTime Player "Get Info" for movie with multiple audio tracks]]
</div>

=== What about... ===

...that crazy-looking <tt>new DataRef (new QTHandle( ))</tt> parameter in the <tt>SoundMedia</tt> constructor? OK, scary edge case—here's the story. Zoom out for a second: movies have tracks, tracks have media, media have samples. Those samples need to live ''somewhere''. It's not a problem when you open a movie from disk, but when you create new media in a new movie, QuickTime has no idea where it's supposed to put any samples that you add, whether by way of inserting segments from other tracks or by adding individual samples one by one (which will be covered in Chapters [[QuickTime for Java: A Developer's Notebook/Audio Media|Chapter 7]], [[QuickTime for Java: A Developer's Notebook/Video Media|Chapter 8]], and [[QuickTime for Java: A Developer's Notebook/Miscellaneous Media|Chapter 9]]). So, this example uses the <tt>SoundMedia</tt> constructor that takes a <tt>DataRef</tt>, which represents a location to store the samples. This <tt>DataRef</tt> can be practically anything, even a zero-length buffer in memory, which is pretty much what this example passes in by constructing a new <tt>DataRef</tt> out of a new, empty <tt>QTHandle</tt>.

<div class="tip">
'''Tip'''

For more on this icky little gotcha, and if you don't mind a C-oriented technote, see "BeginMediaEdits -2050 badDataRefIndex error after calling NewMovie" at ''http://developer.apple.com/qa/qtmtb/qtmtb58.html''.
</div>

Also, what about the control bar? It tells the user nothing about the tracks in the movie. You're absolutely right. Being playback-oriented, the provided GUI is weak for editing movies, and utterly useless for editing tracks. It gives the user no idea how many tracks a movie has, where there's video without sound or vice versa, etc. Moreover, there's no default widget in QTJ to replace it. If you want to provide track-oriented editing, you'll need to develop your own GUI components to display tracks and their contents. I haven't provided one here, because the appearance and behavior of such a component would vary wildly with the kind of application it was needed for (a home movie editor, an MP3 playlist builder, etc.) and because it easily could contain more than 1,000 lines of AWT code with maybe a dozen lines of QuickTime...not exactly ideal for the format of this book.

What about other track-editing methods? Fortunately, many of the concepts from the low-level <tt>Movie</tt> editing lab from earlier in the chapter apply to tracks. Along with <tt>Track.insertSegment()</tt> are a <tt>deleteSegment()</tt> and a <tt>scaleSegment()</tt> that work like their <tt>Movie</tt> equivalents. The <tt>insertEmptySegment()</tt> does what its name implies, and could be useful for building a track in nonconsecutive segments. There's also a <tt>Track.insertMedia()</tt> that will be used in later chapters to build up a <tt>Media</tt> object from raw samples.

As for how the tracks relate to their parent movies, this example uses <tt>Movie.newTrack( )</tt> , though it also is possible to use <tt>addEmptyTrack()</tt> , which takes a prototype track and a <tt>DataRef</tt>. Tracks can be removed with <tt>Movie.removeTrack( )</tt> and temporarily turned on and off with <tt>Track.setEnabled()</tt> .

←Older revision		Revision as of 00:17, 7 March 2008
Line 250:		Line 250:
	'''Figure 3-1. BasicQTEditor with two movies open'''		'''Figure 3-1. BasicQTEditor with two movies open'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt39.png\|BasicQTEditor with two movies open]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt39.png\|BasicQTEditor with two movies open]]
	</div>		</div>

Line 300:		Line 300:
	'''Figure 3-2. MovieController scrubber bar with editing enabled'''		'''Figure 3-2. MovieController scrubber bar with editing enabled'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt40.png\|MovieController scrubber bar with editing enabled]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt40.png\|MovieController scrubber bar with editing enabled]]
	</div>		</div>

Line 559:		Line 559:
	'''Figure 3-3. QuickTime Save As dialog'''		'''Figure 3-3. QuickTime Save As dialog'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt47.png\|QuickTime Save As dialog]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt47.png\|QuickTime Save As dialog]]
	</div>		</div>

Line 609:		Line 609:
	'''Figure 3-4. Default QuickTime progress dialog'''		'''Figure 3-4. Default QuickTime progress dialog'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt49.png\|Default QuickTime progress dialog]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt49.png\|Default QuickTime progress dialog]]
	</div>		</div>

Line 748:		Line 748:
	'''Figure 3-5. Unresolvable media reference dialog'''		'''Figure 3-5. Unresolvable media reference dialog'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt52.png\|Unresolvable media reference dialog]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt52.png\|Unresolvable media reference dialog]]
	</div>		</div>

Line 849:		Line 849:
	'''Figure 3-6. QuickTime Player "Get Info" for movie with multiple audio tracks'''		'''Figure 3-6. QuickTime Player "Get Info" for movie with multiple audio tracks'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_3_tt54.png\|QuickTime Player "Get Info" for movie with multiple audio tracks]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_3_tt54.png\|QuickTime Player "Get Info" for movie with multiple audio tracks]]
	</div>		</div>

QuickTime for Java: A Developer's Notebook/Editing Movies - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook