Nightly builds of Ruffle are available for all platforms. To download a build, click the Assets dropdown, then click the appropriate file for your platform.

You will also need an SWF file to run; try some Ruffle approved test SWFs.

Web Demo

The easiest way to try out Ruffle is to visit the web demo page, then click the Browse... button to load an SWF file of your choice. This works in any modern mobile or desktop browser, as long as you have an SWF file downloaded to your device.

The Internet Archive's Flash collection has a constantly growing selection of Flash files running via Ruffle in your browser - no download required.

Desktop

Desktop builds of Ruffle are available for Windows, Mac and Linux.

Windows

On the Releases page, click the link labeled windows. After the file has downloaded, right-click it and choose "Extract All." Open the extracted folder and double-click the ruffle.exe file. Use the file chooser that pops up to pick an SWF file on your computer.

macOS

On the Releases page, click the link labeled macos. After the file has downloaded, double-click it to extract it. Right-click the ruffle executable and choose "Open." Use the file chooser that pops up to pick an SWF file on your computer.

If you prefer the command line, you can install Ruffle using the commands below:

wget "https://github.com/ruffle-rs/ruffle/releases/download/nightly-$(date -u +%Y-%m-%d)/ruffle-nightly-$(date -u +%Y_%m_%d)-macos-universal.tar.gz"
tar -xzvf "$(basename "$_")"
install ruffle /usr/local/bin

Linux

On the Releases page, click the link labeled linux. After the file has downloaded, extract it and run the ruffle executable. Use the file chooser that pops up to pick an SWF file on your computer.

If you prefer the command line, you can install Ruffle using the commands below:

wget "https://github.com/ruffle-rs/ruffle/releases/download/nightly-$(date -u +%Y-%m-%d)/ruffle-nightly-$(date -u +%Y_%m_%d)-macos-universal.tar.gz"
tar -xzvf "$(basename "$_")"
sudo install ruffle /usr/local/bin

Command-line Usage

After you have extracted the appropriate file for your platform, navigate to the extracted folder using your Terminal or Command Prompt.

If you're on Windows, type ruffle filename.swf to run an SWF, or type ruffle --help to see the rest of the command-line options.

If you're on Linux or Mac, type ./ruffle filename.swf to run an SWF, or type ./ruffle --help to see the rest of the command-line options.

Browser Extension

The browser extension works in Chrome, Firefox, and Safari 14+. Install the extension by following the instructions below.

Chrome

These instructions also apply to Chromium-based browsers such as Edge, Opera and Brave.

The easiest way to install Ruffle is to get it from the Chrome Web Store.

If you have an Android device, you will need to use a Chromium-based browser that supports extensions, such as the Kiwi Browser.

Or if you want to be on the bleeding edge, follow these instructions to install the latest nightly release:

• On the Releases page, click the link ending in web-extension.zip.
• Type chrome://extensions/ into Chrome's address bar, then press Enter.
• Turn on Developer mode in the top-right corner.
• Drag and drop the downloaded ZIP file into the page.

Alternatively, if you're a developer, you can save some time by following these instructions:

• Navigate to chrome://extensions/.
• Turn on Developer mode in the top-right corner.
• Click "Load unpacked".
• Select the assets/ folder.
• Each time you make changes during development, click the reload icon.

Firefox

The easiest way to install Ruffle is to get it from the Firefox Add-ons site.

Or if you want to be on the bleeding edge, follow these instructions to install the latest nightly release:

• On the Releases page, right-click the link for Firefox (ending in firefox-unsigned.xpi) and choose "Save Link As..."
• Type about:debugging into Firefox's address bar, then press Enter.
• Click on "This Firefox."
• Click "Load Temporary Add-on..."
• Select the .xpi file that you saved.

Safari

• Unzip the *_extension.zip file.
• Run xcrun safari-web-extension-converter path/to/unzipped_folder/
• Click "Run on Xcode".
• Enable Safari > Preferences > Advanced > Show Develop menu in menu bar.
• Enable Develop > Allow Unsigned Extensions.
• Enable the extension by checking the box in Safari > Preferences > Extensions.

Note: Converting the extension to be Safari compatible requires Xcode 12+ to be installed. For using the extension Safari 14+ is required

