README

Audio recording plugin for NativePHP Mobile with pause/resume support, background recording, and native permission handling.

Features

Record audio in M4A format (AAC codec)
Pause and resume recordings
Background recording support (Android foreground service)
Automatic permission handling
Custom event dispatching
Recording status tracking

Installation

composer require nativephp/microphone

Register the Plugin

Add the plugin to your NativePluginsServiceProvider:

// app/Providers/NativePluginsServiceProvider.php

public function plugins(): array
{
    return [
        \NativePHP\Microphone\MicrophoneServiceProvider::class,
    ];
}

Usage

Basic Recording

use NativePHP\Microphone\Facades\Microphone;

// Start recording
Microphone::record()->start();

// Stop recording (triggers MicrophoneRecorded event)
Microphone::stop();

With Custom Event

use NativePHP\Microphone\Facades\Microphone;
use App\Events\MyAudioRecordedEvent;

Microphone::record()
    ->event(MyAudioRecordedEvent::class)
    ->start();

With Tracking ID

Microphone::record()
    ->id('voice-note-123')
    ->start();

Pause & Resume

// Pause the current recording
Microphone::pause();

// Resume a paused recording
Microphone::resume();

Check Recording Status

$status = Microphone::getStatus();
// Returns: "idle", "recording", or "paused"

Get Last Recording Path

$path = Microphone::getRecording();
// Returns: "/path/to/audio_123456.m4a" or null

Handling Events

Using Livewire Attributes

use Livewire\Component;
use Native\Mobile\Attributes\OnNative;
use NativePHP\Microphone\Events\MicrophoneRecorded;
use NativePHP\Microphone\Events\MicrophoneCancelled;

class AudioRecorder extends Component
{
    #[OnNative(MicrophoneRecorded::class)]
    public function handleRecorded($path, $mimeType = null, $id = null)
    {
        // $path - absolute path to the recorded audio file
        // $mimeType - "audio/m4a"
        // $id - the ID you set with ->id(), if any

        // Move the file to storage
        File::move($path, storage_path('app/recordings/audio.m4a'));
    }

    #[OnNative(MicrophoneCancelled::class)]
    public function handleCancelled($cancelled, $reason = null, $id = null)
    {
        // $reason - "permission_denied" or "start_failed"
    }
}

Using Custom Events

// app/Events/MyAudioRecordedEvent.php
namespace App\Events;

class MyAudioRecordedEvent
{
    public function __construct(
        public string $path,
        public string $mimeType = 'audio/m4a',
        public ?string $id = null
    ) {}
}

// In your Livewire component
#[OnNative(MyAudioRecordedEvent::class)]
public function handleMyAudio($path, $mimeType, $id)
{
    // Handle the recording
}

Events

Event	Properties	Description
`MicrophoneRecorded`	`path`, `mimeType`, `id`	Dispatched when recording stops successfully
`MicrophoneCancelled`	`cancelled`, `reason`, `id`	Dispatched when recording is cancelled or fails

Cancellation Reasons

permission_denied - User denied microphone permission
start_failed - Failed to initialize the recorder

Permissions

The plugin automatically requests the required permissions:

Android

android.permission.RECORD_AUDIO

The plugin includes a foreground service for background recording support.

iOS

NSMicrophoneUsageDescription - Added to Info.plist automatically
UIBackgroundModes: audio - For background recording

API Reference

Microphone Facade

Method	Returns	Description
`record()`	`PendingMicrophone`	Start building a recording request
`stop()`	`void`	Stop current recording
`pause()`	`void`	Pause current recording
`resume()`	`void`	Resume paused recording
`getStatus()`	`string`	Get status: "idle", "recording", "paused"
`getRecording()`	`?string`	Get path to last recording

PendingMicrophone

Method	Returns	Description
`id(string $id)`	`self`	Set a tracking ID
`getId()`	`string`	Get the ID (auto-generates if not set)
`event(string $class)`	`self`	Set custom event class
`remember()`	`self`	Flash ID to session
`start()`	`bool`	Start recording

File Format

Recordings are saved as M4A files with:

Codec: AAC
Bit rate: 128 kbps
Sample rate: 44.1 kHz

Files are initially saved to the app's cache directory and should be moved to permanent storage in your event handler.

License

MIT

nativephp / microphone

Maintainers

Details