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