@5stones/react-native-audio-browser 0.1.0

package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt

@@ -0,0 +1,80 @@
+package com.audiobrowser.model
+
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Metadata
+import androidx.media3.extractor.metadata.icy.IcyInfo
+import com.margelo.nitro.audiobrowser.TimedMetadata
+
+data class PlaybackMetadata(
+  var title: String? = null,
+  var artist: String? = null,
+  var album: String? = null,
+  var date: String? = null,
+  var genre: String? = null,
+) {
+  companion object {
+    /**
+     * Creates PlaybackMetadata from raw Metadata entries.
+     * Handles ICY streams specially, uses Media3's unified approach for everything else.
+     */
+    fun from(metadata: Metadata): PlaybackMetadata? {
+      // Try ICY first (streaming-specific)
+      fromIcy(metadata)?.let { return it }
+
+      // Use Media3's unified approach for ID3, Vorbis, QuickTime, etc.
+      val builder = MediaMetadata.Builder()
+      for (i in 0 until metadata.length()) {
+        metadata[i].populateMediaMetadata(builder)
+      }
+      return fromMediaMetadata(builder.build())
+    }
+
+    /** Shoutcast / Icecast metadata (ICY protocol) https://cast.readme.io/docs/icy */
+    private fun fromIcy(metadata: Metadata): PlaybackMetadata? {
+      for (i in 0 until metadata.length()) {
+        when (val entry = metadata[i]) {
+          is IcyInfo -> {
+            if (entry.title != null) {
+              return PlaybackMetadata(title = entry.title)
+            }
+          }
+        }
+      }
+      return null
+    }
+
+    /** Converts Media3's unified MediaMetadata to PlaybackMetadata. */
+    private fun fromMediaMetadata(mediaMetadata: MediaMetadata): PlaybackMetadata? {
+      val title = mediaMetadata.title?.toString()
+      val artist = mediaMetadata.artist?.toString()
+      val album = mediaMetadata.albumTitle?.toString()
+      val genre = mediaMetadata.genre?.toString()
+
+      // Use recordingYear first (more specific), fall back to releaseYear
+      val date = (mediaMetadata.recordingYear ?: mediaMetadata.releaseYear)?.toString()
+
+      // Return null if no meaningful data
+      if (title == null && artist == null && album == null && genre == null && date == null) {
+        return null
+      }
+
+      return PlaybackMetadata(
+        title = title,
+        artist = artist,
+        album = album,
+        date = date,
+        genre = genre,
+      )
+    }
+  }
+
+  fun toNitro(): TimedMetadata {
+    return TimedMetadata(
+      title = title,
+      artist = artist,
+      album = album,
+      date = date,
+      genre = genre,
+    )
+  }
+}

package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt

