Chapter 14: Smart Objects

Smart Objects are user-programmable canvas graphics that let you create custom visual elements using JavaScript code. They enable effects, charts, decorations, and animated visuals that go beyond the built-in element types.

What Are Smart Objects?

A Smart Object is a scene element driven by a JavaScript drawing function. The code receives a 2D canvas context and draws whatever you need—gradients, charts, particle effects, animated patterns, and more.

Smart Objects can be:

• Static: A single rendered frame (e.g., a gradient, a chart)
• Animated: Multi-frame sequences with configurable frame count and FPS

Adding a Smart Object

1. Open the element palette on the right sidebar
2. Look for the Smart Objects section
3. Browse available definitions by category:
   • Builtin: Pre-made smart objects included with FX Express
   • Charts: Data visualization elements
   • Progress: Progress bars, loaders
   • Decorative: Visual accents and patterns
   • Transition: Scene transition effects
   • Custom: Your own uploaded smart objects
4. Click or drag a smart object to the canvas

Smart Object Parameters

Smart Objects accept configurable parameters that control their appearance:

Parameter Type	Description	Example
Number	Numeric value with min/max range	Line thickness, count
String	Text input	Labels, titles
Color	Color picker value	Fill color, stroke color
Boolean	On/off toggle	Show grid, enable shadow
Select	Dropdown from predefined options	Style variant, direction

Editing Parameters

1. Select the smart object on the canvas
2. Open the Properties panel
3. Adjust parameter values
4. The smart object re-renders with updated settings

Animation Support

Smart Objects can be animated:

• Frame Count: Total number of animation frames
• FPS: Playback speed (frames per second)
• Each frame calls the render function with an incrementing frameIndex
• Use frameIndex / totalFrames to calculate animation progress

Smart Objects as Transitions

Smart Objects in the Transition category can serve as scene transitions:

1. Open the Scene Transition dialog for the scene you are leaving (see Chapter 2)
2. Select Smart Object as the transition type
3. Choose a transition-category smart object and adjust its parameters
4. Set the duration and easing, and click Apply

The smart object plays over the whole transition, on top of both scenes. Its cutTime property (0–1) is the point in the transition, as a fraction of its duration, where the scenes switch underneath it: before it the object covers the outgoing scene, after it the object uncovers the incoming one. With a 1-second transition and a cutTime of 0.5, the switch happens at 0.5 seconds. The scene sound switches at the same moment.

The rendered video shows the transition the way the preview does. Transition objects you created yourself are the exception: they exist only in your browser, so a render cannot draw them and shows a plain cut at the midpoint instead.

Like every transition, it overlaps the two scenes, so it shortens the video by its duration.

AI-Assisted Creation

FX Express can generate smart object code using AI:

1. Open the Smart Object editor
2. Click the AI generation button
3. Describe the visual effect you want
4. Review and edit the generated code
5. Save as a custom smart object

Performance

• Smart Object renders are cached using an LRU cache for efficiency
• Static smart objects render once and reuse the result
• Animated smart objects render per frame during playback
• Keep canvas operations simple for best performance

Troubleshooting

Smart Object Not Rendering

• Check for JavaScript errors in the code
• Verify all required parameters have values
• Ensure canvas dimensions are valid

Animation Stuttering

• Reduce frame count or complexity
• Check FPS setting (30fps is standard)
• Simplify drawing operations

Parameters Not Updating

• Re-select the element to refresh
• Check parameter types match expected values

---

← Previous: Variables | Next: Track Mattes →