# jpg2heic

**Repository Path**: C12bit/jpg2heic

## Basic Information

- **Project Name**: jpg2heic
- **Description**: jpg2heic 是一个多线程批量图片转换工具，用于将JPG/JPEG格式的图片转换为HEIC格式。相同的人眼清晰度下，HEIF格式图像的大小相较于JPG减小30%~50%。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-06
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JPG2HEIC User Guide

Project based on https://github.com/zanjie1999/png2heic open source project, modified for JPG to HEIC conversion with multi-process and multi-threading technology to improve conversion speed.

## Introduction
JPG2HEIC is a high-performance batch image conversion tool specifically designed to convert JPG/JPEG format images to HEIC format.

HEIC format can save 40-60% storage space compared to JPG while maintaining the same visual quality, with almost lossless compression that is visually indistinguishable.

### Core Advantages
- **Extreme Compression**: Halve file size while maintaining image quality, significantly reducing storage space
- **Preserve Complete Information**: Retain original directory structure, modification dates, and EXIF image information
- **Color Optimization**: Use yuvj420p color space to alleviate color deviation issues compared to yuv420 vs yuv444
- **Compatibility Priority**: Default configuration achieves perfect compatibility across all platforms
- **Smart Processing**: Automatically skip processed files, temporary files are automatically cleaned up

## Main Features
- ✅ **Multi-process Parallel**: Support multi-process parallel processing of different directories
- ✅ **Multi-threaded Acceleration**: Use thread pool within each process to handle files
- ✅ **Smart Skip**: Automatically skip existing output files
- ✅ **Progress Display**: Real-time display of conversion progress and estimated remaining time
- ✅ **Error Handling**: Comprehensive error handling and retry mechanisms
- ✅ **Performance Optimization**: Optimized file scanning and processing workflow

## System Requirements
- Python 3.6+
- Dependency Tools:
  - ffmpeg (video/image processing)
  - mp4box/gpac (HEIC container processing)
  - exiftool (optional, for EXIF information copying)

## Installing Dependencies

### Windows
1. **FFmpeg**: Download from https://www.gyan.dev/ffmpeg/builds
2. **GPAC/MP4Box**: Download from https://gpac.io/downloads
3. **ExifTool**: Download from https://exiftool.org/index.html (optional)

