MStudio Sync — After Effects Plugin

Bidirectional sync between MStudio and Adobe After Effects. Edit storyboards in AE with full compositing power, then sync changes back to the web platform.

Requirements

• Adobe After Effects 2024 or later (v24.0+)
• Node.js 18+ (for building from source)
• An MStudio account with an API key that has sync scope

Installation

Option 1: Standalone Executable (Easiest)

Download the installer for your platform from the latest release, then:

macOS:

chmod +x install-darwin-arm64   # or install-darwin-x64 for Intel Macs
./install-darwin-arm64

Windows:

.\install-windows-x64.exe

No Node.js, npm, or build tools required. The executable handles everything.

Option 2: From Source

macOS / Linux:

git clone https://github.com/ModelsLab/mstudio-AE-plugin.git
cd mstudio-AE-plugin
./install.sh

Windows (PowerShell as Administrator):

git clone https://github.com/ModelsLab/mstudio-AE-plugin.git
cd mstudio-AE-plugin
.\install.ps1

Or using npm (any platform):

git clone https://github.com/ModelsLab/mstudio-AE-plugin.git
cd mstudio-AE-plugin
npm run install-plugin

The install script will:

1. Build the plugin from source
2. Enable CEP debug mode (allows unsigned extensions)
3. Copy CSInterface.js from your AE installation
4. Symlink the plugin into Adobe's CEP extensions directory
5. Verify the installation

Then restart After Effects and open Window → Extensions → MStudio Sync.

Build Standalone Executables

To compile installers for all platforms (requires Bun):

bun run build-bin

This creates executables in dist-bin/ for macOS (ARM64, x64) and Windows (x64).

Uninstall

Standalone executable: Run the uninstall binary for your platform.

From source:

• macOS/Linux: ./uninstall.sh
• Windows: .\uninstall.ps1
• npm: npm run uninstall-plugin

Prerequisites

Before installing, enable script access in After Effects:

1. Open Edit → Preferences → Scripting & Expressions (Windows) or After Effects → Settings → Scripting & Expressions (macOS)
2. Enable Allow Scripts to Write Files and Access Network

From Source (Development)

npm install
npm run build
npm run install-plugin

For live development with auto-rebuild:

npm run dev

Setup

1. Get Your API Key

1. Log in to MStudio
2. Go to Settings > API Keys
3. Create a new API key with the sync scope enabled
4. Copy the key (starts with sk_live_)

2. Connect the Plugin

1. Open the MStudio Sync panel in After Effects
2. Click the Settings tab (gear icon)
3. Paste your API key into the API Key field
4. Click Test Connection — you should see a green "Connected" status
5. Optionally configure:
   • API Base URL — only change if using a self-hosted instance
   • Auto Sync — automatically poll for changes (default: off, interval: 30s)
   • Conflict Resolution — how to handle simultaneous edits (manual / keep server / keep local)
   • Render Before Push — render AE edits to video before uploading (default: on)

3. Select a Project

1. Switch to the Projects tab
2. Browse your MStudio projects
3. Click a project to select it for sync

Usage

Initial Sync (Pull)

Click Full Sync to pull the entire project from MStudio:

• Creates an AE composition matching the project resolution
• Downloads all frame images/videos and imports them as footage
• Places each frame as a layer with composition markers defining boundaries
• Downloads and places all audio tracks with correct timing

Incremental Sync

Click Sync Now for a delta sync:

1. Pull — downloads only frames/audio changed since your last sync
2. Push — detects your local AE edits and uploads them back to MStudio
3. Conflicts — if both sides changed the same frame, a resolution dialog appears

Editing in AE

• Edit layers within frame marker boundaries — changes are tracked via checksums
• Add effects, compositing, color grading — when you sync, the frame region is rendered to video and uploaded
• Add/modify audio layers — volume, timing, and trim changes sync back
• Composition markers define frame boundaries — don't delete them

Conflict Resolution

When both AE and MStudio edit the same frame:

• Keep Server — discard your local changes, use the web version
• Keep Local — push your AE version to the server, overwriting web changes
• Manual — review both versions side-by-side and choose per-frame

Project Structure

src/
  core/           # API client, config, logging
  ae/             # AE scripting layer (comp reader/writer, layer mappers)
  sync/           # Sync engine, state management, conflict resolution
  ui/             # Panel UI (settings, project selector, sync panel)
  types/          # TypeScript type definitions
  storage/        # localStorage wrapper
manifest.json     # UXP plugin manifest

Sync Architecture

• Checksum-based change detection — SHA-256 hashes on frame data, audio parameters, and file content
• Version tracking — monotonically incrementing sync_version per project
• Delta manifests — only transfer what changed since last sync
• Advisory locking — prevents concurrent sync conflicts (10-min TTL with auto-renewal)
• Batch operations — create/update/delete multiple frames or audio tracks in one API call

API Endpoints Used

All under /api/v1/projects/{uuid}/sync/:

Method	Path	Purpose
GET	/manifest	Full or delta project manifest
POST	/frames/batch	Batch frame create/update/delete
POST	/audio-tracks/batch	Batch audio track operations
POST	/assets/batch-urls	Generate signed download URLs
POST	/lock	Acquire sync lock
PUT	/lock	Renew sync lock
DELETE	/lock	Release sync lock
GET	/status	Current sync version and lock info

Troubleshooting

Plugin won't load: Ensure AE is version 24.0+ and CEP PlayerDebugMode is enabled (the install script does this automatically). Check the AE console for errors (Help → Enable Console).

Connection failed: Verify your API key has the sync scope. Check that your subscription is active.

Sync stuck: If a sync operation hangs, the lock will auto-expire after 10 minutes. You can also manually release it from the sync panel.

Missing frames after sync: Check that composition markers haven't been deleted. The plugin uses markers to define frame boundaries.

Audio out of sync: Ensure your AE comp frame rate matches the project settings. The plugin converts between AE seconds and MStudio milliseconds.

Development

npm run dev              # Watch mode — rebuilds on file changes
npm run build            # One-time production build
npm run install-plugin   # Rebuild + reinstall into CEP extensions
npm run uninstall-plugin # Remove plugin from CEP extensions
npm run clean            # Remove dist/ directory
bun run build-bin        # Build standalone installers for macOS/Windows
bun run install-bin      # Run installer via Bun (development)
bun run uninstall-bin    # Run uninstaller via Bun (development)

After code changes, run npm run install-plugin and restart AE to pick up changes.

License

Proprietary — ModelsLab, Inc.