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