README

   1
   2                     Gnash: the GNU SWF Player
   3
   4 Gnash is a player for animated "movies" in the Macromedia Shockwave Flash
   5 (SWF) format.  It can be run as a graphical application, as a Web browser
   6 plugin, or as a library used by other programs.  It is not yet complete;
   7 it does not correctly handle every SWF file.
   8
   9 This is the README file for the Gnash-0.8.8 release (or snapshot).
  10
  11 Gnash is originally based on the code of GameSWF, by Thatcher Ulrich.
  12 GameSWF was the most advanced among free SWF players; it implemented a
  13 fairly broad set of SWF Format v7 features.  In December 2005, Rob
  14 Savoye (then one of the GameSWF developers) forked GameSWF to become
  15 Gnash.  New improvements added to Gnash are copyrighted by the Free
  16 Software Foundation under the GNU General Public License.  After Rob
  17 rearranged the GameSWF code into the GNU project style, he began
  18 development on the browser plugins.  The Free Software Foundation made
  19 Gnash a priority project, and many volunteers started contributing
  20 useful improvements.  We thank Thatcher Ulrich for the great start,
  21 Rob Savoye and John Gilmore for organizing the project, and the Gnash
  22 volunteers for making Gnash what it is today.
  23
  24 SWF Support:
  25 --------------
  26
  27 Many SWF movies play fine in Gnash.  Many others do not.  Occasionally,
  28 SWF movies that are used for browser navigation may fail. Almost all
  29 SWF-based web-site navigation should work.
  30
  31 Gnash supports practically all SWF opcodes and most ActionScript classes up
  32 to SWF version 9. There is currently no real support for ActionScript
  33 3 (ABC blocks) and AVM2, which were introduced in SWF version
  34 9. Despite this, Gnash can play most SWF8 and many SWF9 movies,
  35 because not all rely on unimplemented features.
  36
  37 All unimplemented opcodes and ActionScript methods should print a warning
  38 when using -vv with gnash or gprocessor. Running gprocessor -vv is often an
  39 easy way to see why a movie isn't playing correctly.
  40
  41 Plugin:
  42 -------
  43
  44 The plugin can play SWF files in cooperation with the browser.
  45 It works with any browser that supports Mozilla's NPAPI plugin interface.
  46 Gnash is know to work with Mozilla, Firefox, Iceweasel, Icecat, Konqueror,
  47 Epiphany, Galeon, Opera, SeaMonkey, Midori and Chromium.
  48 Gnash runs equally well in 32-bit and 64-bit environments.
  49
  50 Configure with --with-plugindir= to set the directory that "make
  51 install-plugin" will install the plugin in. By default it will be installed
  52 in the user's .mozilla/plugins directory, even if you install using
  53 sudo.
  54
  55 Platforms Supported:
  56 --------------------
  57
  58 Gnash has been ported to a wide variety of hardware and operating
  59 systems. Primary platforms that get the most support are most of
  60 the GNU/Linux distributions, but Ubuntu, Fedora, and Debian primarily.
  61 Gnash is known to run on most BSD derived systems as well. There are
  62 also ports to Beos, Haiku, OS/2, Irix, Solaris, Sylllable, and
  63 OpenEmbedded.
  64
  65 There are also ports of the standalone player to Darwin and
  66 Win32. Both require adding the dependent libraries Gnash needs. Work
  67 has started on a native Darwin (Aqua/Carbon/OpenGL) GUI so most of
  68 these packages won't be required. The win32 player can be built with
  69 Mingw32 and ought to be compilable with VC++ (but this has not been
  70 confirmed recently).
  71
  72 Gnash has also been ported to a variety of embedded devices, most
  73 running variations of OpenEmbedded. These include several custom
  74 hardware platforms aimed at educational software for children. Better
  75 known devices are the Sharp Zaurus family of PDAs (reflashed to run Open
  76 Zaurus), the Nokia Internet Tablets (770 / 800 / 810), the OLPC and the
  77 Pepper Pad 3, the latter two running a trimmed down Fedora.
  78
  79 Gnash has been known to run on these 64-bit systems: the Itanium,
  80 UltraSparc, PowerPC, AMD64, MIPS. Embedded processors include several
  81 ARM variants, MIPS, and the Geode LX/GX.
  82
  83 Building Gnash:
  84 ---------------
  85
  86 See the generic installation instructions in the file called "INSTALL".
  87 (If you are building from a fresh git checkout, first see the file
  88 "README.git" for additional instructions.)
  89
  90 Depending on chosen functionality, CPU architecture, and OS the temporary
  91 files needed when Gnash compiles require as much as 1 GB of storage space.
  92 Approximately 400MB of virtual memory(RAM + swap) is also needed for linking.
  93 After installation, the temporary files may be removed with "make clean".
  94
  95 Gnash has three main options: choice of renderer (graphics library used
  96 to render the SWF movie), choice(s) of GUI toolkit (gtk, qt4, etc), and choice
  97 of multimedia backend (audio and video decoder).
  98
  99 Gnash supports multiple renderers. By default it'll build them all in
 100 the rendering library, or you can select which ones you want:
 101
 102    --enable-renderer=opengl
 103    --enable-renderer=cairo
 104    --enable-renderer=agg
 105 or --enable-renderer=all (default)
 106
 107 Gnash can use different multimedia back-ends for sound and/or
 108 video. By default it'll build both FFmpeg and Gstreamer, which you
 109 can select at runtime. To select only one media handler use:
 110
 111    --enable-media=GST                   Gstreamer (default)
 112 or --enable-media=ffmpeg                FFmpeg
 113
 114 In some countries, the codecs needed to display audio and video are patented.
 115 The FFmpeg library implements these codecs.  If you link them directly into
 116 Gnash, you will create an executable which contains patented software and
 117 requires a license for redistribution in those countries.  If, instead,
 118 you build using gstreamer, the user installs the codecs of their choice.
 119
 120 Gnash supports multiple graphics toolkits, and will build multiple
 121 executables:
 122
 123    --enable-gui=gtk
 124    --enable-gui=qt4
 125 or --enable-gui=gtk,qt4 (default)
 126
 127 Other guis: dump, raw framebuffer, fltk, kde3, qt4, gtk, sdl, qtopia,
 128 hildon, alp, riscos, aqua. Some guis are very specialized (dump writes
 129 out raw frames to a disk file). Other guis are not very well supported
 130 and may not even compile (aqua).
 131
 132 Different options will cause gnash to require different libraries.  The
 133 configure script does a good job of telling you how to get these libraries.
 134
 135 The GTK support is the most developed and featureful, while the SDL
 136 support has fewer dependencies on other packages. The AGG backend
 137 gives better quality results, and works on devices with only a
 138 framebuffer.  Performance is better with the OpenGL backend, but
 139 only if an accelerated graphics driver installed. This may require the
 140 use of a non-free driver, so it's not for everyone.
 141
 142 Other required packages are libjpeg.
 143
 144 If gettext support is installed, or is present in the standard C library,
 145 gnash will support translation of its messages into other
 146 languages. Boost is also required, as Gnash uses it for portable
 147 mutexes and threading.
 148
 149 If you select gstreamer as the media backend, gnash requires version 0.10
 150 because earlier versions wouldn't let you insert clips into an existing
 151 sound stream, as Gnash needs to do. If you compile gnash to use
 152 Gstreamer, users who want to view Flash videos while running gnash
 153 will need to install the FFmpeg plugin for gstreamer. Flash uses
 154 MPEG4, MP3, FLV, ACC, and Sorenson primarily. Gnash supports any codec
 155 supported by FFmpeg and Gstreamer.
 156
 157 Building the Gnash plugin for browsers:
 158 --------------------------------------
 159
 160 The plugin is automatically built, but is installed only when you
 161 say "make install-plugins". Installation target is controlled
 162 by a configure switch: --with-plugins-install=system|user|prefix.
 163
 164 By default, the policy is 'user', which means the plugins will
 165 be installed for the sole user running 'make install-plugins'.
 166 Keep this in mind as you likely don't want to install plugins
 167 only for the root user...
 168
 169 To build Klash, the Konqueror plugin, you need to have the KDE
 170 development packages installed. This now installs a Qt executable
 171 called "qt4-gnash" that is used by this plugin.
 172
 173 The Gnash Community:
 174 --------------------
 175
 176 Gnash has three mailing lists hosted at gnu.org. Archives of these
 177 lists are stored at http://mail.gnu.org/pipermail/:
 178
 179     * gnash-dev@gnu.org is for discussion of gnash development,
 180       porting to new platforms, ideas for the future. This is where
 181       the nitty-gritty gets discussed about Gnash, and is the best
 182       list for technical questions. To subscribe, go to
 183       http://mail.gnu.org/mailman/listinfo/gnash-dev
 184     * gnash@gnu.org is a moderated list for announcements. New releases are
 185       announced here. To subscribe, go to
 186       http://mail.gnu.org/mailman/listinfo/gnash and register. Volume is
 187       typically very low.
 188     * gnash-commit@gnu.org is where summaries of changes committed to
 189       the git repository are automatically posted. Register at
 190       http://mail.gnu.org/mailman/listinfo/gnash-commit to be informed of
 191       these changes as they happen. Volume may be high.
 192
 193
 194 IRC:
 195     * #gnash on irc.freenode.net The #gnash channel on irc.freenode.net is
 196       where many of the developers hang out.
 197
 198 If you would like a new feature to be included in future versions of
 199 Gnash, please send a request to <gnash-dev@gnu.org>. You can also
 200 submit patches at https://savannah.gnu.org/patch/?group=gnash.
 201
 202 Please remember that development of Gnash is a volunteer effort.
 203 You can contribute to its development. The Gnash project would like to
 204 find volunteers to focus on win32 and Darwin support, as well as help
 205 us fill in missing functionality. Offers of help can be sent to
 206 <gnash-dev@gnu.org>.
 207
 208 For information about contributing to the GNU Project, please read How
 209 to help GNU at <http://www.gnu.org/help/help.html>.
 210
 211 If you think you have found a bug in Gnash, then
 212 you should file as complete a report as possible at
 213 https://savannah.gnu.org/bugs/?group=gnash.  Please include the operating
 214 system name and version, and which gnash version you are using, in your
 215 bug reports. Please try to reproduce your bug reports with the most
 216 recent version of Gnash in git, as bugs are fixed there that may be
 217 broken in a standard release.
 218