disdrop

Name	disdrop JSON
Version	0.1.1 JSON
	download
home_page	None
Summary	Compress videos and create platform-optimized GIFs (Discord/Twitter/etc.)
upload_time	2025-10-10 02:09:36
maintainer	None
docs_url	None
author	Disdrop
requires_python	>=3.10
license	MIT License Copyright (c) 2025 Disdrop Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	video gif compression ffmpeg discord twitter
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Video Compressor & GIF Generator

A comprehensive Python tool for compressing videos and creating optimized GIFs for social media platforms, with intelligent hardware detection and automated workflows.

## What's New - Simplified CLI

The CLI has been streamlined for easier use while maintaining full functionality:

✨ **Smart Auto-Detection**

- Glob patterns (`*.mp4`) automatically trigger batch mode
- Unified `gif` command auto-detects operation type (create/optimize/quality)
- No need for separate `batch-compress` or `batch-gif` commands

⚡ **Command Aliases**

- `c` / `v` / `video` → `compress`
- `g` / `a` / `anim` → `gif`
- `w` / `watch` / `m` / `monitor` → `auto`
- `hw` / `i` / `info` → `hardware-info`
- `cfg` → `config`, `ch` → `cache`
- `open` → Open application folders in file explorer

🎯 **Short Flags**

- `-p` → `--platform`
- `-s` → `--max-size`
- `-o` → `--output-dir`
- `-i` → `--input-dir`
- `-j` → `--parallel`
- `-d` → `--duration`
- `-q` → `--quality`
- `-f` → `--fps`
- `-v` → `--debug`

**Example:** `python main.py g "*.mp4" -o gifs/ -p discord -j 3`

All old commands still work for backward compatibility!

## Features

- **Video Compression**: Optimize videos for various social media platforms
- **GIF Generation**: Create high-quality GIFs from videos with iterative quality optimization
- **Hardware Acceleration**: Automatic detection and utilization of GPU acceleration
- **Platform Optimization**: Tailored settings for Twitter, Instagram, TikTok, YouTube Shorts, Facebook, Discord, and Slack
- **Batch Processing**: Process multiple files automatically
- **Automated Workflow**: Monitor input directory for new files
- **Quality Optimization**: Iterative GIF optimization to maximize quality while staying under size limits

## Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd disdrop
```

2. Create a virtual environment:

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:

```bash
pip install -r requirements.txt
```

4. Ensure FFmpeg is installed on your system:

   - **Windows**: Download from https://ffmpeg.org/download.html
   - **macOS**: `brew install ffmpeg`
   - **Linux**: `sudo apt install ffmpeg` (Ubuntu/Debian)

5. (Optional) Install globally for use from anywhere:

```bash
pip install --user -e .
```

After installation, you can use `disdrop` command from anywhere instead of `python main.py`:

```bash
disdrop auto           # Start automated workflow
disdrop open -i -o     # Open input and output folders
disdrop hw             # Show hardware info
```

## Quick Start

### Zero-argument auto mode

```bash
python main.py
# or use short alias:
python main.py w
```

Watches `input/` and processes new files to `output/` (defaults: max size 10 MB, check every 5s). Stop with Ctrl+C.

### Basic Video Compression

```bash
# Long form
python main.py compress input.mp4 output.mp4 --platform instagram

# Short form with aliases
python main.py c input.mp4 output.mp4 -p instagram
```

### Batch Video Compression (Auto-Detected)

```bash
# Glob patterns automatically trigger batch mode
python main.py c "*.mp4" -o compressed/ -p tiktok -j 4
```

### Basic GIF Creation

```bash
# Long form
python main.py gif input.mp4 output.gif --platform twitter

# Short form with aliases
python main.py g input.mp4 output.gif -p twitter -d 10
```

### Batch GIF Creation (Auto-Detected)

```bash
# Glob patterns automatically trigger batch mode
python main.py g "*.mp4" -o gifs/ -p discord -j 3
```

### Quality-Optimized GIF Creation

```bash
# With max-size (iterative optimization)
python main.py g input.mp4 output.gif -s 5.0 -p twitter

# With target-size (advanced optimization)
python main.py g input.mp4 output.gif --target-size 5.0 --quality-preference balanced
```

### Optimize an existing GIF

```bash
# Auto-detected when both input and output are GIFs
python main.py g input.gif output.gif
```

### Automated workflow

```bash
# Long form
python main.py auto --check-interval 10 -s 8

