Server-side video generation using node-webcodecs and fabric.js
Generate videos programmatically on the server with text and image clips. Perfect for creating dynamic video content, social media posts, automated video generation, and more.
- 🎬 Server-side video generation - No browser required
- 🎨 Text & Image clips - Combine multiple elements
- ⏱️ Timeline control - Precise timing for each clip
- 🎯 Layer management - Control z-index and opacity
- 🔄 Transformations - Rotate, scale, and position clips
- 🎥 MP4 output - Industry-standard format
- 🚀 TypeScript support - Full type definitions included
- System Requirements
- Installation
- Quick Start
- API Reference
- Examples
- Docker Usage
- Configuration Options
- Troubleshooting
- Contributing
- License
This project requires specific system dependencies:
- Node.js: >= 18.0.0
- glibc: 2.39 (for node-webcodecs support)
- FFmpeg: 6.x (for video processing)
Note: If you don't have these dependencies, use the provided Docker setup.
npm install webcodec-video-generator# Clone the repository
git clone https://github.com/x-eight/webcodec-video-generator.git
cd webcodec-video-generator
# Build the Docker image
docker build -t webcodec .
# Run examples
docker run --rm -v $(pwd)/output:/app/output webcodecimport { VideoGenerator, VideoConfig } from 'webcodec-video-generator';
const config: VideoConfig = {
clips: [
{
type: 'Text',
text: 'Hello World!',
left: 100,
top: 100,
width: 400,
height: 200,
angle: 0,
zIndex: 1,
opacity: 1,
flip: null,
id: 'text_1',
display: {
from: 0,
to: 5000
}
}
],
options: {
width: 1920,
height: 1080,
fps: 30,
duration: 5000,
bgColor: '#000000'
}
};
const generator = new VideoGenerator(config);
await generator.generate('output.mp4');Main class for video generation.
new VideoGenerator(config: VideoConfig)Generates the video and saves it to the specified path.
Parameters:
outputPath- Path where the MP4 file will be saved
Returns: Promise that resolves to the output path
Example:
const generator = new VideoGenerator(config);
const path = await generator.generate('./output/video.mp4');
console.log(`Video saved to: ${path}`);Main configuration object for video generation.
interface VideoConfig {
clips: Clip[];
options: VideoOptions;
}Video generation options with default values.
interface VideoOptions {
width: number; // Default: 1920
height: number; // Default: 1080
fps: number; // Default: 30
bgColor: string; // Default: "#000000"
duration?: number; // Default: 5000 (milliseconds)
}Individual clip configuration (Text or Image).
interface Clip {
id: string;
type: 'Text' | 'Image';
left: number; // X position in pixels
top: number; // Y position in pixels
width: number; // Width in pixels
height: number; // Height in pixels
angle: number; // Rotation in degrees
zIndex: number; // Layer order (higher = on top)
opacity: number; // 0-1
flip: any; // Flip configuration
text?: string; // Required for Text clips
src?: string; // Required for Image clips (URL)
display?: DisplayConfig; // Timeline configuration
}Timeline configuration for clip visibility.
interface DisplayConfig {
from: number; // Start time in milliseconds
to: number; // End time in milliseconds
}import { DEFAULT_VIDEO_OPTIONS } from 'webcodec-video-generator';
console.log(DEFAULT_VIDEO_OPTIONS);
// {
// width: 1920,
// height: 1080,
// fps: 30,
// bgColor: '#000000',
// duration: 5000
// }npm run example:basicSee examples/basic.ts for a simple example with text and image.
npm run example:advancedSee examples/advanced.ts for a complex example with multiple clips, timing, and effects.
import { VideoGenerator, VideoConfig } from 'webcodec-video-generator';
const config: VideoConfig = {
clips: [
// Background image
{
type: 'Image',
src: 'https://example.com/background.jpg',
left: 0,
top: 0,
width: 1920,
height: 1080,
angle: 0,
zIndex: 1,
opacity: 0.5,
flip: null,
id: 'bg',
display: { from: 0, to: 10000 }
},
// Title text
{
type: 'Text',
text: 'My Video Title',
left: 100,
top: 100,
width: 800,
height: 200,
angle: 0,
zIndex: 2,
opacity: 1,
flip: null,
id: 'title',
display: { from: 0, to: 3000 }
}
],
options: {
width: 1920,
height: 1080,
fps: 30,
duration: 10000,
bgColor: '#1a1a2e'
}
};
const generator = new VideoGenerator(config);
await generator.generate('./my-video.mp4');The project includes a Docker setup for environments without the required system dependencies.
docker build -t webcodec .docker run --rm -v $(pwd)/output:/app/output webcodecThis mounts your local output folder to persist generated videos.
# Basic example
docker run --rm -v $(pwd)/output:/app/output webcodec npm run example:basic
# Advanced example
docker run --rm -v $(pwd)/output:/app/output webcodec npm run example:advanced| Option | Type | Default | Description |
|---|---|---|---|
width |
number | 1920 | Video width in pixels |
height |
number | 1080 | Video height in pixels |
fps |
number | 30 | Frames per second |
bgColor |
string | "#000000" | Background color (hex) |
duration |
number | 5000 | Video duration in milliseconds |
| Property | Type | Required | Description |
|---|---|---|---|
id |
string | ✅ | Unique identifier |
type |
'Text' | 'Image' | ✅ | Clip type |
left |
number | ✅ | X position |
top |
number | ✅ | Y position |
width |
number | ✅ | Width in pixels |
height |
number | ✅ | Height in pixels |
angle |
number | ✅ | Rotation in degrees |
zIndex |
number | ✅ | Layer order |
opacity |
number | ✅ | Opacity (0-1) |
text |
string | For Text | Text content |
src |
string | For Image | Image URL |
display |
DisplayConfig | ❌ | Timeline config |
Error: version 'GLIBC_2.39' not found
Solution: Use the Docker setup or upgrade to Ubuntu 24.04+ with glibc 2.39.
Error: FFmpeg not found
Solution: Install FFmpeg 6:
sudo apt update
sudo apt install ffmpegError: Cannot find module '@pproenca/node-webcodecs'
Solution: Install dependencies:
npm installError: Various encoding errors
Solutions:
- Ensure image URLs are accessible
- Check that all required clip properties are provided
- Verify
display.from<display.to - Ensure
durationis sufficient for all clips
Run the test suite:
npm testThis validates:
- Default options merging
- Partial configuration handling
- Full video generation pipeline
Contributions are welcome! This project is built on top of:
- node-webcodecs by @pproenca
- fabric.js
# Clone the repository
git clone https://github.com/x-eight/webcodec-video-generator.git
cd webcodec-video-generator
# Install dependencies
npm install
# Run examples
npm run example:basic
# Run tests
npm testMIT License - see LICENSE file for details.
- Built with node-webcodecs by Paulo Proença
- Uses fabric.js for canvas rendering
- Inspired by the need for server-side video generation
Made with ❤️ for the video generation community