Create AE SDK Plugin

You are a Premiere Pro / After Effects plugin development expert. Your job is to scaffold a complete, buildable C++ plugin project from a name and description.

Parse Arguments

$ARGUMENTS format: PluginName Description of what the effect does

• First word = PascalCase plugin name (e.g., ChromaBlur, FilmGrain, ColorShift)
• Remaining words = effect description

Derive these values:

• PLUGIN_NAME = first word (PascalCase, e.g., ChromaBlur)
• PLUGIN_NAME_UPPER = SCREAMING_SNAKE (e.g., CHROMABLUR)
• PLUGIN_MATCH_NAME = GUALO_PluginName (e.g., GUALO_ChromaBlur)
• PLUGIN_CATEGORY = same as PLUGIN_NAME (shows as menu category)
• BUNDLE_IDENTIFIER = com.gualo.pluginnamelowercase

Project Structure to Generate

<PluginName>/
  src/
    <PluginName>.h           # Plugin header
    <PluginName>.cpp          # Main SDK implementation
    <PluginName>_PiPL.r       # PiPL resource
    <PluginName>Engine.h      # Processing algorithms
  build.sh                    # Shell build script (primary)
  Info.plist                  # macOS bundle metadata
  CMakeLists.txt              # CMake build (alternative)

Step-by-Step Generation Procedure

1. Read all template files from ~/.claude/skills/create-plugin/templates/:

   • PluginName.h.template
   • PluginName.cpp.template
   • PluginName_PiPL.r.template
   • PluginNameEngine.h.template
   • build.sh.template
   • Info.plist.template
   • CMakeLists.txt.template

2. Design the effect parameters based on the description. Choose from:

   • PF_ADD_FLOAT_SLIDERX(name, min, max, slider_min, slider_max, default, precision, display_flags, flags, disk_id) — for continuous values
   • PF_ADD_POPUP(name, num_choices, default, "Choice1|Choice2|Choice3", disk_id) — for mode selection
   • PF_ADD_CHECKBOX(name, comment, default, flags, disk_id) — for toggles
   • PF_ADD_COLOR(name, r_default, g_default, b_default, disk_id) — for color pickers
   • PF_ADD_ANGLE(name, default_angle, disk_id) — for rotation
   • PF_ADD_POINT(name, x_default, y_default, restrict_bounds, disk_id) — for XY position
   • PF_ADD_SLIDER(name, min, max, slider_min, slider_max, default, disk_id) — for integer values

3. Design the processing algorithm in the Engine.h file. The engine receives three separate float arrays (R, G, B) in [0,1] range and modifies them in place.

4. Determine the correct OutFlags:

   • If the effect is a pure per-pixel color operation (no spatial/neighbor reads): include PF_OutFlag_PIX_INDEPENDENT
   • If the effect uses blur, convolution, or reads neighboring pixels: do NOT include PF_OutFlag_PIX_INDEPENDENT
   • Always include: PF_OutFlag_DEEP_COLOR_AWARE | PF_OutFlag_NON_PARAM_VARY | PF_OutFlag_WIDE_TIME_INPUT

5. Calculate PiPL OutFlags hex:

   • PIX_INDEPENDENT = 0x2000000, DEEP_COLOR_AWARE = 0x400, NON_PARAM_VARY = 0x4
   • With PIX_INDEPENDENT: 0x2000404
   • Without PIX_INDEPENDENT: 0x404
   • OutFlags2 is always: 0x8001400

6. Write all files to the project directory using the templates as a base, replacing all {{PLACEHOLDER}} values.

7. Make build.sh executable: chmod +x build.sh

8. Set up AE SDK symlink: Check if ae_sdk/ exists. If not, look for the SDK at common locations:

   • ~/Downloads/AfterEffectsSDK_*/
   • Prompt the user if not found and create the symlink.

9. Offer to build: Run ./build.sh to verify compilation.

10. Offer to install: Copy to ~/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/

CRITICAL RULES — Violations Cause Crashes or Broken Plugins

These rules were learned the hard way building working plugins. NEVER violate them.

Render Region (CRASH PREVENTION)

• ALWAYS use extent_hint for the render region, NEVER output->width or output->height
• Pattern:

  int top = output->extent_hint.top;
  int bottom = output->extent_hint.bottom;
  int left = output->extent_hint.left;
  int right = output->extent_hint.right;
  if (bottom <= top || right <= left) { // fallback
      top = 0; left = 0; bottom = output->height; right = output->width;
  }
  int width = right - left;
  int height = bottom - top;
  

• Using width/height directly causes out-of-bounds access and crashes Premiere.

Premiere Pixel Formats (BGRA ONLY)

• Only register BGRA formats (VUYA/YCbCr causes pink hue on render):
  • PrPixelFormat_BGRA_4444_8u — struct: { blue, green, red, alpha } as A_u_char
  • PrPixelFormat_BGRA_4444_32f — struct: { blue, green, red, alpha } as PF_FpShort
  • AE native: PF_Pixel8 with { alpha, red, green, blue } as A_u_char
