react-native-media-notification 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Marius Butz
+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/MediaControls.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "MediaControls"
+  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/mbpictures/react-native-media-notification.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.private_header_files = "ios/**/*.h"
+
+
+  install_modules_dependencies(s)
+
+  # iOS frameworks
+  s.frameworks = 'MediaPlayer', 'AVFoundation'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES'
+  }
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,237 @@
+<h1 align="center">
+    Welcome to react-native-media-notification👋<br />
+</h1>
+<h3 align="center">
+    Your React Native library for media notifications and controls
+</h3>
+<p align="center">
+    <a href="LICENSE" target="_blank">
+      <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" />
+    </a>
+    <img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/mbpictures/react-native-media-notification/ci.yml?style=for-the-badge" />
+    <a href="https://badge.fury.io/js/react-native-media-notification">
+        <img src="https://img.shields.io/npm/v/react-native-media-notification?style=for-the-badge" alt="npm version">
+    </a>
+</p>
+
+> A react native package for media notifications and controls, using AndroidX Media3 for Android and the ControlCenter API for iOS.
+
+## Features
+
+- 🎵 Media Notifications with Play/Pause/Stop Controls
+- ⏭️ Skip Forward/Backward Support
+- 🎨 Album Artwork Support (URL-based)
+- 🔊 Audio Interruption Handling
+- 📱 iOS Control Center Integration
+- 🤖 Android Media3 Session Support
+- 🎯 TypeScript Support
+- ⚡ New Architecture (Turbo Modules) Ready
+
+## Installation
+
+```bash
+npm install react-native-media-notification
+```
+
+```bash
+yarn add react-native-media-notification
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+### Android
+
+#### Android Auto
+To enable Android Auto support, you need to add the following in the application tag of your `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.yourapp">
+    <!--...-->
+    <application>
+        <!--...-->
+        <meta-data
+            android:name="com.google.android.gms.car.application"
+            android:resource="@xml/automotive_app_desc" />
+    </application>
+</manifest>
+```
+
+And create the file `android/app/src/main/res/xml/automotive_app_desc.xml` with the following content:
+
+```xml
+<automotiveApp>
+  <uses name="media"/>
+</automotiveApp>
+```
+
+#### Customize Appearance
+
+If you want to customize the small media notification icon on Android, you can add the following to your `android/app/src/main/res/values/styles.xml`:
+
+```xml
+<resources>
+  <!--...-->
+  <drawable name="media3_notification_small_icon">@drawable/my_custom_icon</drawable>
+</resources>
+```
+
+## Verwendung
+
+### Basic Setup
+
+```typescript
+import * as MediaControls from 'react-native-media-notification';
+
+// register event listeners
+const removePlayListener = MediaControls.addEventListener('play', () => {
+  console.log('Play button pressed');
+});
+
+const removePauseListener = MediaControls.addEventListener('pause', () => {
+  console.log('Pause button pressed');
+});
+
+// Cleanup
+useEffect(() => {
+  return () => {
+    removePlayListener.remove();
+    removePauseListener.remove();
+  };
+}, []);
+```
+
+### Update Metadata or Create Media Notification
+
+```typescript
+await MediaControls.updateMetadata({
+  title: 'Song Title',
+  artist: 'Artist Name',
+  album: 'Album Name',
+  duration: 240, // in seconds
+  position: 30,  // current position in seconds
+  isPlaying: true,
+  artwork: 'https://example.com/artwork.jpg',
+  shuffle: false, // optional, default is false
+  repeat: 'one',  // optional, default is 'off', can be 'all', 'one', or 'off'
+});
+```
+
+### All available Events
+
+```typescript
+// Playback Controls
+MediaControls.addEventListener('play', () => {});
+MediaControls.addEventListener('pause', () => {});
+MediaControls.addEventListener('stop', () => {});
+MediaControls.addEventListener('shuffle', () => {});
+MediaControls.addEventListener('repeatMode', () => {});
+
+// Navigation
+MediaControls.addEventListener('skipToNext', () => {});
+MediaControls.addEventListener('skipToPrevious', () => {});
+
+// Seeking
+MediaControls.addEventListener('seekForward', () => {});
+MediaControls.addEventListener('seekBackward', () => {});
+MediaControls.addEventListener('seek', (data) => {
+  console.log('Seek to position:', data?.position);
+});
+
+// Interruptions
+MediaControls.addEventListener('duck', () => {}); // reduce volume for interruption
+MediaControls.addEventListener('unduck', () => {}); // restore volume after interruption
+```
+
+### Stop Media Notification
+
+```typescript
+await MediaControls.stopMediaNotification();
+```
+
+## API Reference
+
+### Functions
+
+#### `updateMetadata(metadata: MediaTrackMetadata): Promise<void>`
+
+Updates the media track metadata for the notification. When called for the first time, it creates the media notification.
+
+**Parameter:**
+- `metadata`: Object with media track information, including title, artist, album, duration, artwork URL, current position, and playback state.
+
+#### `stopMediaNotification(): Promise<void>`
+
+Stops media notification and removes audio focus (if enabled)
+
+#### `enableAudioInterruption(enabled: boolean): Promise<void>`
+
+Enable or disable audio interruption handling. When enabled, the media controls will respond to audio interruptions (like incoming calls) by pausing playback and resuming when the interruption ends.
+
+#### `enableBackgroundMode(enabled: boolean): Promise<void>`
+
+**iOS ONLY**. Enable or disable background mode for iOS.
+
+#### `addEventListener(event: MediaControlEvent, handler: Function): EventSubscription`
+
+Registers an event listener for a specific media control event. Returns a function to remove the listener.
+
+#### `removeAllListeners(event?: MediaControlEvent): void`
+
+Entfernt alle Event Listener für ein bestimmtes Event oder alle Events, wenn kein Event angegeben ist.
+
+### Types
+
+```typescript
+interface MediaTrackMetadata {
+  title: string;
+  artist: string;
+  album?: string;
+  duration?: number;    // in seconds
+  artwork?: string;     // URL for album artwork
+  position?: number;    // current position in seconds
+  isPlaying?: boolean;
+  shuffle?: boolean;    // optional, default is false
+  repeat?: 'off' | 'all' | 'one'; // optional, default is
+}
+
+type MediaControlEvent =
+  | 'play'
+  | 'pause'
+  | 'stop'
+  | 'skipToNext'
+  | 'skipToPrevious'
+  | 'seekForward'
+  | 'seekBackward'
+  | 'seek';
+
+type MediaControlEventData = {
+  position?: number; // for seek events
+};
+```
+
+## Platform specific notes
+
+### Android
+
+- Uses AndroidX Media3
+- Creates notification channel automatically
+
+### iOS
+
+- Uses MPNowPlayingInfoCenter and MPRemoteCommandCenter
+- Integrates in Control Center and Lock Screen
+- Supports ear bud and other external controls
+- Requires Background Audio Capability for Background Playback
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

package/android/build.gradle

@@ -0,0 +1,89 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['MediaControls_' + name]
+  }
+
+  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"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["MediaControls_" + name]).toInteger()
+}
+
+android {
+  namespace "com.mediacontrols"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+  // androidx Media3 dependencies
+  implementation "androidx.media3:media3-session:1.8.0"
+  implementation "androidx.media3:media3-common:1.8.0"
+  implementation "androidx.media3:media3-ui:1.8.0"
+  implementation "androidx.core:core-ktx:1.16.0"
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "MediaControls"
+  codegenJavaPackageName = "com.mediacontrols"
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+MediaControls_kotlinVersion=2.0.21
+MediaControls_minSdkVersion=24
+MediaControls_targetSdkVersion=34
+MediaControls_compileSdkVersion=35
+MediaControls_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,29 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Permissions for media playback and notifications -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <!-- MediaSessionService for background playback -->
+        <service
+            android:name=".MediaControlsService"
+            android:enabled="true"
+            android:exported="true"
+            android:foregroundServiceType="mediaPlayback">
+            <intent-filter>
+                <action android:name="androidx.media3.session.MediaSessionService" />
+            </intent-filter>
+            <!-- Android Auto discovery -->
+            <intent-filter>
+                <action android:name="android.media.browse.MediaBrowserService" />
+            </intent-filter>
+        </service>
+
+        <meta-data
+            android:name="com.samsung.android.support.ongoing_activity"
+            android:value="true" />
+    </application>
+
+</manifest>

package/android/src/main/java/com/mediacontrols/AudioFocusListener.kt

@@ -0,0 +1,79 @@
+package com.mediacontrols
+
+import android.content.Context
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.media.AudioManager.OnAudioFocusChangeListener
+import android.os.Build
+import android.os.Handler
+import androidx.media3.common.util.UnstableApi
+import com.facebook.react.bridge.ReactApplicationContext
+
+@UnstableApi
+class AudioFocusListener(
+    context: ReactApplicationContext,
+    private val module: MediaControlsModule,
+    private val player: MediaControlsPlayer
+) : OnAudioFocusChangeListener {
+
+    private val mAudioManager: AudioManager =
+        context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+    private var mFocusRequest: AudioFocusRequest? = null
+
+    private var mPlayOnAudioFocus = false
+    private var ducked = false
+
+    private var hasFocus = false
+
+    override fun onAudioFocusChange(focusChange: Int) {
+        if (focusChange == AudioManager.AUDIOFOCUS_LOSS) {
+            abandonAudioFocus()
+            mPlayOnAudioFocus = false
+            module.sendEvent(Controls.STOP, null)
+        } else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT) {
+            Handler(player.applicationLooper).post {
+                if (player.isPlaying) {
+                    mPlayOnAudioFocus = true
+                    module.sendEvent(Controls.PAUSE, null)
+                }
+            }
+        } else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK) {
+            module.sendEvent(Controls.DUCK, null)
+            ducked = true
+        } else if (focusChange == AudioManager.AUDIOFOCUS_GAIN) {
+            if (mPlayOnAudioFocus) {
+                module.sendEvent(Controls.PLAY, null)
+            }
+            if (ducked) {
+                module.sendEvent(Controls.UN_DUCK, null)
+            }
+            mPlayOnAudioFocus = false
+            ducked = false
+        }
+    }
+
+    fun requestAudioFocus() {
+        if (hasFocus) return
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            mFocusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+                .setOnAudioFocusChangeListener(this).build()
+
+            hasFocus = mAudioManager.requestAudioFocus(mFocusRequest!!) == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+        } else {
+            hasFocus = mAudioManager.requestAudioFocus(
+                this,
+                AudioManager.STREAM_MUSIC,
+                AudioManager.AUDIOFOCUS_GAIN
+            ) == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+        }
+    }
+
+    fun abandonAudioFocus() {
+        if (!hasFocus) return
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && mFocusRequest != null) {
+            mAudioManager.abandonAudioFocusRequest(mFocusRequest!!)
+        } else mAudioManager.abandonAudioFocus(this)
+
+        hasFocus = false
+    }
+}

package/android/src/main/java/com/mediacontrols/Controls.kt

@@ -0,0 +1,22 @@
+package com.mediacontrols
+
+enum class Controls(val code: String) {
+    PLAY("play"),
+    PAUSE("pause"),
+    STOP("stop"),
+    NEXT("skipToNext"),
+    PREVIOUS("skipToPrevious"),
+    SEEK("seek"),
+    SEEK_BACKWARD("seekBackward"),
+    SEEK_FORWARD("seekForward"),
+    DUCK("duck"),
+    UN_DUCK("unDuck"),
+    SHUFFLE("shuffle"),
+    REPEAT_MODE("repeatMode");
+
+    companion object {
+        fun fromString(value: String): Controls? {
+            return entries.find { it.code == value }
+        }
+    }
+}

package/android/src/main/java/com/mediacontrols/CustomCommandButton.kt

@@ -0,0 +1,72 @@
+package com.mediacontrols
+
+import android.os.Bundle
+import androidx.media3.session.CommandButton
+import androidx.media3.session.CommandButton.ICON_FAST_FORWARD
+import androidx.media3.session.CommandButton.ICON_REWIND
+import androidx.media3.session.CommandButton.ICON_SHUFFLE_OFF
+import androidx.media3.session.CommandButton.ICON_SHUFFLE_ON
+import androidx.media3.session.SessionCommand
+
+private const val CUSTOM_COMMAND_REWIND_ACTION_ID = "REWIND_15"
+private const val CUSTOM_COMMAND_FORWARD_ACTION_ID = "FAST_FWD_15"
+private const val CUSTOM_COMMAND_SHUFFLE_ON_ACTION_ID = "SHUFFLE_ON"
+private const val CUSTOM_COMMAND_SHUFFLE_OFF_ACTION_ID = "SHUFFLE_OFF"
+private const val CUSTOM_COMMAND_REPEAT_ONE_ACTION_ID = "REPEAT_ONE"
+private const val CUSTOM_COMMAND_REPEAT_ALL_ACTION_ID = "REPEAT_ALL"
+private const val CUSTOM_COMMAND_REPEAT_OFF_ACTION_ID = "REPEAT_OFF"
+
+enum class CustomCommandButton(
+    val customAction: String,
+    val commandButton: CommandButton,
+) {
+    REWIND(
+        customAction = CUSTOM_COMMAND_REWIND_ACTION_ID,
+        commandButton = CommandButton.Builder(ICON_REWIND)
+            .setDisplayName("Rewind")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_REWIND_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    FORWARD(
+        customAction = CUSTOM_COMMAND_FORWARD_ACTION_ID,
+        commandButton = CommandButton.Builder(ICON_FAST_FORWARD)
+            .setDisplayName("Forward")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_FORWARD_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    SHUFFLE_ON(
+        customAction = CUSTOM_COMMAND_SHUFFLE_ON_ACTION_ID,
+        commandButton = CommandButton.Builder(ICON_SHUFFLE_ON)
+            .setDisplayName("ShuffleOn")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_SHUFFLE_ON_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    SHUFFLE_OFF(
+        customAction = CUSTOM_COMMAND_SHUFFLE_OFF_ACTION_ID,
+        commandButton = CommandButton.Builder(ICON_SHUFFLE_OFF)
+            .setDisplayName("ShuffleOn")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_SHUFFLE_OFF_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    REPEAT_ONE(
+        customAction = CUSTOM_COMMAND_REPEAT_ONE_ACTION_ID,
+        commandButton = CommandButton.Builder(CommandButton.ICON_REPEAT_ONE)
+            .setDisplayName("Repeat One")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_REPEAT_ONE_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    REPEAT_ALL(
+        customAction = CUSTOM_COMMAND_REPEAT_ALL_ACTION_ID,
+        commandButton = CommandButton.Builder(CommandButton.ICON_REPEAT_ALL)
+            .setDisplayName("Repeat All")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_REPEAT_ALL_ACTION_ID, Bundle()))
+            .build(),
+    ),
+    REPEAT_OFF(
+        customAction = CUSTOM_COMMAND_REPEAT_OFF_ACTION_ID,
+        commandButton = CommandButton.Builder(CommandButton.ICON_REPEAT_OFF)
+            .setDisplayName("Repeat Off")
+            .setSessionCommand(SessionCommand(CUSTOM_COMMAND_REPEAT_OFF_ACTION_ID, Bundle()))
+            .build(),
+    ),;
+}