image_editor_output_format │ filter-hook │ WP 5.8.0

Allows changing the format in which the WordPress image editor saves processed images and generated sizes.

The filter receives an array in the form source MIME type => output MIME type. By default, WordPress converts HEIC and HEIF to JPEG:

[
	'image/heic'          => 'image/jpeg',
	'image/heif'          => 'image/jpeg',
	'image/heic-sequence' => 'image/jpeg',
	'image/heif-sequence' => 'image/jpeg',
]

Conversion is performed only to a format supported by the image editor in use.

Usage

add_filter( 'image_editor_output_format', 'image_editor_output_format_filter', 10, 3 );

/**
 * Filters the image editor output format mapping.
 *
 * @param array $output_format  An array of mime type mappings. Maps a source mime type to a new
 *                              destination mime type. By default maps HEIC/HEIF input to JPEG output.
 * @param string $filename      Path to the image.
 * @param string $mime_type     The source image mime type.
 */
function image_editor_output_format_filter( $output_format, $filename, $mime_type ){
	// filter...
	return $output_format;
}

$output_format(string[])

An array of mappings in the form source MIME type => output MIME type.

$filename(string)

Path to the source image. It can be an empty string when the path is unavailable in the current context.

$mime_type(string)

MIME type of the source image.

Examples

#1 Convert JPEG to WebP

Saves JPEG image sizes in WebP format.

add_filter( 'image_editor_output_format', 'kama_convert_jpeg_to_webp' );

function kama_convert_jpeg_to_webp( $formats ) {
	$formats['image/jpeg'] = 'image/webp';

	return $formats;
}

#2 Convert JPEG, PNG, WebP, and HEIC/HEIF to AVIF

Saves generated sizes of supported images in AVIF format.

add_filter( 'image_editor_output_format', 'kama_convert_images_to_avif' );

function kama_convert_images_to_avif( $formats ) {
	$source_formats = [
		'image/jpeg',
		'image/png',
		'image/webp',
		'image/heic',
		'image/heif',
		'image/heic-sequence',
		'image/heif-sequence',
	];

	foreach ( $source_formats as $source_format ) {
		$formats[ $source_format ] = 'image/avif';
	}

	return $formats;
}

HEIC/HEIF processing and saving as AVIF must be supported by the image processing library in use.

#3 Convert only a specific file

Converts JPEG to WebP only for images from the products directory.

add_filter( 'image_editor_output_format', 'kama_convert_product_images', 10, 3 );

function kama_convert_product_images( $formats, $filename, $mime_type ) {
	if (
		'image/jpeg' === $mime_type
		&& str_contains( wp_normalize_path( $filename ), '/products/' )
	) {
		$formats['image/jpeg'] = 'image/webp';
	}

	return $formats;
}

#4 Disable format conversion

Disables custom rules and the default HEIC/HEIF-to-JPEG conversion.

add_filter( 'image_editor_output_format', 'kama_disable_image_format_conversion' );

function kama_disable_image_format_conversion() {
	return [];
}