Gnash: the GNU SWF 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 Gnash-0.8.7 release (or bzr snapshot).

Gnash is originally based on the code of GameSWF, by Thatcher Ulrich.
GameSWF was the most advanced among free SWF players; it implemented a
fairly broad set of SWF 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.


SWF Support:
--------------

Many SWF movies play fine in Gnash.  Many others do not.  Occasionally, 
SWF movies that are used for browser navigation may fail. Almost all
SWF-based web-site navigation should work.

Gnash supports practically all SWF opcodes and most ActionScript classes up
to SWF version 7. Gnash also supports some of the most important SWF
version 8 ActionScript classes. There is currently no real support for
ActionScript 3 (ABC blocks) and AVM2, which were introduced in SWF version 9.
Despite this, Gnash can play most SWF8 and many SWF9 movies, because not all
rely on unimplemented features.

All unimplemented opcodes and ActionScript methods should print a warning
when using -v with gnash or gprocessor. Running gprocessor -v is often an
easy way to see why a movie isn't playing correctly.


Plugin:	
-------

The plugin correctly installs itself into Mozilla, Firefox, or Konqueror.
It can play some SWF files in cooperation with the browser. It
should work with any browser that supports 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, Firefox 1.5.x, Firefox 2.x,
Firefox 3.x, Iceweasel 2.0.0.6 and Epiphany.

Gnash runs equally well in 32-bit and 64-bit environments, so works without
any issues as a 64-bit plugin.

Occasionally, web pages may have Internet Explorer-specific Javascript that
fails in other browsers, thus preventing the plugin from being loaded. These
cases are now extremely rare, because web developers are more knowledgable
about supporting multiple browsers and because free, standardised
flash-embedding scripts are widely used. If you do encounter faulty javascript,
"view source" and then use wget to grab the movie for testing.

The plugin works by forking and running the standalone player, so whichever
graphics library Gnash uses will also be used by the plugin. As an alternate
to SDL, Gnash also now has FLTK2 support.

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.

Configure with --with-plugindir= to set the directory that "make
install" will install the plugin in. By default it will be installed
in the user's .mozilla/plugins directory, even if you install using
sudo.

Platforms Supported:
--------------------

Gnash has been ported to a wide variety of hardware and operating
systems. Primary platforms that get the most support are most of
the GNU/Linux distributions, but Ubuntu, Fedora, and Debian primarily.
OpenBSD is also adequately maintained, but Gnash is known to run on
FreeBSD and NetBSD systems as well. There are also ports to Beos,
Haiku, OS/2, Irix, Solaris, and OpenEmbedded.

There are ports of the standalone player to Darwin and Win32. Both
require adding the dependent libraries Gnash needs. Work has started
on a native Darwin (Aqua/Carbon/OpenGL) GUI so most of these packages
won't be required. The win32 player can be built with Mingw32 and ought
to be compilable with VC++ (but this has not been confirmed recently). 

Gnash has also been ported to a variety of embedded devices, most
running variations of OpenEmbedded. These include several custom
hardware platforms aimed at educational software for children. Better
known devices are the Sharp Zaurus family of PDAs (reflashed to run Open
Zaurus), the Nokia Internet Tablets (770 / 800 / 810), the OLPC and the
Pepper Pad 3, the latter two running a trimmed down Fedora.

Gnash has been known to run on these 64-bit systems: the Itanium,
UltraSparc, PowerPC, AMD64, MIPS. Embedded processors include several
ARM variants, MIPS, and the Geode GX.

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

See the generic installation instructions in the file called "INSTALL".
(If you are building from a fresh bzr checkout, first see the file
"README_bzr" for additional instructions.)

Depending on chosen functionality, CPU architecture, and OS the temporary
files needed when Gnash compiles require as much as 1 GB of storage space.
Approximately 400MB of virtual memory(RAM + swap) is also needed for linking.
After installation, the temporary files may be removed with "make clean".

Gnash has three main options: choice of renderer (graphics library used
to render the SWF movie), choice(s) of GUI toolkit (gtk, kde, etc), and choice
of multimedia backend (audio and video decoder).

Gnash supports multiple renderers.
By default it'll build them all in the rendering library, or you can
select which ones you want:

   --enable-renderer=opengl
   --enable-renderer=cairo
   --enable-renderer=agg
or --enable-renderer=all (default)

Gnash can use different multimedia back-ends for sound and/or video:

   --enable-media=GST			Gstreamer (default)
or --enable-media=ffmpeg		Ffmpeg/SDL

In some countries, the codecs needed to display audio and video are patented.
The ffmpeg library implements these codecs.  If you link them directly into
Gnash, you will create an executable which contains patented software and
requires a license for redistribution in those countries.  If, instead,
you build using gstreamer, the user installs the codecs of their choice.

Gnash supports multiple graphics toolkits, and will build multiple
executables:

   --enable-gui=gtk
   --enable-gui=kde
or --enable-gui=gtk,kde (default)

Other guis: dump, fb, fltk, kde3, kde4, gtk, sdl, qtopia, hildon, alp, riscos,
aqua. Some guis are very specialized (dump writes out raw frames to a disk
file). Other guis are not very well supported and may not even compile (aqua).

Different options will cause gnash to require different libraries.  The
configure script does a good job of telling you how to get these libraries.

The GTK support is the most developed and featureful, while the SDL
support has fewer dependencies on other packages. The AGG backend
gives better quality results, and works on devices with only a
framebuffer.  Performance is better with the OpenGL backend, but
only if an accelerated graphics driver installed. This may require the
use of a non-free driver, so it's not for everyone.

Other required packages are libjpeg.

If gettext support is installed, or is present in the standard C library,
gnash will support translation of its messages into other
languages. Boost is also required, as Gnash uses it for portable
mutexes and threading.

If you select gstreamer as the media backend, gnash requires version 0.10
because earlier versions wouldn't let you insert clips into an existing
sound stream, as Gnash needs to do. If you use Gstreamer, you still need
the ffmeg decoders, and the ffmpeg plugin for Gstreamer.

Building the Gnash plugin for browsers:
--------------------------------------

The plugin is automatically built, but is installed only when you
say "make install-plugins". Installation target is controlled
by a configure switch: --with-plugins-install=system|user|prefix.

By default, the policy is 'user', which means the plugins will
be installed for the sole user running 'make install-plugins'.
Keep this in mind as you likely don't want to install plugins
only for the root user...

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 whenever the main gnash program can be built.

To build Klash, the Konqueror plugin, you need to have the KDE
development packages installed. This now installs a KDE executable
called "kde-gnash" 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-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 to
      http://mail.gnu.org/mailman/listinfo/gnash-dev 
    * gnash@gnu.org is a moderated list for announcements. New releases are
      announced here. To subscribe, go to
      http://mail.gnu.org/mailman/listinfo/gnash and register. Volume is
      typically very low.
    * gnash-commit@gnu.org is where summaries of changes commited to
      the bzr repository are automatically posted. Register at
      http://mail.gnu.org/mailman/listinfo/gnash-commit to be informed of
      these changes as they happen. Volume may be high.
      

IRC:
    * #gnash on irc.freenode.net The #gnash channel on irc.freenode.net is 
      where many of the developers hang out.

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. Please try to reproduce your bug reports with the most
recent version of Gnash in bzr, as bugs are fixed there that may be
broken in a standard release.