Web

For integrating Ruffle onto your own website:

• Download the latest Ruffle nightly build for web.
• Extract it into a directory on your web server.

Alternatively, Ruffle is packaged with npm every release, and can be included through one of the official CDN releases on jsDelivr or unpkg.

You may then use Ruffle as a polyfill for legacy Flash embeds, or use the Ruffle JavaScript API directly.

Polyfill

Ruffle will automatically replace any old-style Flash embeds on websites with Ruffle elements. This is ideal for someone looking to preserve a legacy website with a minimum amount of work. All you need to do is include the following script tag on the desired webpage:

<script src="path/to/ruffle/ruffle.js"></script>

If you'd prefer to use the automatically updating CDN release, you can include one of the following script tags instead:

<script src="https://cdn.jsdelivr.net/npm/@ruffle-rs/ruffle"></script>

OR

<script src="https://unpkg.com/@ruffle-rs/ruffle"></script>

If you embed SWF content using JavaScript libraries such as SWFObject, then this tag should be placed as the first script tag in the <head>, so Ruffle will be able to install its plugin spoof in time. In any other case, it's good practice to add the script before the closing </body> tag .

Any Flash embed on the page should now be replaced with Ruffle. If Ruffle fails to load, you may need to specify the publicPath setting: please see the Configuration Options below for further details.

JavaScript API

The Ruffle JavaScript API can be used to create Ruffle instances directly. This is ideal for anyone who wants to create embeds dynamically and get more control over Ruffle.

Here is an example of using the Ruffle JavaScript API to play back an SWF file called movie.swf located in our web server's root directory. Paste the following script onto your website before the closing </body> tag:

<script>
    window.RufflePlayer = window.RufflePlayer || {};
    window.addEventListener("load", (event) => {
        const ruffle = window.RufflePlayer.newest();
        const player = ruffle.createPlayer();
        const container = document.getElementById("container");
        container.appendChild(player);
        player.load("movie.swf");
    });
</script>
<script src="path/to/ruffle/ruffle.js"></script>

player is a DOM object which can be attached and resized as desired using native JavaScript features. For instance, to create a player with a width of 600px and an height of 400px, all you need to do is: player.style.width = "600px"; player.style.height = "400px";

If Ruffle fails to load, you may need to specify the publicPath setting: please see the Configuration Options below for further details.

Advanced usage

The load method also accepts a JavaScript object as an argument. The example below lists all of the valid keys with their default values:

player.load({
    url: "", // A string, indicating the SWF file to load (e.g. "movie.swf").
    parameters: "", // Also known as "flashvars", this is a string indicating values that may be passed to and loaded by the movie (e.g. "key1=value1&key2=value2").
    allowScriptAccess: false, // A boolean indicating whether the file is allowed to interact with the page through JavaScript.
});

The load method returns a promise. This means you can do specific actions depending on the file loading succeeds or fails. Here's an example:

player.load("movie.swf").then(() => {
    console.info("Ruffle successfully loaded the file");
}).catch((e) => {
    console.error(`Ruffle failed to load the file: ${e}`);
});

Fullscreen toggling is done through the Fullscreen API, and is thus subject to the same restrictions. However, vendor prefixes are handled by the player's own code, and thus should not be needed.

The fullscreenEnabled() method checks if this player is allowed to be fullscreen by the browser. Only if it returns true can enterFullscreen() be used.

The isFullscreen() method checks if this player is currently fullscreen inside the browser.

The enterFullscreen() method requests the browser to make this player fullscreen.

The exitFullscreen() method requests the browser to make this player no longer fullscreen.

The pause() method pauses this player, displaying the play button overlay and making it so no more frames, scripts or sounds will be executed and the movie will be considered inactive.

The play() method plays or resumes the movie inside the player and hides the play button overlay.

The displayMessage(message) method can be used to show a custom dismissible message in front of the player.

The metadata property shows information about the swf currently loaded inside the player. It is an object which includes the following:

