# heic-converter

Convert HEIC images to PNG/JPEG entirely in the browser using [libheif-js](https://github.com/catdad-experiments/libheif-js).

[**Try the Live Demo**](https://thomasvstrijland.github.io/heic-converter)

## Features

- **Zero backend dependencies** - Runs entirely in the browser using WebAssembly
- **Simple API** - Clear function names and straightforward usage
- **TypeScript support** - Full type definitions included
- **Multi-image support** - Handle HEIC files with multiple images (bursts)
- **Privacy-focused** - All processing happens client-side

## Installation

```bash
npm install heic-converter
```

## Quick Start

```javascript
import { heicToPng, heicToJpeg } from 'heic-converter';

// Convert HEIC to PNG
const pngBlob = await heicToPng(heicFile);

// Convert HEIC to JPEG with quality setting
const jpegBlob = await heicToJpeg(heicFile, { quality: 0.8 });
```

## Usage

### Convert to PNG

```javascript
import { heicToPng } from 'heic-converter';

const pngBlob = await heicToPng(heicFile);
const url = URL.createObjectURL(pngBlob);
```

### Convert to JPEG

```javascript
import { heicToJpeg } from 'heic-converter';

const jpegBlob = await heicToJpeg(heicFile, { quality: 0.92 });
```

### Handle Multi-Image HEIC Files

HEIC files can contain multiple images (e.g., burst photos):

```javascript
import { heicToPng } from 'heic-converter';

const pngBlobs = await heicToPng(heicFile, { multiple: true });
pngBlobs.forEach((blob, index) => {
  console.log(`Image ${index + 1}:`, blob);
});
```

### Check if File is HEIC

```javascript
import { isHeic } from 'heic-converter';

if (await isHeic(file)) {
  const pngBlob = await heicToPng(file);
}
```

### Advanced Usage

```javascript
import { convert } from 'heic-converter';

const blob = await convert(heicFile, {
  format: 'jpeg',
  quality: 0.95,
  multiple: false
});
```

## API Reference

### `heicToPng(blob, options?)`

Converts a HEIC image to PNG format.

| Parameter | Type | Description |
|-----------|------|-------------|
| `blob` | `Blob` | The HEIC image to convert |
| `options.multiple` | `boolean` | Extract all images from multi-image HEIC files (default: `false`) |

**Returns:** `Promise<Blob>` or `Promise<Blob[]>` if `multiple` is `true`

---

### `heicToJpeg(blob, options?)`

Converts a HEIC image to JPEG format.

| Parameter | Type | Description |
|-----------|------|-------------|
| `blob` | `Blob` | The HEIC image to convert |
| `options.quality` | `number` | JPEG quality between 0 and 1 (default: `0.92`) |
| `options.multiple` | `boolean` | Extract all images from multi-image HEIC files (default: `false`) |

**Returns:** `Promise<Blob>` or `Promise<Blob[]>` if `multiple` is `true`

---

### `convert(blob, options)`

Generic conversion function for advanced use cases.

| Parameter | Type | Description |
|-----------|------|-------------|
| `blob` | `Blob` | The HEIC image to convert |
| `options.format` | `'png' \| 'jpeg'` | Output format (required) |
| `options.quality` | `number` | JPEG quality between 0 and 1 (default: `0.92`, ignored for PNG) |
| `options.multiple` | `boolean` | Extract all images from multi-image HEIC files (default: `false`) |

**Returns:** `Promise<Blob>` or `Promise<Blob[]>` if `multiple` is `true`

---

### `isHeic(blob)`

Checks if a file is a HEIC/HEIF image by examining its file signature.

| Parameter | Type | Description |
|-----------|------|-------------|
| `blob` | `Blob` | The file to check |

**Returns:** `Promise<boolean>` - `true` if the file is HEIC/HEIF

## TypeScript

Full TypeScript support with included type definitions:

```typescript
import type { ConvertOptions, ConvertOptionsWithFormat } from 'heic-converter';

interface ConvertOptions {
  quality?: number;      // 0-1 for JPEG (default: 0.92)
  multiple?: boolean;    // Handle multi-image HEIC files (default: false)
}

interface ConvertOptionsWithFormat extends ConvertOptions {
  format: 'png' | 'jpeg';
}
```

## Browser Support

Requires a modern browser with:
- WebAssembly support
- Canvas API
- ES2020+ features

Supported browsers:
- Chrome/Edge 87+
- Firefox 89+
- Safari 15+

## How It Works

1. Uses [libheif-js](https://github.com/catdad-experiments/libheif-js) (WebAssembly) to decode HEIC to raw image data
2. Renders the decoded data to an HTML Canvas
3. Exports the canvas as PNG or JPEG Blob
4. All processing happens entirely in the browser - no server uploads

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/ThomasVStrijland/heic-converter).

## Credits

Built with [libheif-js](https://github.com/catdad-experiments/libheif-js), the WebAssembly build of libheif.