Media Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Modularity Alignment: The package’s YAML-driven, scene-based approach fits Laravel’s modular architecture, where video generation can be treated as a discrete service. Laravel’s Eloquent ORM can manage metadata (e.g., Video model), while the tool handles asset generation, creating a clean separation of concerns.
• Extensibility: The tool’s design (configurable via YAML/environment variables) allows for future extensions, such as integrating custom TTS engines or post-processing filters, without tightly coupling to Laravel’s core.
• Symfony Compatibility: While the package is Symfony-based, Laravel’s support for Symfony components (e.g., Process, Console) minimizes friction. The tool’s CLI-first design avoids Laravel-specific dependencies, reducing integration complexity.

Integration Feasibility

• CLI Integration: The tool’s command-line interface (app:video:generate) can be invoked from Laravel via:
  • Artisan Commands: Wrap the tool’s CLI in a Laravel Artisan command for consistency.
  • Process Facade: Use Laravel’s Process facade to execute the tool programmatically (e.g., in a job or controller).
  • Queue Workers: Offload generation to Laravel queues (e.g., GenerateVideoJob) for async processing.
• Data Flow:
  • Input: Laravel generates YAML (e.g., from a VideoTemplate model or API payload) and passes it to the tool.
  • Output: The tool writes assets to a filesystem (configurable) and generates a manifest (JSON). Laravel reads the manifest and stores metadata in the database.
• State Management: The tool’s persistent run state (e.g., tracking progress) can be leveraged by Laravel to implement retries or resume failed jobs.

Technical Risk

• Dependency Conflicts: The tool’s reliance on Symfony components (e.g., symfony/console, symfony/process) may introduce version conflicts with Laravel’s dependencies. Risk mitigation:
  • Use Composer’s conflict-checker or why-not to identify conflicts.
  • Pin Symfony dependencies in composer.json to align with Laravel’s versions.
• Filesystem Permissions: The tool requires write access to its output directory. Laravel’s storage system (e.g., storage/app/public) must be configured to grant the tool’s user (e.g., www-data) appropriate permissions.
• API Dependencies: The tool uses Replicate for rendering. Laravel must:
  • Securely manage API keys (e.g., via .env or a secrets manager).
  • Handle rate limits and failures gracefully (e.g., retry logic, fallback mechanisms).
• Testing Complexity: Mocking the tool’s HTTP calls (as per its tests) requires:
  • Laravel’s HTTP testing helpers or a custom mock service.
  • Integration tests to verify the full pipeline (YAML → tool → manifest → DB).
• Concurrency: The tool’s support for parallel generation must be validated if Laravel processes trigger it concurrently. Risk: Low if the tool’s design is stateless and idempotent.

Key Questions

1. Asset Lifecycle:
   • How will generated assets (e.g., voiceovers, video clips) be stored, versioned, and purged? Will Laravel manage this via its storage system, or will the tool handle it?
   • How will assets be served to end-users (e.g., via Laravel’s mix or a CDN)?
2. Error Recovery:
   • How will Laravel handle tool failures (e.g., YAML parsing errors, Replicate API limits)? Should errors be logged, retried, or surfaced to users?
   • Does the tool support partial failures (e.g., skipping a scene)? If so, how will Laravel reconcile incomplete manifests?
3. Customization:
   • Will the project extend the YAML schema or post-process assets? If so, how will the tool’s output be transformed (e.g., via Laravel services or middleware)?
   • Can the tool’s presets (e.g., Seedance 2.0) be overridden or extended?
4. Performance:
   • What are the expected throughput requirements (e.g., videos/hour)? Does the tool’s benchmark mode provide sufficient guidance?
   • How will Laravel handle large-scale generation (e.g., batch processing for 10,000 users)?
5. Security:
   • How will API keys for Replicate (or other services) be secured in Laravel? Will they be injected via environment variables or a secrets manager?
   • Are there risks of asset injection or path traversal if YAML inputs are user-provided?

Integration Approach

Stack Fit

