Skip to content
/ frame_reshuffler Public

A powerful Python CLI tool for splitting video files into multiple frame-separated streams with customizable frame distribution patterns.

License

MIT license
5 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

videofeedback/frame_reshuffler

BranchesTags

Repository files navigation

🎬 Frame Reshuffler

Python 3.7+ License: MIT Video Processing Platform Support

A powerful Python CLI tool for splitting video files into multiple frame-separated streams with customizable frame distribution patterns.

Perfect for video feedback artists, experimental filmmakers, and anyone working with temporal video manipulation techniques. Handles iPhone slow-motion videos, preserves original quality, and supports all modern video formats.

✨ Features

  • 🎯 Smart Frame Distribution: Split videos into 2, 3, or 4 separate files
  • ⚡ High Performance: Fast frame extraction (3000+ FPS) with beautiful progress bars
  • 📊 Intelligent FPS Handling: Automatically adjusts frame rates and preserves existing FPS metadata
  • 🎯 FPS Override Support: Override detected FPS with original shooting rate (perfect for iPhone slow-motion)
  • 🎬 Quality Preservation: Maintains original codec, bitrate, and video settings (no degradation)
  • 🔍 Smart File Validation: Automatically detects and skips non-video files (like HEIC images)
  • 📁 Organized Output: Clean folder structure with automatic file management
  • 📝 Comprehensive Logging: Detailed processing logs with timestamps and metadata
  • 🎨 Beautiful CLI Interface: Colorful ASCII art and intuitive user prompts
  • 🔄 Audio Preservation: Maintains original audio in the first output file
  • 🛡️ Error Handling: Robust fallback mechanisms for various video formats

🚀 Quick Start

System Requirements

  • Python: 3.7 or higher
  • Operating System: Windows 10+, macOS 10.14+, or Linux (Ubuntu 18.04+)
  • Memory: 4GB RAM minimum (8GB recommended for 4K videos)
  • Storage: 2x the size of your largest video file

Installation

Option 1: One-Command Installation (Recommended)

# Clone and install in one command
git clone https://github.com/videofeedback/frame-reshuffler.git && cd frame-reshuffler && pip install -r requirements.txt

Option 2: Step-by-Step Installation

  1. Clone the repository:

    git clone https://github.com/videofeedback/frame-reshuffler.git
cd frame-reshuffler

  2. Install Python dependencies:

    pip install -r requirements.txt

  3. Make script executable (macOS/Linux):

    chmod +x frame_reshuffler.py

Option 3: Virtual Environment (Recommended for developers)

# Clone repository
git clone https://github.com/videofeedback/frame-reshuffler.git
cd frame-reshuffler

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\\Scripts\\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Dependencies Explained

Package Purpose Version
opencv-python Video frame extraction and processing 4.9.0.80
moviepy Advanced video operations and codec handling 1.0.3
tqdm Progress bars and processing feedback 4.66.1
colorama Cross-platform colored terminal output 0.4.6
numpy Efficient array operations 1.24.3

🔧 Installation Troubleshooting

Common Issues and Solutions

Issue: pip: command not found

# Try pip3 instead
pip3 install -r requirements.txt

# Or install pip
python -m pip install -r requirements.txt

Issue: Permission denied on macOS/Linux

# Use user installation
pip install --user -r requirements.txt

# Or use sudo (not recommended)
sudo pip install -r requirements.txt

Issue: OpenCV installation fails

# Try alternative OpenCV package
pip install opencv-python-headless

# Or use conda
conda install opencv

Issue: MoviePy ffmpeg errors

# Install ffmpeg separately
# macOS with Homebrew:
brew install ffmpeg

# Ubuntu/Debian:
sudo apt update && sudo apt install ffmpeg

# Windows: Download from https://ffmpeg.org/download.html

Issue: Memory errors with large videos

  • Solution: Process videos in smaller chunks or upgrade RAM
  • Alternative: Use lower resolution videos for testing

📖 Usage Guide

Basic Usage

  1. Place your video files in the Input/ folder
  2. Run the script: 
    python3 frame_reshuffler.py
  3. Choose your split option (2, 3, or 4-way)
  4. Optional: Enter original shooting FPS if known (e.g., iPhone 120fps → 30fps)
  5. Find processed videos in Processed/[video_name]/
  6. Original files are moved to Done/ folder

Advanced Usage Examples

iPhone Slow-Motion Processing

# When you have iPhone 120fps videos slowed to 30fps:
python3 frame_reshuffler.py
# Select: 2 splits
# FPS Override: 120
# Result: 2x 60fps videos (correct speed)

Batch Processing Multiple Videos

# Place multiple videos in Input/ folder
python3 frame_reshuffler.py
# The tool will process all videos in sequence

