{"id":15093499,"url":"https://github.com/paulpierre/autocrop","last_synced_at":"2025-04-12T07:41:56.447Z","repository":{"id":257016548,"uuid":"857094223","full_name":"paulpierre/autocrop","owner":"paulpierre","description":"🎬 Automagically crop a video clip within another video clip","archived":false,"fork":false,"pushed_at":"2024-09-24T14:30:28.000Z","size":12218,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T02:51:12.392Z","etag":null,"topics":["autocrop","autocropper","crop","cropper","cv","cv2","ffmpeg","mp4","mp4-video","python","video","video-editing","videocropper"],"latest_commit_sha":null,"homepage":"https://paulpierre.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulpierre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-13T19:42:20.000Z","updated_at":"2025-03-11T20:26:22.000Z","dependencies_parsed_at":"2024-10-14T05:41:37.186Z","dependency_job_id":"5a405ef3-7a4c-4b4c-adc6-7396e0deaf1d","html_url":"https://github.com/paulpierre/autocrop","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"5331f9c38d5c07ae801aeefeba739a5731d937d4"},"previous_names":["paulpierre/autocrop"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulpierre%2Fautocrop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulpierre%2Fautocrop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulpierre%2Fautocrop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulpierre%2Fautocrop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulpierre","download_url":"https://codeload.github.com/paulpierre/autocrop/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248536981,"owners_count":21120683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocrop","autocropper","crop","cropper","cv","cv2","ffmpeg","mp4","mp4-video","python","video","video-editing","videocropper"],"created_at":"2024-09-25T11:23:40.931Z","updated_at":"2025-04-12T07:41:56.426Z","avatar_url":"https://github.com/paulpierre.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# 🎬 autocrop\nAutomagically crop a video clip within a video clip\n\n![AutoCrop](https://github.com/paulpierre/autocrop/raw/main/autocrop.png)\n\n\n## Overview\nYou know that feeling when you [spend 30 minutes looking for something](https://github.com/paulpierre/autocrop/blob/main/RESEARCH.MD) and realize \"hm, no way no one has built it, if it's taking this long to find it..\"\nAnd then you just build it? Yep\n\n## ⚡ Quickstart\nLet's do some quick showing vs telling w/ an example:\n\n❗ Note: This assumes you've ran through the setup below\n\nLets take a look at [this meme](https://www.instagram.com/reel/C_JHU6QNhm3/?hl=en) instagram reel from [@memes](https://www.instagram.com/memes/)\n\nHere is the original video in the `./demo` directory:\n\n\u003ca href=\"https://imgur.com/L1gL7ue\"\u003e\n    \u003cimg src=\"https://github.com/paulpierre/autocrop/blob/main/demo/memes_ig_john_cena.png\" alt=\"John Cena uncropped\" style=\"width: 300px;\"\u003e\n\u003c/a\u003e\n\nWe run `autocrop` with the following command:\n\n```bash\npython autocrop-cli.py --video_path ./demo/memes_ig_john_cena.mp4\n```\n\nAnd here is the output of `autocrop`:\n\n\u003ca href=\"https://imgur.com/OUsMztx\"\u003e\n    \u003cimg src=\"https://github.com/paulpierre/autocrop/blob/main/demo/memes_ig_john_cena_cropped.png\" alt=\"John Cena cropped\" style=\"width: 300px;\"\u003e\n\u003c/a\u003e\n\nThis performs better on black backgrounds, you'll notice it defaulted to landscape vs square.\n\nLet's try black background with this meme:\n\n\u003ca href=\"https://imgur.com/kD2jSOF\"\u003e\n    \u003cimg src=\"https://github.com/paulpierre/autocrop/blob/main/demo/memes_ig_southpark_poo.png\" alt=\"Southpark uncropped\" style=\"width: 300px;\"\u003e\n\u003c/a\u003e\n\n```bash\npython autocrop-cli.py --video_path ./demo/memes_ig_southpark_poo.mp4\n```\n\u003ca href=\"https://imgur.com/eHFcM1S\"\u003e\n    \u003cimg src=\"https://github.com/paulpierre/autocrop/blob/main/demo/memes_ig_southpark_poo_cropped.png\" alt=\"Southpark Cropped\" style=\"width: 300px;\"\u003e\n\u003c/a\u003e\n\nNice 👌 much better.\n\n\n## 🌟 Features\n\n- Detects video content area automatically\n- Crops to standard aspect ratios (9:16, 16:9, 1:1)\n- Supports single video or batch processing\n- Supports all black and white backgrounds\n- Supports silencing original audio, adding audio from mp3\n- Uses FFmpeg for high-quality video processing\n\n## 🛠️ How It Works\n\n1. **Frame Sampling**: Randomly selects frames from the video for analysis.\n2. **Background Detection**: Identifies the background color of the video.\n3. **Content Area Detection**: Locates the main content area within the video frames.\n4. **Orientation Detection**: Determines if the content is portrait, landscape, or square.\n5. **Aspect Ratio Adjustment**: Adjusts the crop area to match the closest standard aspect ratio.\n6. **Video Cropping**: Uses FFmpeg to crop the video based on the detected area.\n\n## 🏗️ Setup\n\n```bash\ngit clone https://github.com/paulpierre/autocrop.git\ncd autocrop\npython3 -m venv venv\nsource venv/bin/activate\npip3 install -r requirements.txt\n```\n\n## 🚀 Usage\n\n### CLI\n```bash\n# Process a single video\npython autocrop-cli.py --video_path /path/to/video.mp4\n\n# Process all MP4 files in a directory\npython autocrop-cli.py --video_dir /path/to/video/directory\n\n# Specify output path for single video processing\npython autocrop-cli.py --video_path /path/to/video.mp4 --out /path/to/output.mp4\n\n# Autocrop and add audio from mp3 on top of original audio\npython autocrop-cli.py --video_path /path/to/video.mp4 --out /path/to/output.mp4 --audio-track /path/to/audio.mp3 --audio-volume 0.4\n\n# Silences original audio\npython autocrop-cli.py --video_path /path/to/video.mp4 --out /path/to/output.mp4 --silence-audio\n\n# Silence original audio and replace with new audio\npython autocrop-cli.py --video_path /path/to/video.mp4 --out /path/to/output.mp4 --silence-audio --audio-track /path/to/audio.mp3 --audio-volume 0.4\n```\n\n### Python\n```python\nimport autocrop\n\nautocrop.process_video(\"/path/to/video.mp4\", \"/path/to/output.mp4\")\n```\n\n## 🧩 Main Components\n\n- `sample_frames()`: Extracts random frames from the video for analysis.\n- `detect_background_color()`: Determines the background color of the video.\n- `detect_video_area()`: Identifies the main content area within the video frames.\n- `determine_orientation()`: Classifies the video orientation based on aspect ratio.\n- `adjust_crop_to_ratio()`: Adjusts the crop area to match standard aspect ratios.\n- `crop_video_with_ffmpeg()`: Uses FFmpeg to perform the actual video cropping.\n\n## 🔧 Requirements\n- MacOS / *nix\n- Python 3.9+\n- OpenCV\n- NumPy\n- FFmpeg (`brew install ffmpeg` on MacOS)\n\n## 📝 Note\n\nThis script is designed to work best with videos that have a clear distinction between the main content and the background (i.e. Youtube Short or Instagram Reel) where there is branding and clutter surrounding the video. Results may vary for complex video scenes.\n\nPR's welcome\n\n## 🙌 Credits\n\nCreated by [@paulpierre](https://twitter.com/paulpierre) on X (Twitter)\n\n\n## 📄 License\n\nMIT License\n\nCopyright (c) 2024 Paul Pierre\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulpierre%2Fautocrop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulpierre%2Fautocrop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulpierre%2Fautocrop/lists"}