nosnia-audio-recorder

A compact, high-performance audio recorder library for React Native that records directly to MP3 format on both Android and iOS.

Features

• 🎙️ Direct MP3 Recording: Records audio directly to MP3 format
• 📱 Cross-Platform: Works seamlessly on iOS and Android
• 🎚️ Configurable: Adjust bitrate, sample rate, and channels
• ⏸️ Pause/Resume: Full control over recording with pause and resume
• ⏱️ Real-time Duration: Get continuous recording duration updates via callback
• ▶️ MP3 Playback: Built-in audio player with play/pause/resume/stop/seek
• 🔒 Permission Handling: Built-in permission checking and requesting
• 💾 File Management: Automatic file naming and directory management
• 📦 Compact: Minimal dependencies, optimized for bundle size

Installation

npm install nosnia-audio-recorder
# or
yarn add nosnia-audio-recorder

Quick Start

Request Permission

import { NosniaAudioRecorder } from 'nosnia-audio-recorder';

// Request microphone permission
const hasPermission = await NosniaAudioRecorder.requestPermission();

Record Audio

// Start recording
await NosniaAudioRecorder.startRecording({
  bitrate: 128000,
  channels: 1,
  sampleRate: 44100,
});

// ... recording in progress ...

// Stop and save
const filePath = await NosniaAudioRecorder.stopRecording();
console.log('Recording saved to:', filePath);

Full Example (Record + Playback)

import { NosniaAudioRecorder, NosniaAudioPlayer } from 'nosnia-audio-recorder';
import { useState } from 'react';

// Check and request permission
const hasPermission = await NosniaAudioRecorder.checkPermission();
if (!hasPermission) {
  await NosniaAudioRecorder.requestPermission();
}

// Start recording with real-time duration updates
await NosniaAudioRecorder.startRecording();

// Add listener for recording duration updates (every 100ms)
const removeListener = NosniaAudioRecorder.addRecordingProgressListener(
  ({ duration, isRecording }) => {
    console.log(`Recording ${Math.floor(duration / 1000)}s`);
  }
);

// Pause if needed
await NosniaAudioRecorder.pauseRecording();
await NosniaAudioRecorder.resumeRecording();

// Get status
const status = await NosniaAudioRecorder.getStatus();
console.log(`Recording: ${status.isRecording}, Duration: ${status.duration}ms`);

// Stop and save
const filePath = await NosniaAudioRecorder.stopRecording();

// Remove listener when done
removeListener();

// Or cancel (discard)
await NosniaAudioRecorder.cancelRecording();

// Play it back
await NosniaAudioPlayer.startPlaying({ filePath });
// Optionally listen to progress
const removePlayback = NosniaAudioPlayer.addPlaybackProgressListener(({ currentTime, duration }) => {
  console.log(`Progress: ${Math.floor(currentTime / 1000)} / ${Math.floor(duration / 1000)}s`);
});
// Stop playback
await NosniaAudioPlayer.stopPlaying();
removePlayback();

API Reference

Methods

• requestPermission(): Promise<boolean> - Request microphone permission
• checkPermission(): Promise<boolean> - Check if permission is granted
• startRecording(options?: RecorderOptions): Promise<void> - Start recording
• stopRecording(): Promise<string> - Stop and save (returns file path)
• pauseRecording(): Promise<void> - Pause recording
• resumeRecording(): Promise<void> - Resume recording
• cancelRecording(): Promise<void> - Cancel and discard
• getStatus(): Promise<RecorderStatus> - Get recorder status
• addRecordingProgressListener(callback: RecordingProgressCallback): () => void - Add listener for duration updates (returns cleanup function)
• removeRecordingProgressListener(): void - Remove duration listener

Player Methods

• startPlaying(options: PlayOptions): Promise<void> - Start playing an audio file
• stopPlaying(): Promise<void> - Stop playback and reset
• pausePlaying(): Promise<void> - Pause playback
• resumePlaying(): Promise<void> - Resume playback
• seekToTime(time: number): Promise<void> - Seek to time (seconds)
• setVolume(volume: number): Promise<void> - Set playback volume (0.0–1.0)
• getPlayerStatus(): Promise<PlayerStatus> - Get playback status
• addPlaybackProgressListener(callback: PlaybackProgressCallback): () => void - Listen to playback progress
• addPlaybackCompleteListener(callback: () => void): () => void - Listen for playback completion
• removePlaybackProgressListener(): void - Remove progress listener
• removePlaybackCompleteListener(): void - Remove completion listener

Types

interface RecorderOptions {
  filename?: string;      // Auto-generated if not provided
  bitrate?: number;       // Default: 128000 (128 kbps)
  channels?: number;      // 1 = mono (default), 2 = stereo
  sampleRate?: number;    // Default: 44100 (44.1 kHz)
}

interface RecorderStatus {
  isRecording: boolean;
  duration: number;           // In milliseconds
  currentFilePath?: string;
}

type RecordingProgressCallback = (data: {
  duration: number;           // In milliseconds
  isRecording: boolean;
}) => void;

interface PlayOptions {
  filePath: string;
  volume?: number;  // 0.0 - 1.0
  loop?: boolean;   // repeat playback
}

interface PlayerStatus {
  isPlaying: boolean;
  duration: number;     // In milliseconds
  currentTime: number;  // In milliseconds
  currentFilePath?: string;
}

type PlaybackProgressCallback = (data: {
  currentTime: number;
  duration: number;
  isPlaying: boolean;
}) => void;

Platform Setup

Android

Add permission to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

iOS

Add microphone permission to ios/[AppName]/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs access to your microphone to record audio.</string>

Configuration

Default Settings

| Setting | Value | |---------|-------| | Format | MP3 | | Bitrate | 128 kbps | | Sample Rate | 44.1 kHz | | Channels | 1 (Mono) |

Recommended Settings

• Speech: 64 kbps, 16 kHz, mono
• Music: 192-320 kbps, 44.1-48 kHz, stereo
• Balanced: 128 kbps, 44.1 kHz, mono

File Locations

• Android: Documents/NosniaAudioRecorder/ (API 29+) or Music/NosniaAudioRecorder/
• iOS: Documents/NosniaAudioRecorder/

Performance

• Lightweight native implementation
• Minimal memory footprint
• Direct encoding to M4A format
• Efficient file handling

More Documentation

For detailed usage guide, see USAGE.md

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library