Overview
TheVideoWriter class is responsible for composing multiple clips into a final video. It handles:
- Rendering visual clips (video, image, text, composite)
- Mixing audio tracks
- Encoding the output with configurable quality
- Multi-process rendering for performance
Basic Usage
VideoWriter Configuration
Constructor Parameters
If
size or duration are not specified, they are automatically calculated from the added clips.Auto-Calculated Properties
src/movielite/core/video_writer.py:28
Adding Clips
Single Clip
Multiple Clips
Clip Types
VideoWriter automatically handles:- GraphicClip subclasses (VideoClip, ImageClip, TextClip, CompositeClip)
- AudioClip instances
- Video audio - automatically extracts and mixes audio from VideoClip instances
When you add a
VideoClip, its audio track is automatically added to the audio mix. You don’t need to manually add video.audio.Rendering Process
Basic Rendering
Quality Presets
MovieLite provides four quality levels:Quality Preset Details
Quality Preset Details
Quality presets control FFmpeg’s libx264 encoder:
CRF (Constant Rate Factor): Lower = better quality, larger files. Range: 0-51, typical: 17-28.Source:
| Quality | Preset | CRF | Use Case |
|---|---|---|---|
| LOW | ultrafast | 23 | Quick previews, draft renders |
| MIDDLE | veryfast | 21 | General use, balanced quality/speed |
| HIGH | fast | 19 | Production quality |
| VERY_HIGH | slow | 17 | Maximum quality, archival |
src/movielite/core/video_writer.py:441Multi-Process Rendering
Speed up rendering by distributing work across multiple CPU cores:High Precision Blending
For complex compositions with many transparent layers:When to use high precision:
- Compositing 5+ layers with transparency
- Subtle gradients and color blending
- Professional color accuracy required
- Uses float32 (4x more memory than uint8)
- Slower rendering
- Prevents color banding artifacts
src/movielite/core/video_writer.py:91
Composition Mechanics
Layer Ordering
Clips are composited in the order they’re added:Render Pipeline
For each frame, VideoWriter:- Identifies active clips - clips where
start <= current_time < end - Renders background - first active clip rendered as base
- Composites overlays - remaining clips blended on top
- Applies transformations - position, scale, opacity, effects
- Encodes frame - writes to FFmpeg pipe
src/movielite/core/video_writer.py:162
Alpha Blending
Transparency is handled automatically:Blending Implementation Details
Blending Implementation Details
MovieLite uses numba-compiled blending functions for performance:
- BGR background: Blends RGB channels, alpha affects blend amount
- BGRA background: Full alpha compositing with premultiplied alpha
- Mask support: Additional mask layer multiplies with clip’s alpha
src/movielite/core/graphic_clip.py:657 for implementation.Audio Mixing
VideoWriter automatically mixes all audio sources:Audio Mixing Process
- Determine target format - highest sample rate and channel count among clips
- Resample if needed - convert all clips to target sample rate
- Channel conversion - mono to stereo or stereo to mono as needed
- Mix samples - sum overlapping audio, accounting for clip timing and speed
- Normalize - prevent clipping by normalizing if peak > 1.0
- Encode - convert to AAC and mux with video
src/movielite/core/video_writer.py:279
Audio is processed in 10-second chunks to keep memory usage low, even for long videos.
Progress Tracking
VideoWriter usestqdm for progress bars:
Complete Example
Performance Tips
Multi-Process Rendering
Use
processes=cpu_count() for videos longer than 30 seconds. Each process renders a segment independently.Quality Selection
Use
VideoQuality.MIDDLE for general use. Reserve VERY_HIGH for final renders only.High Precision
Only enable
high_precision_blending=True when compositing many transparent layers. It uses 4x more memory.Clip Ordering
Place background clips first in
add_clips(). The first active clip is optimized as the background layer.Troubleshooting
FFmpeg not found
FFmpeg not found
Ensure FFmpeg is installed and in your PATH:
Out of memory errors
Out of memory errors
For long videos or high resolutions:
- Reduce the number of parallel processes
- Use
high_precision_blending=False - Lower the output resolution
- Close other applications
Audio sync issues
Audio sync issues
If audio is out of sync:
- Ensure all clips have correct
starttimes - Check that
set_speed()is applied to both video and audio - Verify source videos don’t have variable frame rates
Related Resources
Clips
Learn about different clip types
Effects
Apply visual and audio effects
Audio Mixing
Advanced audio mixing techniques