MotionMiner

Extract videos from Google Motion Photos with ease!

MotionMiner is a powerful Python tool that extracts embedded MP4 videos from Google Motion Photos (JPG files) and converts them to various formats including MP4 and GIF animations.

🚀 Features

• Extract MP4 videos from Google Motion Photos
• Convert to GIF animations with customizable quality settings
• Batch processing for multiple files
• Multiple output formats: MP4, GIF, or both
• Quality presets for GIF output (tiny, low, medium, high)
• File structure analysis to examine Motion Photo internals
• Cross-platform support (Windows, macOS, Linux)

📋 Requirements

• Python 3.6+
• FFmpeg (for video conversion)

🛠️ Installation

Method 1: Install from PyPI (Recommended)

pip install motionminer

Method 2: Install from Source

git clone https://github.com/yourusername/motionminer.git
cd motionminer
pip install -e .

Step 2: Install FFmpeg

FFmpeg is required for video processing. Choose your platform:

Windows

1. Download FFmpeg from https://ffmpeg.org/download.html
2. Extract to a folder (e.g., C:\ffmpeg)
3. Add the bin folder to your system PATH
4. Test installation: ffmpeg -version

macOS

# Using Homebrew
brew install ffmpeg

# Using MacPorts
port install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Linux (CentOS/RHEL/Fedora)

# CentOS/RHEL
sudo yum install ffmpeg

# Fedora
sudo dnf install ffmpeg

Step 3: Verify Installation

Test that everything is working:

motionminer --help

Or use the alternative command:

motion-extract --help

🎯 Usage

Basic Usage

Extract MP4 from a single Motion Photo:

motionminer photo.jpg

Extract as GIF animation:

motionminer photo.jpg --gif

Extract both MP4 and GIF:

motionminer photo.jpg --both

Output Options

Specify custom output filename:

motionminer photo.jpg -o my_video.mp4
motionminer photo.jpg -o my_animation.gif --gif

GIF Quality Settings

MotionMiner offers 4 quality presets for GIF output:

Quality	Colors	File Size	Description
--gif-tiny	64	~1-2MB	Maximum compression
--gif-low	128	~2-3MB	Heavy compression, decent quality
--gif-medium	192	~3-4MB	Balanced quality and size (default)
--gif-high	256	~5-7MB	Best quality

Examples:

motionminer photo.jpg --gif-tiny      # Small file size
motionminer photo.jpg --gif-high      # Best quality

Custom GIF Width

Adjust GIF width (height is automatically calculated):

motionminer photo.jpg --gif --gif-width 640

GIF Looping Control

By default, GIFs loop infinitely. Use --gif-no-loop to create a GIF that plays once:

motionminer photo.jpg --gif --gif-no-loop      # GIF plays once
motionminer photo.jpg --gif-high --gif-no-loop # High quality GIF that plays once

Batch Processing

Process all JPG files in a directory:

motionminer photos/ --batch

Batch process with custom output directory:

motionminer photos/ --batch --batch-output extracted_videos/

Batch convert to GIFs:

motionminer photos/ --batch --gif-low

File Analysis

Analyze Motion Photo structure without extracting:

motionminer photo.jpg --analyze

📖 Command Reference

Required Arguments

• input - Input JPG file or directory containing JPG files

Optional Arguments

• -o, --output [OUTPUT] - Output file path (auto-generated if not provided)
• -p, --photo [PATH] - Extract a standalone photo and save it to the specified PATH (PATH is optional, auto-generated if not provided)
• --mp4 - Extract as MP4 video (default)
• --gif - Extract as GIF animation
• --both - Extract both MP4 and GIF
• --gif-tiny - Extract as tiny GIF (64 colors, ~1-2MB)
• --gif-low - Extract as low quality GIF (128 colors, ~2-3MB)
• --gif-medium - Extract as medium quality GIF (192 colors, ~3-4MB)
• --gif-high - Extract as high quality GIF (256 colors, ~5-7MB)
• --gif-width - GIF width in pixels (default: 480)
• --gif-no-loop - Create GIF that plays once instead of looping infinitely
• --batch - Process all JPG files in input directory
• --batch-output - Output directory for batch processing
• --analyze - Analyze file structure without extracting

💡 Examples

Single File Examples

# Extract MP4 from Motion Photo
motionminer IMG_20231201_123456.jpg

# Extract MP4 and standalone JPEG
motionminer IMG_20231201_123456.jpg --photo

# Extract high-quality GIF
motionminer IMG_20231201_123456.jpg --gif-high

# Extract GIF that plays once (no loop)
motionminer IMG_20231201_123456.jpg --gif --gif-no-loop

# Extract both video formats with custom output
motionminer motion_photo.jpg --both -o my_video.mp4

# Extract both video formats and standalone JPEG with custom output
motionminer motion_photo.jpg --both -o my_video.mp4 -p my_photo.jpg

# Analyze file structure
motionminer motion_photo.jpg --analyze

Batch Processing Examples

# Process all photos in current directory
motionminer . --batch

# Process photos and save to specific directory
motionminer photos/ --batch --batch-output extracted/

# Batch convert to tiny GIFs for web use
motionminer photos/ --batch --gif-tiny --batch-output web_gifs/

# Process with custom GIF settings
motionminer photos/ --batch --gif --gif-width 320 --batch-output small_gifs/

# Batch convert to non-looping GIFs
motionminer photos/ --batch --gif-medium --gif-no-loop --batch-output single_play_gifs/

🔧 Troubleshooting

Common Issues

"No embedded MP4 video found"

• The file might not be a Google Motion Photo
• Some Motion Photos have different internal structures
• Use --analyze to examine the file structure

"FFmpeg not found"

• Make sure FFmpeg is installed and in your system PATH
• Test with ffmpeg -version in your terminal

"Permission denied"

• Check file permissions for input files
• Ensure you have write permissions in the output directory

Getting Help

View all available options:

motionminer --help

📁 Project Structure

MotionMiner/
├── motionminer/        # Main package directory
│   ├── __init__.py     # Package initialization
│   ├── main.py         # Main application entry point
│   ├── cli.py          # Command-line interface
│   ├── extractor.py    # Motion Photo extraction logic
│   ├── converter.py    # Video conversion utilities
│   ├── analyzer.py     # File structure analysis
│   └── config.py       # Configuration and settings
├── tests/              # Test suite
├── pyproject.toml      # Package configuration
├── requirements.txt    # Python dependencies
└── README.md           # This file

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

This project is licensed under the terms specified in the LICENSE file.

🙏 Acknowledgments

• Thanks to Google for creating Motion Photos
• FFmpeg community for excellent video processing tools
• Python community for amazing libraries

---

Happy extracting! 🎬✨