		    Gnash: the GNU Flash Player

Gnash is a player for animated "movies" in the Macromedia Shockwave Flash
(.swf) format.  It can be run as a graphical application, as a Web browser
plugin, or as a library used by other programs.  It is not yet complete;
it does not correctly handle every .swf file.

This is the README file for Gnash-0.7, released in April 2006.

Gnash is originally based on the code of GameSWF, by Thatcher Ulrich.
GameSWF was the most advanced among free flash movie players; it
implemented a fairly broad set of Flash Format v7 features.  In December
2005, Rob Savoye forked GameSWF to become Gnash.  New improvements added to
Gnash are copyrighted by the Free Software Foundation under the GNU
General Public License.  After Rob rearranged the GameSWF code into the
GNU project style, he began development on the browser plugins.  The Free
Software Foundation made Gnash a priority project, and many volunteers
started contributing useful improvements.  We thank Thatcher Ulrich for
the great start, Rob Savoye and John Gilmore for organizing the project,
and the Gnash volunteers for making Gnash what it is today.


Flash Support:
--------------

Many of the Flash movies that I come across play fine in Gnash.  Many
others do not.  In particular, Flash movies that are used for browser
navigation do not cause the browser to navigate yet.  Producing sound
does not generally work yet.

Gnash supports the majority of Flash opcodes up to SWF version 7, and
a wide sampling of ActionScript classes for SWF version 7. All the core
ones are implemented, and many of the newer ones work, but may be missing
some of their methods. All unimplemented opcodes and ActionScript classes
and methods print a warning when using -v with gnash or gprocessor. Using
gprocessor -v is a quick way to see why a movie isn't playing correctly.

Currently implemented ActionScript classes are: Array, Boolean, Date,
Key, Math, Mouse, Number, Object, Sound, String, XML,
XMLNode, and XMLSocket.

Partially implemented classes are: MovieClipLoader, NetConnection,
LocalConnection, MovieClip, TextField, and TextFormat.

Unimplemented classes are: Accessibility, Error, Function, LoadVars,
Microphone, NetStream, Selection, SharedObject, Stage, System, Button,
Camera, Color, ContextMenu, CustomActions, Video.

Unimplemented Opcodes are: Throw, Implements, Extends, EnumObject, Try,
NewMethod, MDLength, MDSubstring, MDChr, Delete, GetTarget.

There is currently no FLV video, only minimal AMF data support,
and no loading of external jpegs. Sound is currently non-functional.

Plugin:	
-------

The plugin correctly installs itself into Mozilla, Firefox, or Konqueror.
It can play some Flash files in cooperation with the browser. It
should work with any browser that supports the newer version of
Mozilla's NSPR API and plugin SDK. This does not work with the older
browsers like Firefox 1.0.x, but works find with any Firefox 1.5 or
newer browser. The older browsers fail to initialize the plugin, so
you only get a blank screen.

Some web pages have Internet Explorer-specific Javascript that fail
in Firefox, which prevents the plugin from being loaded. In these cases
I "view source" and then use wget to grab the movie for testing.

By default, the configure script looks for the GtkGl extension, and if
that can't be found, it defaults to using SDL. The plugin works by
using the standalone player, so which ever graphics library Gnash
uses, it's the same as the standalone player.

The GTK version has full event handling, and supports a right-click
mouse menu to control the movie. The SDL version has no event
handling, which means mouse clicks and keys pressed get ignored. Also
the windows don't resize, and occasionally they overrun thweir
biundaries. The GTK version requires GtkGlExt, and defaults to SDL if
GtkGlExt is not installed, or if --disable-glext is passed to configure.

All Flash movies are downloaded in full to /tmp, and then played from there.
Gnash is not yet able to play a Flash file "as it arrives" over the
network. Adding the ability to handle input streams is on the TODO list.

Configure with --with-plugindir= to set the directory that "make
install" will install the plugin in. By default it will be installed
in the users .mozilla/plugins or .firefox/plugins directory.


Building Gnash:
---------------

See the generic installation instructions in the file called
"INSTALL". As the configure script is not included in CVS, you need to
run ./autogen.sh to produce this file. This depends on having
autoconf, automake, and libtool installed on your system. After
producing the configure script, executing it as "./configure" should
be all that is necessary to buuild Gnash.

You will also need the following development packages installed to
build the player with GTK support: glib, atk, pango, cairo, gtk2,
gtkglext.

You can build the player without GTK support, and these are the
dependent packages: OpenGL(libMesa), SDL.

The GTK support is more developed and featureful, while the SDL
support has less dependancies on other packages.

Other required packages are libxml2, libpng, libjpeg.  The use of
libxml2 can be dropped if configured with --disable-xml.

At this time the sound support is non-functional until the new Gstreamer
support is done. For sound support, currently SDL_Mixer is
supported. SDL_Mixer will be going away soon to be replace by the new
Gstreamer support. Gstreamer version 0.10 will required for this when
available. As the sound support doesn't work yet, Gnash wll build just
fine without either SDL_mixer or Gstreamer installed. These packages
are referenced by Gnash for development purposes.

You no longer need the Mozilla or Firefox development packages to
build Gnash. All the required files are now included in Gnash so the
plugin can be built as long as the other development libraries are
installed.

To build Klash, the Konqueror plugin, you need to have the KDE
development packages installed. This now installs a KDE executable
called "klash" that is used by this plugin.

The Gnash Community:
--------------------

Gnash has three mailing lists hosted at gnu.org. Archives of these
lists are stored at http://mail.gnu.org/pipermail/: 

    * gnash@gnu.org is for discussion of Gnash. Ideas for the future,
      general gnash usage or problems, etc... New alpha and stable
      releases are announced here. To subscribe, go the
      http://mail.gnu.org/mailman/listinfo/gnash. Volume is typically
      low.
    * gnash-dev@gnu.org is for discussion of gnash development,
      porting to new platforms, ideas for the future. This is where
      the nitty-gritty gets discussed about Gnash, and is the best
      list for technical questions. To subscribe, go the
      http://mail.gnu.org/mailman/listinfo/gnash-dev 
    * gnash-commit@gnu.org is where summaries of changes commited to
      the CVS repository are automatically posted. If you wish to see
      these changes as they happen,
      http://mail.gnu.org/mailman/listinfo/gnash-commit Volume is
      sporadic, but typically low.

If you would like a new feature to be included in future versions of
Gnash, please send a request to <gnash-dev@gnu.org>. You can also
submit patches at https://savannah.gnu.org/patch/?group=gnash.

Please remember that development of Gnash is a volunteer effort.
You can contribute to its development. The Gnash project would like to
find volunteers to focus on win32 and Darwin support, as well as help
us fill in missing functionality. Offers of help can be sent to
<gnash-dev@gnu.org>.

For information about contributing to the GNU Project, please read How
to help GNU at <http://www.gnu.org/help/help.html>.

If you think you have found a bug in Gnash, then you should file as
complete a report as possible at 
https://savannah.gnu.org/bugs/?group=gnash.  Please include the
operating system name and version, and which gnash version you are
using, in your bug reports.