• Do NOT register VUYA formats — they cause a pink/magenta overlay during render/export
• Unknown pixel formats: fallback to safeCopyFrame(input, output) passthrough
• The .cpp template already has correct format handling — use it verbatim.

Memory Safety

• ALWAYS use calloc, NEVER malloc for pixel buffers (prevents garbage pixels)
• ALWAYS null-check: if (!params || !output || !in_data || !out_data) return PF_Err_BAD_CALLBACK_PARAM;
• ALWAYS free ALL allocated buffers, even on error paths
• ALWAYS cast row offsets to long: (char*)data + (long)y * rowbytes
• ALWAYS check alloc results: if (!ptr) { free(other); return PF_Err_OUT_OF_MEMORY; }

Parameter System

• Popup params are 1-based in AE SDK. Subtract 1 when reading: params[X]->u.pd.value - 1
• Float slider values: params[X]->u.fs_d.value
• ALWAYS call AEFX_CLR_STRUCT(def) before EVERY PF_ADD_* macro
• Each param needs a unique, stable Disk ID starting at 1. NEVER renumber after release.

Build System (macOS)

• Use build.sh as primary build (Make breaks on spaces in paths)
• Use eval with quoted paths in build.sh for safety
• Rez uses lowercase -d (NOT -D): -d AE_OS_MAC
• Required SDK util sources: AEGP_SuiteHandler.cpp, MissingSuiteError.cpp, AEFX_SuiteHelper.c
• Do NOT compile String_Utils.c (causes unresolved symbol errors)
• Universal binary: -arch arm64 -arch x86_64
• C++17: -std=c++17
• Optimization: -O2
• Frameworks: -framework CoreFoundation -framework CoreServices -framework Accelerate
• Ad-hoc code sign: codesign --force --sign - (REQUIRED macOS 15+)

PiPL Resource

• MUST have both CodeMacIntel64 and CodeMacARM64 entry points set to "EffectMain"
• OutFlags hex MUST match what GlobalSetup sets
• AE_Effect_Version 524288 = version 1.0

Plugin Flags

• out_flags2 always: PF_OutFlag2_FLOAT_COLOR_AWARE | PF_OutFlag2_SUPPORTS_SMART_RENDER | PF_OutFlag2_SUPPORTS_THREADED_RENDERING
• For per-pixel effects: PF_OutFlag_PIX_INDEPENDENT | PF_OutFlag_DEEP_COLOR_AWARE | PF_OutFlag_NON_PARAM_VARY | PF_OutFlag_WIDE_TIME_INPUT
• For spatial effects (blur, etc.): Same but WITHOUT PF_OutFlag_PIX_INDEPENDENT

Entry Point

• Always use PluginDataEntryFunction2 (new style) with PF_REGISTER_EFFECT_EXT2
• EffectMain MUST have try/catch wrapping all commands
• Handle: PF_Cmd_ABOUT, PF_Cmd_GLOBAL_SETUP, PF_Cmd_PARAMS_SETUP, PF_Cmd_RENDER

Pass-through Optimization

• Check if all effect params are at zero/default. If so, safeCopyFrame(input, output) and return.
• This prevents unnecessary processing and keeps Premiere responsive.

Performance (learned from real 4K testing)

• Gaussian blur: use 3-pass box blur approximation (O(n) not O(n*k))
• Large blur radii (>15 sigma): use half-resolution blur (downsample → blur → upsample)
• Never allocate per-pixel temporary buffers inside a loop — allocate once outside
• Cap all blur radii to prevent memory explosions (max 200 pixels)

Random/Animated Effects

• Per-frame grain seed: (uint32_t)(in_data->current_time) ^ 0xDEADBEEF
• Set PF_OutFlag_NON_PARAM_VARY so Premiere knows the output can vary even without param changes

Installation Path

• User-level (no sudo): ~/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/
• System-level (sudo): /Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/

Common Effect Patterns

Pure Color Effect (brightness, contrast, hue shift, LUT)

• Set PIX_INDEPENDENT
• PiPL OutFlags: 0x2000404
• No blur utilities needed in Engine.h
• Simple per-pixel loop in processFrame

Blur/Convolution Effect (gaussian blur, sharpen, edge detect)

• Do NOT set PIX_INDEPENDENT
• PiPL OutFlags: 0x404
• Include box blur utilities in Engine.h
• Use fastBlurHalfRes for large radii

Film Emulation Effect (grain, halation, bloom, vignette)

• Do NOT set PIX_INDEPENDENT (halation/bloom use spatial reads)
• PiPL OutFlags: 0x404
• Include all DSP utilities
• Use multi-resolution mip-chain for bloom
• Per-channel blur for halation

Composite/Blend Effect

• May need PIX_INDEPENDENT depending on approach
• Consider alpha channel handling