• Laravel + Symfony CLI:
  • Treat the tool as a subprocess invoked via Laravel’s Process facade or Artisan commands. Avoid deep integration with Symfony’s DI container unless necessary.
  • Use Laravel’s service container to manage:
    • YAML template generation (e.g., from a VideoTemplate model).
    • Manifest parsing and DB persistence (e.g., Video model).
    • Error handling and logging.
• Filesystem:
  • Configure the tool’s output directory to align with Laravel’s storage system (e.g., storage/app/video_assets).
  • Use Laravel’s Storage facade to:
    • Read YAML templates (e.g., from storage/app/video_templates/).
    • Write manifests (tool’s JSON output) to storage/app/video_manifests/.
    • Serve assets via Laravel’s mix or a CDN (e.g., S3).
• API Keys:
  • Store Replicate API keys in Laravel’s .env (e.g., REPLICATE_API_KEY).
  • Pass keys to the tool via environment variables (as documented in mvp-video.md).
  • Use Laravel’s env() helper or a dedicated service to inject keys into the tool’s process.

Migration Path

1. Phase 1: Proof of Concept (1-2 weeks)
   • Installation: Add the package to Laravel via Composer:

     composer require darkwood/media-bundle
     

   • Manual Testing: Verify the tool works in isolation:

     php bin/console app:video:generate examples/video.yaml
     

   • Output Validation: Check that assets and manifests are generated as expected.
   • Benchmark Mode: Test with --benchmark flag to avoid live API calls.
2. Phase 2: Laravel Wrapper (1 week)
   • Artisan Command: Create a Laravel-specific command (e.g., GenerateVideoCommand) that:
     • Validates YAML input (e.g., schema validation via spatie/fork or custom rules).
     • Invokes the tool via Process::run() with environment variables.
     • Parses the manifest and persists metadata to a Video model.
     • Logs output/errors for debugging.
   • Example:

     use Symfony\Component\Process\Process;
     use Illuminate\Support\Facades\Log;
     
     class GenerateVideoCommand extends Command {
         protected $signature = 'video:generate {template : Path to YAML template}';
         protected $description = 'Generate video assets from a YAML template';
     
         public function handle() {
             $yamlPath = storage_path('app/video_templates/' . $this->argument('template'));
             $manifestPath = storage_path('app/video_manifests/manifest.json');
     
             $process = new Process([
                 'php', 'bin/console', 'app:video:generate', $yamlPath,
                 '--env', 'REPLICATE_API_KEY=' . env('REPLICATE_API_KEY'),
             ]);
             $process->run();
     
             if (!$process->isSuccessful()) {
                 Log::error('Video generation failed', ['output' => $process->getOutput()]);
                 throw new \RuntimeException('Failed to generate video');
             }
     
             // Parse manifest and save to DB
             $manifest = json_decode(file_get_contents($manifestPath), true);
             Video::create([
                 'template' => $this->argument('template'),
                 'status' => 'generated',
                 'metadata' => $manifest,
             ]);
         }
     }
     

   • Queue Job: Convert the command into a queued job (e.g., GenerateVideoJob) for async processing.
3. Phase 3: API Integration (1 week)
   • Controller: Expose the job via a Laravel API route (e.g., POST /api/videos):

     public function generate(GenerateVideoRequest $request) {
         GenerateVideoJob::dispatch($request->template)->onQueue('videos');
         return response()->json(['status' => 'queued']);
     }
     

   • Webhook Support: Add a webhook endpoint to notify users when videos are ready (e.g., via Laravel’s queue:failed or job:handled events).
4. Phase 4: Monitoring and Optimization (Ongoing)
   • Logging: Integrate the tool’s output with Laravel’s monolog (e.g., log all stdout/stderr).
   • Health Checks: Add a Laravel command to validate Replicate API connectivity and tool readiness.
   • Performance Tuning: Use the tool’s benchmark mode to optimize YAML templates and asset sizes.

Compatibility

• Laravel Versions: The tool has no Laravel-specific