Developer reference

Code lives under the BytCrush\ namespace in includes/. The prefix for options, meta keys and hooks is bytcrush_. The REST namespace is bytcrush/v1.

Filters

bytcrush_skip_auto_optimize

Skip automatic optimization for a specific upload. The image stays pending and can still be optimized by a bulk run or by hand.

add_filter( 'bytcrush_skip_auto_optimize', function ( $skip, $attachment_id ) {
	// e.g. leave uploads to a "Print files" folder alone.
	$file = get_attached_file( $attachment_id );
	return $skip || false !== strpos( (string) $file, '/print/' );
}, 10, 2 );

bytcrush_mimes

The attachment mime types BytCrush works on. Default: image/jpeg, image/png, image/webp, image/gif. The engine can only process these four, so this is mainly useful for removing one.

add_filter( 'bytcrush_mimes', function ( $mimes ) {
	return array_diff( $mimes, array( 'image/gif' ) ); // never touch GIFs.
} );

bytcrush_levels

The compression presets shown on the Settings screen, keyed by slug. Each preset is an array:

add_filter( 'bytcrush_levels', function ( $levels ) {
	$levels['balanced']['jpeg'] = 76;
	return $levels;
} );

A saved level that no longer exists falls back to balanced.

bytcrush_sibling_formats

The next-gen copies created for one file. Only the webp and avif keys are used.

apply_filters( 'bytcrush_sibling_formats', $siblings, $settings, $level, $format );
// $siblings: array( 'webp' => array( 'quality' => 80, 'lossless' => false, 'sources' => array( 'jpeg', 'png', 'gif' ) ) )
// $format:   format of the file being processed: jpeg | png | webp | gif

A copy is created only when the file's format is in that entry's sources. Removing an entry deletes that copy from the file the next time it's processed.

// No WebP copies for PNGs.
add_filter( 'bytcrush_sibling_formats', function ( $siblings, $settings, $level, $format ) {
	if ( 'png' === $format ) {
		unset( $siblings['webp'] );
	}
	return $siblings;
}, 10, 4 );

bytcrush_served_formats

The formats delivered to browsers, best first (array( 'avif', 'webp' ) when both are on). Used by picture tags and by the rewrite rules.

apply_filters( 'bytcrush_served_formats', $formats, $settings );

The rewrite rules are written when settings are saved, so save the Settings screen once after changing this filter.

bytcrush_driver

Force the image library: 'imagick' or 'gd'. Empty (the default) means Imagick when available, otherwise GD. Only 'gd' changes anything in practice, since Imagick is already preferred.

add_filter( 'bytcrush_driver', function () {
	return 'gd';
} );

bytcrush_encoded

Post-process an encode. Pro's Smart target file size uses it to re-encode until the file fits. The callback must return the same shape.

apply_filters( 'bytcrush_encoded', $encoded, $driver, $format, $flags, $options );
// $encoded: array( 'blob' => string, 'quality' => int, 'resized' => bool )
// $driver:  BytCrush\Engine\Driver\Driver (may be resized by the callback)
// $format:  jpeg | png | webp | avif
// $flags:   array( 'subsample' => bool, 'png_lossy' => bool, 'lossless' => bool )
// $options: the compress options, including 'target_bytes' and 'min_width'

bytcrush_img_tag

Filter each <img> tag of a front-end page. The page is buffered and processed once; <img> tags inside <picture>, <noscript>, <script>, <style>, <textarea> and HTML comments are skipped. Picture delivery hooks in at priority 20 (Pro's page fixes at 5). The page is only buffered when at least one callback is attached.

add_filter( 'bytcrush_img_tag', function ( $tag, $index ) {
	// $index: 0-based position among the page's images.
	return 0 === $index ? str_replace( '<img ', '<img fetchpriority="high" ', $tag ) : $tag;
}, 10, 2 );

bytcrush_picture_enabled

Return false to skip <picture> wrapping for the current request.

add_filter( 'bytcrush_picture_enabled', function ( $enabled ) {
	return $enabled && ! is_page( 'gallery' );
} );

bytcrush_buffer_enabled

Return false to turn off all of BytCrush's HTML processing for the current request (picture tags and Pro page fixes).

bytcrush_bulk_time_budget

Seconds one bulk request keeps processing images before it returns. Default 20. Applies to the dashboard runner, background batches and Restore all. Lower it on hosts with a short PHP time limit.

add_filter( 'bytcrush_bulk_time_budget', function () {
	return 10;
} );

bytcrush_bg_dispatch_url

The URL the server calls to start the next background batch. Default: admin_url( 'admin-ajax.php?action=bytcrush_bg' ). Change it when the site can't reach itself on its public address, for example behind a proxy. The request is a non-blocking POST carrying the run's random token; the handler answers 403 without a valid one.

apply_filters( 'bytcrush_bg_dispatch_url', $url );

The request is sent with WordPress's https_local_ssl_verify filter value for certificate checks.

Actions

add_action( 'bytcrush_optimized', function ( $id, $result ) {
	if ( 'error' === $result['status'] ) {
		error_log( "BytCrush could not optimize #{$id}: {$result['message']}" );
	}
}, 10, 2 );

Functions

Settings keys: level, auto_optimize, backup, strip_metadata, resize, max_width, max_height, webp, avif, delivery (picture, rewrite or off), target_size, target_kb, background, fix_srcset, fix_dimensions, fix_lazy, remove_data. Defaults are listed in the Settings reference.

REST API

All routes are under /wp-json/bytcrush/v1/ and need a logged-in user with a REST nonce, as the admin screens use them.

Pro adds /audit/analyze, /audit/fix and /audit/fixes (manage_options).

Data the plugin stores

_bytcrush_status is optimized, skipped, error or processing. An image without it is pending.

Deleting _bytcrush_status (and the other _bytcrush* meta) for an image puts it back in the queue without touching its files.

Code map