RAV Documentation

Getting Started

Installation

RAV is available as a desktop application for macOS (Apple Silicon and Intel) and Windows. Download the latest release from the downloads section or from GitHub Releases.

macOS

1. Download the .dmg file for your architecture (Apple Silicon or Intel)
2. Open the DMG and drag RAV to your Applications folder
3. On first launch, right-click the app and select "Open" to bypass Gatekeeper
4. RAV registers as the default handler for .riv files — you can double-click any .riv file to open it directly

Windows

1. Download the .msi installer
2. Run the installer and follow the setup wizard
3. RAV will be available from the Start menu

Browser Mode

RAV can also run as a local web server for quick inspection without installing:

git clone https://github.com/ivg-design/rive-animation-viewer.git
cd rive-animation-viewer
npm install
npm start  # Opens browser at http://localhost:1420

Opening Files

Drag and Drop

Drag any .riv file onto the RAV window to load it. The animation begins playing immediately using the default playback target (or your configured state machine / animation).

File Dialog

Click the file input area in the toolbar to browse your filesystem and select a .riv file.

Double-Click (Desktop)

On macOS, RAV registers as a handler for .riv files. Double-click any .riv file in Finder to open it directly in RAV. If RAV is already running, the file is loaded into the existing window. On Windows, right-click a .riv file and choose "Open with" to associate RAV with the file type.

Supported Formats

RAV supports Rive runtime files (.riv). These are the compiled binary output from the Rive Editor. Source .rev project files cannot be opened directly.

UI Layout

RAV uses a three-panel layout optimized for animation inspection:

In 2.0.2, the default startup state was tightened so the right properties panel opens by default while the editor and console stay closed until you explicitly open them.

Left Panel — Animation Canvas

The primary animation viewport. Renders the loaded Rive animation with the selected renderer (Canvas or WebGL2). Fit and alignment are controlled from the main toolbar so you can change composition without opening a secondary settings panel.

Top Toolbar

The top toolbar is split into three working clusters:

• Left — app identity and the bright green OPEN button for file loading
• Center — reset, play, pause, renderer, fit, alignment, and FPS status
• Right — EXPORT, Settings, and the MCP Setup dialog

Renderer selection now lives in the central controls cluster next to playback and layout controls, not beside the file-open action.

Right Panel — Controls

Contains ViewModel controls, state machine inputs, and playback settings. The panel is resizable by dragging the divider and can be collapsed entirely. Controls are organized in collapsible sections:

• ViewModel inputs — auto-discovered from the loaded animation
• State machine inputs — legacy number, boolean, and trigger controls
• Player settings — renderer, layout, runtime semver, background color

Bottom Panel — Event Console

Collapsible transcript panel with two modes: Event Console and JavaScript Console. Both modes are resizable, timestamped, newest-first, and expose a sticky FOLLOWcontrol that keeps the latest message pinned in view.

The console action row now uses outlined icon buttons for FOLLOW,COPY, and CLEAR so both console modes share the same visual language and behavior.

Runtime Strip

When the console is closed, only the runtime strip remains visible. It shows the MCP indicator, console state, runtime version, loaded file, update status, and refresh state. The console chip cycles between closed, event console, and JS console.

Code Editor Panel

An optional panel (toggled from the toolbar) with a CodeMirror 6 editor for writing JavaScript configuration objects. Useful for advanced initialization options, custom callbacks, artboard/state machine selection, and live runtime re-instantiation.

The EDITOR title block is also the live-source indicator. A faint neutral outline means RAV's internal wiring is driving the runtime. When the applied editor config is live, that same title block switches to green and its status dot pulses. The yellow outlined APPLY button promotes the current editor code to the active runtime configuration.

ViewModel Controls

RAV automatically discovers ViewModel inputs from loaded animations and renders them as native controls in the right panel.

Supported Input Types

Nested ViewModels

When a ViewModel contains nested ViewModel properties, RAV renders them as collapsible sections with indentation. The root ViewModel starts expanded, nested ViewModels start collapsed. Click the section header to expand or collapse.

