Centric Livestreaming Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require centric/live-broadcast-bundle
   

   Add to config/app.php under providers:

   Centric\LiveBroadcastBundle\LiveBroadcastServiceProvider::class,
   

   Publish config:

   php artisan vendor:publish --provider="Centric\LiveBroadcastBundle\LiveBroadcastServiceProvider" --tag=config
   

2. Configure Platforms Edit config/live-broadcast.php to enable platforms (e.g., Facebook, YouTube) and set API credentials.

3. First Use Case: Stream a File

   use Centric\LiveBroadcastBundle\Services\LiveBroadcastService;
   
   $broadcast = $liveBroadcastService->createBroadcast('My Awesome Stream');
   $broadcast->addOutput('facebook', ['title' => 'Facebook Live']);
   $broadcast->addInput('file', ['path' => '/path/to/video.mp4']);
   $broadcast->start();
   

Where to Look First

• Config File: config/live-broadcast.php (platforms, defaults, and credentials).
• Service Container: LiveBroadcastService for core functionality.
• Demo Project: Live Broadcast Demo for real-world examples.

Implementation Patterns

Core Workflow

1. Broadcast Creation Instantiate a broadcast object and define metadata (title, description, etc.).

   $broadcast = $liveBroadcastService->createBroadcast('Event Title');
   $broadcast->setDescription('Live coverage of XYZ');
   

2. Adding Outputs Attach multiple platforms (Facebook, YouTube, Twitch) with platform-specific configs.

   $broadcast->addOutput('facebook', [
       'title' => 'Facebook Live Stream',
       'privacy' => 'PRIVATE',
   ]);
   

3. Input Configuration Define the source (file, URL, or RTMP stream) and optional encoding settings.

   $broadcast->addInput('file', [
       'path' => storage_path('videos/stream.mp4'),
       'bitrate' => '5000k',
   ]);
   

4. Execution Start the broadcast with optional callbacks for events (e.g., onStart, onError).

   $broadcast->start(function ($event) {
       if ($event->isStarted()) {
           Log::info('Broadcast started!');
       }
   });
   

5. Admin GUI (Optional) Use the bundled admin panel to manage broadcasts via a web interface.

   php artisan vendor:publish --provider="Centric\LiveBroadcastBundle\LiveBroadcastServiceProvider" --tag=assets
   

   Access /admin/live-broadcast (configure routes in routes/web.php).

Integration Tips

• Event Listeners Subscribe to broadcast events for real-time monitoring or notifications.

  Event::listen(LiveBroadcastStarted::class, function ($event) {
      // Send Slack notification, etc.
  });
  

• Queue Jobs Offload long-running broadcasts to Laravel queues for better performance.

  $broadcast->onQueue('broadcasts');
  

• Custom Platforms Extend the bundle to support additional platforms (see Adding New Outputs).

• FFmpeg Integration Leverage FFmpeg for advanced input/output transformations (e.g., transcoding).

  $broadcast->addInput('rtmp', [
      'url' => 'rtmp://example.com/live/stream',
      'ffmpeg_args' => '-vcodec libx264 -acodec aac',
  ]);
  

Gotchas and Tips

Pitfalls

1. API Credentials

   • Issue: Hardcoding API keys in config/live-broadcast.php is insecure.
   • Fix: Use Laravel’s .env file and encrypt sensitive data.

     FACEBOOK_LIVE_PAGE_ID=your_page_id
     FACEBOOK_LIVE_ACCESS_TOKEN=your_encrypted_token
     

     Encrypt tokens with:

     php artisan encrypt:token
     

2. FFmpeg Dependencies

   • Issue: Missing FFmpeg or incorrect paths cause input/output failures.
   • Fix: Verify FFmpeg is installed and accessible:

     ffmpeg -version
     

     Configure the path in config/live-broadcast.php:

     'ffmpeg' => [
         'path' => '/usr/bin/ffmpeg',
     ],
     

3. Platform-Specific Errors

   • Facebook/YouTube: Rate limits or invalid permissions may halt broadcasts.
   • Debugging: Check platform-specific logs or enable verbose logging in the config:

     'debug' => true,
     

4. Concurrent Broadcasts

   • Issue: Running multiple broadcasts simultaneously may exhaust system resources.
   • Fix: Limit concurrent broadcasts via queue workers or platform API quotas.

Debugging

• Log Outputs Enable debug mode in config/live-broadcast.php and check Laravel logs:

  'debug' => env('APP_DEBUG', false),
  

  Logs are stored in storage/logs/laravel.log.

• Event Dumping Use Laravel’s dd() or dump() in event listeners to inspect broadcast states:

  Event::listen(LiveBroadcastError::class, function ($event) {
      dd($event->getBroadcast(), $event->getError());
  });
  

• Admin Panel Debugging Clear cached views if the admin GUI fails to load:

  php artisan view:clear
  php artisan cache:clear
  

Extension Points

1. Custom Output Platforms Extend the bundle by creating a new output driver. Example structure:

   namespace App\LiveBroadcast\Outputs;
   
   use Centric\LiveBroadcastBundle\Contracts\OutputInterface;
   
   class CustomPlatformOutput implements OutputInterface {
       public function publish($broadcast, $input) {
           // Custom logic to publish to your platform
       }
   }
   

   Register the driver in config/live-broadcast.php:

   'outputs' => [
       'custom' => [
           'class' => App\LiveBroadcast\Outputs\CustomPlatformOutput::class,
       ],
   ],
   

2. Input Filters Add preprocessing to inputs (e.g., watermarking, dynamic overlays) by extending the InputInterface:

   namespace App\LiveBroadcast\Inputs;
   
   use Centric\LiveBroadcastBundle\Contracts\InputInterface;
   
   class WatermarkedInput implements InputInterface {
       public function getStream($broadcast) {
           $stream = parent::getStream($broadcast);
           // Apply watermark using FFmpeg
           return $stream->pipe(['ffmpeg', '-i', '-', '-vf', 'drawtext=...']);
       }
   }
   

3. Broadcast Events Dispatch custom events for integration with other systems (e.g., analytics, notifications):

   Event::dispatch(new CustomBroadcastEvent($broadcast, 'custom_event'));
   

Configuration Quirks

• Platform-Specific Fields Some platforms require additional fields (e.g., YouTube’s categoryId). Always check the latest API docs and update the config schema:

  'outputs' => [
      'youtube' => [
          'fields' => [
              'title',
              'description',
              'categoryId', // Custom field
          ],
      ],
  ],
  

• Environment-Specific Configs Use Laravel’s config() helper to dynamically load configs based on the environment:

  $config = config("live-broadcast.outputs.{$platform}", []);
  

• Default Values Override defaults in config/live-broadcast.php or via service container binding:

  $this->app->bind('live-broadcast.defaults', function () {
      return [
          'bitrate' => '3000k',
          'preset' => 'high',
      ];
  });