@repzo/widget-react-native 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -12,6 +12,47 @@ All notable changes to `@repzo/widget-react-native`, newest first.
 
 ## Unreleased
 
+## 1.3.0 — 2026-10-27
+
+### Changed
+
+- **Voice messages play without `expo-audio`.** The SDK now brings its own
+  small player on the phone's audio player (AVPlayer on iOS, MediaPlayer on
+  Android), with no extra libraries or permissions. In apps with Expo modules
+  it links automatically on the next native build. On iOS, notes now play with
+  the ringer switch on silent and pause music while they play, like in
+  messaging apps; an app that set its own audio session category (including
+  `ambient`) keeps it. A note pauses when the visitor leaves the app, and when
+  a call, navigation prompt or another app's audio starts.
+  Where the player isn't built in (Expo Go, bare React Native without Expo
+  modules), notes still play with `expo-audio` if the app has it, or open in
+  the browser.
+- **Placeholder bubbles while a conversation loads.** Opening a conversation
+  shows the outline of a thread, gently pulsing, until its messages arrive,
+  instead of a "Loading..." line. It holds still when the device has Reduce
+  Motion on.
+- **Zoom into images.** In the full-screen image viewer, visitors can pinch
+  to zoom, drag a zoomed image around, and double-tap to zoom in on a spot
+  (and again to zoom out). This now works on Android too; before, only iOS
+  had pinch-to-zoom. No new dependency.
+
+### Fixed
+
+- **Back from a conversation returns to where the visitor opened it.** A
+  conversation opened from the home screen (a recent conversation or "send us
+  a message") now goes back to home instead of the conversation list. One
+  opened from the list still goes back to the list, and one opened with the
+  messenger closed (a push or a notification card) goes to the list as before.
+
+### Upgrading
+
+- **A native build picks up the voice player.** Nothing else to do: build the
+  app again (development or store build) after upgrading. `expo-audio` can be
+  removed if nothing else in your app uses it. Until the new build, an
+  over-the-air update with this version keeps using `expo-audio` or the file
+  row. If your `runtimeVersion` uses the `fingerprint` policy, it changes with
+  this update.
+
 ## 1.2.2 — 2026-10-26
 
 ### Added

package/README.md

@@ -7,9 +7,10 @@
 ![Expo Go](https://img.shields.io/badge/Expo%20Go-supported-000020.svg)
 
 The Repzo chat widget for React Native — an Intercom-style messenger that drops
-into any app. Pure JavaScript/TypeScript: **no native modules of its own, no
-config plugin, no `pod install`**. Works on iOS and Android, Expo and bare
-React Native, old and new architecture.
+into any app. Pure JavaScript/TypeScript, apart from one small optional
+native piece (the voice message player, linked automatically in Expo apps): **no
+config plugin and nothing extra to set up**. Works on iOS and Android, Expo and
+bare React Native, old and new architecture.
 
 It connects to the same channel as your Repzo website chat (Workstation →
 Settings → Inbox Channels → Website Chat), so a message sent from the app lands
@@ -24,8 +25,9 @@ in your Repzo Inbox and agent replies arrive live.
 - Sent/Seen receipts, teammate avatars and presence, deleted-message placeholders
 - Catches up after a dropped connection or a trip to the background — no missed or duplicated replies
 - Agent UI blocks: product cards, slot pickers, lead forms, quotes, receipts
+- **Image viewer** with pinch and double-tap zoom for photos in the conversation
 - **Photo and file attachments** (optional — with `expo-image-picker` / `expo-document-picker`, or your own picker)
-- **Voice messages play in the chat** (optional — with `expo-audio`)
+- **Voice messages play in the chat**, with the phone's own audio player — nothing to install in Expo apps
 - **In-app notification cards** for new replies while the messenger is closed
 - **Posts** from Workstation over the app, with replies or emoji reactions
 - **Push notifications via FCM** (optional — needs `@react-native-firebase/messaging` in the host app), including Mobile Push campaigns from Workstation with images
@@ -46,7 +48,7 @@ in your Repzo Inbox and agent replies arrive live.
 | `expo-document-picker` | optional — "File" attachments |
 | `expo-file-system` | optional — reads picked files as base64 (falls back to `fetch` without it) |
 | `expo-image-manipulator` | optional — shrinks photos so camera shots fit the 1.5 MB attachment limit |
-| `expo-audio` | optional (*1.2.2+*) — plays voice messages and audio files inside the chat (Expo SDK 53+) |
+| `expo-audio` | optional (*1.2.2+*) — no longer needed from *1.3.0+* in apps with Expo modules (see "Voice messages"); still used where the SDK's own player isn't built in |
 | `expo-crypto` | optional (*1.1.0+*) — secure random source for the anonymous device id when the runtime has no `crypto` global (see below) |
 
 Realtime uses React Native’s built-in streaming XMLHttpRequest; there are no bundled runtime dependencies.
@@ -380,30 +382,33 @@ the app regardless of the channel setting, pass `attachments: { enabled: false }
 
 *1.2.2+.* Voice messages from your team, and any other audio file in the
 conversation, play right in the chat — a play button, a waveform to tap or
-drag through, and 1×/1.5×/2× speed — once your app has `expo-audio`:
-
-```sh
-npx expo install expo-audio
-```
-
-It's a native module, so rebuild the app (a new development build or store
-build; an over-the-air update alone isn't enough). Without it, audio shows as a
-file the visitor taps to open in the browser, as before. A note only downloads
-once the visitor taps play, starting one pauses any other, and a note that
-can't be played falls back to that file.
-
-The widget leaves your app's audio session alone, so notes follow your
-expo-audio settings. On iOS that means they're muted while the ringer switch is
-on silent, unless your app turns that on:
-
-```ts
-import { setAudioModeAsync } from 'expo-audio';
-
-await setAudioModeAsync({ playsInSilentMode: true });
-```
-
-On iOS, `setAudioModeAsync` resets any field you leave out to its default, so
-pass the rest of your app's audio mode along with it.
+drag through, and 1×/1.5×/2× speed.
+
+*1.3.0+.* The SDK brings its own small player, built on the phone's audio
+player (AVPlayer on iOS, MediaPlayer on Android), so there's nothing to
+install. In an app with Expo modules (any Expo app, or bare React Native with
+`expo` installed) it's linked automatically the next time you build the app (a
+new development build or store build; an over-the-air update alone isn't
+enough). It adds no permissions and no other libraries.
+
+Where the SDK's player isn't built in — Expo Go, bare React Native without
+Expo modules, or an app binary built with 1.2.2 or older — notes play with
+`expo-audio` if your app has it, and otherwise show as a file the visitor taps
+to open in the browser, as before. A note only downloads once the visitor taps
+play, starting one pauses any other, and a note that can't be played falls
+back to that file.
+
+With the SDK's player, notes play like in messaging apps: on iOS they play
+with the ringer switch on silent, and they pause music while they play and
+let it carry on after. A note pauses when the visitor leaves the app, and when
+a phone call, a navigation prompt or another app's audio starts. If your app
+has set its own iOS audio session category (including `ambient`), the player
+keeps it.
+
+With `expo-audio` instead, the widget leaves your app's audio session alone, so
+notes follow your expo-audio settings. On iOS that means they're muted while the
+ringer switch is on silent, unless your app calls
+`setAudioModeAsync({ playsInSilentMode: true })` from `expo-audio`.
 
 ## Errors
 
@@ -730,6 +735,7 @@ action from you:
 | 1.0.0 | In-app notification cards are now on by default (`inAppNotifications: false` turns them off). The attach button appears if `expo-image-picker` or `expo-document-picker` is installed (`attachments: { enabled: false }` hides it). The `withRepzoWidget` Metro wrapper is optional now. |
 | 1.0.9 or older | Nothing required. Development builds now warn once if the visitor token isn't in secure storage, or if the device has no secure random source — see "Secure token storage" and "Requirements". |
 | 1.1.0 or older | Posts from Workstation now show over the app by default, once one is set live for Mobile (`posts: false` turns them off). They need `<RepzoWidgetProvider>` mounted at the root. |
+| 1.2.2 or older | Nothing required. In apps with Expo modules, the SDK now includes a small native voice player, so build the app again (development or store build) to get it; `expo-audio` can be removed if nothing else in your app uses it. If your `runtimeVersion` uses the `fingerprint` policy, it changes with this update. |
 
 ## Troubleshooting
 

package/android/build.gradle

@@ -0,0 +1,22 @@
+apply plugin: 'com.android.library'
+
+group = 'expo.modules.repzowidget'
+version = '1.0.0'
+
+// The way Expo modules were built before Expo SDK 52, which newer SDKs still
+// support. The `expo-module-gradle-plugin` form would only build on SDK 52+.
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useDefaultAndroidSdkVersions()
+
+android {
+  namespace "expo.modules.repzowidget"
+  defaultConfig {
+    versionCode 1
+    versionName "1.0.0"
+  }
+}
+
+// No other dependencies: voice notes play through Android's own MediaPlayer.

package/android/src/main/java/expo/modules/repzowidget/RepzoVoicePlayer.kt

@@ -0,0 +1,222 @@
+package expo.modules.repzowidget
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.media.MediaPlayer
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+
+/**
+ * One voice note on Android's own MediaPlayer. Created, driven and released
+ * on the main thread, so MediaPlayer's callbacks arrive there too.
+ */
+internal class RepzoVoicePlayer(
+  context: Context,
+  url: String,
+  private val onStatus: (Map<String, Any?>) -> Unit
+) {
+  private val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+  private val handler = Handler(Looper.getMainLooper())
+  private val player = MediaPlayer()
+  private val attributes = AudioAttributes.Builder()
+    .setUsage(AudioAttributes.USAGE_MEDIA)
+    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+    .build()
+
+  private var prepared = false
+  private var released = false
+  // The visitor asked for playback; it starts once the note has loaded.
+  private var wantsPlay = false
+  private var buffering = false
+  private var error: String? = null
+  private var rate = 1f
+  private var pendingSeek: (() -> Unit)? = null
+  private var focusRequest: AudioFocusRequest? = null
+
+  // A call or another app taking the audio pauses the note, as messaging apps do.
+  // That includes a request to duck (navigation prompts): Android doesn't duck
+  // speech for us, and two voices at once can't be followed.
+  private val focusListener = AudioManager.OnAudioFocusChangeListener { change ->
+    when (change) {
+      AudioManager.AUDIOFOCUS_LOSS,
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT,
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> pause()
+    }
+  }
+
+  // Moves the playhead while the note plays.
+  private val tick = object : Runnable {
+    override fun run() {
+      if (released) return
+      emit()
+      if (isPlaying()) handler.postDelayed(this, TICK_MS)
+    }
+  }
+
+  init {
+    player.setAudioAttributes(attributes)
+    player.setOnPreparedListener {
+      prepared = true
+      if (wantsPlay) startPlayback() else emit()
+    }
+    player.setOnCompletionListener {
+      wantsPlay = false
+      handler.removeCallbacks(tick)
+      abandonFocus()
+      emit(didJustFinish = true)
+    }
+    player.setOnErrorListener { _, what, extra ->
+      error = "Can't play this audio ($what/$extra)"
+      prepared = false
+      wantsPlay = false
+      handler.removeCallbacks(tick)
+      abandonFocus()
+      emit()
+      true
+    }
+    player.setOnInfoListener { _, what, _ ->
+      when (what) {
+        MediaPlayer.MEDIA_INFO_BUFFERING_START -> { buffering = true; emit() }
+        MediaPlayer.MEDIA_INFO_BUFFERING_END -> { buffering = false; emit() }
+      }
+      false
+    }
+    player.setOnSeekCompleteListener {
+      val done = pendingSeek
+      pendingSeek = null
+      emit()
+      done?.invoke()
+    }
+    try {
+      player.setDataSource(url)
+      player.prepareAsync()
+    } catch (e: Exception) {
+      error = e.message ?: "Can't play this audio"
+      handler.post { emit() }
+    }
+  }
+
+  fun play() {
+    if (released) return
+    wantsPlay = true
+    if (prepared) startPlayback() else emit()
+  }
+
+  fun pause() {
+    if (released) return
+    wantsPlay = false
+    if (isPlaying()) player.pause()
+    handler.removeCallbacks(tick)
+    abandonFocus()
+    emit()
+  }
+
+  fun seekTo(seconds: Double, done: () -> Unit) {
+    if (released || !prepared) {
+      done()
+      return
+    }
+    // A seek that hasn't landed yet is overtaken by this one.
+    pendingSeek?.invoke()
+    pendingSeek = done
+    val ms = (seconds.coerceAtLeast(0.0) * 1000).toLong()
+    try {
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        player.seekTo(ms, MediaPlayer.SEEK_CLOSEST)
+      } else {
+        player.seekTo(ms.toInt())
+      }
+    } catch (e: IllegalStateException) {
+      pendingSeek = null
+      done()
+    }
+  }
+
+  fun setRate(value: Float) {
+    rate = value
+    // Setting the speed of a paused MediaPlayer starts it, so a paused note
+    // keeps the new speed for its next start instead.
+    if (isPlaying()) applyRate()
+  }
+
+  fun release() {
+    if (released) return
+    released = true
+    handler.removeCallbacks(tick)
+    abandonFocus()
+    pendingSeek?.invoke()
+    pendingSeek = null
+    player.release()
+  }
+
+  private fun startPlayback() {
+    if (released || !prepared) return
+    requestFocus()
+    try {
+      applyRate()
+      if (!player.isPlaying) player.start()
+    } catch (e: IllegalStateException) {
+      error = e.message ?: "Can't play this audio"
+    }
+    handler.removeCallbacks(tick)
+    handler.post(tick)
+  }
+
+  private fun applyRate() {
+    try {
+      player.playbackParams = player.playbackParams.setSpeed(rate)
+    } catch (e: Exception) {
+      // Speed unsupported for this note: it plays at 1×.
+    }
+  }
+
+  private fun isPlaying(): Boolean =
+    prepared && !released && try { player.isPlaying } catch (e: IllegalStateException) { false }
+
+  private fun requestFocus() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      val request = focusRequest ?: AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
+        .setAudioAttributes(attributes)
+        .setOnAudioFocusChangeListener(focusListener, handler)
+        .build()
+        .also { focusRequest = it }
+      audioManager.requestAudioFocus(request)
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.requestAudioFocus(focusListener, AudioManager.STREAM_MUSIC, AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
+    }
+  }
+
+  private fun abandonFocus() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      focusRequest?.let { audioManager.abandonAudioFocusRequest(it) }
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.abandonAudioFocus(focusListener)
+    }
+  }
+
+  private fun emit(didJustFinish: Boolean = false) {
+    if (released) return
+    val duration = if (prepared) player.duration.coerceAtLeast(0) / 1000.0 else 0.0
+    val position = if (prepared) player.currentPosition.coerceAtLeast(0) / 1000.0 else 0.0
+    onStatus(
+      mapOf(
+        "currentTime" to position,
+        "duration" to duration,
+        "playing" to isPlaying(),
+        "isLoaded" to prepared,
+        "isBuffering" to (buffering || (wantsPlay && !prepared && error == null)),
+        "didJustFinish" to didJustFinish,
+        "error" to error
+      )
+    )
+  }
+
+  private companion object {
+    const val TICK_MS = 100L
+  }
+}

package/android/src/main/java/expo/modules/repzowidget/RepzoWidgetAudioModule.kt

@@ -0,0 +1,68 @@
+package expo.modules.repzowidget
+
+import android.os.Handler
+import android.os.Looper
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.functions.Queues
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * Plays the chat's voice notes, so apps don't need an audio package of their
+ * own. JS addresses each note's player by an id it picks (see
+ * `src/audio/native-player.ts`); every change comes back as an `onStatus`
+ * event carrying that id.
+ */
+class RepzoWidgetAudioModule : Module() {
+  // Only touched on the main thread: every function below runs there.
+  private val players = HashMap<String, RepzoVoicePlayer>()
+
+  override fun definition() = ModuleDefinition {
+    Name("RepzoWidgetAudio")
+
+    Events("onStatus")
+
+    AsyncFunction("create") { id: String, url: String ->
+      val context = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+      players.remove(id)?.release()
+      players[id] = RepzoVoicePlayer(context, url) { status ->
+        sendEvent("onStatus", status + ("id" to id))
+      }
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("play") { id: String ->
+      players[id]?.play()
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("pause") { id: String ->
+      players[id]?.pause()
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("seekTo") { id: String, seconds: Double, promise: Promise ->
+      val player = players[id]
+      if (player == null) promise.resolve(null) else player.seekTo(seconds) { promise.resolve(null) }
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("setRate") { id: String, rate: Double ->
+      players[id]?.setRate(rate.toFloat())
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("release") { id: String ->
+      players.remove(id)?.release()
+    }.runOnQueue(Queues.MAIN)
+
+    // Leaving the app pauses every note, including one still loading, so it
+    // doesn't keep playing with its controls out of sight.
+    OnActivityEntersBackground {
+      players.values.forEach { it.pause() }
+    }
+
+    OnDestroy {
+      Handler(Looper.getMainLooper()).post {
+        players.values.forEach { it.release() }
+        players.clear()
+      }
+    }
+  }
+}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["RepzoWidgetAudioModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.repzowidget.RepzoWidgetAudioModule"]
+  }
+}

package/ios/RepzoVoicePlayer.swift

@@ -0,0 +1,175 @@
+import AVFoundation
+
+/**
+ * One voice note on the system AVPlayer. Created, driven and released on the
+ * main queue; observers hop back to it before touching anything.
+ */
+final class RepzoVoicePlayer {
+  private let player: AVPlayer
+  private let item: AVPlayerItem
+  private let onStatus: ([String: Any?]) -> Void
+  private var rate: Float = 1
+  private var released = false
+  private var timeObserver: Any?
+  private var observations: [NSKeyValueObservation] = []
+  private var notificationObservers: [NSObjectProtocol] = []
+
+  init(url: URL, onStatus: @escaping ([String: Any?]) -> Void) {
+    self.onStatus = onStatus
+    item = AVPlayerItem(url: url)
+    // Keeps voices at their normal pitch at 1.5× and 2×.
+    item.audioTimePitchAlgorithm = .timeDomain
+    player = AVPlayer(playerItem: item)
+
+    observations = [
+      item.observe(\.status) { [weak self] _, _ in self?.emitOnMain() },
+      item.observe(\.duration) { [weak self] _, _ in self?.emitOnMain() },
+      player.observe(\.timeControlStatus) { [weak self] _, _ in self?.emitOnMain() },
+    ]
+    // Moves the playhead while the note plays.
+    timeObserver = player.addPeriodicTimeObserver(
+      forInterval: CMTime(value: 1, timescale: 10),
+      queue: .main
+    ) { [weak self] _ in
+      guard let self = self, self.player.timeControlStatus == .playing else { return }
+      self.emit()
+    }
+    let center = NotificationCenter.default
+    notificationObservers = [
+      center.addObserver(forName: .AVPlayerItemDidPlayToEndTime, object: item, queue: .main) { [weak self] _ in
+        self?.finish()
+      },
+      center.addObserver(forName: .AVPlayerItemFailedToPlayToEndTime, object: item, queue: .main) { [weak self] _ in
+        self?.emit()
+      },
+      // A call or another app taking the audio pauses the note, as messaging apps do.
+      center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) { [weak self] note in
+        let type = (note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt).flatMap(AVAudioSession.InterruptionType.init)
+        if type == .began { self?.pause() }
+      },
+    ]
+  }
+
+  func play() {
+    guard !released else { return }
+    RepzoVoiceSession.shared.begin(self)
+    let duration = item.duration.seconds
+    if duration.isFinite, duration > 0, player.currentTime().seconds >= duration - 0.05 {
+      player.seek(to: .zero)
+    }
+    // Starts once enough has loaded; until then timeControlStatus reports waiting.
+    player.rate = rate
+    emit()
+  }
+
+  func pause() {
+    guard !released else { return }
+    player.pause()
+    RepzoVoiceSession.shared.end(self)
+    emit()
+  }
+
+  func seek(to seconds: Double, completion: @escaping () -> Void) {
+    guard !released else {
+      completion()
+      return
+    }
+    let time = CMTime(seconds: max(0, seconds), preferredTimescale: 600)
+    player.seek(to: time, toleranceBefore: .zero, toleranceAfter: .zero) { [weak self] _ in
+      DispatchQueue.main.async {
+        self?.emit()
+        completion()
+      }
+    }
+  }
+
+  func setRate(_ value: Float) {
+    rate = value
+    // Setting the rate of a paused AVPlayer would start it.
+    if player.timeControlStatus != .paused { player.rate = value }
+  }
+
+  func release() {
+    guard !released else { return }
+    player.pause()
+    released = true
+    if let timeObserver = timeObserver { player.removeTimeObserver(timeObserver) }
+    timeObserver = nil
+    observations.forEach { $0.invalidate() }
+    observations = []
+    notificationObservers.forEach { NotificationCenter.default.removeObserver($0) }
+    notificationObservers = []
+    player.replaceCurrentItem(with: nil)
+    RepzoVoiceSession.shared.end(self)
+  }
+
+  private func finish() {
+    guard !released else { return }
+    player.pause()
+    RepzoVoiceSession.shared.end(self)
+    emit(didJustFinish: true)
+  }
+
+  private func emitOnMain() {
+    if Thread.isMainThread {
+      emit()
+    } else {
+      DispatchQueue.main.async { [weak self] in self?.emit() }
+    }
+  }
+
+  private func emit(didJustFinish: Bool = false) {
+    guard !released else { return }
+    let duration = item.duration.seconds
+    let current = player.currentTime().seconds
+    var error: String?
+    if item.status == .failed {
+      error = item.error?.localizedDescription ?? "Can't play this audio"
+    }
+    onStatus([
+      "currentTime": current.isFinite ? max(0, current) : 0,
+      "duration": duration.isFinite ? max(0, duration) : 0,
+      "playing": player.timeControlStatus == .playing,
+      "isLoaded": item.status == .readyToPlay,
+      "isBuffering": player.timeControlStatus == .waitingToPlayAtSpecifiedRate,
+      "didJustFinish": didJustFinish,
+      "error": error,
+    ])
+  }
+}
+
+/**
+ * The app's audio session while a note plays. A note plays with the ringer
+ * switch on silent, like in messaging apps, so an app still on the default
+ * (silenced) category is moved to playback for the note and put back after.
+ * An app that chose its own category keeps it.
+ */
+final class RepzoVoiceSession {
+  static let shared = RepzoVoiceSession()
+
+  private weak var owner: RepzoVoicePlayer?
+  private var previous: (category: AVAudioSession.Category, mode: AVAudioSession.Mode, options: AVAudioSession.CategoryOptions)?
+
+  func begin(_ player: RepzoVoicePlayer) {
+    owner = player
+    let session = AVAudioSession.sharedInstance()
+    // Only .soloAmbient is the system default; .ambient is a deliberate choice
+    // to mix with music and follow the silent switch, so it's left alone.
+    if previous == nil, session.category == .soloAmbient {
+      previous = (session.category, session.mode, session.categoryOptions)
+      try? session.setCategory(.playback, mode: .spokenAudio, options: [])
+    }
+    try? session.setActive(true)
+  }
+
+  func end(_ player: RepzoVoicePlayer) {
+    guard owner === player else { return }
+    owner = nil
+    guard let previous = previous else { return }
+    self.previous = nil
+    let session = AVAudioSession.sharedInstance()
+    // Lets music the note interrupted carry on.
+    try? session.setActive(false, options: .notifyOthersOnDeactivation)
+    try? session.setCategory(previous.category, mode: previous.mode, options: previous.options)
+  }
+}

package/ios/RepzoWidgetAudio.podspec

@@ -0,0 +1,26 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'RepzoWidgetAudio'
+  s.version        = package['version']
+  s.summary        = 'Plays voice messages inside the Repzo chat widget'
+  s.description    = 'Plays voice messages inside the Repzo chat widget with the system audio player.'
+  s.license        = package['license']
+  s.author         = 'Repzo'
+  s.homepage       = 'https://www.npmjs.com/package/@repzo/widget-react-native'
+  s.platforms      = { :ios => '13.4' }
+  s.swift_version  = '5.9'
+  s.source         = { git: '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = '**/*.swift'
+end