Extract event data from promotional flyer and poster images using AI vision capabilities.

Overview

The Event Flyer handler processes flyer and poster images using vision model capabilities to extract event information. It implements a "fill OR AI extracts" pattern where users can pre-populate known fields and let AI extract the remaining details from the image.

Features

AI Vision Extraction

• Image Analysis: Processes JPG, PNG, GIF, and WebP images
• Field Extraction: Extracts title, date, time, venue, price, and performer information
• Smart Defaults: Uses configured values when provided, falls back to AI extraction

"Fill OR AI Extracts" Pattern

Each configuration field follows a simple rule:

• Field populated: Uses the configured value
• Field empty: AI extracts from the flyer image

Integration with Data Machine Files

• Reads images from the Data Machine Files handler storage
• Processes one image per job execution
• Tracks processed files to prevent duplicates

Configuration

Available Fields

Example Configuration

$config = [
    'venue' => 'The Music Hall',        // Pre-filled - AI won't extract
    'city' => 'Charleston',             // Pre-filled - AI won't extract
    'state' => 'SC',                    // Pre-filled - AI won't extract
    'title' => '',                      // Empty - AI extracts from flyer
    'startDate' => '',                  // Empty - AI extracts from flyer
    'startTime' => '',                  // Empty - AI extracts from flyer
    'price' => ''                       // Empty - AI extracts from flyer
];

AI Extraction Guidance

Vision Prompt

The handler provides structured guidance for AI extraction:

Extract event information from this promotional flyer, poster, or event graphic.

Look for and extract:
- Event title or headliner (usually the largest, most prominent text)
- Date and time information (parse into standard formats)
- Venue name and address
- Ticket prices (advance, door, VIP tiers if shown)
- Supporting acts, opening bands, or additional performers
- Ticket purchase URLs if visible
- Any age restrictions (21+, All Ages, etc.)

Time rules:
- If the flyer lists separate DOORS and SHOW times, the SHOW time is the event start time. The doors time is never the start time and never the end time.
- When a doors time is shown, include it in the description (e.g. "Doors: 8 PM") — there is no dedicated doors field.
- If the flyer shows only a doors time, use that doors time as the start time.
- Set an end time only when the flyer states an explicit end or time range (e.g. "8PM–11PM", "until 2AM"). A doors/show pair is not a start/end range.

Format guidelines:
- Dates should be in YYYY-MM-DD format
- Times should be in HH:MM 24-hour format
- If information is not clearly visible, leave the field empty
- Do not guess or infer information that is not present on the flyer

AI Field Descriptions

Fields available for AI extraction include detailed descriptions:

Integration

Handler Registration

Uses HandlerRegistrationTrait for self-registration:

self::registerHandler(
    'event_flyer',
    'event_import',
    self::class,
    __('Event Flyer', 'data-machine-events'),
    __('Extract event data from flyer/poster images using AI vision', 'data-machine-events'),
    false,
    null,
    EventFlyerSettings::class,
    null
);

File Storage Integration

Reads from Data Machine’s file storage system:

$storage = $this->getFileStorage();
$repo_files = $storage->get_all_files($context);

Supported Image Formats

• JPEG/JPG
• PNG
• GIF
• WebP

Engine Data Storage

Stores image information for downstream processing:

datamachine_merge_engine_data($job_id, [
    'image_file_path' => $image_path,
    'image_url' => $image_url,
]);

Usage Workflow

1. Upload Images: Add flyer images to the pipeline’s file repository
2. Configure Handler: Set known fields (venue, city, state) or leave empty for AI extraction
3. Run Pipeline: Handler processes one image per execution
4. AI Extraction: Vision model extracts missing fields from the flyer
5. Event Creation: EventUpsert creates the event with extracted data

Best Practices

Pre-Fill Known Information

When you know the venue or location, pre-fill those fields:

• Reduces AI extraction errors
• Ensures consistent venue naming
• Improves venue matching and deduplication

Image Quality

For best AI extraction results:

• Use high-resolution images
• Ensure text is legible
• Avoid heavily stylized or distorted text
• Include the full flyer in the image

Date Handling

• AI extracts dates in YYYY-MM-DD format
• For ambiguous dates (e.g., "Friday the 13th"), provide context in the date field
• Multi-date events may require manual configuration

Limitations

• Requires Data Machine Files handler for image storage
• Processes one image per job execution
• AI extraction accuracy depends on flyer design clarity
• Cannot extract information not visible on the flyer