Media Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require darkwood/media-bundle
   

   Ensure bin/console is executable (chmod +x bin/console).

2. First Use Case: Generate a video from the provided example YAML:

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

   Verify output in var/output/ (default directory; configurable via .env).

3. Where to Look First:

   • Configuration: Check docs/mvp-video.md for environment variables (e.g., REPLICATE_API_TOKEN).
   • YAML Schema: Review examples/video.yaml for scene/asset structure.
   • Output: Inspect var/output/ for generated assets (e.g., scenes/, voiceovers/).

4. Benchmark Mode: Test locally without API calls:

   REPLICATE_MODE=benchmark php bin/console app:video:generate examples/video.yaml
   

Implementation Patterns

Usage Patterns

1. Laravel Artisan Wrapper: Create a Laravel command to invoke the tool and handle output:

   // app/Console/Commands/GenerateVideo.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Symfony\Component\Process\Process;
   use Symfony\Component\Process\Exception\ProcessFailedException;
   
   class GenerateVideo extends Command
   {
       protected $signature = 'video:generate {yaml : Path to YAML file}';
       protected $description = 'Generate video assets via Darkwood Media Bundle';
   
       public function handle()
       {
           $process = new Process(['php', 'bin/console', 'app:video:generate', $this->argument('yaml')]);
           $process->run();
   
           if (!$process->isSuccessful()) {
               throw new ProcessFailedException($process);
           }
   
           // Parse manifest and save to DB
           $manifest = json_decode(file_get_contents(storage_path('app/video_manifests/manifest.json')), true);
           $this->call('video:store-manifest', ['manifest' => json_encode($manifest)]);
       }
   }
   

2. YAML Generation: Dynamically create YAML in Laravel and pass it to the tool:

   // Generate YAML from a model (e.g., VideoTemplate)
   $yaml = "scenes:\n";
   $yaml .= "  - title: Welcome\n    video: path/to/video.mp4\n    voice: Hello, {$user->name}!\n";
   
   file_put_contents(storage_path("app/video_templates/{$id}.yaml"), $yaml);
   $this->call('video:generate', ['yaml' => "app/video_templates/{$id}.yaml"]);
   

3. Asset Management: Use Laravel’s Storage facade to handle generated assets:

   // Store manifest in DB
   $manifest = json_decode(file_get_contents($manifestPath), true);
   Video::create([
       'manifest' => $manifest,
       'asset_path' => 'storage/app/public/videos/' . $manifest['id'],
   ]);
   
   // Serve assets via Laravel
   Storage::disk('public')->put('videos/' . $manifest['id'] . '/final.mp4', file_get_contents($manifest['output_path']));
   

Workflows

1. Template → Asset Pipeline:

   Laravel Model/Service → YAML Generation → Darkwood Tool → Asset Output → Laravel DB/Storage
   

2. Error Handling:

   • Log tool output to Laravel’s monolog:

     $process->run(function ($type, $buffer) {
         if ($type === Process::ERR) {
             \Log::error('Video Generation Error: ' . $buffer);
         }
     });
     

   • Retry failed jobs with exponential backoff (use Laravel Queues).

3. Queue-Based Generation:

   // app/Jobs/GenerateVideoJob.php
   namespace App\Jobs;
   
   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   
   class GenerateVideoJob implements ShouldQueue
   {
       use Queueable;
   
       public function handle()
       {
           $this->call('video:generate', ['yaml' => $this->yamlPath]);
       }
   }
   

Integration Tips

1. Environment Variables: Sync Laravel’s .env with the tool’s requirements:

   # Laravel .env
   REPLICATE_API_TOKEN=${REPLICATE_API_TOKEN}
   MEDIA_BUNDLE_OUTPUT=storage/app/public/videos
   

2. Testing:

   • Mock the tool’s HTTP calls in Laravel tests:

     // tests/Feature/VideoGenerationTest.php
     public function test_video_generation()
     {
         $this->artisan('video:generate', ['yaml' => 'tests/fixtures/video.yaml'])
             ->expectsOutput('Success!')
             ->assertExitCode(0);
     }
     

   • Use the tool’s benchmark mode for CI:

     REPLICATE_MODE=benchmark ./vendor/bin/phpunit
     

3. Extending YAML Schema: Add custom fields to YAML and extend the tool’s configuration:

   # Custom YAML example
   scenes:
     - title: Custom Scene
       video: custom_path.mp4
       voice: Custom text
       custom_field: value  # Extend as needed
   

Gotchas and Tips

Pitfalls

1. Filesystem Permissions:

   • Ensure Laravel’s storage directory (storage/app/) and the tool’s output path are writable by the PHP process.
   • Fix: Run chmod -R 755 storage/ and verify the www-data (or equivalent) user has access.

2. Replicate API Limits:

   • The tool uses Replicate for voice/video generation. Exceeding API limits will fail silently.
   • Fix: Implement retry logic with exponential backoff in Laravel:

     use Illuminate\Support\Facades\Http;
     
     Http::retry(3, 100)->post('https://api.replicate.com/...');
     

3. YAML Schema Mismatches:

   • Invalid YAML will cause the tool to fail without clear error messages.
   • Fix: Validate YAML before passing it to the tool:

     use Symfony\Component\Yaml\Yaml;
     
     try {
         $data = Yaml::parseFile($yamlPath);
     } catch (\Exception $e) {
         \Log::error("Invalid YAML: " . $e->getMessage());
         throw new \InvalidArgumentException("YAML validation failed");
     }
     

4. Stateful Runs:

   • The tool persists run state to var/run/. Concurrent runs may overwrite state.
   • Fix: Use unique run IDs or disable state persistence in development:

     MEDIA_BUNDLE_PERSIST_STATE=false php bin/console app:video:generate video.yaml
     

5. Manifest Parsing:

   • The tool’s manifest output may change between versions. Pin the Composer version to avoid breaking changes:

     "require": {
         "darkwood/media-bundle": "8.0.12"
     }
     

Debugging

1. Verbose Output: Enable debug mode for detailed logs:

   php bin/console app:video:generate video.yaml --verbose
   

2. Dry Runs: Test without generating assets:

   MEDIA_BUNDLE_DRY_RUN=true php bin/console app:video:generate video.yaml
   

3. Tool-Specific Logs: Check var/log/ for tool-generated logs. Redirect to Laravel’s log:

   $process->run(function ($type, $buffer) {
       \Log::info($buffer);
   });
   

Tips

1. Laravel Service Provider: Register the tool’s commands in Laravel’s AppServiceProvider:

   public function boot()
   {
       $this->commands([
           \Darkwood\MediaBundle\Command\GenerateVideoCommand::class,
       ]);
   }
   

2. Custom Presets: Extend the tool’s presets (e.g., Seedance 2.0) by overriding its configuration:

   # config/media_bundle.yaml
   presets:
       custom_preset:
           voice_model: "custom-model"
           resolution: "1080p"
   

3. Asset Cleanup: Automate cleanup of old assets using Laravel’s scheduled tasks:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->command('video:cleanup-assets')->daily();
   }
   

4. API Key Rotation: Securely rotate Replicate API keys in Laravel’s .env and restart the queue worker:

   php artisan queue:restart
   

5. Benchmarking: Use the tool’s benchmark mode to test performance locally:

   REPLICATE_MODE=benchmark php bin/console app:video:generate video.yaml --benchmark