# SmartZoom
A Python utility to automatically apply a smooth, continuous zoom to a video, perfectly framing its content.
---
This tool solves a common problem for video creators: adding a subtle, engaging "Ken Burns" style zoom to static shots (like presentations, code tutorials, or talking-head videos) without manual editing. It intelligently detects the subject of your video, calculates the optimal framing, and renders a new high-quality video with a perfectly smooth zoom.
### Key Features
- **Automatic Content Detection:** Intelligently finds the bounding box of all non-background content on the first frame.
- **Perfectly Centered Zoom:** The zoom is always mathematically centered on your content.
- **Smooth, Constant Motion:** A linear zoom is applied throughout the video's duration, ensuring no stutter or jitter.
- **Aspect Ratio Correction:** The final framing is guaranteed to match the video's aspect ratio (e.g., 16:9), providing a "what you see is what you get" result.
- **High-Quality Output:** The original audio is copied without re-encoding, preserving its quality completely.
- **Built-in Debug Mode:** Generate visual aids to see exactly what the detection algorithm is doing before rendering the full video.
## Installation
This package requires Python 3.8+ and FFmpeg.
**1. Install FFmpeg:**
You must have FFmpeg installed on your system and accessible from your PATH. You can download it from the official website: [ffmpeg.org](https://ffmpeg.org/download.html)
**2. Install the Package:**
Install `smartzoom` using pip:
```bash
pip install smartzoom
```
This will also install its Python dependencies, `opencv-python` and `numpy`.
## Usage
### As a Python Library
Using the library is straightforward. Import the package and call it directly with your input and output paths.
```python
import smartzoom
smartzoom('input_video.mp4', 'output.mp4', margin=50, debug=True)
```
or
```python
import smartzoom
import os
# Define your input and output files
input_video = 'my_presentation.mp4'
output_folder = 'processed_videos'
output_video = os.path.join(output_folder, 'my_presentation_zoomed.mp4')
# Create the output directory if it doesn't exist
if not os.path.exists(output_folder):
os.makedirs(output_folder)
# Run the smart zoom function
smartzoom(
input_path=input_video,
output_path=output_video,
margin=50, # Set a 50px margin around the detected content
debug=True # Set to True to save detection images in the output folder
)
print(f"Processing complete! Check '{output_video}'")
```
## API Reference
The package provides one primary public function.
```python
smartzoom(
input_path: str,
output_path: str,
margin: int = 50,
debug: bool = False
)
```
**Parameters:**
- `input_path` (str):
Path to the source video file.
- `output_path` (str):
Path where the final video will be saved. The output directory will be created if it doesn't exist.
- `margin` (int, optional):
The pixel distance to keep from the detected content on all sides. Defaults to `50`.
- `debug` (bool, optional):
If `True`, saves two visualization images (`debug_raw_viewport.png` and `debug_margin_viewport.png`) to the output folder to show the detection results. Defaults to `False`.
## How It Works
1. **Analyze Frame:** The script reads the first frame of the input video.
2. **Detect Content:** It converts the frame to grayscale and uses a binary threshold to isolate all light-colored content from the dark background.
3. **Find Bounding Box:** It finds the single bounding box that encloses all detected content.
4. **Calculate Viewport:** It adds the specified `margin` and then expands this box to match the video's 16:9 aspect ratio. This becomes the final "target viewport".
5. **Determine Zoom:** It calculates the zoom multiplier required to make the target viewport fill the entire screen.
6. **Render Video:** It processes the video frame-by-frame, applying a linear zoom from 1.0x to the final calculated zoom value.
7. **Add Audio:** It uses FFmpeg to losslessly copy the audio stream from the original video and merge it with the newly rendered video frames.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/AMAMazing/smartzoom",
"name": "smartzoom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "video, zoom, automation, opencv, ffmpeg, cli",
"author": "Alex M",
"author_email": "alexmalone489@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/57/5d/c819f2de3f60221fb83d02c568171fb98a8f89a76a5513e4028c3a909d44/smartzoom-0.1.0.tar.gz",
"platform": null,
"description": "# SmartZoom\r\n\r\nA Python utility to automatically apply a smooth, continuous zoom to a video, perfectly framing its content.\r\n\r\n\r\n\r\n\r\n---\r\n\r\nThis tool solves a common problem for video creators: adding a subtle, engaging \"Ken Burns\" style zoom to static shots (like presentations, code tutorials, or talking-head videos) without manual editing. It intelligently detects the subject of your video, calculates the optimal framing, and renders a new high-quality video with a perfectly smooth zoom.\r\n\r\n\r\n\r\n### Key Features\r\n\r\n- **Automatic Content Detection:** Intelligently finds the bounding box of all non-background content on the first frame.\r\n- **Perfectly Centered Zoom:** The zoom is always mathematically centered on your content.\r\n- **Smooth, Constant Motion:** A linear zoom is applied throughout the video's duration, ensuring no stutter or jitter.\r\n- **Aspect Ratio Correction:** The final framing is guaranteed to match the video's aspect ratio (e.g., 16:9), providing a \"what you see is what you get\" result.\r\n- **High-Quality Output:** The original audio is copied without re-encoding, preserving its quality completely.\r\n- **Built-in Debug Mode:** Generate visual aids to see exactly what the detection algorithm is doing before rendering the full video.\r\n\r\n## Installation\r\n\r\nThis package requires Python 3.8+ and FFmpeg.\r\n\r\n**1. Install FFmpeg:**\r\nYou must have FFmpeg installed on your system and accessible from your PATH. You can download it from the official website: [ffmpeg.org](https://ffmpeg.org/download.html)\r\n\r\n**2. Install the Package:**\r\nInstall `smartzoom` using pip:\r\n\r\n```bash\r\npip install smartzoom\r\n```\r\n\r\nThis will also install its Python dependencies, `opencv-python` and `numpy`.\r\n\r\n## Usage\r\n\r\n### As a Python Library\r\n\r\nUsing the library is straightforward. Import the package and call it directly with your input and output paths.\r\n\r\n```python\r\nimport smartzoom\r\n\r\nsmartzoom('input_video.mp4', 'output.mp4', margin=50, debug=True)\r\n```\r\n\r\nor\r\n\r\n```python\r\nimport smartzoom\r\nimport os\r\n\r\n# Define your input and output files\r\ninput_video = 'my_presentation.mp4'\r\noutput_folder = 'processed_videos'\r\noutput_video = os.path.join(output_folder, 'my_presentation_zoomed.mp4')\r\n\r\n# Create the output directory if it doesn't exist\r\nif not os.path.exists(output_folder):\r\n os.makedirs(output_folder)\r\n\r\n# Run the smart zoom function\r\nsmartzoom(\r\n input_path=input_video,\r\n output_path=output_video,\r\n margin=50, # Set a 50px margin around the detected content\r\n debug=True # Set to True to save detection images in the output folder\r\n)\r\n\r\nprint(f\"Processing complete! Check '{output_video}'\")\r\n```\r\n## API Reference\r\n\r\nThe package provides one primary public function.\r\n\r\n```python\r\nsmartzoom(\r\n input_path: str,\r\n output_path: str,\r\n margin: int = 50,\r\n debug: bool = False\r\n)\r\n```\r\n\r\n**Parameters:**\r\n\r\n- `input_path` (str):\r\n Path to the source video file.\r\n\r\n- `output_path` (str):\r\n Path where the final video will be saved. The output directory will be created if it doesn't exist.\r\n\r\n- `margin` (int, optional):\r\n The pixel distance to keep from the detected content on all sides. Defaults to `50`.\r\n\r\n- `debug` (bool, optional):\r\n If `True`, saves two visualization images (`debug_raw_viewport.png` and `debug_margin_viewport.png`) to the output folder to show the detection results. Defaults to `False`.\r\n\r\n## How It Works\r\n\r\n1. **Analyze Frame:** The script reads the first frame of the input video.\r\n2. **Detect Content:** It converts the frame to grayscale and uses a binary threshold to isolate all light-colored content from the dark background.\r\n3. **Find Bounding Box:** It finds the single bounding box that encloses all detected content.\r\n4. **Calculate Viewport:** It adds the specified `margin` and then expands this box to match the video's 16:9 aspect ratio. This becomes the final \"target viewport\".\r\n5. **Determine Zoom:** It calculates the zoom multiplier required to make the target viewport fill the entire screen.\r\n6. **Render Video:** It processes the video frame-by-frame, applying a linear zoom from 1.0x to the final calculated zoom value.\r\n7. **Add Audio:** It uses FFmpeg to losslessly copy the audio stream from the original video and merge it with the newly rendered video frames.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python utility to automatically apply a smooth, continuous zoom to a video, perfectly framing its content.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/AMAMazing/smartzoom"
},
"split_keywords": [
"video",
" zoom",
" automation",
" opencv",
" ffmpeg",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eff93ceaf3fc1fb67cab811fcc6841c632cd463f19d9b06274e9806afeb6ac19",
"md5": "c8fcb66af768dd529132701a28836c65",
"sha256": "2b6553afdcd688831b0c1d3573b10dcd77f65ce010ff8dd11ef520304ad7d12e"
},
"downloads": -1,
"filename": "smartzoom-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8fcb66af768dd529132701a28836c65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7778,
"upload_time": "2025-07-13T11:48:44",
"upload_time_iso_8601": "2025-07-13T11:48:44.726802Z",
"url": "https://files.pythonhosted.org/packages/ef/f9/3ceaf3fc1fb67cab811fcc6841c632cd463f19d9b06274e9806afeb6ac19/smartzoom-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "575dc819f2de3f60221fb83d02c568171fb98a8f89a76a5513e4028c3a909d44",
"md5": "b64d9a7385cbdea4d58da8a87b3237c6",
"sha256": "347a9327218e3200c6ae06a964ba578cf04822cf59efef0c208037bdbbf6fe96"
},
"downloads": -1,
"filename": "smartzoom-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b64d9a7385cbdea4d58da8a87b3237c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7450,
"upload_time": "2025-07-13T11:48:46",
"upload_time_iso_8601": "2025-07-13T11:48:46.080022Z",
"url": "https://files.pythonhosted.org/packages/57/5d/c819f2de3f60221fb83d02c568171fb98a8f89a76a5513e4028c3a909d44/smartzoom-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 11:48:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AMAMazing",
"github_project": "smartzoom",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "smartzoom"
}
JSON