**Quick Installation Method**:
- Check jpg2heic.py file header comments for detailed installation instructions
- [Video Tutorial: How to Install on Windows](https://www.bilibili.com/video/BV1jefDYfEiB)
- Windows HEIC Support: Install HEIF plugin from Microsoft Store, or run `start ms-windows-store://pdp/?ProductId=9n4wgh0z6vhq` in cmd to install HEVC plugin, then you can use the built-in image viewer to view HEIC files with thumbnail support (LTSC systems need to install Store first)

### macOS
```bash
brew install ffmpeg mp4box exiftool
```

### Linux (Ubuntu/Debian)
```bash
sudo apt-get install ffmpeg gpac exiftool
```

## Usage

### Quick Start
1. Edit configuration file `config.py`, set input/output paths and conversion parameters
2. Run conversion script:
   ```bash
   python jpg2heic.py
   ```

### Configuration File Instructions
Edit the `config.py` file to configure conversion options:

```python
# Input/Output Path Configuration
INPUT_OUTPUT_PATHS = {
    'your_input_directory/': 'your_output_directory/',
    'D:/Pictures/': 'D:/Pictures_HEIC/',
}

# Conversion Options
CONVERSION_OPTIONS = {
    'copy_exif': True,      # Whether to copy EXIF information
    'use_10bit': False,      # Use 10-bit color depth (better quality)
    'use_yuv444': False,     # Use yuv444 color space
    'delete_original': False, # Delete original files after conversion (be careful!)
}

# Performance Options
PERFORMANCE_OPTIONS = {
    'max_processes': 8,      # Maximum number of processes
    'thread_pool_size': 16,  # Thread pool size
    'show_progress_bar': True, # Show progress bar
}
```

### Performance Tuning

#### Process Count Settings
- **Default**: Use CPU core count, maximum 8
- **Recommendation**: For IO-intensive tasks, can set slightly higher than CPU core count
- **Note**: Too many processes may exhaust system resources

#### Thread Pool Size
- **Default**: CPU core count × 2, maximum 16
- **Recommendation**: Adjust based on specific hardware and file size
- **SSD**: Can set larger values
- **HDD**: Recommend smaller values to avoid disk IO bottleneck

## Conversion Quality

### Encoding Parameters
- **CRF Value**: 10 (high quality, larger files)
- **Preset**: veryslow (slowest but best quality)
- **Color Space**: yuvj420p (best compatibility, alleviates color deviation)

**Important Notes**:
- CRF value range 0-51, 0 is lossless, smaller values mean better quality and larger files, recommended 5 or 10; but I personally use 23 and still achieve excellent image quality
- Use CPU compression for best image quality, hardware acceleration is faster but results in larger files and lower quality

### File Size
Compared to original JPG files, HEIC files typically save 40-60% storage space while maintaining the same visual quality.

## Common Issues

### Q: Conversion failed, what should I do?
A: Check the following:
1. Confirm all dependency tools are properly installed
2. Check if input files are corrupted
3. Confirm sufficient disk space
4. View console output error messages

### Q: Conversion speed is very slow?
A: Try adjusting performance parameters:
1. Increase process count and thread pool size
2. Use faster encoding presets (like `fast` instead of `veryslow`)
3. Check if disk IO becomes a bottleneck

### Q: Output file quality is poor?
A: Quality-related settings:
1. Decrease CRF value (like set to 5) for better quality
2. Enable 10-bit color depth for better color
3. Use yuv444 color space (but compatibility decreases)

### Q: How to handle large numbers of files?
A: For large file conversions:
1. Use smaller batch sizes
2. Process in batches to avoid memory overflow
3. Monitor system resource usage

## Advanced Usage

### Custom FFmpeg Parameters
Edit the `ADVANCED_OPTIONS` section in the configuration file:
```python
ADVANCED_OPTIONS = {
    'ffmpeg_args': r'-deblock 1:1 -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2,crop=1920:1080:0:0"',
    'hevc_crf': 5,           # Higher quality
    'encoding_preset': 'medium', # Balance speed and quality
}
```

## Troubleshooting

### Dependency Check Failed
Ensure all tools are available before running:
```bash
ffmpeg -version
mp4box -version
exiftool -version
```

**Important Tips**:
- Presumably no one really reads the documentation, but if you do, there's also a video tutorial on how to install on Windows
- Once configured, just run and it will automatically convert, no complex setup needed
- Temporary file size is about 1-2 times the original file, ensure sufficient disk space

### High Memory Usage
If you encounter memory issues:
1. Reduce process count and thread count
2. Use smaller batch sizes
3. Process large files in batches

### Insufficient Disk Space
HEIC conversion generates temporary files, ensure sufficient disk space:
- Temporary file size is about 1-2 times the original file
- Final output file is about 40-60% of the original file

## Update Log

### v1.2 (Current Version)
- ✅ Integrated core features from original PNG2HEIC
- ✅ Optimized color space using yuvj420p
- ✅ Improved CRF value and encoding preset configuration
- ✅ Enhanced Windows HEIC support instructions
- ✅ Added detailed dependency installation guidance

### v1.1 
- ✅ Optimized file scanning and processing workflow
- ✅ Added progress bar display
- ✅ Improved error handling and logging
- ✅ Added dependency checking
- ✅ Optimized memory usage

### v1.0
- ✅ Initial version with multi-process and multi-threading support
- ✅ Focused on JPG to HEIC conversion
- ✅ Basic configuration file support

## License
Modified based on the original PNG2HEIC project, following the same open source license.

## Project Background
Because I couldn't find any tools online to convert images to HEIC format, only tools to convert HEIC to JPG or PNG. I wrote a Python3 script that works well on powerful M1 Macs, Linux, and also supports Windows.

## Related Projects
- [Go Language Lossy Image Compression Tool](https://github.com/zanjie1999/mecopy) - Supports PNG and JPG, no dependencies required

## Technical Support
If you encounter problems, please:
1. Check console output error messages
2. Check configuration file settings
3. Ensure all dependency tools are properly installed
4. Try debugging with a smaller test set
5. Refer to video tutorial: [How to Install on Windows](https://www.bilibili.com/video/BV1jefDYfEiB)