rns-audiomix

Native audio processing module for Expo React Native (iOS & Android).
Powered by FFmpegKit (iOS) and JavaCV/FFmpeg (Android).

Supports multi-track mixing with per-track EQ, volume, delay, reverb, and a master bus — plus audio trimming, video export with a cover image, audio duration lookup, and waveform generation.

Installation

npm install rns-audiomix

Usage

Import

import { audioMix } from 'rns-audiomix';

Methods

audioMix

Mix multiple audio tracks together with per-track processing and a master bus.

audioMix(
  inputUris: string[],
  outputPath: string,
  delayMsList: number[],
  volumeList: number[],
  eqList: Array<{ low?: number; mid?: number; high?: number; reverb?: number }>,
  masterEq: { low?: number; mid?: number; high?: number; reverb?: number },
  syncValue: number,
): Promise<string>

| Parameter | Type | Description | |---------------|------------|-------------| | inputUris | string[] | File URIs of the audio tracks to mix | | outputPath | string | Desired output path. If blank or "undefined", a temp file is used | | delayMsList | number[] | Per-track delay in ms (index-aligned with inputUris) | | volumeList | number[] | Per-track volume multiplier (1.0 = unity) | | eqList | object[] | Per-track EQ settings (see EQ values below) | | masterEq | object | Master bus EQ applied after mixing | | syncValue | number | Global sync offset in ms — subtracted from all non-base-track delays |

Returns: Promise resolving with the file:// URI of the mixed .wav output.

EQ values — all fields are optional and default to 1.0 (no effect):

| Field | Range | Effect | |----------|-------|--------| | low | 0–2 | Low shelf gain. 1.0 = 0 dB, 2.0 = +12 dB, 0.0 = -12 dB | | mid | 0–2 | Peaking EQ at 3 kHz. Same scale as low | | high | 0–2 | High shelf gain. Same scale as low | | reverb | 0–2 | > 1.0 adds echo/reverb; < 1.0 adds dryness (cuts highs) |

The master bus also applies chorus and loudness normalisation (-14 dBFS) to the final mix on both platforms.

Example

const result = await audioMix(
  ['/path/to/track1.wav', '/path/to/track2.wav'],
  '',                // outputPath — leave blank to auto-generate
  [0, 120],         // delays in ms
  [1.0, 0.8],       // volumes
  [
    { low: 1.2, mid: 1.0, high: 0.9, reverb: 1.0 },
    { low: 1.0, mid: 1.1, high: 1.0, reverb: 1.3 },
  ],
  { low: 1.0, mid: 1.0, high: 1.1, reverb: 1.0 }, // master EQ
  0,                // syncValue
);

console.log('Mixed file:', result); // file:///...mixed_output_<uuid>.wav

trimAudio

Trim an audio file between two timestamps.

trimAudio(
  uri: string,
  startTime: number,
  endTime: number,
  outputPath: string,
): Promise<{ uri: string; duration: number }>

| Parameter | Type | Description | |--------------|----------|-------------| | uri | string | Source audio file URI | | startTime | number | Start time in seconds | | endTime | number | End time in seconds | | outputPath | string | Desired output path. If blank or "undefined", a temp file is used |

Returns: Promise resolving with:

{
  uri: string;      // file:// URI of the trimmed output
  duration: number; // Actual duration of the trimmed segment in seconds
}

Example

const result = await trimAudio(
  'file:///path/to/recording.wav',
  5.0,   // start at 5 seconds
  12.5,  // end at 12.5 seconds
  '',    // auto-generate output path
);

console.log(result.uri);      // file:///...trimmed_<uuid>.wav
console.log(result.duration); // 7.5

exportWithCover

Export audio as a video with a static cover image and optional logo overlay, or as a plain audio file if no image is provided. Emits ExportProgress events during video encoding.

exportWithCover(
  audioUri: string,
  imageUri: string,
  logoUri: string,
  outputPath: string,
): Promise<string>

| Parameter | Type | Description | |--------------|----------|-------------| | audioUri | string | Source audio file URI | | imageUri | string | Cover image URI. Pass "" or "undefined" for audio-only export | | logoUri | string | Logo overlay URI — positioned bottom-right at 25% of image width. Pass "" to skip | | outputPath | string | Desired output path. Auto-generates .mp4 (with image) or .mp3/.wav (without) |

Returns: Promise resolving with the file:// URI of the exported file.

Progress events: Listen to ExportProgress during video encoding:

Example

// Export as video with cover image
const outputUri = await exportWithCover(
  'file:///path/to/mixed.wav',
  'file:///path/to/cover.jpg',
  'file:///path/to/logo.png',
  '',
);
console.log('Exported video:', outputUri); // file:///...mastered_<uuid>.mp4

// Export as audio only
const audioOnly = await exportWithCover(
  'file:///path/to/mixed.wav',
  '',  // no image → audio-only
  '',
  '',
);
console.log('Exported audio:', audioOnly); // file:///...mastered_<uuid>.mp3

getAudioDuration

Get the duration of an audio file in seconds.

getAudioDuration(path: string): Promise<number>

| Parameter | Type | Description | |-----------|----------|-------------| | path | string | Audio file path or file:// URI |

Returns: Promise resolving with duration in seconds, or 0 on failure.

Example

const duration = await getAudioDuration('file:///path/to/audio.wav');
console.log(`Duration: ${duration}s`);

generateWaveformData

Generate a normalised peak array for rendering a waveform UI.

generateWaveformData(
  path: string,
  samplesPerSecond: number,
): Promise<number[]>

| Parameter | Type | Description | |--------------------|----------|-------------| | path | string | Audio file path or file:// URI | | samplesPerSecond | number | Number of data points to generate. Capped at 1200 |

Returns: Promise resolving with an array of peak values between 0.0 and 1.0, smoothed with a 3-sample weighted average. Returns [] on failure.

Example

const peaks = await generateWaveformData('file:///path/to/audio.wav', 200);
// [0.12, 0.45, 0.67, ...] — up to 200 floats between 0.0–1.0

Output Files

All output files land in the app's cache directory when no outputPath is provided:

| Method | Filename pattern | Format | |-------------------|---------------------------------|-----------| | audioMix | mixed_output_<uuid>.wav | WAV | | trimAudio | trimmed_<uuid>.wav | WAV | | exportWithCover | mastered_<uuid>.mp4 or .mp3 | MP4 / MP3 |

Error Handling

All methods return Promises that reject on failure:

try {
  const result = await audioMix(...);
} catch (err) {
  console.error('Audio processing failed:', err.message);
}

Platform Notes

• iOS uses FFmpegKit. audioMix and trimAudio output .mp3; exportWithCover outputs .mp4 or .mp3.
• Android uses JavaCV/FFmpeg. audioMix and trimAudio output .wav; exportWithCover outputs .mp4 or .wav for audio-only.
• Audio is internally resampled to 44.1 kHz stereo on both platforms.
• syncValue only affects non-first-track delays — the base track (index 0) always uses its raw delayMs.
• ExportProgress events are only emitted during video (.mp4) exports, not audio-only exports.

License

MIT