RWPP Documentation

Everything you need to know about Rive Wallpaper Player for macOS. Transform your desktop with beautiful animated wallpapers.

Quick Start

1. Install

Open the DMG, drag RWPP to Applications, and launch it.

2. Load Animation

Click the menu bar icon, select "Add Animation...", and choose a .riv file.

3. Enjoy!

Your desktop is now animated. Use the gallery to save favorites.

Need .riv files? Get free animations from the Rive Community

System Requirements

Minimum

Recommended

Installation

From DMG (Recommended)

1. Download RWPP.dmg from your email link
2. Double-click to mount the disk image
3. Drag RWPP.app to the Applications folder
4. Eject the disk image
5. Launch RWPP from Applications

First Launch Security

Since RWPP is not notarized with Apple, macOS will show a security warning on first launch.

To open:

1. Go to System Settings → Privacy & Security
2. Scroll down to find the blocked app message
3. Click "Open Anyway"

Features

Animated Wallpaper

Rive animations render behind your desktop icons using GPU-accelerated Metal rendering for smooth 60fps playback.

Multi-Display

Automatically detects all connected displays. Same animation plays across all screens seamlessly.

Gallery

Save and organize your favorite animations. Files are copied to internal storage - moving or deleting the original won't break your wallpaper.

Persistence

Remembers your last animation, gallery contents, control settings, and preferences. Optionally launches at login.

Dynamic ViewModel Controls

If your Rive file includes a ViewModel with specially-named properties, RWPP displays controls to adjust them in real-time.

Multi-Artboard Support

RWPP automatically selects the correct artboard based on screen orientation (landscape/portrait).

Combined Mode

Span a single animation seamlessly across all monitors with the "combined" artboard.

Animation Controls

Control animation parameters directly from RWPP without editing the Rive file.

Available Control Types

Sync & Reset

• Sync - Copy values from current artboard to all others
• Reset - Restore original default values

Values are automatically persisted and restored on next launch.

Creating Compatible Rive Files

To take full advantage of RWPP features, structure your Rive files as follows:

Example Project: The Hex Background animation available for download on this page demonstrates all RWPP features - it includes landscape, portrait, and combined artboards with ViewModel controls. Download the .rev project file to see exactly how to structure your own animations.

Artboard Setup

Include artboards for different screen orientations:

Important: All artboards except the default must be converted to components in Rive for RWPP to detect them. The default artboard works regardless.

Artboard Fallback Behavior

RWPP handles missing artboards gracefully:

ViewModel Property Naming

To expose controls in RWPP, name your ViewModel properties with this syntax:

rwpp[Type]-[parameters]-[Label_With_Underscores]

Label Formatting:

• Use underscores for spaces: Background_Color → "Background Color"
• Hyphens separate syntax parts

ViewModel Instances

Create ViewModel instances for each artboard:

Settings

Frame Rate Settings

RWPP v1.3.2 introduces configurable frame rate limiting to optimize performance:

Why 30 FPS is recommended for laptops:

• Wallpapers don't need high frame rates - you're not interacting with them
• At 30 FPS, Luau scripts execute half as often, significantly reducing CPU load
• The visual difference is imperceptible for background wallpapers
• Battery life improves noticeably on MacBooks

Combined Mode Requirements

1. Go to System Settings → Desktop & Dock
2. Disable "Displays have separate Spaces"
3. Log out and log back in
4. Your Rive file must include a combined artboard

Keyboard Shortcuts

FAQ

What are .riv files?

.riv files are animation files created with Rive, a design tool for creating interactive animations. They contain vector graphics and animation data that can be rendered in real-time.

Where can I get .riv files?

• Rive Community: rive.app/community - Free community animations
• Create your own: rive.app - Free editor to create animations

Does RWPP affect performance?

RWPP is optimized for efficiency with configurable performance settings:

Simple animations (no Luau scripts):

• CPU: 2-5% (single core)
• Memory: 80-120 MB
• GPU: 5-15%
• Energy Impact: Very Low

Complex animations (with Luau procedural drawing):

• CPU: 15-50% at 30 FPS, up to 97% at unlimited
• Memory: 140-200 MB
• GPU: 20-40%
• Energy Impact: Low (30 FPS) to High (unlimited)

Performance Tips:

• Use 30 FPS setting for script-heavy animations
• Simpler vector animations use less CPU than procedural ones
• GPU (Metal) handles rendering efficiently on all Apple Silicon Macs

Will RWPP drain my battery?

Battery impact depends on your settings and animation complexity:

Battery Optimization Tips:

