react-native-waveform-player 0.0.1 → 1.0.0

package/AudioWaveform.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "AudioWaveform"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/maitrungduc1410/react-native-audio-waveform.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  s.swift_versions = ["5.0"]
+  s.frameworks = "AVFoundation", "CoreMedia", "QuartzCore", "UIKit"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    "SWIFT_OBJC_INTERFACE_HEADER_NAME" => "AudioWaveform-Swift.h",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20"
+  }
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Duc Trung Mai
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# react-native-waveform-player
+
+Native audio-message UI for React Native — play any local or remote audio file
+and render its waveform purely natively. Swift on iOS, Kotlin on Android,
+Fabric (new architecture) only.
+
+<p align="center">
+  <img src="./demo/ios.png" alt="iOS" width="48%" />
+  <img src="./demo/android.png" alt="Android" width="48%" />
+</p>
+
+## Features
+
+- Play / pause / scrub / cycle speed — all rendered in native code, no JS in
+  the hot path.
+- Custom rounded-bar waveform with a partial-fill playhead (the bar straddling
+  the playhead is highlighted up to the exact pixel).
+- Press-and-drag scrubbing with zero activation delay.
+- Configurable bar size / gap / radius / count, played + unplayed colors.
+- Built-in play button, time label (count-up or count-down), and tap-to-cycle
+  speed pill — each individually showable / themable.
+- Pre-computed `samples` escape hatch when you already have peaks data.
+- Controlled (`playing`, `speed`) and uncontrolled modes.
+- Imperative `ref.play()` / `pause()` / `toggle()` / `seekTo(ms)` /
+  `setSpeed(s)`.
+- Opt-in background playback via `playInBackground` (paused on backgrounding
+  by default), with `pauseUiUpdatesInBackground` to skip cheap-but-pointless
+  UI work while offscreen.
+- Events: `onLoad`, `onLoadError`, `onPlayerStateChange`, `onTimeUpdate`,
+  `onSeek`, `onEnd`.
+
+## Installation
+
+```sh
+npm install react-native-waveform-player
+# or
+yarn add react-native-waveform-player
+```
+
+iOS:
+
+```sh
+cd ios && pod install
+```
+
+This library is Fabric-only; the host app must have the new architecture
+enabled (it's the default in RN 0.85+).
+
+## Usage
+
+```tsx
+import { AudioWaveformView } from 'react-native-waveform-player';
+
+export function VoiceNote() {
+  return (
+    <AudioWaveformView
+      source={{
+        uri: 'https://example.com/voice-note.m4a',
+      }}
+      style={{ height: 56 }}
+    />
+  );
+}
+```
+
+### Themed + count-down + custom speeds
+
+```tsx
+<AudioWaveformView
+  source={{ uri: REMOTE_AUDIO }}
+  containerBackgroundColor="#0F172A"
+  containerBorderRadius={20}
+  playedBarColor="#22D3EE"
+  unplayedBarColor="rgba(34, 211, 238, 0.35)"
+  playButtonColor="#22D3EE"
+  timeColor="#A5F3FC"
+  timeMode="count-down"
+  speedColor="#0F172A"
+  speedBackgroundColor="#22D3EE"
+  speeds={[1, 1.5, 2]}
+  defaultSpeed={1.5}
+  barWidth={4}
+  barGap={3}
+  style={{ height: 56 }}
+/>
+```
+
+### Controlled component
+
+When `playing` and/or `speed` are supplied, the component is fully controlled
+— tapping the play button or speed pill fires `onPlayerStateChange` with the
+*requested* new value but does **not** mutate internal state. Update the prop
+in your parent state.
+
+```tsx
+const [playing, setPlaying] = useState(false);
+const [speed, setSpeed] = useState(1);
+
+<AudioWaveformView
+  source={{ uri }}
+  playing={playing}
+  speed={speed}
+  onPlayerStateChange={(e) => {
+    if (e.isPlaying !== playing) setPlaying(e.isPlaying);
+    if (e.speed !== speed) setSpeed(e.speed);
+  }}
+/>;
+```
+
+### Imperative ref API
+
+```tsx
+import {
+  AudioWaveformView,
+  type AudioWaveformViewRef,
+} from 'react-native-waveform-player';
+
+const ref = useRef<AudioWaveformViewRef>(null);
+
+ref.current?.play();
+ref.current?.pause();
+ref.current?.toggle();
+ref.current?.seekTo(0);
+ref.current?.setSpeed(2);
+```
+
+### Pre-computed samples (skip native decode)
+
+```tsx
+<AudioWaveformView
+  source={{ uri }}
+  samples={[0.1, 0.4, 0.85, 0.6, /* ... */]}
+/>
+```
+
+### Hide every chrome element (visualiser only)
+
+```tsx
+<AudioWaveformView
+  source={{ uri }}
+  showPlayButton={false}
+  showTime={false}
+  showSpeedControl={false}
+  showBackground={false}
+/>
+```
+
+### Background playback
+
+By default the component pauses playback when the host app is backgrounded
+(matches iOS's default behaviour, and we add the same on Android for parity).
+Opt in with `playInBackground`:
+
+```tsx
+<AudioWaveformView source={{ uri }} playInBackground />
+```
+
+When `playInBackground` is `true`:
+
+#### iOS — required
+
+Enable the **Audio** background mode on the host app target. Either:
+
+1. **Xcode** → Project → app target → **Signing & Capabilities** →
+   **+ Capability** → **Background Modes** → check
+   *Audio, AirPlay, and Picture in Picture*.
+
+   _or_
+
+2. Add to your app's `Info.plist`:
+
+   ```xml
+   <key>UIBackgroundModes</key>
+   <array>
+     <string>audio</string>
+   </array>
+   ```
+
+The library configures `AVAudioSession` to `.playback` and activates it for
+you. Note that this will play through the silent-mode switch and interrupt
+other apps' audio (Spotify, etc.) by default. If your app already manages
+its own audio session, set the category yourself before mounting the
+component and the library won't override it.
+
+#### Android — optional
+
+`MediaPlayer` keeps playing through `Activity.onPause` already, so for
+typical voice-message use cases **nothing extra is required**.
+
+If you need playback to survive **device sleep** (screen off + idle, CPU
+suspended), add `WAKE_LOCK` to your **app's** `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+```
+
+The library will then automatically call `MediaPlayer.setWakeMode` when
+`playInBackground` is `true`. Without the permission `setWakeMode` is
+silently skipped (a warning is logged) — playback still works while the
+screen is on, it just pauses with the device.
+
+#### Suspending UI work while backgrounded
+
+The 30 Hz progress polling that drives the bars + time label keeps running
+even after the OS has stopped compositing the view, so a tiny amount of
+CPU is wasted on math + string formatting per tick.
+
+`pauseUiUpdatesInBackground` (default `true`) gates that work:
+
+- `true` — when backgrounded, skip the bars / time-label refreshes. The view
+  is offscreen so there's nothing visible to lose. The library snaps the UI
+  to the engine's current state on resume.
+- `false` — keep refreshing in background (rare; only useful if something
+  in your view hierarchy is observing those UI changes from background).
+
+`onTimeUpdate` keeps firing in either case, so Now Playing / Lock Screen /
+analytics integrations work the same way.
+
+## Props
+
+| Prop                       | Type                                | Default                   | Description |
+| -------------------------- | ----------------------------------- | ------------------------- | ----------- |
+| `source` (required)        | `{ uri: string }`                   | —                         | Audio source. Supports `file://`, `https://`, `content://`. |
+| `samples`                  | `number[]`                          | `undefined`               | Pre-computed amplitudes in `[0, 1]`. When set, native decode is skipped. |
+| `playedBarColor`           | `ColorValue`                        | `#FFFFFF`                 | Color of the highlighted ("played") portion of each bar. |
+| `unplayedBarColor`         | `ColorValue`                        | `rgba(255,255,255,0.5)`   | Color of the not-yet-played portion. |
+| `barWidth`                 | `number`                            | `3`                       | Bar thickness in dp. |
+| `barGap`                   | `number`                            | `2`                       | Gap between bars in dp. |
+| `barRadius`                | `number`                            | `barWidth / 2`            | Bar corner radius in dp. |
+| `barCount`                 | `number`                            | auto from view width      | Force a specific number of bars. |
+| `containerBackgroundColor` | `ColorValue`                        | `#3478F6`                 | Rounded container background. |
+| `containerBorderRadius`    | `number`                            | `16`                      | Rounded container corner radius. |
+| `showBackground`           | `boolean`                           | `true`                    | Whether to draw the rounded container background. |
+| `showPlayButton`           | `boolean`                           | `true`                    | |
+| `playButtonColor`          | `ColorValue`                        | `#FFFFFF`                 | Play / pause icon tint (uses SF Symbols on iOS, vector drawables on Android). |
+| `showTime`                 | `boolean`                           | `true`                    | |
+| `timeColor`                | `ColorValue`                        | `#FFFFFF`                 | |
+| `timeMode`                 | `'count-up' \| 'count-down'`        | `'count-up'`              | |
+| `showSpeedControl`         | `boolean`                           | `true`                    | |
+| `speedColor`               | `ColorValue`                        | `#FFFFFF`                 | Speed pill text color. |
+| `speedBackgroundColor`     | `ColorValue`                        | `rgba(255,255,255,0.25)`  | Speed pill background color. |
+| `speeds`                   | `number[]`                          | `[0.5, 1, 1.5, 2]`        | Tap-to-cycle speed values. |
+| `defaultSpeed`             | `number`                            | `1`                       | Initial speed on mount. |
+| `autoPlay`                 | `boolean`                           | `false`                   | Begin playback as soon as the source is ready. |
+| `initialPositionMs`        | `number`                            | `0`                       | Seek to this position (ms) on load. |
+| `loop`                     | `boolean`                           | `false`                   | Restart from `0` on end-of-track. |
+| `playInBackground`         | `boolean`                           | `false`                   | Keep playing when the host app backgrounds. iOS requires the Audio Background Mode; Android optionally honours `WAKE_LOCK`. See [Background playback](#background-playback). |
+| `pauseUiUpdatesInBackground` | `boolean`                         | `true`                    | While backgrounded, suspend the bars / time-label refreshes that piggy-back on every progress tick. The OS already skips painting; this saves the cheap math/string work. `onTimeUpdate` is unaffected. |
+| `playing`                  | `boolean \| undefined`              | `undefined`               | Controlled playing state. When defined, internal play/pause taps are inert. |
+| `speed`                    | `number \| undefined`               | `undefined`               | Controlled speed. When defined, internal speed-pill taps are inert. |
+
+### Events
+
+| Event                  | Payload                                              |
+| ---------------------- | ---------------------------------------------------- |
+| `onLoad`               | `{ durationMs: number }`                             |
+| `onLoadError`          | `{ message: string }`                                |
+| `onPlayerStateChange`  | `{ state, isPlaying, speed, error? }` (full snapshot on every transition: load lifecycle, play/pause, speed change) |
+| `onTimeUpdate`         | `{ currentTimeMs, durationMs }` (≈30 Hz while playing) |
+| `onSeek`               | `{ positionMs }` (end of scrub gesture or `seekTo`)  |
+| `onEnd`                | `{}`                                                 |
+
+`state` is one of `'idle' | 'loading' | 'ready' | 'ended' | 'error'`.
+
+### Imperative API
+
+```ts
+type AudioWaveformViewRef = {
+  play: () => void;
+  pause: () => void;
+  toggle: () => void;
+  seekTo: (positionMs: number) => void;
+  setSpeed: (speed: number) => void;
+};
+```
+
+## Out of scope
+
+- Recording (playback + visualisation only).
+- Live / streaming waveforms — we visualise a fixed audio file.
+- `react-native-gesture-handler` / Reanimated integration — gestures are
+  handled natively for zero JS overhead.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/build.gradle

@@ -0,0 +1,67 @@
+buildscript {
+  ext.AudioWaveform = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return AudioWaveform[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.audiowaveform"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+</manifest>