Spatial Video Maker

Convert 2D videos to stereoscopic 3D spatial videos for Apple Vision Pro using AI depth estimation. Runs locally on macOS with Apple Silicon Metal acceleration.

Installation

uv tool install spatial-maker

Requirements

• macOS with Apple Silicon (for Metal acceleration)
• ffmpeg with VideoToolbox support
• spatial CLI for MV-HEVC output

brew install ffmpeg spatial

Model Checkpoints

Download Depth Anything V2 checkpoints:

mkdir -p ~/.spatial-maker/checkpoints

# Small (fastest, 24.8M params)
curl -L -o ~/.spatial-maker/checkpoints/depth_anything_v2_vits.pth \
  https://huggingface.co/depth-anything/Depth-Anything-V2-Small/resolve/main/depth_anything_v2_vits.pth

# Base (balanced, 97.5M params)
curl -L -o ~/.spatial-maker/checkpoints/depth_anything_v2_vitb.pth \
  https://huggingface.co/depth-anything/Depth-Anything-V2-Base/resolve/main/depth_anything_v2_vitb.pth

# Large (best quality, 335.3M params)
curl -L -o ~/.spatial-maker/checkpoints/depth_anything_v2_vitl.pth \
  https://huggingface.co/depth-anything/Depth-Anything-V2-Large/resolve/main/depth_anything_v2_vitl.pth

You only need the model sizes you plan to use. vits (small) is a good default.

Usage

# Single file
spatial-maker video.mp4

# Specify output path
spatial-maker video.mp4 -o output_spatial.mov

# Process all videos in a folder
spatial-maker /path/to/videos/

Options

# Depth model size: vits (fast), vitb (balanced), vitl (best)
spatial-maker video.mp4 --encoder vitl

# 3D intensity in pixels (20-50 recommended)
spatial-maker video.mp4 --max-disparity 40

# Process only first 10 seconds (for testing)
spatial-maker video.mp4 --duration 10

# Skip downscaling (if input is already 1080p@24fps)
spatial-maker video.mp4 --skip-downscale

# Keep intermediate files
spatial-maker video.mp4 --keep-intermediate

# JSON progress output (for GUI integration)
spatial-maker video.mp4 --json-progress

Pipeline

Input 2D Video
    |
[Downscale to 1080p @ 24fps]
    |
[Depth estimation + stereo pair creation (Depth Anything V2 + DIBR)]
    |
[Audio extraction + muxing]
    |
[MV-HEVC spatial video via spatial CLI]
    |
Spatial Video (.mov)

Parameters

3D Intensity Guide

• 20-30: Subtle, comfortable for long viewing
• 30-40: Moderate, good balance
• 40-50: Strong, more immersive

Development

git clone https://github.com/mrgnw/spatial-maker.git
cd spatial-maker
uv sync
uv run spatial-maker video.mp4

Acknowledgments

• Depth Anything V2 by Yang et al.
• spatial by Mike Swanson

License

MIT