Live Sync

ViewModel controls continuously sync with the runtime. If a value is changed by the animation logic (e.g., a listener or state change), the control UI updates automatically. Active focused inputs are skipped during sync to avoid disrupting user edits.

Value Persistence

When you reset/restart an animation, RAV captures the current values of all ViewModel and state machine properties and restores them after reload. Trigger inputs are excluded from persistence since they are one-shot actions.

Artboard Switcher

RAV can display any artboard in a .riv file and switch between them without reloading the file. The Artboard / Animation control section appears in the Properties panel when a file is loaded.

Artboard Dropdown

Lists every artboard in the loaded file. Selecting a different artboard tears down the current Rive instance and creates a new one for the chosen artboard. Playback starts automatically.

Playback Dropdown

Shows the exact authored state machine and timeline animation names available on the selected artboard. Labels preserve original capitalization and formatting. Selecting a different playback target reloads the artboard with that target. State machines are listed first, but the viewer no longer rewrites names with visible prefixes.

VM Instance Selector

When the selected artboard's ViewModel definition has multiple named instances, an additional VM Instance dropdown appears. Selecting a different instance binds it to the runtime and re-renders the ViewModel controls with that instance's values. This is useful for inspecting per-instance data such as card variants or color presets.

Reset to Default

The DEFAULT button returns to the artboard and state machine that were detected when the file was first loaded. This is the quickest way to get back to the primary artboard after exploring other artboards or animations.

ViewModel Labels

ViewModel section headers display the exact name from the Rive file, preserving original casing, dashes, and special characters.

Export Behavior

The standalone export always captures the exact artboard, playback target, and ViewModel state currently shown in the viewer. If you are viewing a secondary artboard with a specific animation, the export will embed that configuration.

Event Console

The event console captures and displays events from multiple sources in real time.

Event Sources

Filtering

Each source has an independent toggle button. Click to enable/disable events from that source. Multiple sources can be active simultaneously. A text search field provides additional filtering across all visible events.

Console Actions

The console toolbar places search first, followed by outlined icon actions for:

• FOLLOW — amber toggle that keeps the newest event in view
• COPY — green action that copies the current transcript
• CLEAR — red action that clears the current console transcript

Ordering and Follow Mode

Events are listed newest-first. The FOLLOW toggle keeps the latest entry pinned in view. If you scroll away from the top, follow mode turns off automatically. Scroll back to the latest event or toggle FOLLOW to re-enable it.

Script Console

Script Console mode transforms the bottom panel into a REPL for live JavaScript evaluation against the running animation.

Activating Console Mode

Use the runtime-strip console control to cycle between closed, Event Console, and JavaScript Console. When the JS console is active, the bottom panel shows a command input and output stream while preserving the same transcript styling as the Event Console.

REPL Behavior

The JavaScript console is a true REPL against the live runtime. Commands execute against the current page context, results appear with timestamps in the shared newest-first transcript, and command history is available from the input. The input stays at the bottom of the panel while the transcript above it follows the same ordering and follow-mode semantics as the Event Console.

Consistent Row Chrome

As of 2.0.3, the JavaScript console uses one consistent visual language for every row. REPL commands, REPL results, warnings, errors, and app-generated log lines all render with the same timestamp-and-badge treatment. This keeps the console readable without giving up Eruda's native lazy object inspection for complex runtime objects like riveInst.

Available Globals

window.riveInst    // The active Rive instance
window.canvas      // The animation canvas element
vmExplore()        // Show root VM properties
vmGet("path")      // Get a VM property value
vmSet("path", val) // Set a VM property value
vmTree             // View full VM hierarchy
vmPaths            // List all property paths

Output

The console displays timestamped command, result, warning, info, and error rows. Results are inserted at the top like event entries, and the shared FOLLOW behavior works the same way as in the Event Console.

Filtering and Copy

Level filters and search operate on the visible JavaScript console transcript itself, not a separate hidden logger state. That means command/result rows obey the same filter rules as normal log lines. The COPY action also mirrors exactly what is currently visible on screen, in the same newest-first order.

