Overview
Video Composition is the final stage where all generated assets (slides, animations, images, audio) are assembled into a single, synchronized video file. The system uses MoviePy (a Python wrapper for FFmpeg) to handle timeline management, video concatenation, and audio synchronization.How It Works
High-Level Process
- Load Slide Clips: Each slide becomes a video clip (either image or animation)
- Apply Durations: Clips are timed according to narration length
- Composite Animations: Manim videos are overlaid onto slide templates
- Concatenate Clips: All slides are joined sequentially
- Sync Audio: Complete narration audio is attached to video
- Export Final Video: Render as MP4 with H.264 video and AAC audio
The composition process ensures perfect audio-video synchronization by using narration timing from the script data to set clip durations.
Timeline Synchronization
Slide Timing Calculation
Each slide’s duration is determined by its narration timing:Timeline Structure
Thescript_data contains precise timing information:
Slide Processing
Creating Slide Clips
Each slide is converted to a video clip:Handling Different Media Types
| Media Type | Processing |
|---|---|
| Static Image | Creates ImageClip with specified duration |
| Animation Video | Loads VideoFileClip, adjusts duration |
| Animation + Slide | Composites animation onto slide template |
| Missing Asset | Generates blank colored clip |
Animation Compositing
Overlay Process
When a slide has both a base slide image and an animation, they are composited:Animation Duration Handling
Scenario 1: Animation shorter than narration- Action: Loop animation seamlessly
- Example: 3s animation, 9s narration → animation plays 3 times
- Action: Trim animation to match narration
- Example: 8s animation, 5s narration → first 5s used
- Action: Use animation as-is
Concatenation
Joining Slide Clips
All processed slides are concatenated sequentially:compose
- Ensures consistent resolution across clips
- Handles clips of different types (image, video, composite)
- Maintains frame rate throughout
The
method="compose" parameter ensures all clips are rendered at the same resolution (1920x1080) even if source dimensions vary.Audio Integration
Attaching Narration
The complete audio track is synced to the video:Audio Sync Validation
- Tolerance: ±0.5 seconds
- Warning Trigger: Duration mismatch exceeds tolerance
- Common Causes:
- Slide durations don’t match audio chunks
- Audio generation had truncation or errors
- Manual edits to slide timing
FFmpeg Export
Final Rendering
The composed video is exported using FFmpeg via MoviePy:Export Configuration
| Parameter | Value | Purpose |
|---|---|---|
| fps | 30 | Frames per second (matches Manim renders) |
| codec | libx264 | H.264 video compression (widely compatible) |
| audio_codec | aac | Advanced Audio Coding (industry standard) |
| preset | medium | Balanced encoding speed vs quality |
| bitrate | 5000k | 5 Mbps video quality (HD quality) |
| audio_bitrate | 192k | High-quality audio (near CD quality) |
FFmpeg Presets
You can adjust thepreset parameter for different use cases:
- ultrafast: Fastest encoding, largest file size
- fast: Quick encoding, larger file
- medium: Balanced (default)
- slow: Better compression, smaller file
- veryslow: Best compression, takes longest
Output Structure
Final Video Path
- Spaces → Underscores
- Colons, slashes → Removed
- Quotes, question marks → Removed
- Max 30 characters
Video Specifications
- Container: MP4 (MPEG-4 Part 14)
- Video Codec: H.264 (AVC)
- Audio Codec: AAC
- Resolution: 1920x1080 (Full HD)
- Aspect Ratio: 16:9
- Frame Rate: 30 FPS
- Typical File Size: 50-200 MB for 1-5 minute video
Cleanup
Resource Management
After export, all video clips are properly closed to free memory:Error Handling
Common Issues
No slide clips created:- Cause: All slides missing visual assets
- Solution: Check that images/animations were generated
- Cause: Slide timing doesn’t match audio
- Solution: Regenerate audio or adjust slide durations
- Cause: Missing FFmpeg installation or codec issues
- Solution: Verify FFmpeg with
ffmpeg -version
Performance Optimization
Rendering Speed Tips
-
Use Lower Quality During Testing
-
Process Slides in Parallel (Future Enhancement)
- Current: Sequential processing
- Potential: Parallel clip creation with threading
-
Cache Intermediate Renders
- Reuse slide clips if content hasn’t changed
- Skip regeneration of unchanged animations
Memory Management
- Large Presentations: Close clips immediately after concatenation
- Multiple Videos: Run garbage collection between generations
- Animation Loops: Use
concatenate_videoclipsinstead of manual looping
Customization Options
Output Resolution
Change resolution inconfig.py:
Animation Placement
Modify animation position/size invideo_composer.py:361-362:
Troubleshooting
Video Export Fails
Symptom: Error duringwrite_videofile()
Solutions:
- Verify FFmpeg is installed:
ffmpeg -version - Check disk space (exports need 2-3x final size temporarily)
- Ensure output directory exists and is writable
- Try different preset:
preset='ultrafast'
Audio Not Playing
Symptom: Video renders but no audio in final MP4 Solutions:- Verify audio file exists and is valid WAV
- Check audio codec support: use
'aac'not'mp3' - Test audio separately:
ffplay <audio_path>
Animations Mispositioned
Symptom: Animation appears in wrong location or cut off Solutions:- Verify slide template dimensions (should have placeholder)
- Adjust position coordinates in
composite_animation_on_slide() - Check animation resolution matches expected size (850x700)
Related Features
- Content Generation - Provides slide structure and timing requirements
- Voice Narration - Generates audio track that drives timeline
- Visual Media - Creates animation and image assets for composition