n8n-nodes-sb-render

This is an n8n community node for video rendering with customizable subtitles, background music (BGM), and narration using FFmpeg.

sb-render allows you to automate video composition workflows in n8n, combining video files with:

• 🎵 Background music with volume control and fade effects
• 🎙️ Narration audio with timing control
• 📝 Customizable subtitles with extensive styling options
• 🎨 Multiple output formats and quality presets
• 🖼️ AI-powered parallax effects from static images (Depth Anything V2)
• 🔀 Video merging with transitions and audio sync

Inspired by n8n-nodes-mediafx.

Table of Contents

• Installation
• Prerequisites
• Operations
• Parallax Effect
• Configuration
• Examples
• Development
• Troubleshooting
• License

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in n8n
2. Select Install
3. Enter n8n-nodes-sb-render
4. Agree to the risks and install

Manual Installation

npm install n8n-nodes-sb-render

For n8n self-hosted installations:

cd ~/.n8n
npm install n8n-nodes-sb-render
# Restart n8n

Prerequisites

• n8n version: 1.0.0 or higher
• Node.js: 16.0.0 or higher
• FFmpeg: Auto-detected from system or installed via npm packages

FFmpeg Installation (Docker/n8n Users)

For Docker or self-hosted n8n, installing system ffmpeg is recommended:

# Alpine-based containers (n8n official image)
docker exec <container-name> apk add --no-cache ffmpeg

# Debian/Ubuntu-based containers
docker exec <container-name> apt-get update && apt-get install -y ffmpeg

docker-compose.yml example:

services:
  n8n:
    image: n8nio/n8n
    command: >
      sh -c "
        apk add --no-cache ffmpeg &&
        n8n start
      "

The node will automatically:

1. ✅ Use system ffmpeg/ffprobe if available (most reliable)
2. ✅ Fall back to npm packages with auto-permission fix
3. ✅ Gracefully degrade with limited functionality

Note: v1.1.20+ automatically handles ffmpeg/ffprobe detection and permission issues!

Operations

Video → Render

Compose a video with optional background music, narration, and subtitles.

Features:

• ✅ Multiple input sources (URL or binary data)
• ✅ Audio mixing with independent volume controls
• ✅ Fade in/out effects for BGM
• ✅ Customizable subtitle positioning and styling
• ✅ Multiple output formats (MP4, MOV, WebM)
• ✅ Quality presets (Low, Medium, High, Custom)
• ✅ Smart audio merging (handles mixed audio/silent video inputs)

Image → Parallax

Create 2.5D parallax video effects from static images using AI depth estimation.

Features:

• ✅ AI-powered depth estimation (Depth Anything V2)
• ✅ True layer separation with inpainting
• ✅ Direction + Zoom combination effects
• ✅ Intensity control (subtle, normal, dramatic)
• ✅ Falls back to Ken Burns effect if AI not available

Parallax Effect

The parallax feature uses Depth Anything V2 AI model to create professional 2.5D parallax effects from static images.

How It Works

1. Depth Estimation: AI model analyzes the image to create a depth map
2. Layer Separation: Foreground is extracted based on depth (closer objects)
3. Inpainting: Background is filled where foreground was removed
4. Animation: Layers move at different speeds creating parallax illusion

Parameters

| Parameter | Type | Options | Description | |-----------|------|---------|-------------| | direction | String | left, right, up, down | Pan direction | | zoom | String | none, in, out | Zoom effect (combinable with direction) | | intensity | String | subtle, normal, dramatic | Movement intensity | | duration | Number | seconds | Video duration |

Combined Effects

You can combine zoom with direction for richer effects:

{
  "direction": "left",
  "zoom": "in",
  "intensity": "normal",
  "duration": 5
}

Effect Combinations:

• left + zoomIn: Pan left while zooming in
• right + zoomOut: Pan right while zooming out
• up + zoomIn: Pan up with zoom in
• zoomIn only: Pure zoom in effect (set direction to empty)

Requirements for AI Parallax

For AI-powered depth parallax, the following Python packages are required on the server:

pip3 install torch transformers pillow opencv-python-headless

If not available, the node automatically falls back to Ken Burns (zoompan) effect.

Configuration

