Disney Vlog + Mapbox Integration

Automatically generate a cinematic vlog video from iPhone MP4 clips with Mapbox map transitions between scenes.

Features

• 🎬 Automatic Metadata Extraction: Extracts timestamps from iPhone MP4 videos (uses recording date)
• 🗺️ Mapbox Transitions: Generates static map images with animated dot transitions between scenes
• 📍 Location Inheritance: Scenes inherit location from previous scene if not specified
• 🎥 Remotion Composition: Creates a professional vlog video with smooth transitions
• ⚡ Smart Transitions: Only shows map transitions when location actually changes

Setup

1. Install Dependencies

   npm install

2. Configure Mapbox Token

   cp .env.example .env
   # Edit .env and add your MAPBOX_ACCESS_TOKEN

3. Add Your Videos

   • Place your iPhone MP4 videos in assets/videos/
   • Videos will be automatically sorted by recording timestamp

Usage

Workflow

1. Extract Metadata

   npm run extract-metadata

   • Scans assets/videos/ for MP4 files
   • Extracts timestamps (uses recording date from DateTimeOriginal)
   • Generates data/scenes.json with all scenes sorted chronologically

2. Add Location Annotations

   • Edit data/locations.json
   • Add video-to-location mappings in videoLocations:

   {
     "videoLocations": {
       "IMG_9843.mp4": "LGA",  // Use alias
       "IMG_9845.mp4": "MCO",
       "IMG_9863.mp4": "MAGIC_KINGDOM",
       "IMG_9883.mp4": { "lat": 28.3714061, "lng": -81.5489587 }  // Or direct coordinates
     }
   }

   • Available aliases: LGA, MCO, HYATT_HOTEL, DISNEY_SPRINGS, MAGIC_KINGDOM, ANIMAL_KINGDOM, EPCOT, HOLLYWOOD_STUDIOS
   • Scenes without location annotations inherit from the previous scene
   • Only add locations for scenes where the location changes (park transitions)

3. Generate Maps

   npm run generate-maps

   • Creates Mapbox static images only for transitions where location changes
   • Skips transitions when consecutive scenes have the same location
   • Saves maps to assets/maps/ and metadata to data/maps.json

4. Preview

   npm run remotion:preview

   • Opens Remotion Studio for preview
   • Map transitions only appear when location changes between scenes

5. Render

   npm run remotion:render

   • Renders final video to out/vlog.mp4 (1080p)

Project Structure

disney/
├── assets/
│   ├── videos/          # Your iPhone MP4 files
│   └── maps/            # Generated Mapbox images
├── data/
│   ├── scenes.json      # Auto-generated scene metadata (timestamps)
│   ├── locations.json   # Location aliases and video-to-location mappings
│   └── maps.json        # Generated map metadata (pixel coordinates, etc.)
├── src/
│   ├── compositions/    # Remotion components
│   ├── scripts/         # CLI tools
│   ├── utils/           # Utilities (metadata, mapbox, location resolver)
│   └── types/           # TypeScript types
└── out/                 # Rendered video output

Requirements

• Node.js 18+
• Mapbox access token (get one at https://mapbox.com)
• iPhone MP4 videos (timestamps extracted automatically)

How It Works

Location Resolution Priority

1. Video Location Mapping: Check locations.json → videoLocations[videoFilename]
   • If alias string (e.g., "MAGIC_KINGDOM") → resolve from aliases dictionary
   • If Location object → use directly
2. Scene Location: Fallback to scene.location in scenes.json (if manually added)
3. Inheritance: If neither exists, inherit location from previous scene
4. Undefined: Only undefined if no previous scene to inherit from

Map Transitions

• Maps are only generated/rendered when location changes between consecutive scenes
• If scene A and scene B have the same location, no transition is shown
• This prevents unnecessary transitions when staying at the same park/location

Notes

• Timestamps are extracted from video recording date (DateTimeOriginal field)
• Location annotations are stored in data/locations.json for easy editing
• Map images are cached - won't re-download if they exist
• Mapbox free tier: 100k requests/month (plenty for this project)
• Map images are generated at 1280x720 (within Mapbox API limits) and scaled in Remotion