Transparency Mode

Transparency mode removes the canvas background and window chrome, allowing you to overlay the animation on top of other content.

Enabling Transparency

1. Click the Transparency toggle in player settings
2. The canvas background becomes transparent
3. On desktop, the window background also becomes transparent

Click-Through (Desktop Only)

When transparency mode is active on the desktop app, enable Click Throughto allow mouse events to pass through transparent pixels to the window below. RAV uses continuous cursor-position sync to sample pixel transparency and forward clicks when the cursor is over a fully transparent area.

Background Reset

Use the No BG button to return the canvas to transparent mode after selecting a solid background color.

Transparency mode is a desktop-only feature. Exported standalone demos disable the transparency toggle to avoid exposing a non-functional control.

Standalone Export

RAV can export self-contained HTML demo files that embed the animation, runtime, and ViewModel controls into a single portable file.

What Gets Exported

• The .riv binary, base64-encoded and embedded
• The selected runtime package (Canvas or WebGL2) bundled inline
• The selected runtime semver baked into the exported file
• The current artboard, playback target, and active live source mode
• Only the checked or changed ViewModel / state-machine values from the export dialog
• ViewModel control UI matching the current hierarchy
• The generated canonical instantiation snippets (`cdn` and `local` variants)
• Current player layout state (panel sizes, visibility, toolbar layout state)
• Complete styling for standalone viewing

Exporting

1. Load and configure your animation in RAV
2. Adjust panels, playback, runtime, and controls to the desired live state
3. Click the Export button in the toolbar
4. Use the Snippet & Export Controls dialog to choose CDN or local-package output and curate which controls should be serialized
5. Copy the generated snippet directly from the dialog if you only need the code
6. Choose a save location for the HTML file if you want a standalone export

Snippet & Export Controls

The export dialog is shared by both in-app snippet generation and standalone export. Branch checkboxes select entire nested ViewModel sections, while individual leaf checkboxes select just one control. The dialog defaults to the changed-control set, but you can switch toSELECT ALL or CLEAR as needed.

Branch expansion state is preserved while you select nested controls, so you can work deeply inside a ViewModel tree without the dialog collapsing back to the root after each checkbox change.

Limitations

• Transparency mode toggle is disabled in exports (desktop-only feature)
• The exported file requires a modern browser that supports the selected runtime (WebGL2 exports require WebGL2)
• File size depends on the embedded .riv animation size

Configuration

Code Editor

The code editor panel accepts JavaScript objects (not JSON) for advanced Rive initialization. You can use comments, trailing commas, and unquoted keys:

{
  // Select a specific artboard
  artboard: "MyArtboard",
  stateMachines: ["StateMachine1"],
  autoplay: true,
  layout: {
    fit: "contain",
    alignment: "center"
  },
  onLoad: () => {
    console.log("Animation loaded!");
  }
}

The editor header itself indicates which configuration source is driving the live runtime. A faint neutral outline means RAV's internal wiring is active. A green pulsing state means the applied editor config is live. Unsaved draft edits do not affect playback until applied.

Apply & Reload

The APPLY button in the script editor toolbar takes the JavaScript config object you've written, evaluates it, tears down the current Rive instance, and creates a new one with that configuration. This is how you apply any changes you make in the editor — artboard selection, state machine targeting, autoplay settings, custom callbacks, and layout options. The refresh path preserves the active artboard/playback context and other live state as far as the runtime allows instead of resetting back to defaults.

The config object supports all Rive constructor options including:

• artboard — select a specific artboard by name
• stateMachines — target a state machine (string or array)
• animations — target a timeline animation (string or array)
• autoplay — start playback immediately (default true)
• autoBind — bind ViewModels automatically (default true, required for VM controls)
• layout — set fit and alignment ({ fit: "contain", alignment: "center" })
• useOffscreenRenderer — improves glow/shadow quality for transparent overlays
• onLoad, onPlay, onPause, onStateChange — lifecycle callbacks

Internal vs Editor Live Mode

RAV distinguishes between your editable draft and the live runtime source:

