<?php

namespace App\Contracts;

use App\DTOs\VideoRenderResult;
use App\Exceptions\ProviderNotConfiguredException;
use App\Models\Avatar;
use App\Models\Voice;

interface VideoAvatarProvider
{
    /**
     * Render a talking-avatar video from a script and storyboard.
     *
     * @param  array{hook: string, problem: string, product: string, benefits: string, cta: string}  $script
     * @param  list<array{scene: string}>  $storyboard
     * @param  int  $duration  Requested length in seconds; a vendor may clamp this to its own supported values.
     * @param  string  $ratio  Aspect ratio, e.g. "16:9" or "9:16".
     * @param  ?string  $style  Visual/tone treatment, e.g. "UGC" for an organic, phone-shot look instead of a polished ad.
     * @param  ?callable(int, string): void  $onProgress  Estimated percentage and current render stage.
     * @param  ?array  $context  Optional brand, product, features, benefits, and campaign messaging context.
     *
     * @throws ProviderNotConfiguredException if no video vendor is configured.
     */
    public function render(Avatar $avatar, Voice $voice, array $script, array $storyboard, int $duration, string $ratio, ?string $style = null, ?callable $onProgress = null, ?array $context = null): VideoRenderResult;
}