# Short aliases
python main.py w --check-interval 10 -s 8
python main.py watch --check-interval 10 -s 8
```

## How It Works

### Video Compression

- Content analysis (ffprobe) informs encoder, bitrate, FPS, and resolution
- Hardware acceleration is used when available with robust software fallback
- If a single output cannot reasonably meet target size, the system may invoke the video segmenter as a last resort

Video segmentation behavior (configurable in `config/video_compression.yaml`):

- Default trigger: estimated size ≥ 3.0× target, or extremely long videos (≥ 10 minutes)
- Segment duration stays within bounds and is tuned by content complexity and motion

### GIF Creation and Optimization

- Generates high-quality GIFs with a palette pipeline, `mpdecimate`, and aspect-ratio preservation (`force_original_aspect_ratio=decrease`, `setsar=1`)
- If `--max-size` is given, an iterative optimizer searches multiple quality stages to land under the target with best visual fidelity
- Platforms supported by CLI: `twitter`, `discord` (8 MB), `slack`. Internal presets also exist for Telegram/Reddit
- GIF segmentation is adaptive: long/complex source clips can be split into multiple GIFs; nested segmentation is avoided

### Iterative Quality Optimization for GIFs

The tool includes an advanced iterative optimization system that automatically tries to generate the best quality GIF possible while staying within size limits. This feature performs multiple optimization attempts with different quality levels to find the optimal balance.

#### How It Works

1. **Quality Stages**: The system tries multiple quality levels in order:

   - **Maximum Quality**: Highest resolution, FPS, colors, and best dithering
   - **High Quality**: Good balance of quality and size
   - **Medium Quality**: Moderate settings for smaller files
   - **Standard Quality**: Basic settings as fallback

2. **Iterative Attempts**: For each quality stage:

   - Attempts multiple GIF generation methods (FFmpeg palette, direct conversion, OpenCV+PIL)
   - If the result is under the size limit, calculates a quality score
   - If too large, reduces parameters and tries again
   - Continues until finding the best quality result within size limits

3. **Quality Scoring**: Each successful attempt is scored based on:

   - Color depth (0-256 colors)
   - Frame rate quality (up to 30fps)
   - Resolution quality (up to 800x800)
   - Size efficiency (how close to target size)
   - Compression quality (lossy settings)
   - Dithering quality (Floyd-Steinberg vs Bayer)

4. **Best Result Selection**: Chooses the result with the highest quality score that meets size requirements

## CLI Overview

### Smart Features

- **Auto-Batch Detection**: Glob patterns (`*.mp4`) automatically trigger batch mode
- **Unified GIF Command**: Single `gif` command auto-detects optimization type
- **Command Aliases**: Short versions for faster typing
- **Short Flags**: Single-letter options for common flags

### Global Options

| Long Form           | Short | Description                             |
| ------------------- | ----- | --------------------------------------- |
| `--debug`           | `-v`  | Verbose console + file logs             |
| `--max-size MB`     | `-s`  | Global size cap for output files        |
| `--output-dir PATH` | `-o`  | Output directory for all modes          |
| `--input-dir PATH`  | `-i`  | Input directory for auto mode           |
| `--temp-dir PATH`   |       | Temporary directory (default: `./temp`) |
| `--force-software`  |       | Bypass hardware encoders                |
| `--no-cache`        |       | Don't use success cache                 |

### Commands and Aliases

| Command         | Aliases                      | Description              |
| --------------- | ---------------------------- | ------------------------ |
| `compress`      | `c`, `v`, `video`            | Compress video file(s)   |
| `gif`           | `g`, `a`, `anim`             | Create/optimize GIF(s)   |
| `auto`          | `w`, `watch`, `m`, `monitor` | Watch input folder       |
| `open`          | -                            | Open app folders         |
| `hardware-info` | `hw`, `i`, `info`            | Show hardware info       |
| `config`        | `cfg`                        | Configuration management |
| `cache`         | `ch`                         | Cache operations         |

### Command Details

#### compress / c / v / video

Compress video file(s). Auto-detects batch mode from glob patterns.

```bash
compress <input> [output] [options]
```

**Options:**

- `-p, --platform` - Target platform (instagram, twitter, tiktok, youtube_shorts, facebook)
- `-q, --quality CRF` - Quality setting (lower = better)
- `-f, --fps N` - Target frame rate
- `--encoder` - Force specific encoder
- `--bitrate` - Target bitrate (e.g., 1000k)
- `--resolution` - Target resolution (e.g., 1080x1080)
- `--suffix` - Suffix for batch output files (default: \_compressed)
- `-j, --parallel N` - Number of parallel processes for batch

#### gif / g / a / anim

Create or optimize GIF(s). Auto-detects operation type and batch mode.

```bash
gif <input> [output] [options]
```

**Options:**

- `-p, --platform` - Target platform (twitter, discord, slack)
- `-s, --max-size MB` - Max file size (enables quality optimization)
- `--target-size MB` - Target size for advanced optimization
- `-d, --duration S` - Duration in seconds
- `--start S` - Start time in seconds
- `-f, --fps N` - Frame rate
- `--width W` - Width in pixels
- `--height H` - Height in pixels
- `--colors C` - Number of colors in palette
- `--quality-preference` - Strategy: quality, balanced, size
- `-j, --parallel N` - Number of parallel processes for batch

#### auto / w / watch / m / monitor

Watch input folder and automatically process new files.

```bash
auto [options]
```

**Options:**

- `--check-interval S` - Check frequency in seconds (default: 5)
- `-s, --max-size MB` - Max output size (default: 10.0)
- `-i, --input-dir PATH` - Input directory (default: ./input)
- `-o, --output-dir PATH` - Output directory (default: ./output)
- `--no-cache` - Don't use success cache

#### open

Open application folders in file explorer. Useful for quickly accessing input, output, logs, or config directories.

```bash
open [options]
```

**Options:**

- `-i, --input` - Open input folder
- `-o, --output` - Open output folder
- `-l, --logs` - Open logs folder
- `-c, --config` - Open config folder

**Examples:**

```bash
# Open single folder
disdrop open -i                # Open input folder
disdrop open -o                # Open output folder