• Internal — the app is using its built-in default instantiation wiring
• Editor — the last applied script editor config is driving the runtime

Draft changes in the editor do nothing until you click APPLY. Exports, generated snippets, and MCP status all reflect the active live mode, not the unsaved editor buffer.

Renderer Selection

Choose between Canvas and WebGL2 renderers. WebGL2 is recommended for vector feathering and complex animations. Canvas provides better compatibility on older hardware.

Runtime Version (Semver) Selection

In Settings, use Runtime Ver to choose which runtime semver to load. RAV provides Latest (auto), the latest 4 concrete versions, and aCustom entry for manual semver input.

• Latest (auto) resolves to a concrete semver before loading
• Custom reveals the version input + Set button (hidden otherwise)
• Selected runtime semver is persisted per file and restored when that file is opened again
• Exported standalone demos embed the currently selected runtime semver

Layout Options

Fit and alignment are surfaced directly in the main toolbar, so the viewer layout is always visible while you work. Those selections are mirrored into generated snippets and exports.

MCP Integration

RAV includes a built-in MCP (Model Context Protocol) sidecar that lets Claude Code , Claude Desktop, Codex, or any MCP client control the viewer remotely — open files, inspect ViewModels, drive playback, manipulate inputs, read event logs, edit scripts, execute JS, generate web snippets, and export demos.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI tools like Claude Code connect to external applications. With RAV's MCP server, Claude can open your .riv files, inspect their structure, drive playback, modify ViewModel values, and export demos — all through natural language commands.

How it works

RAV includes a bundled native rav-mcp sidecar that acts as a bridge between your MCP client and the RAV desktop app. When both are running, the client can control RAV remotely:

MCP Client <-(stdio)-> rav-mcp sidecar <-(WebSocket)-> RAV App

The RAV app starts its bridge automatically when it launches. The MCP dialog reportsMCP ready when the bundled sidecar path and bridge are healthy, and the runtime-strip MCP indicator brightens when a client is actively connected.

Setup (one-time)

The desktop app ships with the MCP sidecar already bundled inside the app resources. Open the in-app MCP Setup dialog to copy the exact path, detect supported clients, and use one-click installation where available.

1. Open the MCP Setup dialog from the toolbar cable icon.
2. Install for your client using the dialog's one-click buttons for Codex, Claude Code, or Claude Desktop when those clients are detected. Existing installs show REINSTALL and REMOVE.
3. Choose the bridge port and Script Access mode if you want something other than the default read-only MCP on port 9274.
4. Or copy a snippet manually:

   claude mcp add-json -s user rav-mcp '{"type":"stdio","command":"/Applications/Rive Animation Viewer.app/Contents/Resources/resources/rav-mcp","args":["--stdio-only","--port","9274"]}'

5. Open RAV — launch the desktop app. The MCP indicator in the runtime strip turns indigo when a client connection is established.

That's it. From now on, whenever both RAV and Claude Code are running, Claude can control the viewer. Try asking Claude: "Open my animation file in RAV and show me the ViewModel tree."

MCP Setup Dialog

• Status row — simplified to MCP ready or MCP disabled
• Server path — the exact bundled rav-mcp binary path used for snippets
• Script Access — explicit safety gate for JS execution tools
• MCP Port — editable bridge port with immediate snippet regeneration
• Client detection — checks whether supported clients are installed and whether the RAV MCP entry is already present in their config
• Install actions — shows ADD, REINSTALL, or REMOVE based on the actual detected state

Available Tools (30)

Instantiation and Export Semantics

• rav_status reports whether the live runtime is using internal wiring or the applied editor config
• rav_apply_code switches the live runtime to the last applied editor config
• generate_web_instantiation_code always mirrors what is actually running, not the unsaved draft buffer
• generate_web_instantiation_code defaults to the CDN form unless you explicitly request package_source: "local"
• Generated snippets restore only the checked ViewModel/state-machine values on load, round numbers to 2 decimals, and expose helper methods on window.ravRive
• The Snippet & Export Controls dialog lets you choose exactly which values are serialized; if you never touch it, RAV defaults to the changed-control set
• Exported demos mirror the active live mode, surface fit/alignment in the main toolbar, and expose a Copy Instantiation Code toolbar button

