| Name | zoomcutter JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | Automatically process Zoom recordings to switch between speaker-only and side-by-side views based on screen sharing chapters |
| upload_time | 2025-10-22 01:25:18 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
zoom
video
processing
ffmpeg
screen-sharing
presentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ZoomCutter
Automatically process Zoom recordings to switch between speaker-only and side-by-side views based on screen sharing chapters.
## What it does
ZoomCutter intelligently combines your Zoom camera and screen sharing recordings into a single video that:
- Shows **speaker-only view** when you're not sharing your screen
- Switches to your chosen layout (side-by-side or diagonal) when screen sharing is detected
- Supports multiple layout options and custom backgrounds
- Maintains camera's native resolution for optimal performance
- Uses Zoom's built-in chapter markers to detect sharing automatically
Perfect for creating professional-looking recordings of presentations, lectures, or meetings!
## Layout Examples
### Side-by-Side Layout
50/50 split with slides on the left and camera on the right - perfect for balanced presentations.
### Diagonal Layout
Large slides (~72% width) with a small camera overlay in the bottom-right corner - ideal for slide-heavy content.
## Features
- **Automatic switching**: Reads Zoom chapter markers to detect when screen sharing starts/stops
- **Smart resolution handling**: Uses camera's native resolution by default (no unnecessary upscaling)
- **Custom dimensions**: Optional override to set specific output resolution (e.g., 1080p, 720p)
- **Multiple layouts**: Choose between side-by-side (50/50 split) or diagonal (large slides with small camera overlay)
- **Custom backgrounds**: Set background color or use custom background images
- **Trim support**: Cut your video to specific start/end times
- **Fast processing**: Optimized ffmpeg settings for quick encoding
- **Dry-run mode**: Preview the ffmpeg command before processing
## Installation
```bash
pip install zoomcutter
```
## Run without installing
```bash
uvx zoomcutter --help
```
### Requirements
ZoomCutter requires **ffmpeg** to be installed on your system:
**macOS:**
```bash
brew install ffmpeg
```
**Ubuntu/Debian:**
```bash
sudo apt install ffmpeg
```
**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) or use [Chocolatey](https://chocolatey.org/):
```bash
choco install ffmpeg
```
## Usage
### Basic Usage
```bash
zoomcutter camera_file.mp4 slides_file.mp4 output.mp4
```
Where:
- `camera_file.mp4` - Your Zoom camera recording (usually named `*_avo_*.mp4`)
- `slides_file.mp4` - Your Zoom screen sharing recording (usually named `*_as_*.mp4`)
- `output.mp4` - The output filename
### Trim Video
Cut your video to a specific time range:
```bash
# Start at 2 minutes, end at 45 minutes
zoomcutter camera.mp4 slides.mp4 output.mp4 --start 00:02:00 --end 00:45:00
# Using short options
zoomcutter camera.mp4 slides.mp4 output.mp4 -ss 00:02:00 -to 00:45:00
```
### Custom Output Dimensions
Set custom output dimensions instead of using the camera's native resolution:
```bash
# Output at 1080p (1920x1080) even if camera is 720p
zoomcutter camera.mp4 slides.mp4 output.mp4 --dimensions 1080p
# Or specify exact dimensions
zoomcutter camera.mp4 slides.mp4 output.mp4 -d 1920x1080
# Common presets: 1080p, 720p, 480p
# Or any custom WIDTHxHEIGHT format
```
**Note**: This will scale the video to the specified dimensions. Upscaling (e.g., 720p to 1080p) may reduce quality, while downscaling can reduce file size.
### Dry Run
Preview the ffmpeg command without processing:
```bash
zoomcutter camera.mp4 slides.mp4 output.mp4 --dry-run
```
### Layout Options
Choose between different layout modes for when screen sharing is active:
#### Side-by-Side Layout (default)
```bash
zoomcutter camera.mp4 slides.mp4 output.mp4 --layout side-by-side
# Or short form:
zoomcutter camera.mp4 slides.mp4 output.mp4 -l side-by-side
```
- 50/50 split: slides on left, camera on right
- Equal space for both elements
- Classic presentation layout
#### Diagonal Layout
```bash
zoomcutter camera.mp4 slides.mp4 output.mp4 --layout diagonal
# Or short form:
zoomcutter camera.mp4 slides.mp4 output.mp4 -l diagonal
```
- Large slides (~72% width) on the left
- Small camera overlay in bottom-right corner
- Minimal content overlap
- Great for slide-heavy presentations
### Background Customization
Customize the background color or use a custom image:
#### Custom Background Color
```bash
# Use a named color
zoomcutter camera.mp4 slides.mp4 output.mp4 --background-color white
# Use a hex color
zoomcutter camera.mp4 slides.mp4 output.mp4 --background-color "#1E3A8A"
# Short form:
zoomcutter camera.mp4 slides.mp4 output.mp4 -bg "#FF5733"
```
#### Background Image
```bash
# Use a custom background image
zoomcutter camera.mp4 slides.mp4 output.mp4 --background-image /path/to/background.jpg
# Short form:
zoomcutter camera.mp4 slides.mp4 output.mp4 -bgi background.png
```
#### Combine Options
```bash
# Diagonal layout with custom background
zoomcutter camera.mp4 slides.mp4 output.mp4 \
--layout diagonal \
--background-color "#2C3E50" \
--start 00:05:00 \
--end 01:30:00
```
## How It Works
1. **Reads chapter markers**: ZoomCutter analyzes the screen sharing video file to find "Sharing Started" and "Sharing Stopped" chapter markers that Zoom automatically adds
2. **Detects camera resolution**: Uses the camera feed's native resolution for optimal quality
3. **Builds filter**: Creates an ffmpeg filter that:
- Shows camera at full resolution when not sharing (speaker-only mode)
- Switches to your chosen layout during sharing:
- **Side-by-side**: 50/50 split with slides on left, camera on right
- **Diagonal**: Large slides with small camera overlay in bottom-right
- Applies custom background colors or images if specified
4. **Processes video**: Runs ffmpeg with optimized settings for fast, high-quality output
## Output Quality
- **Video codec**: H.264 with CRF 18 (high quality)
- **Preset**: veryfast (good balance of speed and compression)
- **Audio**: Copied directly from camera feed (no re-encoding)
- **Resolution**: Matches camera's native resolution
## Example
```bash
# Process a 1-hour Zoom recording
$ zoomcutter zoom_0.mp4 zoom_share.mp4 final.mp4
Processing Zoom recordings...
Camera: zoom_0.mp4
Slides: zoom_share.mp4
Output: final.mp4
Camera resolution: 1920x1080
Found 12 chapters
Found 3 screen sharing intervals:
1. 120.50s - 850.30s
2. 1200.00s - 2400.50s
3. 2800.00s - end
Output resolution: 1920x1080 (camera native)
- Speaker-only mode: No scaling (maximum performance!)
- Side-by-side mode: Only scales slides down
Running ffmpeg...
Successfully created: final.mp4
```
## Troubleshooting
**Error: "Could not detect camera resolution"**
- Make sure the camera file is a valid video file
- Try running `ffprobe camera_file.mp4` to verify
**Error: "Error running ffprobe"**
- Ensure ffmpeg (which includes ffprobe) is installed and in your PATH
**No chapters found**
- Verify you're using the screen sharing file (`*_as_*.mp4`) for chapter detection
- Some older Zoom versions may not include chapters
## Development
### Setup
```bash
git clone https://github.com/weltonrodrigo/zoomcutter.git
cd zoomcutter
uv pip install -e .
```
### Run locally
```bash
python main.py camera.mp4 slides.mp4 output.mp4
```
## License
MIT License - see LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "zoomcutter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "zoom, video, processing, ffmpeg, screen-sharing, presentation",
"author": null,
"author_email": "Welton Rodrigo <rodrigo@familianascimento.org>",
"download_url": "https://files.pythonhosted.org/packages/e8/63/4de8048f10b37fb8ab66f366b011a4a8bf29e44354fb1444cc1f6e2d2c3e/zoomcutter-0.2.2.tar.gz",
"platform": null,
"description": "# ZoomCutter\n\nAutomatically process Zoom recordings to switch between speaker-only and side-by-side views based on screen sharing chapters.\n\n## What it does\n\nZoomCutter intelligently combines your Zoom camera and screen sharing recordings into a single video that:\n- Shows **speaker-only view** when you're not sharing your screen\n- Switches to your chosen layout (side-by-side or diagonal) when screen sharing is detected\n- Supports multiple layout options and custom backgrounds\n- Maintains camera's native resolution for optimal performance\n- Uses Zoom's built-in chapter markers to detect sharing automatically\n\nPerfect for creating professional-looking recordings of presentations, lectures, or meetings!\n\n## Layout Examples\n\n### Side-by-Side Layout\n50/50 split with slides on the left and camera on the right - perfect for balanced presentations.\n\n\n\n### Diagonal Layout\nLarge slides (~72% width) with a small camera overlay in the bottom-right corner - ideal for slide-heavy content.\n\n\n\n## Features\n\n- **Automatic switching**: Reads Zoom chapter markers to detect when screen sharing starts/stops\n- **Smart resolution handling**: Uses camera's native resolution by default (no unnecessary upscaling)\n- **Custom dimensions**: Optional override to set specific output resolution (e.g., 1080p, 720p)\n- **Multiple layouts**: Choose between side-by-side (50/50 split) or diagonal (large slides with small camera overlay)\n- **Custom backgrounds**: Set background color or use custom background images\n- **Trim support**: Cut your video to specific start/end times\n- **Fast processing**: Optimized ffmpeg settings for quick encoding\n- **Dry-run mode**: Preview the ffmpeg command before processing\n\n## Installation\n\n```bash\npip install zoomcutter\n```\n\n## Run without installing\n\n```bash\nuvx zoomcutter --help\n```\n\n### Requirements\n\nZoomCutter requires **ffmpeg** to be installed on your system:\n\n**macOS:**\n```bash\nbrew install ffmpeg\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install ffmpeg\n```\n\n**Windows:**\nDownload from [ffmpeg.org](https://ffmpeg.org/download.html) or use [Chocolatey](https://chocolatey.org/):\n```bash\nchoco install ffmpeg\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\nzoomcutter camera_file.mp4 slides_file.mp4 output.mp4\n```\n\nWhere:\n- `camera_file.mp4` - Your Zoom camera recording (usually named `*_avo_*.mp4`)\n- `slides_file.mp4` - Your Zoom screen sharing recording (usually named `*_as_*.mp4`)\n- `output.mp4` - The output filename\n\n### Trim Video\n\nCut your video to a specific time range:\n\n```bash\n# Start at 2 minutes, end at 45 minutes\nzoomcutter camera.mp4 slides.mp4 output.mp4 --start 00:02:00 --end 00:45:00\n\n# Using short options\nzoomcutter camera.mp4 slides.mp4 output.mp4 -ss 00:02:00 -to 00:45:00\n```\n\n### Custom Output Dimensions\n\nSet custom output dimensions instead of using the camera's native resolution:\n\n```bash\n# Output at 1080p (1920x1080) even if camera is 720p\nzoomcutter camera.mp4 slides.mp4 output.mp4 --dimensions 1080p\n\n# Or specify exact dimensions\nzoomcutter camera.mp4 slides.mp4 output.mp4 -d 1920x1080\n\n# Common presets: 1080p, 720p, 480p\n# Or any custom WIDTHxHEIGHT format\n```\n\n**Note**: This will scale the video to the specified dimensions. Upscaling (e.g., 720p to 1080p) may reduce quality, while downscaling can reduce file size.\n\n### Dry Run\n\nPreview the ffmpeg command without processing:\n\n```bash\nzoomcutter camera.mp4 slides.mp4 output.mp4 --dry-run\n```\n\n### Layout Options\n\nChoose between different layout modes for when screen sharing is active:\n\n#### Side-by-Side Layout (default)\n```bash\nzoomcutter camera.mp4 slides.mp4 output.mp4 --layout side-by-side\n# Or short form:\nzoomcutter camera.mp4 slides.mp4 output.mp4 -l side-by-side\n```\n- 50/50 split: slides on left, camera on right\n- Equal space for both elements\n- Classic presentation layout\n\n#### Diagonal Layout\n```bash\nzoomcutter camera.mp4 slides.mp4 output.mp4 --layout diagonal\n# Or short form:\nzoomcutter camera.mp4 slides.mp4 output.mp4 -l diagonal\n```\n- Large slides (~72% width) on the left\n- Small camera overlay in bottom-right corner\n- Minimal content overlap\n- Great for slide-heavy presentations\n\n### Background Customization\n\nCustomize the background color or use a custom image:\n\n#### Custom Background Color\n```bash\n# Use a named color\nzoomcutter camera.mp4 slides.mp4 output.mp4 --background-color white\n\n# Use a hex color\nzoomcutter camera.mp4 slides.mp4 output.mp4 --background-color \"#1E3A8A\"\n\n# Short form:\nzoomcutter camera.mp4 slides.mp4 output.mp4 -bg \"#FF5733\"\n```\n\n#### Background Image\n```bash\n# Use a custom background image\nzoomcutter camera.mp4 slides.mp4 output.mp4 --background-image /path/to/background.jpg\n\n# Short form:\nzoomcutter camera.mp4 slides.mp4 output.mp4 -bgi background.png\n```\n\n#### Combine Options\n```bash\n# Diagonal layout with custom background\nzoomcutter camera.mp4 slides.mp4 output.mp4 \\\n --layout diagonal \\\n --background-color \"#2C3E50\" \\\n --start 00:05:00 \\\n --end 01:30:00\n```\n\n## How It Works\n\n1. **Reads chapter markers**: ZoomCutter analyzes the screen sharing video file to find \"Sharing Started\" and \"Sharing Stopped\" chapter markers that Zoom automatically adds\n2. **Detects camera resolution**: Uses the camera feed's native resolution for optimal quality\n3. **Builds filter**: Creates an ffmpeg filter that:\n - Shows camera at full resolution when not sharing (speaker-only mode)\n - Switches to your chosen layout during sharing:\n - **Side-by-side**: 50/50 split with slides on left, camera on right\n - **Diagonal**: Large slides with small camera overlay in bottom-right\n - Applies custom background colors or images if specified\n4. **Processes video**: Runs ffmpeg with optimized settings for fast, high-quality output\n\n## Output Quality\n\n- **Video codec**: H.264 with CRF 18 (high quality)\n- **Preset**: veryfast (good balance of speed and compression)\n- **Audio**: Copied directly from camera feed (no re-encoding)\n- **Resolution**: Matches camera's native resolution\n\n## Example\n\n```bash\n# Process a 1-hour Zoom recording\n$ zoomcutter zoom_0.mp4 zoom_share.mp4 final.mp4\n\nProcessing Zoom recordings...\n Camera: zoom_0.mp4\n Slides: zoom_share.mp4\n Output: final.mp4\n\nCamera resolution: 1920x1080\n\nFound 12 chapters\nFound 3 screen sharing intervals:\n 1. 120.50s - 850.30s\n 2. 1200.00s - 2400.50s\n 3. 2800.00s - end\n\nOutput resolution: 1920x1080 (camera native)\n - Speaker-only mode: No scaling (maximum performance!)\n - Side-by-side mode: Only scales slides down\n\nRunning ffmpeg...\n\n\u0013 Successfully created: final.mp4\n```\n\n## Troubleshooting\n\n**Error: \"Could not detect camera resolution\"**\n- Make sure the camera file is a valid video file\n- Try running `ffprobe camera_file.mp4` to verify\n\n**Error: \"Error running ffprobe\"**\n- Ensure ffmpeg (which includes ffprobe) is installed and in your PATH\n\n**No chapters found**\n- Verify you're using the screen sharing file (`*_as_*.mp4`) for chapter detection\n- Some older Zoom versions may not include chapters\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/weltonrodrigo/zoomcutter.git\ncd zoomcutter\nuv pip install -e .\n```\n\n### Run locally\n\n```bash\npython main.py camera.mp4 slides.mp4 output.mp4\n```\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically process Zoom recordings to switch between speaker-only and side-by-side views based on screen sharing chapters",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/weltonrodrigo/zoomcutter",
"Issues": "https://github.com/weltonrodrigo/zoomcutter/issues",
"Repository": "https://github.com/weltonrodrigo/zoomcutter"
},
"split_keywords": [
"zoom",
" video",
" processing",
" ffmpeg",
" screen-sharing",
" presentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55b87b55afee386b12530f11f9d11f02a3273a18f29ab9e5b912c5e59bf9bf42",
"md5": "72ed9dfef694913480d8da2973d61348",
"sha256": "8fb56b5e18839df3f3aa2f31a6030333c219e90eaecbd227efc97ecc7e6725e3"
},
"downloads": -1,
"filename": "zoomcutter-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "72ed9dfef694913480d8da2973d61348",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10231,
"upload_time": "2025-10-22T01:25:16",
"upload_time_iso_8601": "2025-10-22T01:25:16.735148Z",
"url": "https://files.pythonhosted.org/packages/55/b8/7b55afee386b12530f11f9d11f02a3273a18f29ab9e5b912c5e59bf9bf42/zoomcutter-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e8634de8048f10b37fb8ab66f366b011a4a8bf29e44354fb1444cc1f6e2d2c3e",
"md5": "810c058a2ffd9d318454e523e5c5162e",
"sha256": "7b00ed0cda69b1887226d1d887a97ecf197b0a22a9493b91aa2ec5517f5a0d9c"
},
"downloads": -1,
"filename": "zoomcutter-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "810c058a2ffd9d318454e523e5c5162e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12220,
"upload_time": "2025-10-22T01:25:18",
"upload_time_iso_8601": "2025-10-22T01:25:18.019570Z",
"url": "https://files.pythonhosted.org/packages/e8/63/4de8048f10b37fb8ab66f366b011a4a8bf29e44354fb1444cc1f6e2d2c3e/zoomcutter-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 01:25:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "weltonrodrigo",
"github_project": "zoomcutter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zoomcutter"
}