@@ -0,0 +1,101 @@
+package com.audiobrowser.model
+
+import androidx.media3.exoplayer.DefaultLoadControl
+import com.margelo.nitro.audiobrowser.AndroidAudioContentType
+import com.margelo.nitro.audiobrowser.AndroidPlayerWakeMode
+import com.margelo.nitro.audiobrowser.PartialSetupPlayerOptions
+import com.margelo.nitro.audiobrowser.Variant_Boolean_AndroidAudioOffloadSettings
+import com.margelo.nitro.audiobrowser.Variant_Boolean_RetryConfig
+
+/**
+ * Audio offload preferences for power-efficient playback. When this object exists, offload is
+ * considered enabled.
+ */
+data class AudioOffloadOptions(
+  val gaplessSupportRequired: Boolean = true,
+  val rateChangeSupportRequired: Boolean = true,
+)
+
+/** Retry policy for load errors (network failures, timeouts, etc.) */
+sealed class RetryPolicy {
+  /** Use ExoPlayer's default behavior (limited retries, surfaces errors) */
+  data object Default : RetryPolicy()
+
+  /** Retry indefinitely with exponential backoff */
+  data class Infinite(val maxRetryDurationMs: Long? = null) : RetryPolicy()
+
+  /** Retry up to maxRetries times with exponential backoff */
+  data class Limited(val maxRetries: Int, val maxRetryDurationMs: Long? = null) : RetryPolicy()
+}
+
+/**
+ * Setup options for the AudioBrowser that are applied once during player initialization. These
+ * options configure the audio engine and system-level behavior.
+ */
+data class PlayerSetupOptions(
+  // Android-specific options (all under android.* in JS)
+  var minBuffer: Double = DefaultLoadControl.DEFAULT_MIN_BUFFER_MS.toDouble(),
+  var audioContentType: AndroidAudioContentType = AndroidAudioContentType.MUSIC,
+  var maxBuffer: Double = DefaultLoadControl.DEFAULT_MAX_BUFFER_MS.toDouble(),
+  var playBuffer: Double = DefaultLoadControl.DEFAULT_BUFFER_FOR_PLAYBACK_MS.toDouble(),
+  var rebufferBuffer: Double? = null,
+  var backBuffer: Double = DefaultLoadControl.DEFAULT_BACK_BUFFER_DURATION_MS.toDouble(),
+  var maxCacheSize: Double = 0.0,
+  var handleAudioBecomingNoisy: Boolean = true,
+  var wakeMode: AndroidPlayerWakeMode = AndroidPlayerWakeMode.NONE,
+  var audioOffload: AudioOffloadOptions? = null,
+  var retryPolicy: RetryPolicy = RetryPolicy.Default,
+) {
+  /**
+   * Whether automatic buffer management is enabled. True when rebufferBuffer is not explicitly set
+   * (null).
+   */
+  val automaticBuffer: Boolean
+    get() = rebufferBuffer == null
+
+  fun update(options: PartialSetupPlayerOptions) {
+    // Android-specific options
+    options.android?.let { android ->
+      android.minBuffer?.let { minBuffer = it }
+      android.maxBuffer?.let { maxBuffer = it }
+      android.playBuffer?.let { playBuffer = it }
+      android.rebufferBuffer?.let { rebufferBuffer = it.asSecondOrNull() }
+      android.backBuffer?.let { backBuffer = it }
+      android.maxCacheSize?.let { maxCacheSize = it }
+      android.handleAudioBecomingNoisy?.let { handleAudioBecomingNoisy = it }
+      android.audioContentType?.let { audioContentType = it }
+      android.wakeMode?.let { wakeMode = it }
+      android.audioOffload?.let {
+        audioOffload =
+          when (android.audioOffload) {
+            is Variant_Boolean_AndroidAudioOffloadSettings.First -> {
+              if (android.audioOffload.value) AudioOffloadOptions() else null
+            }
+            is Variant_Boolean_AndroidAudioOffloadSettings.Second -> {
+              val settings = android.audioOffload.value
+              AudioOffloadOptions(
+                gaplessSupportRequired = settings.gaplessSupportRequired ?: false,
+                rateChangeSupportRequired = settings.rateChangeSupportRequired ?: false,
+              )
+            }
+          }
+      }
+    }
+
+    // Top-level cross-platform options
+    options.retry?.let {
+      retryPolicy =
+        when (it) {
+          is Variant_Boolean_RetryConfig.First -> {
+            if (it.value) RetryPolicy.Infinite() else RetryPolicy.Default
+          }
+          is Variant_Boolean_RetryConfig.Second -> {
+            RetryPolicy.Limited(
+              maxRetries = it.value.maxRetries.toInt(),
+              maxRetryDurationMs = it.value.maxRetryDurationMs?.toLong(),
+            )
+          }
+        }
+    }
+  }
+}

package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt

