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:8080

Opening Files

Drag and Drop

Drag any .riv file onto the RAV window to load it. The animation begins playing immediately with the first available state machine.

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:

Left Panel — Animation Canvas

The primary animation viewport. Renders the loaded Rive animation with the selected renderer (Canvas or WebGL2). The canvas resizes automatically when panels are toggled or resized.

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, background color

Bottom Panel — Event Console

Collapsible event log with filtering and search. Shows Rive events, state changes, and UI events in real time. Can be resized by dragging the top edge.

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, and artboard/state machine selection.

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.

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.

Event Details

Each event entry shows a timestamp, source tag, event name, and a collapsible details section with the full event payload (properties, data values). Click an event row to expand its details.

Script Console

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

Activating Console Mode

Toggle the console mode button in the Script Editor toolbar. When active, the event console body is replaced with a command input and output stream. You can type JavaScript expressions and see results immediately.

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 command/result/error rows. Runtime and UI events are also mirrored into the console output stream so you can observe side effects of your commands.

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 Rive WebGL2 runtime, bundled inline
• ViewModel control UI matching the current hierarchy
• Current player layout state (panel sizes, visibility, event console state)
• Complete styling for standalone viewing

Exporting

1. Load and configure your animation in RAV
2. Adjust panels and controls to the desired layout
3. Click the Export button in the toolbar
4. Choose a save location for the HTML file

Limitations

• Transparency mode toggle is disabled in exports (desktop-only feature)
• The exported file requires a modern browser with WebGL2 support
• 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!");
  }
}

Renderer Selection

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

Layout Options

Keyboard Shortcuts

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

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.