Filament Notification Sound Laravel Package

Getting Started

1. Install the package

   composer require moataz-01/filament-notification-sound
   

2. Publish config and assets (the package ships a config file and an audio asset under public/):

   php artisan vendor:publish --tag="filament-notification-sound-config"
   php artisan vendor:publish --tag="filament-notification-sound-assets"
   

   If a tag is missing, run php artisan vendor:publish and pick the moataz-01 entries interactively — small Filament plugins are inconsistent about tag naming.

3. Register the plugin in the panel provider where you want audible alerts (app/Providers/Filament/AdminPanelProvider.php):

   use Moataz01\FilamentNotificationSound\FilamentNotificationSoundPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(FilamentNotificationSoundPlugin::make());
   }
   

4. First use case to validate: open two browser windows. In one, trigger a database notification to the logged-in user (e.g. $user->notify(new SomeNotification())). In the other, wait for Filament's notification poller to pick it up. If a chime plays, the wiring is correct; if not, the problem is almost always the browser autoplay policy (see Gotchas).

Where to look first: config/filament-notification-sound.php after publishing. That is where the sound file path, volume, and enable/disable switches live. Read the README.md for the exact plugin namespace and config keys — at 12 stars the API surface is small but the namespace casing matters for autoloading.

Implementation Patterns

Panel-scoped registration. The plugin is registered per-panel, so multi-panel apps (admin + staff + vendor) need it added to each PanelProvider independently. Use a shared base provider or a trait if you want consistent behaviour everywhere.

Pair it with database notifications. The sound is only useful when Filament is polling for notifications. Enable that on the panel:

->databaseNotifications()
->databaseNotificationsPolling('15s')

The sound fires when the poller discovers a new notification, so the polling interval is effectively your maximum alert latency. Tighten it (10–15s) for a support desk, loosen it (60s) for low-traffic back offices.

Ship a custom sound per environment. Publish the asset, drop your own .mp3/.wav into public/, and point the config at it:

// config/filament-notification-sound.php
'sound' => public_path('sounds/notification.mp3'),

Keep the file under ~100 KB and mono — large stereo files are noticeably delayed on first play because the browser has to buffer them.

Different sound per notification type. If the package exposes the underlying Livewire/JS event, you can override per notification by dispatching your own browser event from a custom Notification class rather than relying on the default. This is the extension point to reach for if "urgent" and "FYI" notifications should sound different.

Queue-friendly. Because the sound is driven by the notification poller rather than the request that created the notification, queued notifications work transparently — the sender's request never touches the audio, which is what you want.

Integration with a custom toast flow. If you use Notification::make()->send() inside a Livewire action, the alert is already visible; a sound on top of that is usually noise. Configure (or gate) the sound to only play for background/database notifications, not for notifications triggered by the current user's own action.

Gotchas and Tips

Browser autoplay policy is the #1 failure mode. Chrome, Safari, and Firefox block audio until the user has interacted with the page. On a freshly loaded dashboard with no clicks, the first chime is silently dropped. Practical mitigations: prime the audio element on the first click/keypress (a login redirect into the panel counts once the user clicks anything), or instruct users that the first alert after a page load may be silent. There is no reliable server-side fix.

Unpublished assets. php artisan filament:assets and php artisan vendor:publish are separate steps; if you deploy via a pipeline, make sure the publish step runs before filament:optimize / filament:cache-components. A missing audio file usually shows as a console 404, not a PHP error, so check the browser network tab first.

Sound file caching. Browsers cache by URL. If you replace the audio file to change the chime, users keep hearing the old one. Either bump the filename (notification-v2.mp3) or append a query string in the config path.

Multiple tabs, multiple chimes. Filament notifications are per-user, and each open tab polls independently. Three tabs means three overlapping chimes. If that's a problem, dedupe with a BroadcastChannel in a small custom script, or accept it as a minor annoyance.

Filament version skew. Check the package's composer.json for the filament/filament constraint. Filament v3 → v4 changed plugin registration signatures in places; a package released in early 2026 targets one of them. If you're on an older minor, pin the package or skip it.

Polling interval doubles as sound latency. Users often report "the sound is late" when the real cause is databaseNotificationsPolling('60s'). Measure the interval before debugging the package.

Config cache. php artisan config:cache in production will freeze the config values. After changing the sound path, run php artisan config:clear — otherwise you'll edit the config file and see no effect at all.

Extension points to check in the repo. Look for a published Blade view or a registerScripts/getScriptData method — those are where you'd inject a custom Audio object if you need volume ramps, a mute toggle persisted in localStorage, or per-notification-type sounds. Small plugins like this rarely expose a formal API beyond config, so overriding the view or listening for the dispatched JS event is the realistic path.

Not a real-time solution. This is polling-based, not websocket-based. If you need sub-second alerting (on-call, live chat), pair it with Laravel Echo / Reverb broadcasting and dispatch the same audio event from the broadcast handler instead.