Video Input

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | Video Source | Options | Yes | url or binary | | Video URL | String | If URL | URL of the video file | | Video Binary Property | String | If Binary | Name of binary property containing video |

Background Music (BGM)

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Enable BGM | Boolean | false | Add background music | | BGM Source | Options | - | url or binary | | BGM URL | String | - | URL of BGM file | | BGM Volume | Number | 30 | Volume 0-100 | | BGM Fade In | Number | 2 | Fade-in duration (seconds) | | BGM Fade Out | Number | 2 | Fade-out duration (seconds) |

Narration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Enable Narration | Boolean | false | Add narration audio | | Narration Source | Options | - | url or binary | | Narration URL | String | - | URL of narration file | | Narration Volume | Number | 80 | Volume 0-100 | | Narration Delay | Number | 0 | Delay before start (seconds) |

Subtitles

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Enable Subtitles | Boolean | false | Add subtitles | | Text | String | - | Subtitle text content | | Start Time | Number | - | Start time in seconds | | End Time | Number | - | End time in seconds | | Position | Options | bottom | top, middle, bottom, custom | | Font Size | Number | 75 | Text size | | Font Color | Color | #FFFFFF | Text color (hex) | | Font Family | String | Arial | Font name | | Alignment | Options | center | left, center, right | | Background Color | Color | #000000 | Background color (hex) | | Background Opacity | Number | 80 | Opacity 0-100 | | Border Color | Color | #000000 | Border color (hex) | | Border Width | Number | 2 | Border width (pixels) |

Output Options

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Output Format | Options | mp4 | mp4, mov, webm | | Video Codec | Options | libx264 | libx264, libx265, vp9 | | Quality | Options | high | low, medium, high, custom | | Custom CRF | Number | 18 | CRF value 0-51 (if custom quality) | | Output Binary Property | String | data | Property name for output |

Examples

Example 1: Simple Video with Subtitles

{
  "videoSource": "url",
  "videoUrl": "https://example.com/video.mp4",
  "enableSubtitles": true,
  "subtitles": {
    "subtitle": [
      {
        "text": "Welcome to our video!",
        "startTime": 0,
        "endTime": 5,
        "position": "bottom",
        "fontSize": 48,
        "fontColor": "#FFFFFF",
        "alignment": "center"
      }
    ]
  },
  "outputFormat": "mp4",
  "quality": "high"
}

Example 2: Video with BGM and Narration

{
  "videoSource": "url",
  "videoUrl": "https://example.com/video.mp4",
  "enableBGM": true,
  "bgmSource": "url",
  "bgmUrl": "https://example.com/music.mp3",
  "bgmVolume": 20,
  "bgmFadeIn": 3,
  "bgmFadeOut": 3,
  "enableNarration": true,
  "narrationSource": "url",
  "narrationUrl": "https://example.com/narration.mp3",
  "narrationVolume": 90,
  "narrationDelay": 2,
  "outputFormat": "mp4"
}

Example 3: Custom Positioned Subtitles

{
  "videoSource": "url",
  "videoUrl": "https://example.com/video.mp4",
  "enableSubtitles": true,
  "subtitles": {
    "subtitle": [
      {
        "text": "Top-left subtitle",
        "startTime": 0,
        "endTime": 5,
        "position": "custom",
        "customX": 100,
        "customY": 100,
        "fontSize": 36,
        "fontColor": "#FFFF00",
        "alignment": "left",
        "backgroundColor": "#000000",
        "backgroundOpacity": 70,
        "borderColor": "#FFFFFF",
        "borderWidth": 3
      }
    ]
  }
}

Example 4: Workflow Integration

Scenario: Download video from URL, add BGM and subtitles, upload to cloud storage

HTTP Request → SB Render → Google Drive

1. HTTP Request: Download video file
2. SB Render: Add BGM and subtitles
3. Google Drive: Upload rendered video

Development

Build

npm install
npm run build

Development Mode

npm run dev

Linting

npm run lint
npm run lintfix

Project Structure