• width: The width of the movie (not the player) in pixels.
• height: The height of the movie (not the player) in pixels.
• frameRate: The frame rate of the movie in frames per second.
• numFrames: The number of frames on the root timeline of the movie.
• swfVersion: The SWF version of the movie. See also the SWF Version Chart.
• backgroundColor: The background color of the movie as a hex string, such as "#FFFFFF". May be null if the background color is unavailable.
• isActionScript3: Whether this movie is an ActionScript 3.0 movie.

The loadedmetadata event is an event which is triggered when the player metadata becomes available. Note that in the future this can happen before the movie is fully loaded.

The loadeddata event is an event which is triggered when the movie is fully loaded.

The readyState property indicates the readiness of the playing movie. It can hold the following values:

• 0: No movie is loaded, or no information is yet available about the movie.
• 1: The movie is still loading, but it has started playback, and metadata is available.
• 2: The movie has completely loaded.

The config property indicates any configuration that should apply to this specific player.

Configuration Options

Different configuration options exist, affecting playback of specific files or Ruffle's overall behavior.

To specify configuration option values, simply initialize the window.RufflePlayer object as usual, then set window.RufflePlayer.config to a JavaScript literal object with the values you'd like to use. This is a global setting and as such, it will affect all files hosted on the current page.

The example below lists all of the available options with their default values:

window.RufflePlayer = window.RufflePlayer || {};
window.RufflePlayer.config = {
    // Options affecting the whole page
    "publicPath": undefined,
    "polyfills": true,

    // Options affecting files only
    "autoplay": "auto",
    "unmuteOverlay": "visible",
    "backgroundColor": null,
    "letterbox": "fullscreen",
    "warnOnUnsupportedContent": true,
    "contextMenu": true,
    "showSwfDownload": false,
    "upgradeToHttps": window.location.protocol === "https:",
    "maxExecutionDuration": {"secs": 15, "nanos": 0},
    "logLevel": "error",
    "base": null,
    "menu": true,
    "salign": "",
    "scale": "showAll",
    "quality": "high",
};

If you use the Ruffle JavaScript API, then it's also possible to specify a per-instance config that will override the global settings:

let player = ruffle.createPlayer();
player.config = {
    autoplay: "auto",
    // and so on...
};

List of Options

publicPath A string, automatically set by Ruffle on initialization to be wherever ruffle.js is included from. This option should only be specified if you encounter issues loading Ruffle. Note that the path must NOT include any file name.

polyfills A boolean, indicating whether Ruffle should detect Flash object and embed tags and replace them with compatible Ruffle elements. If you use the Ruffle JavaScript API, then you probably won't need this.

autoplay A string, indicating how files should start playing. Possible values are:

• "auto": Ruffle checks if the user's browser allows audio autoplay. If it does, then the file is automatically played, otherwise a button is displayed.
• "off": Ruffle always displays a button that the user has to click to actually play the file.
• "on": Ruffle always plays the file, even if the user's browser doesn't allow audio autoplay.

unmuteOverlay A string, only used when autoplay is "on" and the user's browser doesn't allow audio autoplay. Possible values are:

• "visible": Ruffle displays a "Click to unmute" overlay. The user has to click it to resume audio playback.
• "hidden": Ruffle doesn't show an overlay and pretends that everything is fine. Clicking the file area resumes audio playback.

backgroundColor A string, controlling the background color of the player. The value must be an HTML color (e.g. "#FFFFFF"), as CSS colors are not allowed (e.g. "white"). If null is specified, then the background color of the SWF file is used.

letterbox A string, used to indicate how Ruffle should handle areas outside the movie stage. Possible values are:

• "fullscreen": Letterboxing is only done when the file runs in fullscreen mode.
• "off": Letterboxing is disabled, so areas outside the movie stage are always be visible. This matches Flash Player's behavior.
• "on": Letterboxing is enabled when the container's aspect ratio doesn't match the movie's aspect ratio.

warnOnUnsupportedContent A boolean, indicating whether an overlay with a warning message is displayed when loading a movie with unsupported content. At the time of writing, this message applies to movies made with ActionScript 3 (running on AVM2).

contextMenu A boolean, indicating whether a context menu should be shown when right-clicking a Ruffle instance.

showSwfDownload A boolean, indicating whether to show an option in the context menu to download the loaded movie.

