Filter Hooks Reference

Viscribe provides 21 filter hooks for programmatically modifying data at key points in the pipeline.

AI & API Filters

viscribe_prompt Since v1.0.0

Filters the instruction prompt sent to the AI model.

• Parameters: (string $prompt, int $max_keywords, bool $set_alt)
• Source: Groq_Service::get_prompt()

add_filter( 'viscribe_prompt', function( $prompt, $max_keywords, $set_alt ) {
    return "Describe this image in exactly $max_keywords words. Be concise.";
}, 10, 3 );

viscribe_api_payload Since v1.0.0

Filters the full JSON payload before it is sent to the AI provider.

• Parameters: (array $payload, string $image_path)
• Source: Groq_Service::generate_description()

add_filter( 'viscribe_api_payload', function( $payload ) {
    $payload['temperature'] = 0.5;
    return $payload;
} );

viscribe_api_request_args Since v1.0.0

Filters the HTTP request arguments passed to wp_remote_post().

• Parameters: (array $request_args, array $payload, string $image_path)
• Source: Groq_Service::generate_description()

add_filter( 'viscribe_api_request_args', function( $args ) {
    $args['timeout'] = 45;
    return $args;
} );

viscribe_max_file_size Since v1.0.0

Filters the maximum file size (in bytes) allowed for AI processing. Default is 10 MB.

• Parameters: (int $max_file_size, string $image_path)
• Source: Groq_Service::generate_description()

add_filter( 'viscribe_max_file_size', function( $max, $path ) {
    return 20 * MB_IN_BYTES; // Increase to 20 MB
} );

Upload Processing Filters

viscribe_should_process_upload Since v1.0.0

Determines whether a specific file should be analyzed and renamed.

• Parameters: (bool $should_process, array $file, string $mime_type)
• Source: Image_Uploader::process_upload()

add_filter( 'viscribe_should_process_upload', function( $should, $file, $mime_type ) {
    if ( current_user_can( 'administrator' ) ) return false;
    return $should;
}, 10, 3 );

viscribe_generated_description Since v1.0.0

Filters the raw AI-generated text before it is converted to a filename.

• Parameters: (string|false $description, string $tmp_path, array $file)
• Source: Image_Uploader::process_upload()

add_filter( 'viscribe_generated_description', function( $desc, $tmp_path, $file ) {
    return str_replace( 'image of ', '', $desc );
}, 10, 3 );

viscribe_new_filename Since v1.0.0

Filters the complete filename (base name + extension) before it is applied.

• Parameters: (string $new_filename, string $sanitized_name, string $extension, array $file, string $description)
• Source: Image_Uploader::process_upload()

add_filter( 'viscribe_new_filename', function( $filename, $base, $ext, $file, $desc ) {
    return 'brand-' . $base . '-' . time() . '.' . $ext;
}, 10, 5 );

viscribe_mime_to_ext Since v1.0.0

Filters the file extension determined from the MIME type.

• Parameters: (string $extension, string $mime_type)
• Source: Image_Uploader::get_extension_from_mime()

add_filter( 'viscribe_mime_to_ext', function( $ext, $mime ) {
    return 'image/jpeg' === $mime ? 'jpeg' : $ext;
}, 10, 2 );

viscribe_alt_text Since v1.0.0

Filters the alt text before it is saved to the attachment.

• Parameters: (string $text, string $description, array $file)
• Source: Image_Uploader::process_upload()

add_filter( 'viscribe_alt_text', function( $text, $desc, $file ) {
    return 'Photo: ' . ucfirst( $text );
}, 10, 3 );

viscribe_allowed_file_types Since v1.0.0

Filters the MIME types accepted for AI processing.

• Parameters: (array $file_types, string $mime_type)
• Source: Groq_Service::is_allowed_type()

add_filter( 'viscribe_allowed_file_types', function( $types, $mime ) {
    $types[] = 'image/tiff';
    return $types;
}, 10, 2 );

Settings & Admin Filters

viscribe_settings_defaults Since v1.0.0

Filters the default plugin settings array.

• Parameters: (array $defaults)
• Source: Settings_Page::get_defaults()

viscribe_settings_tabs Since v1.0.0

Filters the tab definitions shown on the settings page.

• Parameters: (array $tabs)
• Source: Settings_Page::get_tabs()

viscribe_settings_panels Since v1.0.0

Filters the pre-rendered HTML panels for each tab.

• Parameters: (array $panels)
• Source: Settings_Page::get_panel_contents()

viscribe_sanitize_settings Since v1.0.0

Filters the entire settings array before it is saved.

• Parameters: (array $sanitized, array $input, array $old)
• Source: Settings_Page::sanitize_settings()

viscribe_available_models Since v1.0.0

Filters the AI models shown in the provider/model dropdown.

• Parameters: (array $models, string $current)
• Source: Settings_Page::get_available_models()

viscribe_valid_models Since v1.0.0

Filters the model IDs accepted during settings validation.

• Parameters: (array $valid_models)
• Source: Settings_Page::sanitize_settings()

viscribe_available_file_types Since v1.0.0

Filters the file types shown in the UI checkboxes.

• Parameters: (array $available_types)
• Source: Settings_Page::get_available_file_types()

viscribe_allowed_file_types_for_validation Since v1.0.0

Filters the MIME types accepted during settings sanitization.

• Parameters: (array $allowed_types)
• Source: Settings_Page::sanitize_settings()

Template & Service Filters

viscribe_template_paths Since v1.0.0

Filters the template directories searched by Twig. First path wins.

• Parameters: (array $paths)
• Source: Template_Engine::__construct()

add_filter( 'viscribe_template_paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/viscribe-templates';
    return $paths;
} );

viscribe_docs_base_url Since v1.0.0

Filters the base URL used for documentation links in the admin UI.

• Parameters: (string $base)
• Source: Template_Engine::__construct()

viscribe_pro_is_licensed Since v1.0.0

Filters whether the Pro add-on is active and licensed.

• Parameters: (bool $is_licensed)
• Source: Plugin::is_pro_active()