sb-render/
├── nodes/
│   └── SbRender/
│       ├── SbRender.node.ts         # Main node implementation
│       ├── SbRender.node.json       # Node metadata
│       ├── services/
│       │   ├── FileManager.ts       # File handling
│       │   ├── AudioMixer.ts        # Audio composition
│       │   ├── SubtitleEngine.ts    # Subtitle generation
│       │   └── VideoComposer.ts     # Video rendering
│       ├── interfaces/
│       │   └── index.ts             # TypeScript types
│       └── utils/
│           ├── ffmpeg.ts            # FFmpeg helpers
│           └── validation.ts        # Input validation
├── fonts/                           # Custom fonts
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

FFmpeg Not Found

The node automatically installs FFmpeg via @ffmpeg-installer/ffmpeg. If you encounter issues:

npm install @ffmpeg-installer/ffmpeg --force

File Download Errors

Issue: Video/audio URLs fail to download

Solutions:

• Verify URL accessibility
• Check for authentication requirements
• Ensure sufficient disk space
• Try using binary data input instead

Subtitle Not Appearing

Issue: Subtitles don't show in output video

Solutions:

• Verify timing (start/end times within video duration)
• Check subtitle position and size
• Ensure font is available on system
• Try different output format (MP4 recommended)

Memory Issues

Issue: Process crashes with large video files

Solutions:

• Reduce video resolution before processing
• Use lower quality preset
• Process videos in smaller batches
• Increase Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"

Audio Sync Issues

Issue: Audio out of sync with video

Solutions:

• Ensure all audio files are in compatible formats
• Check narration delay settings
• Verify video frame rate compatibility
• Try re-encoding source files

Technical Details

FFmpeg Commands

The node uses fluent-ffmpeg to construct FFmpeg commands:

Audio Mixing:

-filter_complex "[0:a]volume=1.0[original];[1:a]volume=0.3,afade=t=in:st=0:d=2[bgm];[original][bgm]amix=inputs=2[mixed]"

Subtitle Overlay:

-vf "ass=subtitles.ass"

Complete Command:

ffmpeg -i video.mp4 -i bgm.mp3 -filter_complex "..." -vf "ass=..." -c:v libx264 -crf 18 output.mp4

Subtitle Formats

• SRT: Simple subtitle format (limited styling)
• ASS: Advanced SubStation Alpha (full styling support) ← Used by default

ASS format provides:

• Custom fonts and colors
• Precise positioning
• Background colors and opacity
• Border/outline effects
• Multiple alignment options

Performance

Resource Usage

| Video Length | Memory | Processing Time | |--------------|--------|-----------------| | 1 minute | ~200MB | ~30 seconds | | 5 minutes | ~500MB | ~2 minutes | | 10 minutes | ~1GB | ~5 minutes |

Times measured on standard VPS (2 CPU, 4GB RAM)

Optimization Tips

1. Use appropriate quality: High quality for final output, medium for testing
2. Compress BGM: Use lower bitrate audio files (128-192 kbps)
3. Batch processing: Process multiple videos in parallel workflows
4. Cache audio files: Reuse same BGM/narration across multiple videos

Compatibility

Supported Video Formats

Input: MP4, MOV, WebM, AVI, MKV Output: MP4, MOV, WebM

Supported Audio Formats

Input: MP3, WAV, AAC, OGG, M4A Output: AAC (default)

Codec Compatibility

| Codec | Quality | Speed | Browser Support | |-------|---------|-------|-----------------| | H.264 (libx264) | Good | Fast | Excellent | | H.265 (libx265) | Better | Slower | Limited | | VP9 | Good | Slow | Good (WebM) |

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Guidelines

• Follow existing code style (ESLint configured)
• Add TypeScript types for new features
• Update documentation for new parameters
• Test with various video formats

Roadmap

v1.1 (Planned)

• [ ] Multiple video layers
• [ ] Video transitions
• [ ] Logo/watermark overlay
• [ ] Preset subtitle templates
• [ ] Batch processing mode

v2.0 (Future)

• [ ] GPU acceleration (NVENC, VideoToolbox)
• [ ] Cloud storage integration
• [ ] Progress callbacks
• [ ] Advanced video effects

Credits

• Inspired by n8n-nodes-mediafx
• Uses FFmpeg for video processing
• Built with fluent-ffmpeg

License

MIT

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• n8n Community: n8n Community Forum

Made with ❤️ for the n8n community