Custom Project Structure

# You can copy the script to any folder and run it there
cp frame_reshuffler.py /path/to/your/project/
cd /path/to/your/project/
python3 frame_reshuffler.py

📊 How It Works

Frame Distribution Patterns

2-Way Split (Even/Odd)

  • File A: Even frames (0, 2, 4, 6, ...)
  • File B: Odd frames (1, 3, 5, 7, ...)
  • New FPS: Original FPS ÷ 2

3-Way Split

  • File A: Frames 0, 3, 6, 9, ...
  • File B: Frames 1, 4, 7, 10, ...
  • File C: Frames 2, 5, 8, 11, ...
  • New FPS: Original FPS ÷ 3

4-Way Split

  • File A: Frames 0, 4, 8, 12, ...
  • File B: Frames 1, 5, 9, 13, ...
  • File C: Frames 2, 6, 10, 14, ...
  • File D: Frames 3, 7, 11, 15, ...
  • New FPS: Original FPS ÷ 4

FPS Override Feature

Perfect for handling slow-motion videos that have been processed by cameras:

iPhone Slow Motion Example:

  • Original shooting: 120 FPS
  • iPhone slows to: 30 FPS (4x slower)
  • Frame Reshuffler detects: 30 FPS
  • Your input: 120 FPS override
  • Result: Split videos at 60 FPS each (maintaining original timing)

Without Override: 2x 15 FPS videos (too slow) With Override: 2x 60 FPS videos (correct speed)

🏗️ Project Structure

frame-reshuffler/
├── frame_reshuffler.py     # Main application script
├── requirements.txt        # Python dependencies
├── README.md              # This documentation
├── CONTRIBUTING.md        # Contribution guidelines
├── LICENSE                # MIT license
├── .gitignore            # Git ignore rules
├── Input/                # Place your videos here
│   └── .gitkeep          # Keeps folder in git
├── Processed/            # Split videos output
│   ├── processing_log.txt # Detailed processing logs
│   └── [video_name]/     # Individual video results
└── Done/                 # Processed originals with FPS metadata
    └── .gitkeep          # Keeps folder in git

File Naming Convention

Original: my_video.mp4 (30 FPS)

After 2-way split:

  • Processed folder:
    • my_video_A_Frame_FPS_15.mp4
    • my_video_B_Frame_FPS_15.mp4
  • Done folder:
    • my_video_FPS_30.mp4

Processing Log Sample

========================================
Timestamp: 2025-09-23 00:21:11
Original File: iphone_slowmo.MOV
Detected FPS: 30.00
FPS Override: 120.00 (user specified original shooting rate)
Effective FPS: 120.00
Original Frames: 1800
Processing Duration: 15.00 seconds
Resolution: 1920x1080
Split Type: 2-way

Output Files:
- iphone_slowmo_A_Frame_FPS_60.mp4 (900 frames, 15.00s)
- iphone_slowmo_B_Frame_FPS_60.mp4 (900 frames, 15.00s)

Processing Time: 12.3 seconds
Status: Success
========================================

🎛️ CLI Interface

The tool features a beautiful ASCII art interface with:

  • 🎨 Colorful banner and prompts with cross-platform support
  • 📊 Real-time progress bars for frame extraction and video creation
  • ✅ Success/error indicators with clear messaging
  • 📈 Processing statistics and timing information
  • 🔍 File validation with skip notifications

🔧 Technical Details

Supported Formats

Input: .mp4, .avi, .mov, .mkv, .flv, .wmv, .webm, .heic*, .hevc, .h265, .m4v

*Note: HEIC files are typically images, but the tool will attempt to process them if they contain video data

Output: .mp4 (preserves original codec: H.264, H.265/HEVC, MPEG-4, etc.)

Performance Benchmarks

  • Frame Extraction: 3,000-4,000 FPS (depending on video resolution)
  • Video Writing: 80-100 FPS with OpenCV fallback
  • Memory Usage: Efficient frame-by-frame processing
  • Quality: Zero degradation with original codec preservation

Dependencies Deep Dive

  • OpenCV (opencv-python): High-performance video frame extraction and writing
  • MoviePy (moviepy): Advanced video processing, codec detection, and audio handling
  • tqdm: Beautiful progress bars with detailed timing information
  • colorama: Cross-platform colored terminal output (Windows, macOS, Linux)
  • NumPy: Efficient array operations for frame data

🛠️ Advanced Features

Quality Preservation

  • Original Codec Preservation: Automatically detects and maintains H.264, H.265/HEVC, MPEG-4, and other codecs
  • Bitrate Preservation: Maintains original video bitrate to prevent quality loss
  • High-Quality Encoding: Uses CRF 18 (visually lossless) when re-encoding is necessary
  • No Transcoding When Possible: Preserves original encoding parameters

