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.8 release (or 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 9. 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 -vv with gnash or gprocessor. Running gprocessor -vv is often an
easy way to see why a movie isn't playing correctly.

Plugin:	
-------

The plugin can play SWF files in cooperation with the browser.
It works with any browser that supports Mozilla's NPAPI plugin interface.
Gnash is know to work with Mozilla, Firefox, Iceweasel, Icecat, Konqueror,
Epiphany, Galeon, Opera, SeaMonkey, Midori and Chromium.
Gnash runs equally well in 32-bit and 64-bit environments.

Configure with --with-plugindir= to set the directory that "make
install-plugin" 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.
Gnash is known to run on most BSD derived systems as well. There are
also ports to Beos, Haiku, OS/2, Irix, Solaris, Sylllable, and
OpenEmbedded.

There are also 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 LX/GX.

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

See the generic installation instructions in the file called "INSTALL".
(If you are building from a fresh git checkout, first see the file
"README.git" 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, qt4, 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. By default it'll build both FFmpeg and Gstreamer, which you
can select at runtime. To select only one media handler use:

   --enable-media=GST			Gstreamer (default)
or --enable-media=ffmpeg		FFmpeg

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=qt4
or --enable-gui=gtk,qt4 (default)

Other guis: dump, raw framebuffer, fltk, kde3, qt4, 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 compile gnash to use
Gstreamer, users who want to view Flash videos while running gnash 
will need to install the FFmpeg plugin for gstreamer. Flash uses
MPEG4, MP3, FLV, ACC, and Sorenson primarily. Gnash supports any codec
supported by FFmpeg and 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...

To build Klash, the Konqueror plugin, you need to have the KDE
development packages installed. This now installs a Qt executable
called "qt4-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/: 

    * [email protected] 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 
    * [email protected] 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.
    * [email protected] is where summaries of changes committed to
      the git 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 <[email protected]>. 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
<[email protected]>.

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 git, as bugs are fixed there that may be
broken in a standard release.