# Open multiple folders at once
disdrop open -i -o -l          # Open input, output, and logs folders
```

Note: Folders are created if they don't exist. Works cross-platform (Windows, macOS, Linux).

#### Other Commands

- `hardware-info` / `hw` / `i` / `info` - Display hardware acceleration info
- `config` / `cfg` `show|validate` - Configuration management
- `cache` / `ch` `clear|stats|validate` - Cache operations

### Quick Reference Card

Common tasks with shortest syntax:

```bash
# Compress single video for Instagram
python main.py c video.mp4 out.mp4 -p instagram

# Batch compress all videos for TikTok
python main.py c "*.mp4" -o compressed/ -p tiktok -j 4

# Create GIF for Twitter
python main.py g video.mp4 out.gif -p twitter -s 5

# Batch create GIFs for Discord
python main.py g "*.mp4" -o gifs/ -p discord -j 3

# Optimize existing GIF
python main.py g input.gif output.gif

# Watch folder for new files
python main.py w

# Open folders in file explorer
python main.py open -i -o

# Check hardware capabilities
python main.py hw

# Show configuration
python main.py cfg show

# Clear cache
python main.py ch clear
```

## Configuration

Default configuration files are packaged under `disdrop/config/` and used automatically. To override, use `--config-dir PATH` or set `DISDROP_BASE_DIR` to change the runtime base (for logs/input/output/temp).

- `video_compression.yaml`: max size (default 10 MB), hardware encoders, conservative segmentation policy, platform presets
- `gif_settings.yaml`: default max size (10 MB), FPS/resolution, palette/dither/lossy, quality-optimization stages, segmentation heuristics
- `logging.yaml`: console/file logging formats and levels (logs in `logs/`)

### Examples (abridged)

```yaml
# video_compression.yaml
video_compression:
  max_file_size_mb: 10
  segmentation:
    size_threshold_multiplier: 3.0
    fallback_duration_limit: 600

# gif_settings.yaml
gif_settings:
  max_file_size_mb: 10
  fps: 20
  width: 360
  height: 360
  quality_optimization:
    enabled: true
```

CLI overrides map into config at runtime, for example:

- `--max-size 8.0` → `video_compression.max_file_size_mb` and `gif_settings.max_file_size_mb`
- `--fps 20` → `video_compression.platforms.custom.fps` and `gif_settings.fps`
- `--width/--height/--colors` → `gif_settings.width/height/colors`

### Custom Platform Configuration

Add custom platform settings in `gif_settings.yaml`:

```yaml
platforms:
  custom_platform:
    max_width: 500
    max_height: 500
    max_duration: 12
    colors: 128
    max_file_size_mb: 6
    dither: "floyd_steinberg"
    lossy: 30
```

## Platform-Specific Optimization

The tool automatically applies platform-specific optimizations:

- **Twitter**: 506x506 max, 15s duration, optimized for web viewing
- **Discord**: 400x400 max, 10s duration, 8MB limit for free users
- **Slack**: 360x360 max, 8s duration, conservative compression
- **Instagram**: 1080x1080 max, optimized for mobile viewing
- **TikTok**: 1080x1920 max, vertical format optimization

## Hardware Acceleration

The tool automatically detects and utilizes available hardware:

- **NVIDIA GPU**: NVENC encoder for fast compression
- **AMD GPU**: AMF encoder support
- **Intel GPU**: QSV encoder for integrated graphics
- **Apple Silicon**: VideoToolbox for M1/M2 Macs

## Examples

### Example 1: Social Media Content Creation

```bash
# Create Instagram-optimized video (long form)
python main.py compress raw_video.mp4 instagram_video.mp4 --platform instagram

# Create Instagram-optimized video (short form)
python main.py c raw_video.mp4 instagram_video.mp4 -p instagram

# Create Twitter GIF with quality optimization (long form)
python main.py gif raw_video.mp4 twitter_gif.gif --target-size 5.0 --quality-preference balanced -p twitter

# Create Twitter GIF with quality optimization (short form)
python main.py g raw_video.mp4 twitter_gif.gif --target-size 5.0 -p twitter
```

### Example 2: Batch Processing (Auto-Detected)

```bash
# Process all videos for Instagram (auto-detects batch mode from glob pattern)
python main.py c "videos/*.mp4" -o instagram/ -p instagram -j 4

# Process all videos for Twitter
python main.py c "videos/*.mp4" -o twitter/ -p twitter -j 4

# Create GIFs for Discord from all videos
python main.py g "videos/*.mp4" -o gifs/ -p discord -d 8 -j 3
```

### Example 3: Automated Workflow

```bash
# Start automated processing (long form)
python main.py auto --check-interval 30 -s 8.0

# Start automated processing (short aliases)
python main.py w --check-interval 30 -s 8.0
python main.py watch --check-interval 30 -s 8.0

# Place videos in input/ directory and they'll be processed automatically
```

### Example 4: Quick Commands with Aliases

```bash
# Check hardware capabilities
python main.py hw

# Show configuration
python main.py cfg show

# Clear cache
python main.py ch clear