upgradeToHttps A boolean, indicating whether inner files should always be loaded over the HTTPS protocol. As this option is designed to prevent cross-domain issues, this means all absolute URLs using the HTTP protocol will be upgraded to HTTPS.

maxExecutionDuration An object, allowing the script timeout to be configured. The object must have the secs and nanos keys, and their values must be an integer.

logLevel A string, indicating the logging level inside the browser's console. Possible values are: "error", "warn", "info", "debug" and "trace".

base A string, default null, which specifies the base directory or URL used to resolve all relative path statements in the SWF file. Helpful when your SWF file is kept in a different directory from your other files.

menu A boolean, default true, which specifies if movie playback controls are available in the context menu.

salign A string with a default value of "". This controls the position of the movie after scaling to fill the viewport and crops it as needed. The default alignment is centered. T, L, B, and R mean top, left, bottom, and right respectively. Can technically be any number of T's, L's, B's, and R's in any order, but the logical choices are "", "T", "L", "B", "R", "TL"/"LT", "TR"/"RT", "BL"/"LB", or "BR"/"RB". If you use some strange combination with both T's and B's or both L's and R's, keep in mind the precedence is L > R > "" and T > B > "".

scale A string with a default value of "showAll". The options are:

• "showAll": Makes the entire SWF file visible in the specified area without distortion, while maintaining the original aspect ratio of the movie. Borders can appear on two sides of the movie.
• "noborder": Scales the SWF file to fill the specified area, while maintaining the original aspect ratio of the file. The content may be cropped, but no distortion occurs.
• "exactfit": Makes the entire SWF file visible in the specified area without trying to preserve the original aspect ratio. Distortion can occur.
• "noscale": Prevents the SWF file from scaling to fit the area of the player. Cropping can occur.

quality A string with a default value of "high". Does nothing in Ruffle currently but can still be set and may do something in the future. The main options are "low", "medium", "high", and "best".

Configure WebAssembly MIME Type

For best performance, your webserver should serve any .wasm files with application/wasm, and sadly not all do by default. If you encounter the error WebAssembly.instantiateStreaming failed because your server does not serve wasm with application/wasm MIME type., then your webserver is not properly configured.

Apache

Apache doesn't serve these files correctly by default, you will need to add this to your httpd.conf configuration file and reload it:

AddType application/wasm .wasm

If you do not have access to the server's httpd.conf or don't want this change to apply to your entire server, you can instead add the line to a .htaccess file on the path where Ruffle's files are located.

For more information please consult the Apache documentation.

NGINX

NGINX doesn't serve these files correctly by default, you will need to add this to your configuration and reload it:

types { application/wasm wasm; }

For more information please consult the NGINX documentation.

LiteSpeed

Follow these steps: Web Admin Console → Server → General → General Settings → MIME Settings → click “mime.properties” → Add → Enter 'wasm' and 'application/wasm' → Save.

Other HTTP Servers

Check to see if Ruffle works without any configuration changes. If you encounter the Incorrect response MIME type. Expected 'application/wasm' error then please do the following:

• Consult the documentation of your server software to see how to add custom MIME types. You want to set .wasm files to application/wasm.
• Inform us over at issue #400 with your HTTP server software name & version, so we can amend this documentation and help future users.

Configure Content Security Policy

If your website uses a Content Security Policy, then you must ensure that the script-src directive includes 'unsafe-eval'. Ruffle uses WebAssembly, and without script-src: 'unsafe-eval', Chrome will not allow WebAssembly compilation.

Addressing a CompileError

A CompileError occurs when Ruffle is unable to properly load the WebAssembly .wasm file that it uses to run Flash content. If you run into this error, it means you or the website administrator have not properly setup Ruffle, or the WebAssembly file became corrupted.

1. If you are the website administrator: You can update your deployment of Ruffle. Ensure that you keep all the files needed to run Ruffle and that you do not rename them. If you are using file transferring software, ensure you know how to upload files in binary mode and that you are doing so for the .wasm file.

2. If you are a website user: You can install the latest Ruffle browser extension for your browser from Ruffle's downloads and follow the usage instructions to add it to your browser. The newest version of Ruffle will take precedence, so your version of Ruffle will likely circumvent the website's version.