Smart FPS Handling

  • Automatically detects existing FPS metadata in filenames
  • FPS Override Feature: Enter original shooting rate when video has been slowed down
  • Perfect for iPhone slow-motion: 120fps → 30fps, 240fps → 60fps videos
  • Preserves correct FPS information without duplication
  • Validates filename FPS against actual video properties

Audio Processing

  • Maintains original audio track in the first output file (A_Frame)
  • Preserves original audio codec and quality
  • Handles audio duration synchronization automatically
  • Graceful fallback when audio processing fails

File Validation

  • Automatic Detection: Validates files before processing to ensure they contain video data
  • Smart Skipping: Gracefully skips image files (HEIC, JPG, PNG) with clear user feedback
  • Format Recognition: Identifies and handles various video container formats correctly

Error Recovery

  • OpenCV fallback when MoviePy encounters compatibility issues
  • Comprehensive error logging for troubleshooting
  • Automatic cleanup of temporary files
  • Detailed error messages with suggested solutions

🎯 Use Cases

Virtual Production

Create alternative views for live previsualization. Perfect for creating temporal offsets and frame-rate variations.

Experimental Film

Generate alternating temporal sequences for artistic video manipulation and non-linear storytelling. Create unique visual effects through frame redistribution.

Technical Analysis

Split high-speed footage into separate streams for detailed frame-by-frame analysis. Ideal for motion studies and scientific video analysis.

Content Creation

Create multi-angle effects by processing the same source material with different temporal offsets. Perfect for social media content and video art.

iPhone Slow-Motion Processing

Handle iPhone slow-motion videos correctly by specifying the original shooting rate, ensuring proper frame timing in output videos.

🔧 Troubleshooting

Common Issues

Script doesn't start

# Check Python version
python3 --version

# Should be 3.7 or higher
# If not, install Python 3.7+

No videos found

  • Ensure videos are in the Input/ folder
  • Check supported formats: MP4, AVI, MOV, MKV, etc.
  • Verify files aren't corrupted

Out of memory errors

  • Close other applications
  • Process smaller videos first
  • Consider upgrading RAM

Slow processing

  • Normal for 4K videos
  • Close other applications
  • Use SSD storage for better performance

Audio sync issues

  • Use FPS override for slow-motion videos
  • Ensure original video has proper audio

Permission errors

# Make script executable
chmod +x frame_reshuffler.py

# Or run with python3
python3 frame_reshuffler.py

Getting Help

  1. Check the processing log in Processed/processing_log.txt
  2. Review error messages for specific solutions
  3. Try with a smaller test video first
  4. Check system requirements and dependencies

🤝 Contributing

We welcome contributions from the video art and open source communities!

Quick Contribution Guide

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes with proper comments and documentation
  4. Test thoroughly with various video formats
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/your-username/frame-reshuffler.git
cd frame-reshuffler

# Create development environment
python -m venv dev-env
source dev-env/bin/activate  # or dev-env\Scripts\activate on Windows

# Install in development mode
pip install -e .
pip install -r requirements.txt

# Run tests
python -m pytest tests/

Contribution Areas

High Priority:

  • Additional video format support
  • Performance optimizations
  • Cross-platform testing
  • GUI interface development

Documentation:

  • Video tutorials and examples
  • Performance benchmarks
  • Use case documentation

For detailed contribution guidelines, see CONTRIBUTING.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary

  • ✅ Commercial use - Use in commercial projects
  • ✅ Modification - Modify and distribute
  • ✅ Distribution - Share with others
  • ✅ Private use - Use for personal projects
  • ❌ Liability - No warranty provided
  • ❌ Trademark use - No trademark rights

🙏 Acknowledgments

  • Built with ❤️ for the Virtual Production Community and experimental film Community
  • Special thanks to the OpenCV and MoviePy communities
  • Created for artists, filmmakers, and video enthusiasts worldwide

📞 Support & Community

Getting Support

  • 🐛 Bug Reports: GitHub Issues
  • 💡 Feature Requests: GitHub Discussions
  • 📖 Documentation: This README and inline code comments
  • 🆘 Help: Check the troubleshooting section above

Community

  • 🎬 Virtual Production Artists: Share your creations!
  • 🎭 Experimental Filmmakers: Document your techniques
  • 👨‍💻 Developers: Contribute improvements and new features
  • 🎨 Digital Artists: Explore new temporal manipulation techniques

Made for VP artists and experimental filmmakers worldwide 🌍✨

Frame Reshuffler - Where temporal art meets technical precision

About

A powerful Python CLI tool for splitting video files into multiple frame-separated streams with customizable frame distribution patterns.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages