# SVG Animation Generation: Capsule-Render Integration

> Techniques borrowed from capsule-render and rebuilt into Chromaflow's SVG generator: CSS-based text animation types, additional background styles, and the API surface that exposes them.

Source: https://chanmeng.org/blog/svg-animation-generation
Author: Chan Meng — https://chanmeng.org
Published: 2026-06-19
Tags: Frontend, Open Source

---

*Originally written as internal engineering notes while building the thing it describes. Republished here with light editing — the timeframe is noted where it matters.*

This document describes the new features inspired by the [capsule-render](https://github.com/kyechan99/capsule-render) project and how they've been integrated into Chromaflow — the SVG banner generator I maintain, published as [gradient-svg-generator](https://github.com/ChanMeng666/gradient-svg-generator) and running at [gradient-svg-generator.vercel.app](https://gradient-svg-generator.vercel.app/).

## 📊 Project Analysis

The capsule-render project is a GitHub profile decoration tool that generates SVG banners with text and animated backgrounds. We analyzed 13 different background types and extracted valuable techniques that complement our existing gradient system.

## 🎨 New Features Implemented

### 1. Text Animation System ✨

Inspired by capsule-render's text animation capabilities, we've added 5 CSS-based animation types:

#### Available Animations

- **`fadeIn`** - Smooth opacity fade (1.2s)
  ```
  /api/svg?text=Hello&animation=fadeIn
  ```

- **`scaleIn`** - Scale from 0 to 1 (0.8s)
  ```
  /api/svg?text=Hello&animation=scaleIn
  ```

- **`blink`** - Quick on/off pattern (0.6s, plays once)
  ```
  /api/svg?text=Hello&animation=blink
  ```

- **`blinking`** - Continuous on/off (1.6s infinite loop)
  ```
  /api/svg?text=Hello&animation=blinking
  ```

- **`twinkling`** - Soft opacity pulsing (4s infinite loop)
  ```
  /api/svg?text=Hello&animation=twinkling
  ```

#### Implementation Details

- **File**: `src/utils/textAnimationUtils.js`
- **Integration**: Automatically applied to all gradient types
- **Compatibility**: Works with existing templates and gradients
- **Default**: No animation (use `animation=none` or omit parameter)

#### Code Example

```javascript
// Using with any gradient type
/api/svg?text=Welcome&gradientType=radial&animation=fadeIn

// Using with templates
/api/svg?text=Hello&template=neural-network&animation=twinkling
```

---

### 2. Blob Morphing Gradients 🌊

Inspired by capsule-render's **Venom effect**, these create organic, liquid-like shapes that continuously morph between different forms.

#### Gradient Types

1. **`blobMorph`** - Basic organic blob morphing
   - Duration: 10s cycle
   - 3-4 shape states
   - Smooth spline transitions
   ```
   /api/svg?text=Venom&gradientType=blobMorph
   ```

2. **`liquidBlob`** - Multi-layer blob with depth
   - Duration: 12s cycle
   - 2 overlapping layers with staggered timing
   - Blur filters for atmospheric effect
   ```
   /api/svg?text=Mercury&gradientType=liquidBlob
   ```

3. **`organicBlob`** - Radial blob with glow
   - Duration: 15s cycle
   - 5 complex shape variations
   - Radial gradient with glow filter
   ```
   /api/svg?text=Plasma&gradientType=organicBlob
   ```

#### Templates Using Blob Morphing

- `liquid-venom` - Purple/pink liquid morphing
- `mercury-flow` - Metallic silver blob
- `organic-plasma` - Warm red/pink plasma
- `morphing-ocean` - Ocean blue liquid
- `sunset-blob` - Warm sunset colors
- `neon-pulse` - Vibrant neon morphing
- `fire-morph` - Fiery liquid effect

#### Implementation Details

- **File**: `src/utils/gradientGenerators/blobMorphingGradients.js`
- **Technique**: SVG path morphing with `<animate>` on `d` attribute
- **Path Generation**: Algorithmic blob path creation with randomization
- **Performance**: Optimized with spline interpolation

---

### 3. Layered Wave Gradients 🌊

Inspired by capsule-render's **Waving effect**, creates oceanic depth with multiple semi-transparent wave layers.

#### Gradient Type

**`layeredWaves`** - Multi-layer depth effect
- 3 independent wave layers
- Staggered animations (begins at 0s, -0.5s, -1s)
- Opacity layering (0.3, 0.4, 0.5)
- Blur filter for atmospheric depth

```
/api/svg?text=Ocean&gradientType=layeredWaves
```

#### Templates Using Layered Waves

- `ocean-depths` - Deep ocean blues (12s)
- `aurora-waves` - Northern lights colors (15s)
- `cosmic-waves` - Deep space purples (18s)

#### Key Features

- **Depth Effect**: Multiple opacity layers create 3D illusion
- **Smooth Motion**: Spline-based keyframe animation
- **Organic Feel**: Quadratic Bezier curves for natural waves
- **Performance**: CSS transforms for smooth 60fps animation

#### Implementation Details

- **File**: Enhanced `src/utils/gradientGenerators/shapeGradients.js`
- **Wave Paths**: SVG path with T (smooth quadratic curve) commands
- **Animation**: Morphs between 4 different wave states
- **Timing**: Independent timing for each layer prevents repetition

---

### 4. Blur Motion Gradients 💫

Inspired by capsule-render's **Blur effect**, creates abstract, dreamy atmospheres with soft floating circles.

#### Gradient Types

1. **`blurMotion`** - Soft floating circles
   - 3 circles with heavy blur (stdDeviation="12")
   - Independent X/Y animations
   - Duration: 12s
   ```
   /api/svg?text=Dream&gradientType=blurMotion
   ```

2. **`dreamyCircles`** - Multiple dreamy circles
   - 4 circles with varied sizes and opacity
   - Staggered begin times (0s, 0.5s, 1s, 1.5s)
   - Duration: 15s
   ```
   /api/svg?text=Fantasy&gradientType=dreamyCircles
   ```

3. **`abstractBlur`** - Minimalist abstract
   - 3 circles with maximum blur (stdDeviation="15")
   - Radial gradients with saturation boost
   - Duration: 20s
   ```
   /api/svg?text=Zen&gradientType=abstractBlur
   ```

#### Templates Using Blur Motion

- `dreamy-sunset` - Warm sunset blur (12s)
- `pastel-dream` - Soft pastel circles (15s)
- `abstract-night` - Dark abstract blur (20s)
- `ethereal-mist` - Lavender mist (18s)
- `soft-lavender` - Gentle lavender (16s)

#### Key Features

- **Heavy Blur**: Gaussian blur with stdDeviation 8-15
- **Opacity Layering**: Ranges from 0.15 to 0.4
- **Independent Motion**: Each circle has unique X/Y animation
- **Color Saturation**: Filters boost saturation 1.4-1.6x

#### Implementation Details

- **File**: `src/utils/gradientGenerators/blurMotionGradients.js`
- **Filters**: `feGaussianBlur` + `feColorMatrix`
- **Animation**: Spline-based easing with keySplines="0.4 0 0.6 1"
- **Performance**: Filter caching for better performance

---

## 📝 API Usage Examples

### Combining Features

```bash
# Text animation + Blob morphing
/api/svg?text=Morphing&gradientType=blobMorph&animation=fadeIn

# Layered waves + Twinkling text
/api/svg?text=Ocean&gradientType=layeredWaves&animation=twinkling

# Blur motion + Scale animation
/api/svg?text=Dream&gradientType=dreamyCircles&animation=scaleIn

# Template + Text animation
/api/svg?text=Venom&template=liquid-venom&animation=blinking
```

### Custom Heights

```bash
# Tall morphing effect
/api/svg?text=Tall&gradientType=blobMorph&height=200

# Wide blur effect
/api/svg?text=Wide&gradientType=blurMotion&height=150
```

### With Custom Colors

```bash
# Custom colors with blob morphing
/api/svg?text=Custom&gradientType=liquidBlob&color0=FF0000&color1=00FF00&color2=0000FF
```

---

## 🎯 Template Reference

### All New Templates (15 total)

#### Blob Morphing (6 templates)
1. `liquid-venom` - Purple/pink liquid
2. `mercury-flow` - Metallic silver
3. `organic-plasma` - Red/pink plasma
4. `morphing-ocean` - Ocean blue
5. `sunset-blob` - Warm sunset
6. `neon-pulse` - Vibrant neon
7. `fire-morph` - Fiery liquid

#### Layered Waves (3 templates)
1. `ocean-depths` - Deep ocean
2. `aurora-waves` - Northern lights
3. `cosmic-waves` - Deep space

#### Blur Motion (5 templates)
1. `dreamy-sunset` - Sunset blur
2. `pastel-dream` - Pastel circles
3. `abstract-night` - Dark abstract
4. `ethereal-mist` - Lavender mist
5. `soft-lavender` - Gentle lavender

---

## 🔧 Technical Implementation

### Architecture

```
src/
├── utils/
│   ├── textAnimationUtils.js          # Text animation CSS generator
│   └── gradientGenerators/
│       ├── blobMorphingGradients.js   # Blob morphing effects
│       ├── blurMotionGradients.js     # Blur motion effects
│       └── shapeGradients.js          # Enhanced with layeredWaves
├── templates/
│   └── capsuleShapeTemplates.js       # 15 new templates
└── config/
    └── gradientConfig.js              # Updated with new types
```

### Key Techniques Learned

1. **SVG Path Morphing**
   - Animate the `d` attribute of `<path>` elements
   - Use matching number of path commands for smooth transitions
   - Spline interpolation for organic motion

2. **Multi-Layer Animation**
   - Stagger animation begin times for depth
   - Use opacity layers (0.3, 0.4, 0.5)
   - Independent timing per layer

3. **Heavy Blur Filters**
   - `feGaussianBlur` with stdDeviation 8-15
   - Combine with `feColorMatrix` for saturation
   - Cache filters for performance

4. **CSS Text Animations**
   - Keyframe-based animations
   - Spline easing for smooth motion
   - Transform-origin for proper scaling

---

## 🚀 Performance Considerations

### Optimizations Applied

1. **Animation Efficiency**
   - CSS transforms over position changes
   - GPU-accelerated properties (transform, opacity)
   - Reduced animation complexity for mobile

2. **Filter Caching**
   - Reusable filter definitions
   - Unique IDs prevent conflicts
   - Minimal filter chains

3. **Path Optimization**
   - Algorithmic path generation
   - Reduced number of path points
   - Smooth curve commands (T, Q) over line segments

### Browser Compatibility

- ✅ Chrome/Edge: Full support
- ✅ Firefox: Full support
- ✅ Safari: Full support
- ✅ Mobile browsers: Optimized performance

---

## 📚 References

- **Original Project**: [capsule-render](https://github.com/kyechan99/capsule-render)
- **Techniques Inspired By**:
  - Venom effect → Blob Morphing
  - Waving effect → Layered Waves
  - Blur effect → Blur Motion
  - Text animations → Text Animation System

---

## 🎓 Learning Outcomes

### Design Insights

1. **Layering Creates Depth**: Multiple semi-transparent layers with staggered animations create perceived 3D depth
2. **Blur Adds Atmosphere**: Heavy Gaussian blur transforms simple shapes into atmospheric effects
3. **Organic Motion**: Path morphing with spline interpolation feels more natural than linear transforms
4. **Subtlety Matters**: Low opacity (0.15-0.4) and slow animations (12-20s) create sophisticated effects

### Technical Insights

1. **SVG Path Animation**: The `d` attribute can be animated for shape morphing
2. **Filter Composition**: Combining multiple SVG filters creates complex visual effects
3. **Animation Timing**: Staggered begin times prevent visual repetition
4. **Performance**: CSS animations perform better than JavaScript-based animations

---

## 🎨 Additional Features Implemented

### 5. Text Effect Enhancements ✨

Building on capsule-render's text customization capabilities, we've added comprehensive text styling options.

#### Text Stroke Effects

Add outlined text with customizable stroke colors and widths:

```bash
# Basic stroke
/api/svg?text=Hello&stroke=FF0000&strokeWidth=2

# Stroke with gradient background
/api/svg?text=Outlined&template=neural-network&stroke=FFFF00&strokeWidth=3

# Combine with animations
/api/svg?text=Glowing&animation=twinkling&stroke=00FFFF&strokeWidth=1.5
```

**Parameters**:
- `stroke` - Hex color for text outline (without #)
- `strokeWidth` - Width in pixels (0-10 recommended)

#### Text Background Rectangles

Add highlighted background boxes behind text:

```bash
# Basic background
/api/svg?text=Important&textBg=FF0000

# Semi-transparent background
/api/svg?text=Notice&textBg=FFD700&template=dreamy-sunset

# Combine with stroke
/api/svg?text=Alert&textBg=FF4444&stroke=FFFFFF&strokeWidth=2
```

**Parameters**:
- `textBg` - Hex color for background rectangle (without #)
- Automatically sized based on text length
- 25px border radius for rounded corners
- 0.9 opacity for subtle effect

#### Text Rotation

Rotate text at any angle:

```bash
# 45-degree angle
/api/svg?text=Diagonal&rotate=45

# Upside down
/api/svg?text=Inverted&rotate=180

# Slight tilt
/api/svg?text=Dynamic&rotate=15&template=cyber-capsule
```

**Parameters**:
- `rotate` - Rotation angle in degrees (-360 to 360)
- Rotates around text center point

#### Combined Text Effects

All text effects can be combined for rich styling:

```bash
# Full styling
/api/svg?text=FEATURED&stroke=FFD700&strokeWidth=2&textBg=000000&rotate=5&animation=scaleIn

# Retro gaming style
/api/svg?text=LEVEL_UP&template=pixel-art-retro&stroke=FFFFFF&strokeWidth=3&textBg=FF00FF

# Modern UI callout
/api/svg?text=NEW&textBg=FF3B30&stroke=FFFFFF&strokeWidth=1&animation=fadeIn
```

---

### 6. Shape Background Templates 🔷

Inspired by capsule-render's diverse shape types, we've implemented 7 unique shaped backgrounds beyond standard rectangles.

#### Available Shape Types

1. **`cylinder`** - Capsule/pill shape with rounded ends
   ```
   /api/svg?text=Capsule&gradientType=cylinder
   ```

2. **`softRounded`** - Subtle rounded corners (15px radius)
   ```
   /api/svg?text=Modern&gradientType=softRounded
   ```

3. **`eggShape`** - Organic oval/egg form
   ```
   /api/svg?text=Organic&gradientType=eggShape
   ```

4. **`sliceShape`** - Diagonal angular cut
   ```
   /api/svg?text=Dynamic&gradientType=sliceShape
   ```

5. **`speechBubble`** - Chat bubble with tail
   ```
   /api/svg?text=Hello!&gradientType=speechBubble
   ```

6. **`sharkTeeth`** - Zigzag bottom edge
   ```
   /api/svg?text=Energy&gradientType=sharkTeeth
   ```

7. **`largeRounded`** - Bold rounded corners (61px radius)
   ```
   /api/svg?text=Bold&gradientType=largeRounded
   ```

#### Shape Background Templates (10 new templates)

Pre-configured templates using shape backgrounds:

- **`capsule-tech`** - Tech-themed cylinder shape
- **`soft-modern`** - Modern soft rounded design
- **`organic-egg`** - Natural egg shape
- **`dynamic-slice`** - Angular diagonal slice
- **`chat-bubble`** - Green chat bubble
- **`energy-teeth`** - Purple shark teeth
- **`bold-rounded`** - Bold blue rounded
- **`cyber-capsule`** - Cyberpunk capsule
- **`golden-egg`** - Luxurious golden egg
- **`message-box`** - Messenger-style bubble

**Usage Examples**:
```bash
# Use pre-made template
/api/svg?text=Hello&template=chat-bubble

# Custom colors with shape
/api/svg?text=Custom&gradientType=cylinder&color0=FF0000&color1=00FF00

# Shape + text effects
/api/svg?text=Styled&template=cyber-capsule&stroke=00FFFF&strokeWidth=2&animation=fadeIn
```

---

## 🔮 Future Enhancements

Potential additional features to consider:

1. **Multi-line Text Support** - Text with line breaks
2. **Text Alignment Options** - Left, right, center positioning
3. **Font Size Control** - Adjustable text size
4. **Additional Shape Variations**:
   - Asymmetric shapes
   - Arrow/pointer designs
   - Badge/shield shapes

---

## ✅ Testing

### Manual Testing Checklist

- [x] Text animations work with all gradient types
- [x] Blob morphing creates smooth transitions
- [x] Layered waves show depth effect
- [x] Blur motion creates atmospheric effect
- [x] All templates render correctly
- [x] Animations loop seamlessly
- [x] Custom colors work with new gradients
- [x] Height parameter affects layout properly
- [x] Performance is acceptable on mobile

### Test URLs

```bash
# Test each animation
/api/svg?text=FadeIn&animation=fadeIn
/api/svg?text=ScaleIn&animation=scaleIn
/api/svg?text=Blink&animation=blink
/api/svg?text=Blinking&animation=blinking
/api/svg?text=Twinkle&animation=twinkling

# Test each gradient type
/api/svg?text=Blob&gradientType=blobMorph
/api/svg?text=Liquid&gradientType=liquidBlob
/api/svg?text=Organic&gradientType=organicBlob
/api/svg?text=Waves&gradientType=layeredWaves
/api/svg?text=Blur&gradientType=blurMotion
/api/svg?text=Dreamy&gradientType=dreamyCircles
/api/svg?text=Abstract&gradientType=abstractBlur

# Test templates
/api/svg?text=Venom&template=liquid-venom
/api/svg?text=Ocean&template=ocean-depths
/api/svg?text=Dream&template=dreamy-sunset
```

---

## 📊 Statistics

### Implementation Summary

- **New Gradient Types**: 14 total
  - Blob morphing: 3 (blobMorph, liquidBlob, organicBlob)
  - Layered waves: 1 (layeredWaves)
  - Blur motion: 3 (blurMotion, dreamyCircles, abstractBlur)
  - Shape backgrounds: 7 (cylinder, softRounded, eggShape, sliceShape, speechBubble, sharkTeeth, largeRounded)
- **New Templates**: 25 total
  - Blob/wave/blur templates: 15
  - Shape background templates: 10
- **New Animation Types**: 5 (fadeIn, scaleIn, blink, blinking, twinkling)
- **New Text Effects**: 3 (stroke, textBg, rotate)
- **New Files Created**: 4
  - textAnimationUtils.js
  - blobMorphingGradients.js
  - blurMotionGradients.js
  - shapeBackgroundGradients.js
- **Files Modified**: 7
  - gradientGenerator.js
  - pages/api/svg.js
  - gradientFactory.js
  - gradientConfig.js
  - shapeGradients.js
  - capsuleShapeTemplates.js
  - CAPSULE_RENDER_INTEGRATION.md
- **Lines of Code Added**: ~1500
- **API Parameters Added**: 5 (`animation`, `stroke`, `strokeWidth`, `textBg`, `rotate`)

### Feature Breakdown

| Feature | Inspiration | Complexity | Value |
|---------|------------|------------|-------|
| Text Animations | capsule-render | Low | High |
| Blob Morphing | Venom effect | Medium | High |
| Layered Waves | Waving effect | Medium | High |
| Blur Motion | Blur effect | Low | Medium |

---

*Generated: 2025-01-10*
*Integration Version: 1.0.0*
*Based on capsule-render analysis*