• Latest Release: ViewMovie 1.0a10 adds the ability to automatically detect QuickTime VR movies and delegate them to the QTVR Player helper application, splits the AU and AIFF functionality to a separate version (ViewMovie XT) due to the loud and opinionated emails of SoundMachine fans, fixes a display bug with movies with no visual tracks that made the top half of the controller not draw and includes additional fixes (aka workarounds) for a heap corruption bug in QuickTime 2.1 when using music tracks and cross-platform movies which should improve stability in a lot of cases.
• Supports ViewMovie Program: Now there is an easy and cool-looking (I think) way to show your pages support ViewMovie and point your visitors to the download site: the Supports Viewmovie button! And if you want to tweak the image to make it fit your page better, the multilayered Photoshop 3.0 file is available as well.
• New ViewMovie-Savvy Sites: The ViewMovie Site List continues to grow (no kidding). Please don't forget to send me mail when you put together a site that supports ViewMovie so I can add you to the list.

Table of Contents

• About This Document
• Installation Instructions
• HTML Embedding Notes (Important)
• Release Notes and Revision History
• Test and Demo
• Troubleshooting
• Cool Applications of ViewMovie
• Acknowledgements

About This Document

This document describes ViewMovie, a plug-in for Netscape 2.0b5 for Macintosh and higher providing support for playback of QuickTime movies. It outlines how to set up ViewMovie, how to embed movies into HTML documents. The version of ViewMovie described here is 1.0a10, posted on Friday, March 8th, 1996.

Installation Instructions

Trivial.

No, really. First, unstuff the downloaded file (Netscape will do that for you transparently if you have Stuffit Expander installed).

Then, take the file named ViewMovie, stick it into the Netscape "Plug-Ins" folder, and quit and relaunch Netscape. You should be up and running.

HTML Embedding Notes

Embedding a movie in a NHTML document is achieved via the <EMBED> tag, as described in the Netscape documentation. The nature of QuickTime movies and particularly the QuickTime movie controller, however, introduces an unobvious peculiarity: the HEIGHT property specified in the tag must be the height of the movie itself plus 16, to account for the size of the movie controller. So, in order to place a 320x240 movie on your page, you'd use:

<EMBED SRC="mymovie.mov" WIDTH=320 HEIGHT=256>

NOTE: As of 1.0a6 you can put the movie's real size as long as you hide the controller without a badge (which can show the controller if it's hidden). To replicate the example above, you'd use:

<EMBED SRC="mymovie.mov" WIDTH=320 HEIGHT=240 CONTROLLER=FALSE>

Also note that the movies should be named using the .mov extension, as that is specified by the plug-in to identify the file as being of "video/quicktime" MIME type. If your server is configured otherwise (for example, to specify that files with the extension .qt) have the "video/quicktime" MIME type, you may use it as well.

Version 1.0a10 includes support for the following attributes in the EMBED tag:

• LOOP: The Loop parameter specifies whether the movie stops when it arrives to the end or whether it loops indefinitely or until manually stopped. When looping it can also loop back and forth, in palindrome mode. Acceptable values are TRUE, FALSE, and PALINDROME; the default is FALSE.
• AUTOPLAY: The Autoplay parameter specifies whether the movie starts up automatically when the page is loaded. Acceptable values are TRUE and FALSE; the default is FALSE. In keeping compatibility with Netscape's sample AVI player, AUTOSTART can be used as a synonym. Additionally, this attribute can be overriden by the use of the new (as of 1.0a8) PLAYRATE attribute.
• CONTROLLER: The Controller parameter specifies whether the movie controller is visible or not and whether the movie has a badge (implying a hidden controller); note that if you use either TRUE or BADGE, you must still add 16 pixels to the height parameter as described above - if you use NONE, however, you can use the movie's true height in HEIGHT. Acceptable values are TRUE, FALSE, or BADGE; the default is TRUE.
• KEEPASPECTRATIO: The KeepAspectRatio parameter specifies how the movie is scaled to fit in the rectangle given. Acceptable values are TRUE and FALSE; the default is TRUE.
• HREFABS: The HREFABS parameter allows you to make the movie function as a link - though including it disables the controller from working. Additionally, and most important, the target URL must be an absolute URL - it must include the protocol (though http will be assumed if it isn't specified), the node's address, and the full pathname. If you just put in a filename or a relative URL, Netscape will think it's an absolute URL and treat it as if it had "http://" stuck in front of it. For testing local files, use "file:///disk/dir/dir/dir/dir/file". Once the Netscape API supports getting the URL of the current page, I will implement relative URLs and rename this parameter HREF, though HREFABS will remain for compatibility. Alternatively, if they allow bracketing EMBED tags with <A HREF> tags and handing back mouse clicks to Navigator (which isn't suportted right now), that would work too. Acceptable values are any absolute URL.
• ISMAP: The ISMAP parameter works like the ISMAP attribute in IMG tags - allows you to have the movie work as an image map by specifying a map cgi in the HREFABS parameter. This paramater takes no values.
• PLUGINSPAGE: This is not a ViewMovie parameter, but rather a Netscape-supported parameter. I list it here because most people don't know about it. This parameter allows you to specify a URL from which the user can fetch the necessary plug-in in case it is not installed - if Netscape cannot find the plug-in when loading your page, it will warn the user and allow them to bring up the specified URL, from which one could download ViewMovie. Please set this parameter to ViewMovie's info page: "http://www.well.com/~ivanski/viewmovie/viewmovie_info.html".
• PLAYRATE: The PlayRate parameter specifies the rate at which the movie starts playing when the page is loaded; its value is an integer intepreted as a percentage - 100 means normal speed. If the value of this parameter is nonzero, it also overrides the AUTOPLAY parameter. Acceptable values are integers.
• VOLUME: The Volume parameter specifies the initial volume for the movie's audible tracks. It's also interpreted as a percentage, and its default value is whatever is stored in the movie (aka the "preferred volume" in QuickTimeSpeak). Acceptable values for the parameter are integers.
• PLAYEVERYFRAME: The PlayEveryFrame parameter, if TRUE, forces the movie to not skip any frames (and thus fall behind rather than drop frames) when playing back, as a side effect, since it can fall behind, sound is disabled. The default value for this parameter is FALSE, and acceptable values are TRUE and FALSE.
• QUALITY: The Quality parameter, if set to HIGH, forces the movie to do high-quality dithering, color reduction, and pixel averaging when scaling down during playback, sacrificing frame rate. It's default value is DRAFT, and acceptable values are HIGH and DRAFT.
• HREFTARGET: The HRefTarget attribute extends the functionality available via the HREFABS attribute: it allows you to specify a named window or frame as a target for the URL to appear on. Thanks to Charles Gasper for this cool suggestion, allowing you to do animated navigation buttons for Netscape frames.
• Compatibility Attributes: The following attributes and values are accepted as synonymous for improved compatibility with other QuickTime plug-ins. Do note that not all non-ViewMovie attributes are compatible; specifically, the ones which would break backward compatibility with ViewMovie's own syntax or might cause problems on Windows are not supported.
  • The LOOP attribute accepts L (linear) as a synonym for TRUE and P as as substitute for PALINDROME.
  • The CONTROLLER attribute accepts CONTROL as synonymous with the attribute name, H as synonymous with the value FALSE and B as synonymous with the value BADGE.
  • The PLAYRATE attribute accepts PLAY as a synonym for it.
  • The VOLUME attribute accepts VOL as a synonym for it.

Release Notes and Revision History

Known problems:

• VM02: Movie disappears (update ignored) when window is resized. The controller, however, remains, and attempting to play or shuttle restores the movie display.
• VM07: FSMakeFSSpec will fail with file-not-found in some cases, resulting in a "ERROR: Couldn't make file specification. Code = -43." It seems that in some cases the pathname handed to the plug-in by Navigator is broken. More info below in troubleshooting.
• VM09: Error reporting sucks (it doesn't suck as much as it used to, but it still sucks). Needs a dialog box, dammit!
• VM15: If a movie is partially clipped by being partially off the web content scrolling pane in the Netscape window and one switches in and out of Netscape, the clipping region will not be respected and artifacts appear.

Release History:

• 1.0a10
  • Bug VM13 Fixed: though ViewMovie still takes over QTVR movies, it detects them and delegates them to the QTVR Player helper application if present.
  • Bug VM14 Fixed: Movies with no visual tracks and a controller now draw properly (the top half of the controller used to not draw).
  • Additional fixes for bug VM08: Final workaround in place for QuickTime's heap corruption bug with cross-platform (flattened) movies and music tracks.
  • Split the version of ViewMovie with the AU/AIFF support into its own version, ViewMovie XT; plain ViewMovie includes support solely for QuickTime movies.
  • 1.0a9
    • Bug VM12 Fixed: Stray crashes when using the URL track feature (due to a stooooopid off-by-one bug that caused heap corruption; I can be a moron sometimes) have been eliminated.
    • Added support for the HREFTARGET attribute.
  • 1.0a8
    • Moved both Mac and Windows (I know, I know; you'll see it soon) versions to common source code to more easily maintain feature parity.
    • New Feature: Added new attributes for improved compatibility with other QuickTime plug-ins.
    • New Feature: Added printing capability.
    • New Feature: ViewMovie now remembers the movie's state when you leave the page, and restores it when you return.
    • New Feature: Added the PLAYRATE, VOLUME, QUALITY, PLAYEVERYFRAME tags.
    • New Feature: Added support for URL Tracks, which support invoking URLs as the movie plays, with an optional TARGET attribute to specify where to open then.
    • Fixed Bug VM11: Gestalt check for presence of QuickTime had broken in 1.0a6; it works again now.
    • Fixed Bug VM08: Worked around QuickTime bug, so that opening single-fork movies with music tracks in them does not corrupt memory anymore.
    • Added better error reporting specifically for bug VM07 (the "couldn't make file spec, err = -43" bug), which is notoriously hard to reproduce. Hopefully this will provide enough info to produce a fix for the next release.
  • 1.0a7 - CDA Memorial Edition (let's hope it dies soon)
    • Bug VM10 fixed: Worked around a Netscape bug that could cause crashes in some cases - the bug involves corrupt data being passed to the plug-in in lieu of the window pointer. While it prevents crashes, it may cause update problems in some cases. I'm working with Netscape to address this problem.
  • 1.0a6
    • Ported over to 2.0 version of Netscape Plug-in SDK, which now supports all callbacks.
    • Added support for new embedding parameters: KEEPASPECTRATIO, HREFABS, ISMAP, the BADGE option for CONTROLLER, and the PALINDROME option for LOOP.
    • Bug VM06 fixed: AUTOPLAY actually does default to false. Modified non-embedded behavior so that AUTOPLAY is true in that case, since people liked this bug so much in that instance.
  • 1.0a5
    • Added support for new embedding parameters: AUTOPLAY, CONTROLLER, and LOOP.
  • 1.0a4
    • Bug VM01 fixed: Movie updates properly when scrolling. Assorted other update bugs fixed by this as well, and VM02 is almost fixed.
    • Bug VM03 fixed: Movie doesn't flash any longer when finished loading. Stoooooopid bug.
    • Bug VM05 fixed: Intermittent problems with loading movies (more common on PowerPC machines) fixed. Another really stoopid bug, an uninitialized variable. Additionally, much better error reporting added as part of this fix.
  • 1.0a3
    • VM04 Fixed: Added Gestalt check to prevent unimplemented-trap crashes if QT not installed. Displays an error message if QuickTime is not found.
  • 1.0a2
    • First public release.

  Some notes for Netscape plug-in developers:

  • Netscape will generally call you to handle events before you're done downloading even if you are operating as a stream-as-file plug-in (judicious use of assertions will catch this one most of the time).
  • Somehow the EventRecord passed to the plug-in's event handler in the case of update events has the message field zeroed out (this field is supposed to have the window to which the event belongs to). In most cases this is no big deal, since the plug-in knows which window it's working within. In the specific case of ViewMovie this is wery wery bad, since the event is passed down to the Movie Controller which expects the message field to be correct and you end up not updating properly sometimes. Doubtlessly similar effects can happen in other cases, so beware.
  • When Netscape calls you to handle an update event, it has already called BeginUpdate. If you call BeginUpdate yourself (or call code that does), you will in fact get an empty update region (thus no update - this was the source of bugs VM01 and most of VM02) and moreover you will destroy the contents of the current port's visRgn and the low-mem global LMSavedVisRgn, which is a bad thing. If you must nest Begin/EndUpdate pairs (like with the movie controller, or someone else's library you're wrapping around), save and restore the update region and LMSavedVisRgn yourself, and copy the current visRgn to the updateRgn. Saves lots of aggravation.

  ---

  Test and Demo

  If you have installed ViewMovie, you should see a movie above (it may take a while to load). If you have not, you will see the standard Netscape missing plug-in pane.

  The demo movie used to be a VanHalen video from underground.net. I removed it because of possible copyright problems. The new one is also vastly smaller (72K - I've seen JPEG's on the Web bigger than that) and has sound (MIDI - so I'm cheating).

  An additional note: the QuickTime Movie Controller is drag-aware. Thus, you can easily save a movie you see on a page by dragging it to the desktop.

  ---

  Troubleshooting

  • ERROR: Couldn't instantiate movie. Code = -2048: This typically arises from an incorrectly uploaded movie; a related symptom is that the page usually works well from local storage, it just fails when downloaded from a server: movies up on a web server need to be cross-platform, single-fork (sometimes misnamed "flattened") movies. The process is to first resave the movie using MoviePlayer's "playable on non-Apple computers" checkbox or a utility like FlatMoov, also available at your closest InfoMac mirror in the /gst/mov/ subdiretory (thanks to Bengt Carlson for the URL). Then, make sure that the application you're using to upload the movie (Fetch, Anarchie, ZTerm, etc.) is set to upload as binary or raw binary - MacBinary will screw things up by appending creator and type information as a header, and including the resource fork if one exists (most tools, MoviePlayer included, do create one). Upload the movie in that mode, and that should do it - if you still have problems, send me mail.
  • ERROR: Couldn't make file specification. Code = -43: In some cases, the pathname handed to the plug-in by Navigator is broken; this seems to be related to the choice of temporary folder and cache folder. Flushing the cache and resetting the temporary folder usually takes care of this.
  • "Dead-space" around the movie: Check the dimensions. Unless you use the KEEPASPECTRATIO attribute, the plug-in (actually the controller) enforces the movie's aspect ratio and shrinks it so it fits in the rectangle given. If you mistakenly swap the dimensions, (easy to do, since people tend to write in the order "HEIGHT = yyy WIDTH = xxx" but dimensions are usually given "Width x Height", as in 320x240) you will get dead space.
  • Netscape complains about not having a 'text/html' plug-in: Your web server is not configured properly; tell your webmaster that the server software needs to serve files with the suffix *.mov as being of the type 'video/quicktime'.

  ---

  Cool Applications of ViewMovie

  Here are some cool things to do with ViewMovie beyond the straightforward "stick a movie on the page".

  • Animation: Create a loopable movie, and embed it using AUTOPLAY=TRUE, LOOP=TRUE, CONTROLLER=FALSE. While this can also be done with GIF89a animation, QuickTime movies have a number of advantages:
    • You have more flexibility in the choice of compressors; thus, animations can look better, you can use material like video without dealing with huge files, and are not limited to an 8-bit palette.
    • You have flexibility in the quality of the compression, so you can sacrifice quality for size (and download speed). You can also use interframe compression, which makes for even smaller files.
    • You have much better control over the animation's pace.
    • You can include other media types, such as text, sound, MIDI, or sprites with QT 2.1.
    • Movies are vastly easier to create - just about any tool worth its salt that can output a sequence of frames supports saving as a QuickTime movie.
  • Background Music: Create a movie with either sound or music and without any image information whatsoever and embed it using AUTOPLAY=TRUE, LOOP=TRUE, CONTROLLER=FALSE, and dimensions set to 0x0. Voilá! Thanks to Andy Hullinger for the idea.
  • Animated buttons and menus: Create animations as above, and add the HREFABS attribute so that it works as a link. You can even use ISMAP for animated menus! Not too animated, of course - you don't want the hotspots moving; but you can have a flag flapping in the breeze and the like, or use movies as micons. Thanks to Charles Wiltgen, keeper of the QuickTime FAQ for this idea.
  • Guided web-tours: Use the ability to embed URLs inside the movie at specific points in time to have Netscape call-up specific URLs as the movie plays back. See the URL Track documentation for more details, or a quick demo I put together.

  ---

  Acknowledgements

  In no particular order:

  • Y'all, who've swamped me with kudos, suggestions, and bug reports, and have started using it aggressively, making ViewMovie a solid and stable product in a very short time (2 weeks?) and encouraging me to develop it further.
  • The QuickTime gang at Apple (not many links here, they like their privacy) for very flexible software that can do great stuff with a few lines of code. Charles Wiltgen, now QuickTime Evangelist at Apple, was especially helpful with the QuickTime for Windows SDK, the various header files, and other stuff (now if Apple could just get true italic bitmaps for Times to be part of the standard system install, so italics on web pages looked italic and not oblique, I'd be happy).
  • The folks at Netscape Communications Corp., especially Tim Hickman and Alec Plumb at Developer Relations, who were very helpful and responsive.
  • Ron Liechty, übersupportman at Metrowerks, for being very responsive, and Metrowerks themselves their tools, especially their cross-compilers; it's enormously cool to sit on a boat off the coast off Perú working on a 040-based Duo 280C and crank code that can run on 68K MacOS, PPC MacOS, and x86 Win32 (are we getting PPC WinNT soon?). (quick note: the above doesn't mean I'm living on said boat, I just go on it often with said 280C).

  [ ICB Home | About moi | Wares | Other sites | Writings | Miscelanea ]

  Copyright © 1995-1996 Iván Cavero Belaúnde. All Rights Reserved.