Script Access

By default, MCP can read state and drive safe control operations. If you want an agent to run JavaScript or apply editor code, enable Script Access in the MCP Setup dialog. That unlocks rav_eval, rav_console_exec, andrav_apply_code.

Event Console

All MCP commands, responses, and connection events appear in the event console with the MCP source tag (indigo). Messages are formatted as human-readable summaries with elapsed time — no raw JSON. Use the MCP filter toggle to show or hide MCP traffic.

Connection Indicator

The runtime strip shows an MCP chip with a status dot. Connected is bright indigo. Disconnected is dim but still visible. Disabled is red with a strike-through.

The MCP Setup dialog now opens immediately and performs its install-state checks in the background so detection of Codex, Claude Code, and Claude Desktop no longer blocks the modal.

Configuration

For normal use, the MCP surface is configured from the MCP Setup dialog inside the app. The only user-facing setting exposed there is the bridge port. Internal timeout and watchdog settings exist, but they are implementation details and are not part of the public UI contract.

Automatic Updates

Desktop builds include Tauri's updater plugin. On launch, RAV checks the configured GitHub Releases feed in the background. If a newer signed release is available, the runtime strip exposes an update chip.

As of the 2.0.1 release path, the published updater feed is merged across all supported desktop targets. One latest.json now carries Apple Silicon, Intel macOS, and Windows updater entries together, so the updater no longer depends on whichever platform job published last.

Update Chip States

• Hidden — no update is available
• UPDATE <version> — a newer version is ready to install
• UPDATING <version> — the update archive is downloading and installing
• RESTARTING — the update is installed and the app is relaunching
• UPDATE RETRY — the last check or install failed and can be retried

How Installation Works

Clicking the update chip downloads the signed updater artifact for your platform, installs it, and relaunches the app. Release builds publish updater archives and signatures alongside the normal desktop installers.

This flow was validated against the installed app itself: a local 2.0.0 build placed in /Applications successfully updated to 2.0.1, relaunched, and then reported that no newer update was available.

Release Feed Semantics

The updater only surfaces a new version after the full multi-platform release finishes and the final merged latest.json feed is published. A partially complete GitHub release is not enough for the in-app updater to advance.

Keyboard Shortcuts

RAV is still primarily a pointer-driven desktop tool. The current build does not ship global playback shortcuts for play, pause, reset, fullscreen, or DevTools. The available keybindings are contextual and tied to the control that has focus.

Troubleshooting

Animation won't load

• Verify the file is a valid .riv file (not a .rev project file)
• Check the event console for error messages
• Try switching between Canvas and WebGL2 renderers
• Ensure the file isn't corrupted — try opening it in the Rive Editor first

Configuration won't apply

• Ensure you're writing valid JavaScript syntax (not JSON)
• Check the red error banner for syntax error details
• Errors auto-dismiss after 5 seconds; check the console for persistent errors

ViewModel controls missing

• The animation must have ViewModelInstances defined in the Rive Editor
• Check that autoBind: true is set (default behavior)
• Try reloading the animation

Desktop build fails

• Run rustup update to ensure latest Rust toolchain
• Check npm run tauri info for missing dependencies
• On macOS, verify Xcode Command Line Tools are installed

MCP not connecting

• Verify the MCP server is registered: claude mcp list or codex mcp list
• Check that RAV is running and the browser console shows [rav-mcp-bridge] Connected
• Ensure port 9274 is available (or set RAV_MCP_PORT to a different port)
• The bridge auto-reconnects with exponential backoff — if the MCP server started after RAV, wait a few seconds

CSP Warnings (Desktop)

The desktop app may show harmless CSP warnings about blob:// URLs in the console. These are WebKit quirks and do not affect functionality.

Getting Help

If you encounter an issue not covered here, open an issue on GitHub with your OS version, RAV version, and the .riv file if possible.