README

A premium NativePHP plugin for professional audio playback on mobile devices (Android & iOS). This plugin provides deep integration with native OS features like MediaSession, background services, and remote controls.

✨ Features

• 🏆 Native Media Integration - Full support for OS Lock Screen controls, Bluetooth devices, and Android Auto/CarPlay.
• 📱 Background Excellence - Reliable background playback using Foreground Services (Android) and specialized Audio Sessions (iOS).
• 🎶 Advanced Playlist Management - Natively managed queues with Shuffle and Repeat modes.
• 🎧 Audio Focus Intelligence - Gracefully handles interruptions (phone calls, notifications, Siri) with auto-ducking and resuming.
• 🕒 Sleep Timers - Programmatic sleep timers that safely release native resources.
• 📊 Detailed Analytics Events - Granular event reporting for playback progress, track changes, buffering, and remote commands.
• 🖼 Rich Metadata - Support for high-quality artwork, titles, artists, and arbitrary custom metadata.

🚀 Installation

# Install via Composer
composer require theunwindfront/nativephp-audio

# Publish the plugins provider (if not already done)
php artisan vendor:publish --tag=nativephp-plugins-provider

# Register the plugin with NativePHP
php artisan native:plugin:register theunwindfront/nativephp-audio

📖 Usage

PHP Interface (Livewire / Controller)

use Theunwindfront\Audio\Facades\Audio;

// 1. Play a single track with metadata
Audio::play('https://example.com/song.mp3', [
    'title'    => 'Midnight City',
    'artist'   => 'M83',
    'artwork'  => 'https://example.com/artwork.jpg',
]);

// 2. Play a Local File (Mobile Storage)
// Raw paths from storage_path() are natively supported
Audio::play(storage_path('app/public/recordings/audio.mp3'), [
    'title'  => 'Voice Note',
    'artist' => 'Recorded Local'
]);

// 3. Manage a Playlist (Natively handled auto-advance)
Audio::setPlaylist([
    [
        'url'   => 'https://example.com/track1.mp3',
        'title' => 'Track 01',
    ],
    // ... more tracks
], autoPlay: true, startIndex: 0);

// 4. Playback Controls
Audio::pause();
Audio::resume();
Audio::next();
Audio::previous();
Audio::skipTo(5); // Skip to index 5 in playlist

// 5. State & Settings
$state = Audio::getState(); 
Audio::setVolume(0.8);
Audio::setPlaybackRate(1.5);
Audio::setShuffleMode(true);
Audio::setRepeatMode('all'); // 'none', 'one', 'all'

// 6. Sleep Timer
Audio::setSleepTimer(1800); // 30 minutes

⚡ JavaScript Bridge

If you are building a SPA (Inertia/Vue/React) or using Alpine.js, you can use the JavaScript bridge directly.

First, include the bridge in your layout:

@include('audio::bridge')

Then, use the audio helper:

import audio from './resources/js/audio.js';

// Play immediately
await audio.play('https://server.com/live.mp3', { title: 'Live Stream' });

// Listen for native events on the window
window.addEventListener('audio:playback-progress-updated', (event) => {
    const { position, duration } = event.detail;
    console.log(`Playing: ${position} / ${duration}`);
});

📡 Event Synchronization

This plugin dispatches powerful Laravel events that you can listen to in your application:

🛠 Advanced Features

Background Sync

When your app returns from the background, you can "drain" any missed events that occurred while the PHP process was suspended:

$missedEvents = Audio::drainEvents();

Absolute Local Paths

Unlike standard web players, this plugin has direct filesystem access. On Android, it even requests READ_MEDIA_AUDIO permissions automatically.

Audio::play('/storage/emulated/0/Download/my-song.mp3');

📋 API Reference

📱 Version Support

• Android: 5.0 (API 21) or higher.
• iOS: 13.0 or higher.

👥 Credits

• Sagar Pansuriya - Lead Developer
• All Contributors

🤝 Support

For questions or issues, contact pansuriya.sagar94@gmail.com or open a GitHub Issue.

📄 License

The MIT License (MIT). Please see License File for more information.