# Optimize existing GIF (auto-detected)
python main.py g input.gif output.gif
```

## Performance Tips

1. **Use Hardware Acceleration**: The tool automatically detects and uses GPU acceleration when available
2. **Batch Processing**: Use glob patterns (`*.mp4`) for automatic batch processing
3. **Short Commands**: Use aliases (`c`, `g`, `w`) and short flags (`-p`, `-s`, `-o`) for faster typing
4. **Quality Optimization**: The unified `gif` command automatically optimizes based on your flags
5. **Platform-Specific Settings**: Always specify the target platform (`-p`) for optimal results
6. **Parallel Processing**: Use `-j N` flag for batch operations on multi-core systems
7. **Valid existing outputs in `output/` are reused to save time**

## Troubleshooting

### Common Issues

- **FFmpeg not found**: Install FFmpeg and ensure it's in your system PATH
- **Hardware encoder errors**: App falls back to software; use `--force-software` to skip hardware detection
- **Outputs slightly over target**: Use `--target-size` for advanced optimization or reduce FPS/scale/colors
- **Large file sizes**: Use `-s` or `--max-size` to enable automatic quality optimization
- **Poor quality**: Increase quality settings or use `--target-size` with `--quality-preference quality`
- **Batch mode not working**: Ensure glob patterns are quoted (`"*.mp4"` not `*.mp4`)

### Debug Mode

Enable debug logging for detailed information:

```bash
# Long form
python main.py compress input.mp4 output.mp4 --debug

# Short form
python main.py c input.mp4 output.mp4 -v
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

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

## Acknowledgments

