# User Configuration File

Individual user preferences may be set by editing variables with the `.gnashrc` file:

          ~/.gnashrc

Each line must begin with an action: either set or, in the case of lists, also append.

The values in this configuration file apply only to an individual user, and become the default settings of the standalone player and the plugin. Note that any command line options take precedence over `.gnashrc` settings.

The variables in the `.gnashrc` file support three types of arguments: on/off, numeric values, or in the case of the whitelist and blacklist, a list of hostnames as ASCII text. User configuration variables in `.gnashrc` are case-insensitive.

## User Configuration Variables

Variable | Value | Function
localdomain | on/off | This value can be set to either on or off, and controls the loading of external Flash movies over a network. This option tells Gnash to only load Flash movies from the existing domain.
localhost | on/off | This value can be set to either on or off, and controls the loading of external Flash movies over a network. This is a stricter version of the localdomain setting as this allows the loading of Flash movies to the same host that is running &app;.
whitelist | hostnames | This is a list of hostnames separated by spaces, or off to disable the whitelist. The hostname must be given without a protocol (http://, https://). If this list is populated, &app; will only load external Flash movies from the specified hosts. The whitelist takes precedence over the blacklist. Because several files can be parsed in succession, each file can override or add to lists in other files. Use set to override all other lists or append to add your blacklisted hosts to lists in previously parsed files.
blacklist | hostnames | This is a list of hostnames separated by spaces, or off to disable the blacklist. The hostname must be given without a protocol (http://, https://). External flash movies from these domains are never allowed to load. If whitelist is present and not empty, blacklist is not used. Because several files can be parsed in succession, each file can override or add to lists in other files. Use set to override all other lists or append to add your blacklisted hosts to lists in previously parsed files.
localSandboxPath | dirs | This is a list of directories separated by spaces. Only resources from these directories and from the directory portion of movie filename (if loaded from filesystem) are allowed to load. Because several files can be parsed in succession, each file can override or add to lists in other files. Use set to override all other lists or append to add new sandboxes. Note that there's currently no way to drop the directory of base dir from the list of allowed local sandboxes.
delay | Number | &app; uses a timer-based event mechanism to advance frames at a steady rate. This option overrides the default setting in Gnash to play a movie slower or faster.
verbosity | Number | This is a numeric value which defines the default level of verbosity from the player.
MalformedSWFVerbosity | on/off | This value can be set to either on or off, and controls whether malformed SWF errors should be printed. If set to true, verbosity level is automatically incremented. Set `verbosity` to 0 afterwards to hush.
ASCodingErrorsVerbosity | on/off | This value can be set to either on or off, and controls whether ActionScript coding errors should be printed. If set to true, verbosity level is automatically incremented. Set `verbosity` to 0 afterwards to hush.
debuglog | Absolute path | This is the full path and name of debug logfile as produced by &app;. On systems with a UNIX-type shell, a tilde prefix (~) will be expanded as by Posix shell requirements (see http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_06_01).
writelog | on/off | This value can be set to either on or off, and controls whether a debug log is always written by &app;, or not at all.
sound | on/off | This value can be set to either on or off, and controls the sound of the standalone player. By default &app; enables playing the sound in any Flash movie.
pluginsound | on/off | This value can be set to either on or off, and controls the sound of the player when running as a browser plugin. By default, sound is enabled when using &app; as a browser plugin.
EnableExtensions | on/off | Set to on to enable extensions. This option is off by default
StartStopped | on/off | Set to on to have the GUI start in "stop" mode. This is useful in particular for the plugin, so you have to explicitly start any movie on a webpage. This option is off by default.
webcamDevice | integer | The integer value (index into vector of video devices) that represents the default webcam. To easily get this entry run utilities/findwebcams (only works with Gstreamer right now)
microphoneDevice | integer | The integer value (index into vector of microphone devices) that represents the default microphone. To easily get this entry run utilities/findmicrophones (only works with Gstreamer right now)
flashVersionString | string | Set the string returned by $version and System.capabilities.version. Useful to get around some flash version detection movies. Note that the version advertised by the plugin is NOT affected by this setting, instead you need to set the GNASH_FLASH_VERSION environment variable for the latter (which doesn't affect $version and System.capabilities.version).
flashSystemOS | string | The string that Gnash should return for System.capabilities.OS
flashSystemManufacturer | string | The string that Gnash should return for System.capabilities.manufacturer
StreamsTimeout | double | Set the number of seconds after which streams download time out. Timeouts only occur after the given number of seconds have passed without anything being received.
insecureSSL | on/off | If set to on, no verification of SSL connections is performed. This means that, although the connection is encrypted, the server certificate could be invalid, may not belong to the host, or both. Equivalent to curl --insecure. By default, this option is off and connections will fail when a host cannot be verified.
SOLsafedir | Absolute path | The full path to a directory where &app; should store Shared Object files ("flash cookies") if they are enabled.
solLocalDomain | on/off | If set to on, allow the loading of Shared Objects only on the localhost.
SOLreadonly | on/off | If set to on, &app; will not write Shared Object files.
ignoreFSCommand | on/off | If set to on (default), &app; will ignore fscommands in standalone mode. Fscommands are requests from the playing movie to the operating system or user interface: the most common are quit, fullscreen, showmenu and exec. &app; always ignores fscommands when running as a plugin.
URLOpenerFormat | string | Set the format of an url opener command. The %u label would be substituted by the actual url to be opened. Examples:
    	      set urlOpenerFormat firefox -remote 'openurl(%u)'
    	      set urlOpenerFormat xdg-open '%u'
    	      set urlOpenerFormat open '%u'
    	      set urlOpenerFormat kfmclient exec '%u'
HWAccel | string | Specify the type of Hardware Video Decoder. Currently only vaapi or none are supported. None disables any acceleration support (the default).
MediaHandler | string | Specify the type of Media Handler to use. Currently only ffmpeg or gst are supported. The default is ffmpeg.
Renderer | string | Specify the type of Renderer to use. Currently only agg, opengl, or cairo are supported. The default is AGG, as it doesn't require any special hardware support.
quality | [-1|0|1|2|3] | Set rendering quality. If set to -1, &app; will use whatever quality set by the movie being run. If set to any value from 0 to 3 &app; will lock quality to the specified value (0=low, 1=medium, 2=high, 3=best). Defaults to -1.
scriptsTimeout | integer | The amount of seconds after which to prompt popup for script execution abortion. Defaults to 15. Can be changed by SWF tags unless you 'set lockScriptLimits on'.
scriptsRecursionLimit | integer | The maximum depth of function call stack for ActionScript execution. Defaults to 256. Can be changed by SWF tags unless you 'set lockScriptLimits on'.
lockScriptLimits | boolean | Makes scriptsRecursionLimit and scriptsTimeout locked to the default (or rcfile) values and doesn't allow SWF tag to modify it. Defaults to off.

The following example `.gnashrc` file allows a user to only play Flash files saved locally to the machine on which &app; is running. It also specifically forbids content from doubleclick.com and mochibot.com. &app;'s error output is set to be fairly verbose, with the debug log placed in a location convenient for the user. Finally, sound is turned on for both the standalone player and the plugin.

        #
        # Gnash client options
        #

        # Only access remote content from our local domain
        set localdomain on

        # Only access content from our local host
        set localhost on

        # These sites are OK
        # uncommenting the following line will allow load of external
        # movies *only* from the specified hosts.
        #set whitelist www.doonesbury.com www.cnn.com www.9news.com

        # Disable whitelists set in any other gnashrc files, because
        # these could override our blacklist.
        set whitelist off

        # Don't access content from these sites
        set blacklist www.doubleclick.com mochibot.com

        # The delay between timer interrupts
        set delay 50

        # The default verbosity level
        set verbosity 1

        # Be verbose about malformed SWF
        set MalformedSWFVerbosity true

        # Be verbose about AS coding errors
        set ASCodingErrorsVerbosity true

        # The full path to the debug log
        set debuglog ~/gnash-dbg.log

        # Write a debug log to disk
        set writelog on

        # Enable or Disable sound for the standalone player
        set sound on

        # Enable or Disable sound for the standalone player
        set pluginsound on

        # Make sure SSL connections are always verified
        set insecureSSL off

        # Use firefox to open urls
        set urlOpenerFormat firefox -remote 'openurl(%u)'