README

Laravel AI Video is a comprehensive, production-ready package for generating cinematic AI videos. It acts as an orchestration layer, combining the best AI models for scripting, visuals, motion, and voice into a single, unified pipeline.

Whether you need to automate Social Media Reels, create Product Ads, or generate Storytelling Content, this package handles the complex workflow of chaining AI APIs and rendering the final output.

🌟 Features

• 🎬 Multi-Model Orchestration ("Composed" Driver):
  • Scripting: OpenAI GPT-4o breaks prompts into cinematic scenes.
  • Visuals: OpenAI DALL-E 3 generates high-consistency scene images.
  • Motion: Runway Gen-4 Turbo / Leonardo Kling 2.1 brings images to life.
  • Voice: OpenAI TTS-1 adds synchronized voiceovers.
  • Rendering: FFmpeg merges everything with transitions and subtitles.
• 🖼️ Image-to-Video: Support for animating images using Runway (Gen-4), Leonardo (Kling 2.1), or OpenAI (Sora).
• 📱 Smart Templates: Built-in aspect ratios for Instagram/TikTok (9:16), YouTube (16:9), and Feeds (1:1).
• 🛡️ AI Guard Integration: Prevents API bill shock by estimating costs before execution and strictly enforcing budgets.
• ⚡ High-Performance Architecture:
  • Queue-based asynchronous processing.
  • Streams temporary files to avoid memory overflows.
  • Parallel execution where possible (dependent on driver).

🛠️ How It Works

The Composed Driver automates the entire video production lifecycle:

graph TD
    User[User Prompt] -->|1. Plan| Planner(Scene Planner / GPT-4o / Gemini 1.5)
    Planner -->|JSON Scenes| Manager{Video Manager}
    
    subgraph "Parallel Processing Per Scene"
        Manager -->|Describe| GenImg[Image Gen / DALL-E 3]
        GenImg -->|Image| Animate[Motion / Runway / Kling / Sora]
        Manager -->|Text| TTS[Voice / OpenAI TTS]
    end
    
    Animate -->|Video Clip| Renderer[FFmpeg Renderer]
    TTS -->|Audio Clip| Renderer
    Planner -->|Subtitles| Renderer
    
    Renderer -->|Merge & Render| Final[Final MP4 Output]

🚀 Installation

1. Install via Composer:

   composer require subhashladumor1/laravel-ai-video

2. Publish Configuration:

   php artisan vendor:publish --tag=ai-video-config

3. Install FFmpeg: Ensure ffmpeg and ffprobe are installed on your server.

   # Ubuntu/Debian
   sudo apt update && sudo apt install ffmpeg

4. Configure .env: Add your API keys. The package works best with multiple providers enabled.

   OPENAI_API_KEY=sk-...
   RUNWAY_API_KEY=...
   LEONARDO_API_KEY=...
   GEMINI_API_KEY=...
   
   # Enable the Budget Guard
   AI_VIDEO_GUARD_ENABLED=true

📖 Complete Usage Guide

1. Text-to-Video (The "Composed" Pipeline)

This is the most powerful feature. It creates a full video from a simple text prompt.

Basic Usage:

use Subhashladumor1\LaravelAiVideo\Facades\AiVideo;

$path = AiVideo::driver('composed')->textToVideo(
    "A cyberpunk detective walking through neon-lit rainy streets of Tokyo.",
    [
        'duration' => 15, // Total video duration (approx)
        'template' => 'youtube-short' // 9:16 Aspect Ratio
    ]
);

return response()->download($path);

Advanced Usage (Asynchronous Job): Recommended for production to avoid timeout issues.

use Subhashladumor1\LaravelAiVideo\Jobs\ProcessVideoJob;

ProcessVideoJob::dispatch(
    'text-to-video',
    "Create a 30-second commercial for a new eco-friendly coffee brand.",
    [
        'template' => 'instagram-reel', 
        'voice_id' => 'alloy',
        'style' => 'Cinematic, Warm Lighting, Slow Motion',
        'fps' => 30
    ],
    'composed'
);

2. Image-to-Video (Motion Generation)

Ideal for bringing product photography or static assets to life. Supports Runway, Leonardo, and Sora.

use Subhashladumor1\LaravelAiVideo\Facades\AiVideo;

// Using Runway Gen-4 Turbo
$videoPath = AiVideo::driver('runway')->imageToVideo(
    public_path('images/product-shoe.jpg'),
    [
        'prompt' => 'Cinematic slow motion, floating in air', // Text prompt required for control
        'duration' => 10,
        'model' => 'gen4_turbo'
    ]
);

// Using Leonardo (Kling 2.1)
$videoPath2 = AiVideo::driver('leonardo')->imageToVideo(
    public_path('images/portrait.jpg'),
    [
        'prompt' => 'Character smiles and waves',
        'model' => 'KLING2_1'
    ]
);

3. Scene Planning (Scripting Only)

Use the AI Director to break down a script into visual scenes without generating the video yet. Useful for UI previews.

$scenes = AiVideo::driver('openai')->generateScenes(
    "A history of the Roman Empire in 60 seconds."
);

// Returns:
// [
//    [
//      'scene_number' => 1,
//      'visual_description' => 'Aerial view of the Colosseum at sunset...',
//      'voiceover_text' => 'It began as a small city-state...',
//      'duration_seconds' => 5
//    ],
//    ...
// ]

4. Voiceover Generation (TTS)

Generate high-quality AI voiceovers directly.

$audioPath = AiVideo::driver('openai')->generateVoice(
    "Welcome to the future of video generation.",
    'nova', // Voice options: alloy, echo, fable, onyx, nova, shimmer
    ['model' => 'tts-1-hd']
);

🛡️ AI Guard & Cost Control

This package includes a Budget Enforcement System. It estimates the cost of every operation before it runs.

How to Configure: In config/ai-video.php:

'guard' => [
    'enabled' => true,
    'cost_limit_per_video' => 5.00, // Maximum USD per video
],

Usage Flow:

try {
    // This will throw an Exception if estimated cost > $5.00
    AiVideo::driver('composed')->textToVideo("An extremely long 1-hour movie description...");
} catch (\Exception $e) {
    // "Estimated cost $12.50 exceeds budget limit of $5.00"
    return back()->with('error', $e->getMessage());
}

📖 Function Reference

VideoDriver Interface

The Facade AiVideo::driver('name') returns an instance implementing these methods:

Supported Templates

Templates control the Output Resolution and default styling.

🏗️ Extending

You can create your own drivers by implementing Subhashladumor1\LaravelAiVideo\Contracts\VideoDriver.

namespace App\Drivers;

use Subhashladumor1\LaravelAiVideo\Contracts\VideoDriver;

class MyCustomDriver implements VideoDriver
{
    public function textToVideo(string $prompt, array $options = []): string
    {
        // Call your custom AI API here
        return 'path/to/video.mp4';
    }
    
    // implement other methods...
}

Register it in AppServiceProvider:

AiVideo::extend('custom', function ($app) {
    return new MyCustomDriver();
});

🧪 Testing

composer test

📄 License

The MIT License (MIT). Please see License File for more information.