Ecsplendid/motion blur

README.md

@@ -15,6 +15,116 @@
 </p>
 <br/>
 
+# Revideo Fork: Professional Motion Blur
+
+**This fork adds professional-grade motion blur to Revideo** using temporal sub-frame accumulation - the same technique used in film and professional video production.
+
+<p align="center">
+  <img src="./docs/motion-blur-demo.gif" alt="Motion Blur Demo - Left side shows blur, right side shows sharp reference" width="800">
+</p>
+
+## Motion Blur Features
+
+### Temporal Sub-Frame Accumulation
+
+The implementation renders multiple sub-frames within each output frame's time window and blends them together with configurable weights. This approach:
+
+- Produces physically accurate motion blur matching real camera behavior
+- Supports any frame rate and resolution
+- Works with all Revideo animations and components
+
+### Quality Presets
+
+| Preset | Samples | Use Case |
+|--------|---------|----------|
+| `low` | 4 | Fast previews, draft renders |
+| `medium` | 8 | Good balance of quality and speed |
+| `high` | 16 | High quality production renders |
+| `ultra` | 32 | Maximum quality |
+
+### Shutter Angle
+
+Controls exposure time as a fraction of frame duration, simulating a rotary disc shutter:
+
+| Angle | Exposure | Effect |
+|-------|----------|--------|
+| 90 degrees | 25% | Minimal blur, staccato motion |
+| 180 degrees | 50% | Film standard, natural motion |
+| 270 degrees | 75% | Pronounced blur |
+| 360 degrees | 100% | Maximum blur, dreamy effect |
+
+### Shutter Curves
+
+Sample weighting distribution for different blur characteristics:
+
+- **Box**: Equal weight for all samples (sharp, defined edges)
+- **Triangle**: Linear falloff from center (softer blur)
+- **Gaussian**: Bell curve distribution (most natural, mimics real cameras)
+
+### Shutter Position
+
+Controls when the blur occurs relative to the frame:
+
+- **Center**: Blur straddles the frame (recommended)
+- **Start**: Blur trails behind (forward/leading motion)
+- **End**: Blur leads ahead (backward/trailing motion)
+
+### Per-Element Motion Blur Control
+
+Individual elements can override the global motion blur setting. This is essential for:
+
+- Keeping text and UI elements sharp
+- Creating visual contrast between static and moving elements
+- Performance optimization
+
+```tsx
+// This element will be blurred (inherits from scene)
+<Circle x={0} y={0} width={100} fill="blue" />
+
+// This element stays sharp (blur disabled)
+<Txt text="Score: 100" fill="white" motionBlur={{enabled: false}} />
+```
+
+### Implementation Architecture
+
+The renderer uses a **two-pass approach** for per-element control:
+
+```
+Frame N:
++-- Pass 1: Motion Blur (sub-frame accumulation)
+|   +-- Subframe 0: Render blur-enabled elements, accumulate with weight
+|   +-- Subframe 1: Advance time, render, accumulate
+|   +-- ...
+|   +-- Finalize: Normalize accumulated values
+|
++-- Pass 2: Static Elements
+    +-- Render blur-disabled elements on top (no accumulation)
+```
+
+### Usage
+
+```typescript
+// Enable motion blur in your project
+export default makeProject({
+  scenes: [scene],
+  settings: {
+    rendering: {
+      motionBlur: {
+        enabled: true,
+        quality: 'high',           // or samples: 16
+        shutterAngle: 180,         // degrees (0-720)
+        shutterCurve: 'gaussian',  // 'box' | 'triangle' | 'gaussian'
+        shutterPosition: 'center', // 'center' | 'start' | 'end'
+      },
+    },
+  },
+});
+```
+
+See full documentation: [Motion Blur Guide](./docs/MOTION_BLUR.md)
+
+---
+
 # Revideo - Create Videos with Code
 
 Revideo is an open source framework for programmatic video editing. It is forked
@@ -129,6 +239,9 @@ Concretely, some of the differences to Motion Canvas are the following ones:
 - **Better Audio Support:** We have enabled audio export from `<Video/>` tags
   during rendering, and have also added an `<Audio/>` tag that makes it easy to
   synchronize audio with your animations.
+- **Professional Motion Blur:** Realistic motion blur using temporal sub-frame
+  accumulation with quality presets, shutter curves (box/triangle/gaussian),
+  and per-element control. See [Motion Blur Documentation](./docs/MOTION_BLUR.md).
 
 <br/>