Cordova CodePlay Music Controls

A maintained and fixed Cordova music controls plugin for Android, iOS, and Windows.

This plugin shows a native media notification / lockscreen controller with play, pause, next, previous buttons and supports real seek and progress updates on Android, which were missing in the original plugin.

---

📌 About This Plugin

This repository is a cleaned, fixed, and maintained fork of the original, now unmaintained plugin:

Original Repository:
https://github.com/homerours/cordova-music-controls-plugin
Original Author: homerours

The original plugin contained multiple Android issues such as:

• Seek mentioned in docs but not implemented
• Progress bar displayed but never updated
• Android 12+ BroadcastReceiver crashes
• Broken MediaSession callback lifecycle
• Duration metadata ignored on Android

✅ All of these issues are fixed in this fork.

---

🔧 Maintainer

Maintained & Fixed by: Merbin Joe
GitHub: https://github.com/merbin2012
Repository: https://github.com/merbin2012/cordova-codeplay-music-controls

---

✅ Supported Platforms

• Android 5.0+ (MediaSession based, Android 13/14 compatible)
• iOS 8+
• Windows 10+

---

📦 Installation

From GitHub (recommended maintained version)

cordova plugin add https://github.com/merbin2012/cordova-codeplay-music-controls

From npm (recommended for Capacitor & Ionic)

npm i cordova-codeplay-music-controls

---

📖 Usage

Create Media Controls

MusicControls.create({
  track       : 'My Audio Track',
  artist      : 'CodePlay',
  album       : '',
  cover       : 'https://example.com/cover.jpg',

  isPlaying   : true,
  dismissable : true,

  hasPrev     : true,
  hasNext     : true,
  hasClose    : true,

  // ✅ REQUIRED for progress bar & seek (Android)
  duration    : 380,   // seconds
  elapsed     : 10,    // seconds

  ticker      : 'Now playing My Audio Track',

  playIcon          : 'media_play',
  pauseIcon         : 'media_pause',
  prevIcon          : 'media_prev',
  nextIcon          : 'media_next',
  closeIcon         : 'media_close',
  notificationIcon  : 'notification'
}, onSuccess, onError);

⚠️ Android Note
The progress bar and seek scrubber work only when duration > 0 is provided.

---

🎧 Media Events

function events(action) {

  // `action` is already an object
  const message = action.message;

  switch (message) {

    case 'music-controls-play':
      audio.play();
      MusicControls.updateIsPlaying(true);
      break;

    case 'music-controls-pause':
      audio.pause();
      MusicControls.updateIsPlaying(false);
      break;

    case 'music-controls-next':
      playNext();
      break;

    case 'music-controls-previous':
      playPrevious();
      break;

    case 'music-controls-destroy':
      stopAudio();
      break;

    // ✅ REAL SEEK SUPPORT (Android + iOS)
    case 'music-controls-seek-to':
      // position is in milliseconds
      audio.currentTime = action.position / 1000;

      // notify native layer about new position
      MusicControls.updateElapsed({
        elapsed   : audio.currentTime * 1000,
        isPlaying : !audio.paused
      });
      break;
  }
}

MusicControls.subscribe(events);
MusicControls.listen();

---

⏱️ Progress Updates (REQUIRED FOR ANDROID)

Android does not automatically update media progress.
You must push progress updates from JavaScript.

setInterval(() => {
  if (!audio || isNaN(audio.currentTime)) return;

  MusicControls.updateElapsed({
    elapsed   : audio.currentTime * 1000, // milliseconds
    isPlaying : !audio.paused
  });
}, 1000);

✅ Keeps notification progress, lockscreen scrubber, and Bluetooth seek in sync.

---

🔄 Toggle Play / Pause

MusicControls.updateIsPlaying(true);
MusicControls.updateDismissable(true);

---

📱 Supported Media Button Events

music-controls-play
music-controls-pause
music-controls-next
music-controls-previous
music-controls-toggle-play-pause
music-controls-seek-to
music-controls-stop

Also supports headset and Bluetooth media buttons.

---

⚠️ Important Notes

Android Seek & Progress

• Android never controls audio playback directly
• JavaScript must apply seek and report progress
• This plugin correctly bridges MediaSession → JS

Audio Events Best Practice

Avoid controlling playback in canplay.

Use:

• loadedmetadata → initialization
• timeupdate → progress
• seeking / seeked → buffering UI

---

✅ Fixes Included in This Fork

• ✅ Android seek implementation
• ✅ Moving progress bar
• ✅ Correct duration handling
• ✅ MediaSession callback fixes
• ✅ BroadcastReceiver crash fixes
• ✅ Cordova callback lifecycle fixes
• ✅ Android 13/14 compatibility
• ✅ Capacitor support

✅ Fully compatible with Capacitor + Ionic projects (tested with Capacitor & Ionic apps)

---

🧾 Credits

• Original plugin by homerours
  https://github.com/homerours/cordova-music-controls-plugin

• Maintained & fixed by Merbin Joe
  https://github.com/merbin2012

---

📄 License

Same license as the original project.