npm package: @lvyanxiang/react-native-audio-waveform
Description: A React Native library for extracting audio waveform data from audio and video files. Supports iOS and Android platforms with streaming processing for large files.
Author: lvyanxiang
Latest version: 12.3.7

# React Native Audio Waveform

A React Native library for extracting audio waveform data from audio and video files. Supports iOS and Android platforms with a functional programming approach.

## Features

- 🎵 Extract waveform data from audio and video files
- 📊 Generate visualization-ready data points
- 🚀 High-performance native implementation
- 📱 iOS and Android support
- ⚡ Functional programming API
- 🎯 TypeScript support
- 🔧 Configurable analysis parameters
- 🌊 **NEW**: Streaming processing for large files (20MB+)
- 💾 **NEW**: Memory-efficient chunk processing
- 🔄 **NEW**: Automatic file size detection and mode switching

## Installation

```bash
npm install react-native-audio-waveform
# or
yarn add react-native-audio-waveform
```

### iOS Setup

Run `cd ios && pod install` to install iOS dependencies.

### Android Setup

No additional setup required for Android.

## Usage

### Basic Waveform Extraction

```typescript
import { extractWaveform, extractPreview } from 'react-native-audio-waveform';

// Extract full waveform analysis
const analysis = await extractWaveform({
  fileUri: 'file:///path/to/audio.mp3',
  segmentDurationMs: 100, // 100ms segments
});

console.log(analysis.dataPoints); // Array of waveform data points
```

### Quick Preview Generation

```typescript
// Generate a quick preview with 100 points
const preview = await extractPreview({
  fileUri: 'file:///path/to/audio.mp3',
  numberOfPoints: 100,
  startTimeMs: 0,
  endTimeMs: 30000, // First 30 seconds
});
```

### Advanced Configuration

```typescript
const analysis = await extractWaveform({
  fileUri: 'file:///path/to/audio.mp3',
  segmentDurationMs: 50,
  decodingOptions: {
    targetSampleRate: 44100,
    targetChannels: 1,
    targetBitDepth: 16,
    normalizeAudio: true,
  },
  features: {
    energy: true,
    rms: true,
    zcr: true,
    spectralCentroid: true,
  },
});
```

## API Reference

### `extractWaveform(options)`

Extracts detailed audio analysis from the specified audio file.

#### Parameters

- `fileUri` (string): Path to the audio file
- `segmentDurationMs` (number, optional): Duration of each segment in milliseconds (default: 100)
- `startTimeMs` (number, optional): Start time in milliseconds
- `endTimeMs` (number, optional): End time in milliseconds
- `decodingOptions` (object, optional): Audio decoding configuration
- `features` (object, optional): Additional features to extract

#### Returns

Promise resolving to `AudioAnalysis` object containing:
- `dataPoints`: Array of waveform data points
- `durationMs`: Total duration in milliseconds
- `sampleRate`: Audio sample rate
- `numberOfChannels`: Number of audio channels
- `amplitudeRange`: Min/max amplitude values

### `extractPreview(options)`

Generates a simplified preview of the audio waveform for quick visualization.

#### Parameters

- `fileUri` (string): Path to the audio file
- `numberOfPoints` (number, optional): Number of data points to generate (default: 100)
- `startTimeMs` (number, optional): Start time in milliseconds (default: 0)
- `endTimeMs` (number, optional): End time in milliseconds (default: 30000)

## Data Structure

### DataPoint

Each data point in the waveform contains:

```typescript
interface DataPoint {
  id: number;
  amplitude: number;      // Peak amplitude for the segment
  rms: number;           // Root mean square value
  dB: number;            // dBFS value
  silent: boolean;       // Whether the segment is silent
  startTime?: number;    // Start time in milliseconds
  endTime?: number;      // End time in milliseconds
  features?: AudioFeatures; // Additional audio features
}
```

## Example App

Check out the example app in the `example/` directory for a complete implementation.

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT