Filament Audio Field Column Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ultraviolettes/filament-audio-field-column
   

   Publish the config (if needed) with:

   php artisan vendor:publish --provider="Ultraviolettes\FilamentAudio\FilamentAudioServiceProvider"
   

2. First Use Case: Display an audio preview in a Table Column:

   use Ultraviolettes\FilamentAudio\Tables\Columns\AudioColumn;
   
   public static function table(Table $table): Table
   {
       return $table->columns([
           AudioColumn::make('audio_file')
               ->label('Listen'),
       ]);
   }
   

   • Ensure your model’s audio_file field contains a valid URL (local or remote) pointing to an audio file (e.g., storage/audio/sample.mp3 or https://example.com/audio.mp3).

Implementation Patterns

1. Common Workflows

Tables

• Basic Usage:

  AudioColumn::make('audio_path')
      ->size(36) // Default: 40px
      ->progressColor('green-500') // Tailwind color
      ->showDuration() // Adds time display
  

• Dynamic URLs:

  AudioColumn::make('id')
      ->audioUrl(fn ($record) => route('audio.download', $record))
  

Forms

• Audio Upload Field:

  use Ultraviolettes\FilamentAudio\Forms\Components\AudioUpload;
  
  AudioUpload::make('audio_file')
      ->directory('audio') // Stores in `storage/app/audio/`
      ->openable() // Allows file selection
  

• Preloaded Audio:

  AudioUpload::make('audio_file')
      ->existingFileUrl(fn ($record) => $record->audio_url)
  

Infolists

• Embedded Player:

  use Ultraviolettes\FilamentAudio\Infolists\Components\AudioPlayer;
  
  AudioPlayer::make('audio_url')
      ->size(50)
      ->volumeControl() // Adds volume slider
  

2. Integration Tips

• Local Files: Use Storage::url() to generate URLs for local files:

  AudioColumn::make('file')
      ->audioUrl(fn ($record) => Storage::url($record->file_path))
  

• Remote Files: Ensure URLs are absolute (e.g., https://example.com/audio.mp3). Relative paths (e.g., /audio.mp3) may fail.
• Caching: For large tables, cache audio metadata (e.g., duration) to avoid repeated API calls:

  $record->audio_duration ??= AudioHelper::getDuration($record->audio_url);
  

3. Advanced Customization

• Global Config: Override defaults in config/filament-audio.php:

  'default' => [
      'size' => 48,
      'progress_color' => 'blue-500',
      'auto_pause' => true,
  ],
  

• Event Listeners: Listen for play/pause events (via Alpine.js):

  document.addEventListener('filament-audio:play', (e) => {
      console.log('Playing:', e.detail.url);
  });
  

Gotchas and Tips

Pitfalls

1. CORS Issues:

   • Remote audio files may block playback due to CORS. Use a proxy or ensure the server allows cross-origin requests.
   • Fix: Configure your server to include:

     Header set Access-Control-Allow-Origin "*"
     

2. File Format Support:

   • The package relies on the browser’s native <audio> element. Test with MP3, WAV, or OGG for broad compatibility.
   • Tip: Convert files to MP3 if support is inconsistent.

3. Auto-Pause Conflicts:

   • The auto_pause feature (only one player plays at a time) may interfere with UX in tables with many rows.
   • Workaround: Disable globally in config or per-column:

     AudioColumn::make('audio')->autoPause(false)
     

4. Alpine.js Conflicts:

   • If using other Alpine.js-based packages, ensure IDs are unique:

     AudioColumn::make('audio')->id('unique-audio-player')
     

Debugging

• Console Errors: Check the browser console for 404 (file not found) or 403 (CORS) errors.

  • Debug URL: Temporarily hardcode a URL to isolate issues:

    AudioColumn::make('dummy')->audioUrl('https://example.com/test.mp3')
    

• Duration Calculation: If durations are NaN, ensure the audio file is accessible and not corrupted. Use a tool like FFmpeg to verify:

  ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp3
  

Extension Points

1. Custom Styling: Override Blade components in resources/views/vendor/filament-audio/. Example: Modify the progress bar in audio-progress.blade.php.

2. Add Metadata: Extend the column to display metadata (e.g., artist, album) from the audio file:

   AudioColumn::make('audio')
       ->extraAttributes(fn ($record) => [
           'data-artist' => $record->artist,
       ])
   

   Then target it in CSS/JS:

   document.querySelector('[data-artist]').dataset.artist;
   

3. Server-Side Duration: Cache durations server-side to avoid repeated client-side calculations:

   // In a model observer or accessor
   public function getAudioDurationAttribute()
   {
       return cache()->remember("audio_duration_{$this->id}", now()->addHours(1), function () {
           return AudioHelper::getDuration($this->audio_url);
       });
   }
   

Pro Tips

• Lazy Loading: For tables with many rows, lazy-load audio players:

  AudioColumn::make('audio')
      ->lazy() // Only loads when scrolled into view
  

• Dark Mode: Use Tailwind’s dark mode classes for consistency:

  AudioColumn::make('audio')
      ->progressColor('emerald-400 dark:emerald-300')
  

• Accessibility: Add ARIA labels for screen readers:

  AudioColumn::make('audio')
      ->ariaLabel('Play audio preview')