$Id: README,v 1.23.2.3 2006/10/30 14:29:22 strk Exp $

		    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 the soon to be released Gnash-0.7.2.

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 (then one of the GameSWF developers) 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 may still have a few issues with some URLs left. Most
Flash based navigation of a web site should work.

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.

There is now experimental sound support if you configure this into
your build. What works now is the sdl sound handler with either the
ffmpeg or libMad decoder.

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 of Mozilla's NSPR API and
plugin SDK. It has been tested with Mozilla 1.7.13 with gtk2 (won't work with
gtk1 due to the NSAPI used), Firefox 1.0.x and Firefox 1.5.x.

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 their
boundaries. 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 played as they are loaded over the network.
Optionally, if the --enable-write configure switch is given, a copy
of movies is stored in /tmp.

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 build 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 by choosing SDL
as gui. In this case the only dependency for the gui is SDL
development package.

The GTK support is more developed and featureful, while the SDL
support has less dependancies on other packages. Note that you
will need a GTK gui for the plugin to work.

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

Other dependencies are required for the 'rendering' part.
Gnash currently supports OpenGL and AGG. An experimental
Cairo backend implementation is also included, but it is
not full functional yet.

The dependent package for the renderer are:
	- for OpenGL : Opengl(libMesa).
	- for AGG    : agg-2.4 (a fairly recent one, the one in debian
	                        testing doesn't work)

Experimental sound support is available trough either SDL or Gstreamer.
The SDL version is more feature rich and can use either ffmpeg or libmad
for mp3 decoding.

If you opt for Gstreamer you'll need Gstreamer version 0.10 becasue earlier
versions wouldn't let you insert clips into an existing sound stream as Gnash
needs to do.

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.

Testing Gnash:
--------------

After a successful build you can run:

	# make check

To run all the available regression tests.
To see result with your eyes, you can try some movies found
under the testsuite/movies.all directory. elvis.swf and gravity.swf
should work fine.

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-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@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-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.
