VR renamer tool

VR Video Format Detector & Renamer

Automatic VR video format detection and renaming tool using simple machine learning.

Feel like saying thank you? Support me here: https://ko-fi.com/k00gar

Features

• ML-based detection: Uses Random Forest classifier trained on quite some videos
• Detects: Projection type (fisheye, 180°), layout (SBS/TB), alpha channel (including alpha-packed)
• Fast: ~5 seconds per video (optimized FFmpeg extraction)
• Batch processing: Process single files or entire directories recursively
• Safe operation: Dry-run mode by default - preview changes before applying
• Cross-platform: Works on Windows, macOS, Linux

Requirements

• Python 3.7+
• ffmpeg/ffprobe (must be in PATH)
• Dependencies: pip install scikit-learn numpy opencv-python

Quick Start

Analyze a single video (dry-run):

python3 vr_rename.py video.mp4

Output example:

============================================================
File: video.mp4
Resolution: 5760x2880
Video Type: VR
Projection: fisheye
Layout: sbs
FOV: 190°
Alpha: Yes
Suggested name: video_FISHEYE_SBS_ALPHA.mp4

Rename a single video:

python3 vr_rename.py video.mp4 --rename

Process entire directory:

python3 vr_rename.py /path/to/videos/

Recursively process all subdirectories:

python3 vr_rename.py /path/to/videos/ --recursive --rename

Usage

usage: vr_rename.py [-h] [-r] [--rename] [-v] [-m MODEL] path

positional arguments:
  path                  Video file or directory path

optional arguments:
  -h, --help            show this help message and exit
  -r, --recursive       Process directories recursively
  --rename              Actually rename files (default is dry-run)
  -v, --verbose         Verbose output
  -m MODEL, --model MODEL
                        Path to model file (default: vr_detector_model_rf.pkl)

Supported Formats

• Projections: fisheye, hemisphere (180°)
• Layouts: SBS (side-by-side), TB (top-bottom)
• Alpha channel: Detects both native alpha and alpha-packed (fisheye only)
• Video formats: MP4, MKV, AVI, MOV, WebM, M4V

Naming Convention

Generated filenames follow the pattern:

{original_name}_{PROJECTION}_{LAYOUT}_{ALPHA}.{ext}

Examples:

• video_FISHEYE_SBS.mp4
• scene_180_TB.mkv
• movie_FISHEYE_SBS_ALPHA.mp4

Existing VR format tags in filenames are automatically cleaned up before adding new tags.

Model Information

• Type: Random Forest Classifier
• Training samples: 883 videos with manual validation
• Features: Histogram correlation, edge detection, brightness analysis (20 features)
• Performance: ~5 seconds per video (4K-8K)

Troubleshooting

"Model file not found"

• Ensure vr_detector_model_rf.pkl is in the same directory as the script

"ffprobe: command not found"

• Install ffmpeg: https://ffmpeg.org/download.html
• Ensure ffmpeg/ffprobe are in your system PATH

"Could not analyze video"

• Video file may be corrupted or unsupported format
• Check file permissions

Safety Features

• Dry-run by default: Preview changes before applying
• Error handling: Continues processing other files if one fails
• Verbose logging: Track what's happening with -v flag

License

Free to use and modify.

models-v1.1.0

Merge pull request #24 from gavonmothma/patch-3

Update README.md