• Use 30 FPS setting when on battery (Settings → Performance)
• Choose simpler animations without heavy Luau scripting
• Dark backgrounds save power on OLED displays (future MacBooks)
• Pause animation when presenting or in meetings

Can I use different animations on different displays?

Currently, RWPP plays the same animation on all displays. Multi-animation support may be added in a future update.

Is RWPP safe?

Yes. RWPP:

• Doesn't collect any user data
• Only accesses files you explicitly select
• Uses standard macOS security (sandboxed file access)
• No network requests except for update checks

Troubleshooting

App Won't Launch

Symptom: Double-clicking RWPP does nothing or shows security warning.

Solution:

1. Go to System Settings → Privacy & Security
2. Look for message about RWPP being blocked
3. Click "Open Anyway"

Animation Doesn't Play

Symptom: File loads but nothing appears on desktop.

Solutions:

• Verify the .riv file works in Rive editor
• Check that file isn't corrupted (try re-downloading)
• Restart RWPP and try again

No Thumbnails in Gallery

Symptom: Gallery shows placeholder icons instead of thumbnails.

Solution: Grant Screen Recording permission:

1. Go to System Settings → Privacy & Security → Screen Recording
2. Enable RWPP (may need to add it via the + button)
3. Load the animation again to regenerate thumbnail

High CPU Usage

Symptom: CPU usage above 30% constantly.

Solutions:

• This is normal for complex animations
• Try a simpler animation with fewer elements
• Animations with particles use more CPU

Animation Controls Not Showing

Symptom: "Animation Controls" menu item doesn't appear.

Solution: Your Rive file needs ViewModel properties with rwpp prefix. See "Creating Compatible Rive Files" section.

Technical Information

Architecture

File Locations

Resource Usage

Simple Animations (vectors, no scripts):

Complex Animations (Luau procedural drawing):

Performance by Mac Model

RWPP performance scales with Apple Silicon generation. Here are extrapolated benchmarks for a complex Luau animation:

Notes:

• Percentages are of total CPU capacity (not single core)
• Newer chips have more efficient cores and better thermal management
• MacBook Air models throttle under sustained load; Pro models maintain performance
• Desktop Macs (Mac Mini, Mac Studio, Mac Pro) can run unlimited FPS with minimal impact

Screen Resolution Impact

Higher resolution displays require more GPU work but have minimal CPU impact:

Tips for High-Resolution Displays:

• GPU handles resolution scaling efficiently on Apple Silicon
• CPU usage is determined by animation complexity, not resolution
• Combined mode on multiple 5K displays works smoothly on M1 Pro or newer

Getting Rive Animations

Rive Community

The Rive Community is the best place to find free, high-quality animations. Browse thousands of community-created animations and download them directly as .riv files.

Creating Your Own

Rive offers a free editor to create your own animations:

1. Sign up for a free account at rive.app
2. Create a new file and design your animation
3. Export as .riv file
4. Load into RWPP

Tips for Wallpaper Animations

• Keep it subtle - Busy animations can be distracting while working
• Use loops - Ensure your animation loops seamlessly
• Consider colors - Dark backgrounds work well and save battery on OLED displays
• Test performance - Complex animations with many layers may impact CPU usage
• Add RWPP controls - Use ViewModel properties with rwpp prefix for user customization

Privacy & Security

RWPP respects your privacy:

• No telemetry - We don't collect any usage data
• No network requests - The app works completely offline
• Local storage only - Your gallery and settings are stored locally on your Mac
• Sandboxed - Uses macOS security for safe file access

Support

Reporting Issues

If you encounter bugs or have feature requests, please reach out via the landing page contact form.

Known Limitations

• Intel Macs are not supported (Apple Silicon required for Rive Renderer)
• Same animation plays on all displays (per-display animations planned)
• No video file support (Rive .riv files only)

Roadmap

Features under consideration for future releases:

• Different animations per display
• Animation scheduling (day/night themes)
• Keyboard shortcuts for quick control
• Animation speed control
• Battery-aware auto-pause

Recently Implemented (v1.3.2)

• ✅ Frame rate limiting (30/60/Unlimited FPS) for battery optimization
• ✅ Performance settings section in Settings panel
• ✅ Mode change crash fix (combined ↔ per-screen)
• ✅ Gallery sandbox path migration

Recently Implemented (v1.3.0)

• ✅ Dynamic ViewModel controls (color, toggle, slider, picker, number)
• ✅ Multi-artboard support with auto-orientation detection
• ✅ Combined mode for multi-monitor spanning
• ✅ Internal animation storage (files persist if originals moved)
• ✅ Control sync between artboards
• ✅ Persistent control values across restarts