- FFmpeg for video processing capabilities
- OpenCV for computer vision features
- Pillow for image processing
- PyYAML for configuration management

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "disdrop",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "video, gif, compression, ffmpeg, discord, twitter",
    "author": "Disdrop",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/78/0f/b0bc7874bf9e2532ebfa8f8da15ead31a0476cd5c6cd9c6b04b235cf10cf/disdrop-0.1.1.tar.gz",
    "platform": null,
    "description": "# Video Compressor & GIF Generator\r\n\r\nA comprehensive Python tool for compressing videos and creating optimized GIFs for social media platforms, with intelligent hardware detection and automated workflows.\r\n\r\n## What's New - Simplified CLI\r\n\r\nThe CLI has been streamlined for easier use while maintaining full functionality:\r\n\r\n\u2728 **Smart Auto-Detection**\r\n\r\n- Glob patterns (`*.mp4`) automatically trigger batch mode\r\n- Unified `gif` command auto-detects operation type (create/optimize/quality)\r\n- No need for separate `batch-compress` or `batch-gif` commands\r\n\r\n\u26a1 **Command Aliases**\r\n\r\n- `c` / `v` / `video` \u2192 `compress`\r\n- `g` / `a` / `anim` \u2192 `gif`\r\n- `w` / `watch` / `m` / `monitor` \u2192 `auto`\r\n- `hw` / `i` / `info` \u2192 `hardware-info`\r\n- `cfg` \u2192 `config`, `ch` \u2192 `cache`\r\n- `open` \u2192 Open application folders in file explorer\r\n\r\n\ud83c\udfaf **Short Flags**\r\n\r\n- `-p` \u2192 `--platform`\r\n- `-s` \u2192 `--max-size`\r\n- `-o` \u2192 `--output-dir`\r\n- `-i` \u2192 `--input-dir`\r\n- `-j` \u2192 `--parallel`\r\n- `-d` \u2192 `--duration`\r\n- `-q` \u2192 `--quality`\r\n- `-f` \u2192 `--fps`\r\n- `-v` \u2192 `--debug`\r\n\r\n**Example:** `python main.py g \"*.mp4\" -o gifs/ -p discord -j 3`\r\n\r\nAll old commands still work for backward compatibility!\r\n\r\n## Features\r\n\r\n- **Video Compression**: Optimize videos for various social media platforms\r\n- **GIF Generation**: Create high-quality GIFs from videos with iterative quality optimization\r\n- **Hardware Acceleration**: Automatic detection and utilization of GPU acceleration\r\n- **Platform Optimization**: Tailored settings for Twitter, Instagram, TikTok, YouTube Shorts, Facebook, Discord, and Slack\r\n- **Batch Processing**: Process multiple files automatically\r\n- **Automated Workflow**: Monitor input directory for new files\r\n- **Quality Optimization**: Iterative GIF optimization to maximize quality while staying under size limits\r\n\r\n## Installation\r\n\r\n1. Clone the repository:\r\n\r\n```bash\r\ngit clone <repository-url>\r\ncd disdrop\r\n```\r\n\r\n2. Create a virtual environment:\r\n\r\n```bash\r\npython -m venv venv\r\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\r\n```\r\n\r\n3. Install dependencies:\r\n\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\n4. Ensure FFmpeg is installed on your system:\r\n\r\n   - **Windows**: Download from https://ffmpeg.org/download.html\r\n   - **macOS**: `brew install ffmpeg`\r\n   - **Linux**: `sudo apt install ffmpeg` (Ubuntu/Debian)\r\n\r\n5. (Optional) Install globally for use from anywhere:\r\n\r\n```bash\r\npip install --user -e .\r\n```\r\n\r\nAfter installation, you can use `disdrop` command from anywhere instead of `python main.py`:\r\n\r\n```bash\r\ndisdrop auto           # Start automated workflow\r\ndisdrop open -i -o     # Open input and output folders\r\ndisdrop hw             # Show hardware info\r\n```\r\n\r\n## Quick Start\r\n\r\n### Zero-argument auto mode\r\n\r\n```bash\r\npython main.py\r\n# or use short alias:\r\npython main.py w\r\n```\r\n\r\nWatches `input/` and processes new files to `output/` (defaults: max size 10 MB, check every 5s). Stop with Ctrl+C.\r\n\r\n### Basic Video Compression\r\n\r\n```bash\r\n# Long form\r\npython main.py compress input.mp4 output.mp4 --platform instagram\r\n\r\n# Short form with aliases\r\npython main.py c input.mp4 output.mp4 -p instagram\r\n```\r\n\r\n### Batch Video Compression (Auto-Detected)\r\n\r\n```bash\r\n# Glob patterns automatically trigger batch mode\r\npython main.py c \"*.mp4\" -o compressed/ -p tiktok -j 4\r\n```\r\n\r\n### Basic GIF Creation\r\n\r\n```bash\r\n# Long form\r\npython main.py gif input.mp4 output.gif --platform twitter\r\n\r\n# Short form with aliases\r\npython main.py g input.mp4 output.gif -p twitter -d 10\r\n```\r\n\r\n### Batch GIF Creation (Auto-Detected)\r\n\r\n```bash\r\n# Glob patterns automatically trigger batch mode\r\npython main.py g \"*.mp4\" -o gifs/ -p discord -j 3\r\n```\r\n\r\n### Quality-Optimized GIF Creation\r\n\r\n```bash\r\n# With max-size (iterative optimization)\r\npython main.py g input.mp4 output.gif -s 5.0 -p twitter\r\n\r\n# With target-size (advanced optimization)\r\npython main.py g input.mp4 output.gif --target-size 5.0 --quality-preference balanced\r\n```\r\n\r\n### Optimize an existing GIF\r\n\r\n```bash\r\n# Auto-detected when both input and output are GIFs\r\npython main.py g input.gif output.gif\r\n```\r\n\r\n### Automated workflow\r\n\r\n```bash\r\n# Long form\r\npython main.py auto --check-interval 10 -s 8\r\n\r\n# Short aliases\r\npython main.py w --check-interval 10 -s 8\r\npython main.py watch --check-interval 10 -s 8\r\n```\r\n\r\n## How It Works\r\n\r\n### Video Compression\r\n\r\n- Content analysis (ffprobe) informs encoder, bitrate, FPS, and resolution\r\n- Hardware acceleration is used when available with robust software fallback\r\n- If a single output cannot reasonably meet target size, the system may invoke the video segmenter as a last resort\r\n\r\nVideo segmentation behavior (configurable in `config/video_compression.yaml`):\r\n\r\n- Default trigger: estimated size \u2265 3.0\u00d7 target, or extremely long videos (\u2265 10 minutes)\r\n- Segment duration stays within bounds and is tuned by content complexity and motion\r\n\r\n### GIF Creation and Optimization\r\n\r\n- Generates high-quality GIFs with a palette pipeline, `mpdecimate`, and aspect-ratio preservation (`force_original_aspect_ratio=decrease`, `setsar=1`)\r\n- If `--max-size` is given, an iterative optimizer searches multiple quality stages to land under the target with best visual fidelity\r\n- Platforms supported by CLI: `twitter`, `discord` (8 MB), `slack`. Internal presets also exist for Telegram/Reddit\r\n- GIF segmentation is adaptive: long/complex source clips can be split into multiple GIFs; nested segmentation is avoided\r\n\r\n### Iterative Quality Optimization for GIFs\r\n\r\nThe tool includes an advanced iterative optimization system that automatically tries to generate the best quality GIF possible while staying within size limits. This feature performs multiple optimization attempts with different quality levels to find the optimal balance.\r\n\r\n#### How It Works\r\n\r\n1. **Quality Stages**: The system tries multiple quality levels in order:\r\n\r\n   - **Maximum Quality**: Highest resolution, FPS, colors, and best dithering\r\n   - **High Quality**: Good balance of quality and size\r\n   - **Medium Quality**: Moderate settings for smaller files\r\n   - **Standard Quality**: Basic settings as fallback\r\n\r\n2. **Iterative Attempts**: For each quality stage:\r\n\r\n   - Attempts multiple GIF generation methods (FFmpeg palette, direct conversion, OpenCV+PIL)\r\n   - If the result is under the size limit, calculates a quality score\r\n   - If too large, reduces parameters and tries again\r\n   - Continues until finding the best quality result within size limits\r\n\r\n3. **Quality Scoring**: Each successful attempt is scored based on:\r\n\r\n   - Color depth (0-256 colors)\r\n   - Frame rate quality (up to 30fps)\r\n   - Resolution quality (up to 800x800)\r\n   - Size efficiency (how close to target size)\r\n   - Compression quality (lossy settings)\r\n   - Dithering quality (Floyd-Steinberg vs Bayer)\r\n\r\n4. **Best Result Selection**: Chooses the result with the highest quality score that meets size requirements\r\n\r\n## CLI Overview\r\n\r\n### Smart Features\r\n\r\n- **Auto-Batch Detection**: Glob patterns (`*.mp4`) automatically trigger batch mode\r\n- **Unified GIF Command**: Single `gif` command auto-detects optimization type\r\n- **Command Aliases**: Short versions for faster typing\r\n- **Short Flags**: Single-letter options for common flags\r\n\r\n### Global Options\r\n\r\n| Long Form           | Short | Description                             |\r\n| ------------------- | ----- | --------------------------------------- |\r\n| `--debug`           | `-v`  | Verbose console + file logs             |\r\n| `--max-size MB`     | `-s`  | Global size cap for output files        |\r\n| `--output-dir PATH` | `-o`  | Output directory for all modes          |\r\n| `--input-dir PATH`  | `-i`  | Input directory for auto mode           |\r\n| `--temp-dir PATH`   |       | Temporary directory (default: `./temp`) |\r\n| `--force-software`  |       | Bypass hardware encoders                |\r\n| `--no-cache`        |       | Don't use success cache                 |\r\n\r\n### Commands and Aliases\r\n\r\n| Command         | Aliases                      | Description              |\r\n| --------------- | ---------------------------- | ------------------------ |\r\n| `compress`      | `c`, `v`, `video`            | Compress video file(s)   |\r\n| `gif`           | `g`, `a`, `anim`             | Create/optimize GIF(s)   |\r\n| `auto`          | `w`, `watch`, `m`, `monitor` | Watch input folder       |\r\n| `open`          | -                            | Open app folders         |\r\n| `hardware-info` | `hw`, `i`, `info`            | Show hardware info       |\r\n| `config`        | `cfg`                        | Configuration management |\r\n| `cache`         | `ch`                         | Cache operations         |\r\n\r\n### Command Details\r\n\r\n#### compress / c / v / video\r\n\r\nCompress video file(s). Auto-detects batch mode from glob patterns.\r\n\r\n```bash\r\ncompress <input> [output] [options]\r\n```\r\n\r\n**Options:**\r\n\r\n- `-p, --platform` - Target platform (instagram, twitter, tiktok, youtube_shorts, facebook)\r\n- `-q, --quality CRF` - Quality setting (lower = better)\r\n- `-f, --fps N` - Target frame rate\r\n- `--encoder` - Force specific encoder\r\n- `--bitrate` - Target bitrate (e.g., 1000k)\r\n- `--resolution` - Target resolution (e.g., 1080x1080)\r\n- `--suffix` - Suffix for batch output files (default: \\_compressed)\r\n- `-j, --parallel N` - Number of parallel processes for batch\r\n\r\n#### gif / g / a / anim\r\n\r\nCreate or optimize GIF(s). Auto-detects operation type and batch mode.\r\n\r\n```bash\r\ngif <input> [output] [options]\r\n```\r\n\r\n**Options:**\r\n\r\n- `-p, --platform` - Target platform (twitter, discord, slack)\r\n- `-s, --max-size MB` - Max file size (enables quality optimization)\r\n- `--target-size MB` - Target size for advanced optimization\r\n- `-d, --duration S` - Duration in seconds\r\n- `--start S` - Start time in seconds\r\n- `-f, --fps N` - Frame rate\r\n- `--width W` - Width in pixels\r\n- `--height H` - Height in pixels\r\n- `--colors C` - Number of colors in palette\r\n- `--quality-preference` - Strategy: quality, balanced, size\r\n- `-j, --parallel N` - Number of parallel processes for batch\r\n\r\n#### auto / w / watch / m / monitor\r\n\r\nWatch input folder and automatically process new files.\r\n\r\n```bash\r\nauto [options]\r\n```\r\n\r\n**Options:**\r\n\r\n- `--check-interval S` - Check frequency in seconds (default: 5)\r\n- `-s, --max-size MB` - Max output size (default: 10.0)\r\n- `-i, --input-dir PATH` - Input directory (default: ./input)\r\n- `-o, --output-dir PATH` - Output directory (default: ./output)\r\n- `--no-cache` - Don't use success cache\r\n\r\n#### open\r\n\r\nOpen application folders in file explorer. Useful for quickly accessing input, output, logs, or config directories.\r\n\r\n```bash\r\nopen [options]\r\n```\r\n\r\n**Options:**\r\n\r\n- `-i, --input` - Open input folder\r\n- `-o, --output` - Open output folder\r\n- `-l, --logs` - Open logs folder\r\n- `-c, --config` - Open config folder\r\n\r\n**Examples:**\r\n\r\n```bash\r\n# Open single folder\r\ndisdrop open -i                # Open input folder\r\ndisdrop open -o                # Open output folder\r\n\r\n# Open multiple folders at once\r\ndisdrop open -i -o -l          # Open input, output, and logs folders\r\n```\r\n\r\nNote: Folders are created if they don't exist. Works cross-platform (Windows, macOS, Linux).\r\n\r\n#### Other Commands\r\n\r\n- `hardware-info` / `hw` / `i` / `info` - Display hardware acceleration info\r\n- `config` / `cfg` `show|validate` - Configuration management\r\n- `cache` / `ch` `clear|stats|validate` - Cache operations\r\n\r\n### Quick Reference Card\r\n\r\nCommon tasks with shortest syntax:\r\n\r\n```bash\r\n# Compress single video for Instagram\r\npython main.py c video.mp4 out.mp4 -p instagram\r\n\r\n# Batch compress all videos for TikTok\r\npython main.py c \"*.mp4\" -o compressed/ -p tiktok -j 4\r\n\r\n# Create GIF for Twitter\r\npython main.py g video.mp4 out.gif -p twitter -s 5\r\n\r\n# Batch create GIFs for Discord\r\npython main.py g \"*.mp4\" -o gifs/ -p discord -j 3\r\n\r\n# Optimize existing GIF\r\npython main.py g input.gif output.gif\r\n\r\n# Watch folder for new files\r\npython main.py w\r\n\r\n# Open folders in file explorer\r\npython main.py open -i -o\r\n\r\n# Check hardware capabilities\r\npython main.py hw\r\n\r\n# Show configuration\r\npython main.py cfg show\r\n\r\n# Clear cache\r\npython main.py ch clear\r\n```\r\n\r\n## Configuration\r\n\r\nDefault configuration files are packaged under `disdrop/config/` and used automatically. To override, use `--config-dir PATH` or set `DISDROP_BASE_DIR` to change the runtime base (for logs/input/output/temp).\r\n\r\n- `video_compression.yaml`: max size (default 10 MB), hardware encoders, conservative segmentation policy, platform presets\r\n- `gif_settings.yaml`: default max size (10 MB), FPS/resolution, palette/dither/lossy, quality-optimization stages, segmentation heuristics\r\n- `logging.yaml`: console/file logging formats and levels (logs in `logs/`)\r\n\r\n### Examples (abridged)\r\n\r\n```yaml\r\n# video_compression.yaml\r\nvideo_compression:\r\n  max_file_size_mb: 10\r\n  segmentation:\r\n    size_threshold_multiplier: 3.0\r\n    fallback_duration_limit: 600\r\n\r\n# gif_settings.yaml\r\ngif_settings:\r\n  max_file_size_mb: 10\r\n  fps: 20\r\n  width: 360\r\n  height: 360\r\n  quality_optimization:\r\n    enabled: true\r\n```\r\n\r\nCLI overrides map into config at runtime, for example:\r\n\r\n- `--max-size 8.0` \u2192 `video_compression.max_file_size_mb` and `gif_settings.max_file_size_mb`\r\n- `--fps 20` \u2192 `video_compression.platforms.custom.fps` and `gif_settings.fps`\r\n- `--width/--height/--colors` \u2192 `gif_settings.width/height/colors`\r\n\r\n### Custom Platform Configuration\r\n\r\nAdd custom platform settings in `gif_settings.yaml`:\r\n\r\n```yaml\r\nplatforms:\r\n  custom_platform:\r\n    max_width: 500\r\n    max_height: 500\r\n    max_duration: 12\r\n    colors: 128\r\n    max_file_size_mb: 6\r\n    dither: \"floyd_steinberg\"\r\n    lossy: 30\r\n```\r\n\r\n## Platform-Specific Optimization\r\n\r\nThe tool automatically applies platform-specific optimizations:\r\n\r\n- **Twitter**: 506x506 max, 15s duration, optimized for web viewing\r\n- **Discord**: 400x400 max, 10s duration, 8MB limit for free users\r\n- **Slack**: 360x360 max, 8s duration, conservative compression\r\n- **Instagram**: 1080x1080 max, optimized for mobile viewing\r\n- **TikTok**: 1080x1920 max, vertical format optimization\r\n\r\n## Hardware Acceleration\r\n\r\nThe tool automatically detects and utilizes available hardware:\r\n\r\n- **NVIDIA GPU**: NVENC encoder for fast compression\r\n- **AMD GPU**: AMF encoder support\r\n- **Intel GPU**: QSV encoder for integrated graphics\r\n- **Apple Silicon**: VideoToolbox for M1/M2 Macs\r\n\r\n## Examples\r\n\r\n### Example 1: Social Media Content Creation\r\n\r\n```bash\r\n# Create Instagram-optimized video (long form)\r\npython main.py compress raw_video.mp4 instagram_video.mp4 --platform instagram\r\n\r\n# Create Instagram-optimized video (short form)\r\npython main.py c raw_video.mp4 instagram_video.mp4 -p instagram\r\n\r\n# Create Twitter GIF with quality optimization (long form)\r\npython main.py gif raw_video.mp4 twitter_gif.gif --target-size 5.0 --quality-preference balanced -p twitter\r\n\r\n# Create Twitter GIF with quality optimization (short form)\r\npython main.py g raw_video.mp4 twitter_gif.gif --target-size 5.0 -p twitter\r\n```\r\n\r\n### Example 2: Batch Processing (Auto-Detected)\r\n\r\n```bash\r\n# Process all videos for Instagram (auto-detects batch mode from glob pattern)\r\npython main.py c \"videos/*.mp4\" -o instagram/ -p instagram -j 4\r\n\r\n# Process all videos for Twitter\r\npython main.py c \"videos/*.mp4\" -o twitter/ -p twitter -j 4\r\n\r\n# Create GIFs for Discord from all videos\r\npython main.py g \"videos/*.mp4\" -o gifs/ -p discord -d 8 -j 3\r\n```\r\n\r\n### Example 3: Automated Workflow\r\n\r\n```bash\r\n# Start automated processing (long form)\r\npython main.py auto --check-interval 30 -s 8.0\r\n\r\n# Start automated processing (short aliases)\r\npython main.py w --check-interval 30 -s 8.0\r\npython main.py watch --check-interval 30 -s 8.0\r\n\r\n# Place videos in input/ directory and they'll be processed automatically\r\n```\r\n\r\n### Example 4: Quick Commands with Aliases\r\n\r\n```bash\r\n# Check hardware capabilities\r\npython main.py hw\r\n\r\n# Show configuration\r\npython main.py cfg show\r\n\r\n# Clear cache\r\npython main.py ch clear\r\n\r\n# Optimize existing GIF (auto-detected)\r\npython main.py g input.gif output.gif\r\n```\r\n\r\n## Performance Tips\r\n\r\n1. **Use Hardware Acceleration**: The tool automatically detects and uses GPU acceleration when available\r\n2. **Batch Processing**: Use glob patterns (`*.mp4`) for automatic batch processing\r\n3. **Short Commands**: Use aliases (`c`, `g`, `w`) and short flags (`-p`, `-s`, `-o`) for faster typing\r\n4. **Quality Optimization**: The unified `gif` command automatically optimizes based on your flags\r\n5. **Platform-Specific Settings**: Always specify the target platform (`-p`) for optimal results\r\n6. **Parallel Processing**: Use `-j N` flag for batch operations on multi-core systems\r\n7. **Valid existing outputs in `output/` are reused to save time**\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n- **FFmpeg not found**: Install FFmpeg and ensure it's in your system PATH\r\n- **Hardware encoder errors**: App falls back to software; use `--force-software` to skip hardware detection\r\n- **Outputs slightly over target**: Use `--target-size` for advanced optimization or reduce FPS/scale/colors\r\n- **Large file sizes**: Use `-s` or `--max-size` to enable automatic quality optimization\r\n- **Poor quality**: Increase quality settings or use `--target-size` with `--quality-preference quality`\r\n- **Batch mode not working**: Ensure glob patterns are quoted (`\"*.mp4\"` not `*.mp4`)\r\n\r\n### Debug Mode\r\n\r\nEnable debug logging for detailed information:\r\n\r\n```bash\r\n# Long form\r\npython main.py compress input.mp4 output.mp4 --debug\r\n\r\n# Short form\r\npython main.py c input.mp4 output.mp4 -v\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests if applicable\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Acknowledgments\r\n\r\n- FFmpeg for video processing capabilities\r\n- OpenCV for computer vision features\r\n- Pillow for image processing\r\n- PyYAML for configuration management\r\n",
    "bugtrack_url": null,
    "license": "MIT License\r\n        \r\n        Copyright (c) 2025 Disdrop\r\n        \r\n        Permission is hereby granted, free of charge, to any person obtaining a copy\r\n        of this software and associated documentation files (the \"Software\"), to deal\r\n        in the Software without restriction, including without limitation the rights\r\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n        copies of the Software, and to permit persons to whom the Software is\r\n        furnished to do so, subject to the following conditions:\r\n        \r\n        The above copyright notice and this permission notice shall be included in all\r\n        copies or substantial portions of the Software.\r\n        \r\n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n        SOFTWARE.\r\n        ",
    "summary": "Compress videos and create platform-optimized GIFs (Discord/Twitter/etc.)",
    "version": "0.1.1",
    "project_urls": null,
    "split_keywords": [
        "video",
        " gif",
        " compression",
        " ffmpeg",
        " discord",
        " twitter"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1b8adaee4df49304a00d4943f4a1f3da7731b79f7a8227540931192810f04649",
                "md5": "d4be18d95a10bb12ea0af0b44313f893",
                "sha256": "2fb8544a3483010341d6157aae96a8d3f8aae53958b6103dbc79451754968e70"
            },
            "downloads": -1,
            "filename": "disdrop-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "d4be18d95a10bb12ea0af0b44313f893",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 177620,
            "upload_time": "2025-10-10T02:09:35",
            "upload_time_iso_8601": "2025-10-10T02:09:35.682286Z",
            "url": "https://files.pythonhosted.org/packages/1b/8a/daee4df49304a00d4943f4a1f3da7731b79f7a8227540931192810f04649/disdrop-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "780fb0bc7874bf9e2532ebfa8f8da15ead31a0476cd5c6cd9c6b04b235cf10cf",
                "md5": "ad2e0a585587c2e2b8911a3247313fcf",
                "sha256": "63e3c7bdafc857270db48b4edb2a6ef3f462b29cebd71f64b9e0939195213e07"
            },
            "downloads": -1,
            "filename": "disdrop-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "ad2e0a585587c2e2b8911a3247313fcf",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 168469,
            "upload_time": "2025-10-10T02:09:36",
            "upload_time_iso_8601": "2025-10-10T02:09:36.889665Z",
            "url": "https://files.pythonhosted.org/packages/78/0f/b0bc7874bf9e2532ebfa8f8da15ead31a0476cd5c6cd9c6b04b235cf10cf/disdrop-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-10 02:09:36",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "disdrop"
}