Description
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
- Installation
- Prerequisites
- Operations
- Configuration
- Examples
- Development
- Troubleshooting
- License
Inspired by n8n-nodes-mediafx.
Table of Contents
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
FFmpeg Installation (Docker/n8n Users)
For Docker or self-hosted n8n, installing system ffmpeg is recommended:
Alpine-based containers (n8n official image)
docker exec apk add --no-cache ffmpegDebian/Ubuntu-based containers
docker exec 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:
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 | 90 | 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:
Subtitle Not Appearing
Issue: Subtitles don’t show in output video
Solutions:
Memory Issues
Issue: Process crashes with large video files
Solutions:
export NODE_OPTIONS="--max-old-space-size=4096"
Audio Sync Issues
Issue: Audio out of sync with video
Solutions:
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
ASS format provides:
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
Roadmap
v1.1 (Planned)
v2.0 (Future)
Credits
License
Support
—
Made with ❤️ for the n8n community
