@puzzlearena/audio
Version:
Lightweight native sound module for React Native
156 lines (98 loc) • 3.57 kB
Markdown
# @puzzlearena/audio
**Lightweight native sound module for React Native (iOS & Android).**
A simple, dependency-free audio module for playing **background music** and **sound effects** in React Native apps.
- 🎵 Supports **mp3**, **wav**, **ogg** formats
- 🔊 Control **volume** per playback
- ⚡ Native performance with **MediaPlayer** (Android) & **AVAudioPlayer** (iOS)
- 🛠 Includes CLI (`puzzlearena-audio`) for copying audio assets to `res/raw` automatically
---
## **Installation**
```bash
yarn add @puzzlearena/audio
# or
npm install @puzzlearena/audio
```
After installation:
### **iOS**
```bash
cd ios && pod install
```
### **Android**
No extra setup required. Just rebuild the app:
```bash
yarn android
```
---
## **Usage**
```ts
import { Audio } from "@puzzlearena/audio";
// Play a looping background music
await Audio.playBackground("menu_theme", true, 0.8);
// Stop background music
await Audio.stopBackground();
// Play a sound effect at 50% volume
await Audio.playEffect("click", 0.5);
```
> **Note:** Do **not** include the file extension.
> For example, `menu_theme.mp3` → `"menu_theme"`.
---
## **Copying Audio Files**
### **Android**
Android requires `.mp3`/`.wav`/`.ogg` files to be placed in `android/app/src/main/res/raw`.
To copy your assets automatically, run:
```bash
npx puzzlearena-audio
```
You will be prompted for the source folder (defaults to `src/assets/sounds`).
### **iOS**
For iOS, you need to manually add your audio files to the Xcode project:
- Open your project in Xcode.
- Go to Build Phases > Copy Bundle Resources.
- Drag and drop your audio files (e.g., theme.mp3, click.wav) into the resources list.
Note: Make sure you don't include the file extension when calling the audio methods.
---
## **API**
### **`Audio.playBackground(name: string, loop?: boolean, volume?: number): Promise<void>`**
- `name`: File name without extension (e.g. `"theme"` for `theme.mp3`).
- `loop`: (optional) `true` for continuous playback. Default: `true`.
- `volume`: (optional) Float from `0.0` to `1.0`. Default: `1.0`.
### **`Audio.stopBackground(): Promise<void>`**
Stops and releases the background music.
### **`Audio.playEffect(name: string, volume?: number): Promise<void>`**
- `name`: File name without extension (e.g. `"click"`).
- `volume`: (optional) Float from `0.0` to `1.0`. Default: `1.0`.
---
## **Supported Formats**
- `.mp3`
- `.wav`
- `.ogg`
If the file is missing or unsupported, the Promise will **reject** with an error code:
- `AUDIO_NOT_FOUND`
- `AUDIO_EFFECT_NOT_FOUND`
- `AUDIO_ERROR`
- `AUDIO_EFFECT_ERROR`
Example:
```ts
try {
await Audio.playBackground("invalid_file");
} catch (e) {
console.error(e); // { code: 'AUDIO_NOT_FOUND', message: 'Audio file not found: invalid_file' }
}
```
---
## **CLI Commands**
### **`npx puzzlearena-audio`**
Copies `.mp3`, `.wav` or `.ogg` files from `src/assets/sounds` (or a custom path) to `android/app/src/main/res/raw`.
---
## **Why @puzzlearena/audio?**
- Zero external dependencies.
- Instant load and playback.
- Tiny footprint compared to `react-native-sound` or `expo-av`.
- Works with **React Native 0.70+**.
---
## **License**
MIT © [Felipe Ramos](https://github.com/feliperramos)