@@ -0,0 +1,125 @@
+package com.audiobrowser.model
+
+import com.margelo.nitro.audiobrowser.AndroidUpdateOptions
+import com.margelo.nitro.audiobrowser.AppKilledPlaybackBehavior
+import com.margelo.nitro.audiobrowser.NativeUpdateOptions
+import com.margelo.nitro.audiobrowser.NotificationButtonLayout
+import com.margelo.nitro.audiobrowser.PlayerCapabilities
+import com.margelo.nitro.audiobrowser.RatingType as NitroRatingType
+import com.margelo.nitro.audiobrowser.UpdateOptions
+import com.margelo.nitro.audiobrowser.Variant_NullType_Double
+import com.margelo.nitro.audiobrowser.Variant_NullType_NotificationButtonLayout
+
+/**
+ * Update options for the AudioBrowser that can be changed at runtime. These options control player
+ * behavior and capabilities that can be modified during playback.
+ */
+data class PlayerUpdateOptions(
+  // Jump intervals
+  var forwardJumpInterval: Double = 15.0,
+  var backwardJumpInterval: Double = 15.0,
+  var progressUpdateEventInterval: Double? = null,
+
+  // Player capabilities - most enabled by default, only false values disable
+  // Exceptions: bookmark, jumpForward, jumpBackward default to false
+  var capabilities: PlayerCapabilities = PlayerCapabilities(
+    play = null, pause = null, stop = null, seekTo = null,
+    skipToNext = null, skipToPrevious = null,
+    jumpForward = false, jumpBackward = false,
+    favorite = null,
+    shuffleMode = null, repeatMode = null, playbackRate = null
+  ),
+
+  // Notification button layout (null = derive from capabilities)
+  var notificationButtons: NotificationButtonLayout? = null,
+
+  // Android-specific runtime options (all under android.* in JS)
+  var ratingType: NitroRatingType? = null,
+  var appKilledPlaybackBehavior: AppKilledPlaybackBehavior =
+    AppKilledPlaybackBehavior.STOP_PLAYBACK_AND_REMOVE_NOTIFICATION,
+  var skipSilence: Boolean = false,
+  var shuffle: Boolean = false,
+) {
+  fun updateFromBridge(options: NativeUpdateOptions) {
+    options.forwardJumpInterval?.let { forwardJumpInterval = it }
+    options.backwardJumpInterval?.let { backwardJumpInterval = it }
+
+    options.progressUpdateEventInterval?.let { variant ->
+      progressUpdateEventInterval =
+        when (variant) {
+          is Variant_NullType_Double.First -> null
+          is Variant_NullType_Double.Second -> variant.value
+        }
+    }
+
+    options.capabilities?.let { newCaps ->
+      capabilities = mergeCapabilities(capabilities, newCaps)
+    }
+
+    // Update Android-specific options
+    options.android?.let { androidOptions ->
+      // Convert rating type
+      androidOptions.ratingType?.let { ratingType = it }
+
+      androidOptions.appKilledPlaybackBehavior?.let { appKilledPlaybackBehavior = it }
+
+      // Update boolean options
+      androidOptions.skipSilence?.let { skipSilence = it }
+
+      androidOptions.shuffle?.let { shuffle = it }
+
+      // Handle notificationButtons - variant allows distinguishing undefined from null
+      androidOptions.notificationButtons?.let { variant ->
+        notificationButtons =
+          when (variant) {
+            is Variant_NullType_NotificationButtonLayout.First -> null
+            is Variant_NullType_NotificationButtonLayout.Second -> variant.value
+          }
+      }
+    }
+  }
+
+  fun toNitro(): UpdateOptions {
+    // Create Android options
+    val androidOptions =
+      AndroidUpdateOptions(
+        appKilledPlaybackBehavior = appKilledPlaybackBehavior,
+        skipSilence = skipSilence,
+        shuffle = shuffle,
+        ratingType = ratingType,
+        notificationButtons =
+          notificationButtons?.let { Variant_NullType_NotificationButtonLayout.create(it) },
+      )
+
+    return UpdateOptions(
+      android = androidOptions,
+      forwardJumpInterval = forwardJumpInterval,
+      backwardJumpInterval = backwardJumpInterval,
+      progressUpdateEventInterval =
+        progressUpdateEventInterval?.let { Variant_NullType_Double.create(it) },
+      capabilities = capabilities,
+      iosPlaybackRates = null, // iOS-only option
+    )
+  }
+
+  /** Merge incoming capabilities with existing - only explicitly set values override */
+  private fun mergeCapabilities(
+    existing: PlayerCapabilities,
+    incoming: PlayerCapabilities
+  ): PlayerCapabilities {
+    return PlayerCapabilities(
+      play = incoming.play ?: existing.play,
+      pause = incoming.pause ?: existing.pause,
+      stop = incoming.stop ?: existing.stop,
+      seekTo = incoming.seekTo ?: existing.seekTo,
+      skipToNext = incoming.skipToNext ?: existing.skipToNext,
+      skipToPrevious = incoming.skipToPrevious ?: existing.skipToPrevious,
+      jumpForward = incoming.jumpForward ?: existing.jumpForward,
+      jumpBackward = incoming.jumpBackward ?: existing.jumpBackward,
+      favorite = incoming.favorite ?: existing.favorite,
+      shuffleMode = incoming.shuffleMode ?: existing.shuffleMode,
+      repeatMode = incoming.repeatMode ?: existing.repeatMode,
+      playbackRate = incoming.playbackRate ?: existing.playbackRate
+    )
+  }
+}

