{"_id":"@beatsphere/expo-music-detector","name":"@beatsphere/expo-music-detector","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@beatsphere/expo-music-detector","version":"0.1.0","description":"Expo native module for detecting currently playing music on Android via MediaSession and NotificationListener","main":"build/index.js","types":"build/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"tsc","clean":"rm -rf build"},"keywords":["expo","react-native","music-detection","now-playing","media-session","notification-listener","android","spotify","youtube-music","apple-music","soundcloud"],"author":{"name":"BeatSphere","email":"hello@beatsphere.live"},"license":"MIT","homepage":"https://github.com/Beatsphere/expo-music-detector#readme","repository":{"type":"git","url":"git+https://github.com/Beatsphere/expo-music-detector.git"},"bugs":{"url":"https://github.com/Beatsphere/expo-music-detector/issues"},"peerDependencies":{"expo":">=51.0.0","expo-modules-core":">=2.0.0","react-native":">=0.74.0"},"devDependencies":{"expo-modules-core":"^2.0.0","typescript":"^5.0.0","react-native":"^0.76.0"},"gitHead":"a9918c418762c3df4766fa0ada40df8f9a6e3bea","_id":"@beatsphere/expo-music-detector@0.1.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-c+hvhUEEdE3YaXKMqKLmuEcSbjVBIoaJMjLmnqfzQmWJDLPyZ50nXQU+nv9edPJE9NdeLp2gRw4L6AJaGKMT1Q==","shasum":"14dce5c4e0898fde3ccb3793afbc4fb764171bcc","tarball":"https://registry.npmjs.org/@beatsphere/expo-music-detector/-/expo-music-detector-0.1.0.tgz","fileCount":21,"unpackedSize":34952,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEcVipz1cXtXTJeoiWPJTI/md0S2kCQ5XoZXKdEfTYeWAiEAmF6SAOODveO0doCKhMmXlpX1wjaWkFxTv2KY8XX2EmE="}]},"_npmUser":{"name":"ayushh2k","email":"rustichouse042@gmail.com"},"directories":{},"maintainers":[{"name":"ayushh2k","email":"rustichouse042@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/expo-music-detector_0.1.0_1776970283895_0.6739066194570638"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T18:51:23.782Z","0.1.0":"2026-04-23T18:51:24.025Z","modified":"2026-04-23T18:51:24.321Z"},"maintainers":[{"name":"ayushh2k","email":"rustichouse042@gmail.com"}],"description":"Expo native module for detecting currently playing music on Android via MediaSession and NotificationListener","homepage":"https://github.com/Beatsphere/expo-music-detector#readme","keywords":["expo","react-native","music-detection","now-playing","media-session","notification-listener","android","spotify","youtube-music","apple-music","soundcloud"],"repository":{"type":"git","url":"git+https://github.com/Beatsphere/expo-music-detector.git"},"author":{"name":"BeatSphere","email":"hello@beatsphere.live"},"bugs":{"url":"https://github.com/Beatsphere/expo-music-detector/issues"},"license":"MIT","readme":"# @beatsphere/expo-music-detector\n\nExpo native module that detects currently playing music on Android. Uses MediaSession and NotificationListenerService to detect tracks from 10+ music apps in real-time. Battle-tested in [BeatSphere](https://beatsphere.live).\n\n## Supported Apps\n\n| App | Package Name |\n|-----|-------------|\n| Spotify | `com.spotify.music` |\n| YouTube | `com.google.android.youtube` |\n| YouTube Music | `com.google.android.apps.youtube.music` |\n| Apple Music | `com.apple.android.music` |\n| SoundCloud | `com.soundcloud.android` |\n| Last.fm | `fm.last.android` |\n| Amazon Music | `com.amazon.mp3` |\n| Pandora | `com.pandora.android` |\n| Tidal | `com.aspiro.tidal` |\n| Deezer | `deezer.android.app` |\n\nAny other app using Android's MediaSession API will be detected as `unknown` provider.\n\n## Install\n\n```bash\nnpm install @beatsphere/expo-music-detector\n```\n\nAdd the plugin to your `app.config.js`:\n\n```js\nexport default {\n  plugins: [\n    '@beatsphere/expo-music-detector',\n  ],\n};\n```\n\nRun prebuild:\n\n```bash\nnpx expo prebuild --clean\n```\n\n## Quick Start\n\n```tsx\nimport {\n  isSupported,\n  isNotificationAccessGranted,\n  openNotificationSettings,\n  getCurrentTrack,\n  addTrackChangedListener,\n} from '@beatsphere/expo-music-detector';\n\n// Check platform support (Android only)\nif (!isSupported) {\n  console.log('Music detection is only supported on Android');\n}\n\n// Check and request permission\nconst hasAccess = isNotificationAccessGranted();\nif (!hasAccess) {\n  // Opens system settings — user must manually enable\n  openNotificationSettings();\n}\n\n// Get current track\nconst track = getCurrentTrack();\nif (track) {\n  console.log(`${track.title} by ${track.artist} (${track.provider})`);\n}\n\n// Listen for track changes\nconst subscription = addTrackChangedListener((event) => {\n  if (event.track) {\n    console.log(`Now playing: ${event.track.title} by ${event.track.artist}`);\n    console.log(`Provider: ${event.track.provider}`);\n    console.log(`Playing: ${event.track.isPlaying}`);\n  } else {\n    console.log('Playback stopped');\n  }\n});\n\n// Clean up\nsubscription.remove();\n```\n\n## How It Works\n\nOn Android, the module uses two detection mechanisms:\n\n1. **MediaSessionManager** (primary) — Listens for active media sessions and registers callbacks for metadata and playback state changes. This provides the most reliable detection.\n\n2. **NotificationListenerService** (fallback) — Parses music notifications for apps that don't use MediaSession properly. Extracts title, artist, and album from notification extras.\n\nThe module requires **Notification Listener Access**, which the user must grant manually in system settings. This is an Android system-level permission that cannot be requested via a dialog.\n\n## API Reference\n\n| Function | Description |\n|----------|-------------|\n| `isSupported` | `boolean` — Whether the current platform supports music detection (Android only) |\n| `isNotificationAccessGranted()` | Check if notification listener permission is granted |\n| `openNotificationSettings()` | Open system settings for notification access |\n| `startMonitoring()` | Start monitoring (service starts automatically with permission) |\n| `stopMonitoring()` | Stop monitoring |\n| `getCurrentTrack()` | Get the currently playing track, or `null` |\n| `addTrackChangedListener(cb)` | Subscribe to track changes. Returns `{ remove() }` |\n\n### Track Type\n\n```typescript\ninterface Track {\n  title: string;\n  artist: string;\n  album?: string;\n  albumArt?: string;\n  provider: MusicProvider;\n  isPlaying: boolean;\n}\n\ntype MusicProvider =\n  | 'spotify'\n  | 'youtube'\n  | 'apple_music'\n  | 'soundcloud'\n  | 'lastfm'\n  | 'amazon_music'\n  | 'pandora'\n  | 'tidal'\n  | 'deezer'\n  | 'unknown';\n```\n\n## Platform Notes\n\n### Android\n- **API 21+** (Lollipop) required\n- Uses `MediaSessionManager` for reliable detection on API 22+\n- Falls back to notification parsing on older versions\n- Requires `BIND_NOTIFICATION_LISTENER_SERVICE` permission\n- The `NotificationListenerService` runs as long as the user grants access\n- Automatically detects track changes across all supported music apps\n\n### iOS\n- Music detection is **not supported** on iOS\n- All functions return safe defaults (`null`, `false`, no-ops)\n- The iOS module stub is included so your app builds cross-platform without conditional imports\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0919f99e3409728bb38d7f4bb60c82eb"}