package/android/src/main/java/com/audiobrowser/player/AutomaticBufferManager.kt

@@ -0,0 +1,256 @@
+package com.audiobrowser.player
+
+import androidx.media3.common.Player
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.exoplayer.analytics.AnalyticsListener
+import timber.log.Timber
+
+/**
+ * Manages automatic buffer sizing based on network conditions and rebuffer events.
+ *
+ * This manager monitors playback state to automatically adjust buffer thresholds when rebuffering
+ * occurs. The goal is to maintain smooth playback by increasing buffer sizes based on measured
+ * drain rate.
+ *
+ * Algorithm:
+ * 1. Track when playback becomes ready (buffer filled)
+ * 2. Track how long until rebuffer occurs
+ * 3. Calculate drain rate: initialBuffer / timeUntilRebuffer
+ * 4. Calculate needed buffer to sustain 60s: drainRate × 60
+ * 5. Reset to defaults when loading new media (station change)
+ *
+ * Target: Sustain 60 seconds of playback without rebuffering.
+ */
+class AutomaticBufferManager(
+  private val loadControl: DynamicLoadControl,
+  private val defaultConfig: BufferConfig = BufferConfig(),
+) : AnalyticsListener, Player.Listener {
+
+  private var exoPlayer: ExoPlayer? = null
+
+  // State tracking for rebuffer detection
+  private var wasReady = false
+  private var rebufferCount = 0
+
+  // Timing tracking for drain rate calculation
+  private var playbackStartTimeMs: Long = 0
+  private var bufferAtPlaybackStartMs: Long = 0
+  private var bufferingStartTimeMs: Long = 0
+
+  // Limits - keep these reasonable for good UX
+  private val maxRebufferBufferMs = 8_000 // 8 seconds max after rebuffer
+  private val targetPlaybackDurationMs = 60_000L // Target: sustain 60s of playback
+
+  /** Attaches this manager to an ExoPlayer instance. Call this after creating the player. */
+  fun attach(player: ExoPlayer) {
+    exoPlayer = player
+    player.addAnalyticsListener(this)
+    player.addListener(this)
+    Timber.d("AutomaticBufferManager attached to player")
+  }
+
+  /** Detaches this manager from the player. Call this before releasing the player. */
+  fun detach() {
+    stopBufferMonitoring()
+    bufferMonitorHandler = null
+    exoPlayer?.removeAnalyticsListener(this)
+    exoPlayer?.removeListener(this)
+    exoPlayer = null
+    Timber.d("AutomaticBufferManager detached from player")
+  }
+
+  /**
+   * Resets buffer configuration to defaults and clears tracking state. Call this when loading new
+   * media (station change).
+   */
+  fun reset() {
+    loadControl.resetToDefaults()
+    wasReady = false
+    rebufferCount = 0
+    playbackStartTimeMs = 0
+    bufferAtPlaybackStartMs = 0
+    Timber.d("AutomaticBufferManager reset to defaults")
+  }
+
+  // region Player.Listener
+
+  // For periodic buffer logging during playback
+  private var lastBufferLogTimeMs: Long = 0
+  private val bufferLogIntervalMs = 2_000L // Log every 2 seconds
+
+  override fun onPlaybackStateChanged(playbackState: Int) {
+    when (playbackState) {
+      Player.STATE_BUFFERING -> {
+        if (wasReady) {
+          // This is a rebuffer - buffer ran out during playback
+          onRebuffer()
+        }
+        // Track when buffering started
+        if (bufferingStartTimeMs == 0L) {
+          bufferingStartTimeMs = System.currentTimeMillis()
+          Timber.d("STATE_BUFFERING entered - starting buffer timer")
+        }
+      }
+      Player.STATE_READY -> {
+        if (!wasReady) {
+          // Playback just became ready - record timing for drain rate calculation
+          playbackStartTimeMs = System.currentTimeMillis()
+          bufferAtPlaybackStartMs = exoPlayer?.totalBufferedDuration ?: 0
+          lastBufferLogTimeMs = playbackStartTimeMs
+
+          val bufferingDurationMs =
+            if (bufferingStartTimeMs > 0) {
+              playbackStartTimeMs - bufferingStartTimeMs
+            } else 0
+
+          Timber.d(
+            "Playback ready with %dms buffer (buffered for %dms)",
+            bufferAtPlaybackStartMs,
+            bufferingDurationMs,
+          )
+          bufferingStartTimeMs = 0
+        }
+        wasReady = true
+      }
+      Player.STATE_IDLE,
+      Player.STATE_ENDED -> {
+        wasReady = false
+        playbackStartTimeMs = 0
+        bufferingStartTimeMs = 0
+      }
+    }
+  }
+
+  // Called frequently during playback - use for buffer monitoring
+  override fun onIsPlayingChanged(
+    eventTime: androidx.media3.exoplayer.analytics.AnalyticsListener.EventTime,
+    isPlaying: Boolean,
+  ) {
+    if (isPlaying) {
+      startBufferMonitoring()
+    } else {
+      stopBufferMonitoring()
+    }
+  }
+
+  private var bufferMonitorHandler: android.os.Handler? = null
+  private val bufferMonitorRunnable =
+    object : Runnable {
+      override fun run() {
+        if (wasReady && exoPlayer?.isPlaying == true) {
+          val bufferedMs = exoPlayer?.totalBufferedDuration ?: 0
+          val playedMs = System.currentTimeMillis() - playbackStartTimeMs
+          val config = loadControl.getBufferConfig()
+          Timber.d(
+            "Buffer status: %dms buffered, played %dms (rebuffer threshold: %dms)",
+            bufferedMs,
+            playedMs,
+            config.bufferForPlaybackAfterRebufferMs,
+          )
+          bufferMonitorHandler?.postDelayed(this, bufferLogIntervalMs)
+        }
+      }
+    }
+
+  private fun startBufferMonitoring() {
+    if (bufferMonitorHandler == null) {
+      bufferMonitorHandler = android.os.Handler(android.os.Looper.getMainLooper())
+    }
+    bufferMonitorHandler?.removeCallbacks(bufferMonitorRunnable)
+    bufferMonitorHandler?.postDelayed(bufferMonitorRunnable, bufferLogIntervalMs)
+  }
+
+  private fun stopBufferMonitoring() {
+    bufferMonitorHandler?.removeCallbacks(bufferMonitorRunnable)
+  }
+
+  override fun onMediaItemTransition(mediaItem: androidx.media3.common.MediaItem?, reason: Int) {
+    // Reset on station change (new media loaded)
+    if (
+      reason == Player.MEDIA_ITEM_TRANSITION_REASON_PLAYLIST_CHANGED ||
+        reason == Player.MEDIA_ITEM_TRANSITION_REASON_SEEK
+    ) {
+      Timber.d("Media item changed, resetting buffer config")
+      reset()
+    }
+  }
+
+  // endregion
+
+  // region Buffer adjustment logic
+
+  private fun onRebuffer() {
+    rebufferCount++
+    val now = System.currentTimeMillis()
+    val playbackDurationMs = if (playbackStartTimeMs > 0) now - playbackStartTimeMs else 0
+
+    Timber.d(
+      "Rebuffer detected (count: $rebufferCount, played for %dms with %dms initial buffer)",
+      playbackDurationMs,
+      bufferAtPlaybackStartMs,
+    )
+
+    // Only adjust if we have valid timing data
+    if (playbackDurationMs > 0 && bufferAtPlaybackStartMs > 0) {
+      val newRebufferBuffer =
+        calculateOptimalRebufferBuffer(playbackDurationMs, bufferAtPlaybackStartMs)
+      val currentConfig = loadControl.getBufferConfig()
+      if (newRebufferBuffer != currentConfig.bufferForPlaybackAfterRebufferMs) {
+        Timber.d(
+          "Adjusting rebuffer threshold: %dms -> %dms",
+          currentConfig.bufferForPlaybackAfterRebufferMs,
+          newRebufferBuffer,
+        )
+        loadControl.updateBufferConfig(
+          currentConfig.copy(bufferForPlaybackAfterRebufferMs = newRebufferBuffer)
+        )
+      }
+    } else {
+      Timber.d("Skipping adjustment - insufficient timing data")
+    }
+
+    // Reset timing and mark not ready (wait for STATE_READY before counting next rebuffer)
+    wasReady = false
+    playbackStartTimeMs = 0
+    bufferAtPlaybackStartMs = 0
+  }
+
+  /**
+   * Calculates optimal rebuffer threshold based on drain rate.
+   *
+   * Drain rate = initialBuffer / timeUntilRebuffer Needed buffer = drainRate × targetDuration (60s)
+   *
+   * Example: 1000ms buffer lasted 30s → drain rate = 33ms/s → need 2000ms for 60s
+   */
+  private fun calculateOptimalRebufferBuffer(playbackDurationMs: Long, initialBufferMs: Long): Int {
+    val currentConfig = loadControl.getBufferConfig()
+
+    // If we don't have good timing data, fall back to 1.5x increase
+    if (playbackDurationMs <= 0 || initialBufferMs <= 0) {
+      Timber.d("Insufficient timing data, using 1.5x fallback")
+      return (currentConfig.bufferForPlaybackAfterRebufferMs * 1.5)
+        .toInt()
+        .coerceIn(defaultConfig.bufferForPlaybackAfterRebufferMs, maxRebufferBufferMs)
+    }
+
+    // Calculate drain rate: how much buffer we lose per second of playback
+    // drainRate = initialBuffer / playbackDuration (ms per second)
+    val drainRateMsPerSec = (initialBufferMs.toFloat() / (playbackDurationMs / 1000f))
+
+    // Calculate buffer needed to sustain 60 seconds
+    val neededBufferMs = (drainRateMsPerSec * (targetPlaybackDurationMs / 1000)).toLong()
+
+    Timber.d(
+      "Drain rate: %.1f ms/sec, needed buffer for 60s: %dms",
+      drainRateMsPerSec,
+      neededBufferMs,
+    )
+
+    // Only increase threshold, never decrease (coerceIn ensures this)
+    return neededBufferMs
+      .toInt()
+      .coerceIn(currentConfig.bufferForPlaybackAfterRebufferMs, maxRebufferBufferMs)
+  }
+
+  // endregion
+}