tunzo-player 1.0.23 → 1.0.25

package/README.md

@@ -76,4 +76,36 @@ yarn add tunzo-player
 | 3     | High (160kbps)    |
 | 4     | Ultra (320kbps)   |
 
+| 4     | Ultra (320kbps)   |
+
+## 📱 Native Configuration (Ionic/Capacitor)
+
+To ensure background audio works correctly on Android and iOS (preventing the app from pausing when the screen locks), you must configure your native projects.
+
+### **Android (`android/app/src/main/AndroidManifest.xml`)**
+
+Add the following permissions inside the `<manifest>` tag:
+
+```xml
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+```
+
+**Note:** Modern Android versions might require a foreground service notification to keep the audio alive indefinitely. The `MediaSession` API implemented in this package helps, but for guaranteed persistence, consider using a native audio plugin if issues persist.
+
+### **iOS (`ios/App/App/Info.plist`)**
+
+Add `audio` to the `UIBackgroundModes` key to allow background playback:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>audio</string>
+</array>
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
 # tunzo-player

package/dist/core/player.d.ts

@@ -37,4 +37,7 @@ export declare class Player {
     static setQuality(index: number): void;
     static getQueue(): any[];
     static getPlaylist(): any[];
+    private static setupMediaSession;
+    private static updateMediaSessionMetadata;
+    private static updatePositionState;
 }

package/dist/core/player.js

@@ -7,6 +7,7 @@ class Player {
     static initialize(playlist, quality = 3) {
         this.playlist = playlist;
         this.selectedQuality = quality;
+        this.setupMediaSession();
     }
     /** Call this once on user gesture to unlock audio in WebView */
     static unlockAudio() {
@@ -27,9 +28,16 @@ class Player {
             url = url.replace('http://', 'https://');
         }
         this.audio.src = url;
+        // @ts-ignore
+        this.audio.title = song.name || song.title || 'Unknown Title'; // Help some browsers identify the track
+        this.audio.preload = 'auto'; // Improve loading
         this.audio.load(); // Ensure audio is loaded before play
         this.audio.play().then(() => {
             this.isPlaying = true;
+            this.updateMediaSessionMetadata(song);
+            if ('mediaSession' in navigator) {
+                navigator.mediaSession.playbackState = 'playing';
+            }
         }).catch((err) => {
             this.isPlaying = false;
             console.warn('Audio play failed:', err);
@@ -37,10 +45,27 @@ class Player {
         // Set duration
         this.audio.onloadedmetadata = () => {
             this.duration = this.audio.duration;
+            this.updatePositionState();
         };
         // Set current time
         this.audio.ontimeupdate = () => {
             this.currentTime = this.audio.currentTime;
+            // Update position state less frequently to avoid spamming, but enough to keep sync
+            if (Math.floor(this.currentTime) % 5 === 0) {
+                this.updatePositionState();
+            }
+        };
+        // Handle buffering/stalled states
+        this.audio.onwaiting = () => {
+            if ('mediaSession' in navigator) {
+                navigator.mediaSession.playbackState = 'none'; // Or 'paused' to indicate buffering
+            }
+        };
+        this.audio.onplaying = () => {
+            this.isPlaying = true;
+            if ('mediaSession' in navigator) {
+                navigator.mediaSession.playbackState = 'playing';
+            }
         };
         // Auto-play next song
         this.audio.onended = () => {
@@ -54,10 +79,16 @@ class Player {
     static pause() {
         this.audio.pause();
         this.isPlaying = false;
+        if ('mediaSession' in navigator) {
+            navigator.mediaSession.playbackState = 'paused';
+        }
     }
     static resume() {
         this.audio.play();
         this.isPlaying = true;
+        if ('mediaSession' in navigator) {
+            navigator.mediaSession.playbackState = 'playing';
+        }
     }
     static togglePlayPause() {
         if (this.isPlaying) {
@@ -88,6 +119,7 @@ class Player {
     }
     static seek(seconds) {
         this.audio.currentTime = seconds;
+        this.updatePositionState();
     }
     static autoNext() {
         this.next();
@@ -148,6 +180,65 @@ class Player {
     static getPlaylist() {
         return this.playlist;
     }
+    // -------------------------------------------------------------------------
+    // Native Media Session (Lock Screen Controls)
+    // -------------------------------------------------------------------------
+    static setupMediaSession() {
+        if ('mediaSession' in navigator) {
+            navigator.mediaSession.setActionHandler('play', () => this.resume());
+            navigator.mediaSession.setActionHandler('pause', () => this.pause());
+            navigator.mediaSession.setActionHandler('previoustrack', () => this.prev());
+            navigator.mediaSession.setActionHandler('nexttrack', () => this.next());
+            navigator.mediaSession.setActionHandler('seekto', (details) => {
+                if (details.seekTime !== undefined) {
+                    this.seek(details.seekTime);
+                }
+            });
+        }
+    }
+    static updateMediaSessionMetadata(song) {
+        var _a;
+        if ('mediaSession' in navigator) {
+            const artwork = [];
+            if (song.image) {
+                if (Array.isArray(song.image)) {
+                    // Assuming image array contains objects with url/link and quality
+                    song.image.forEach((img) => {
+                        let src = img.link || img.url || (typeof img === 'string' ? img : '');
+                        if (src) {
+                            // 🚀 Auto-convert http → https for images too
+                            if (src.startsWith('http://')) {
+                                src = src.replace('http://', 'https://');
+                            }
+                            artwork.push({ src, sizes: '500x500', type: 'image/jpeg' });
+                        }
+                    });
+                }
+                else if (typeof song.image === 'string') {
+                    let src = song.image;
+                    if (src.startsWith('http://')) {
+                        src = src.replace('http://', 'https://');
+                    }
+                    artwork.push({ src: src, sizes: '500x500', type: 'image/jpeg' });
+                }
+            }
+            navigator.mediaSession.metadata = new MediaMetadata({
+                title: song.name || song.title || 'Unknown Title',
+                artist: song.primaryArtists || song.artist || 'Unknown Artist',
+                album: ((_a = song.album) === null || _a === void 0 ? void 0 : _a.name) || song.album || 'Unknown Album',
+                artwork: artwork.length > 0 ? artwork : undefined
+            });
+        }
+    }
+    static updatePositionState() {
+        if ('mediaSession' in navigator && this.duration > 0) {
+            navigator.mediaSession.setPositionState({
+                duration: this.duration,
+                playbackRate: this.audio.playbackRate,
+                position: this.audio.currentTime
+            });
+        }
+    }
 }
 exports.Player = Player;
 Player.audio = new Audio();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tunzo-player",
-    "version": "1.0.23",
+    "version": "1.0.25",
     "description": "A music playback service for Angular and Ionic apps with native audio control support.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/src/core/player.ts

@@ -17,6 +17,7 @@ export class Player {
   static initialize(playlist: any[], quality = 3) {
     this.playlist = playlist;
     this.selectedQuality = quality;
+    this.setupMediaSession();
   }
 
   /** Call this once on user gesture to unlock audio in WebView */
@@ -41,9 +42,16 @@ export class Player {
     }
 
     this.audio.src = url;
+    // @ts-ignore
+    this.audio.title = song.name || song.title || 'Unknown Title'; // Help some browsers identify the track
+    this.audio.preload = 'auto'; // Improve loading
     this.audio.load(); // Ensure audio is loaded before play
     this.audio.play().then(() => {
       this.isPlaying = true;
+      this.updateMediaSessionMetadata(song);
+      if ('mediaSession' in navigator) {
+        navigator.mediaSession.playbackState = 'playing';
+      }
     }).catch((err) => {
       this.isPlaying = false;
       console.warn('Audio play failed:', err);
@@ -52,11 +60,30 @@ export class Player {
     // Set duration
     this.audio.onloadedmetadata = () => {
       this.duration = this.audio.duration;
+      this.updatePositionState();
     };
 
     // Set current time
     this.audio.ontimeupdate = () => {
       this.currentTime = this.audio.currentTime;
+      // Update position state less frequently to avoid spamming, but enough to keep sync
+      if (Math.floor(this.currentTime) % 5 === 0) {
+        this.updatePositionState();
+      }
+    };
+
+    // Handle buffering/stalled states
+    this.audio.onwaiting = () => {
+      if ('mediaSession' in navigator) {
+        navigator.mediaSession.playbackState = 'none'; // Or 'paused' to indicate buffering
+      }
+    };
+
+    this.audio.onplaying = () => {
+      this.isPlaying = true;
+      if ('mediaSession' in navigator) {
+        navigator.mediaSession.playbackState = 'playing';
+      }
     };
 
     // Auto-play next song
@@ -74,11 +101,17 @@ export class Player {
   static pause() {
     this.audio.pause();
     this.isPlaying = false;
+    if ('mediaSession' in navigator) {
+      navigator.mediaSession.playbackState = 'paused';
+    }
   }
 
   static resume() {
     this.audio.play();
     this.isPlaying = true;
+    if ('mediaSession' in navigator) {
+      navigator.mediaSession.playbackState = 'playing';
+    }
   }
 
   static togglePlayPause() {
@@ -110,6 +143,7 @@ export class Player {
 
   static seek(seconds: number) {
     this.audio.currentTime = seconds;
+    this.updatePositionState();
   }
 
   static autoNext() {
@@ -186,4 +220,66 @@ export class Player {
   static getPlaylist(): any[] {
     return this.playlist;
   }
+
+  // -------------------------------------------------------------------------
+  // Native Media Session (Lock Screen Controls)
+  // -------------------------------------------------------------------------
+
+  private static setupMediaSession() {
+    if ('mediaSession' in navigator) {
+      navigator.mediaSession.setActionHandler('play', () => this.resume());
+      navigator.mediaSession.setActionHandler('pause', () => this.pause());
+      navigator.mediaSession.setActionHandler('previoustrack', () => this.prev());
+      navigator.mediaSession.setActionHandler('nexttrack', () => this.next());
+      navigator.mediaSession.setActionHandler('seekto', (details) => {
+        if (details.seekTime !== undefined) {
+          this.seek(details.seekTime);
+        }
+      });
+    }
+  }
+
+  private static updateMediaSessionMetadata(song: any) {
+    if ('mediaSession' in navigator) {
+      const artwork = [];
+      if (song.image) {
+        if (Array.isArray(song.image)) {
+          // Assuming image array contains objects with url/link and quality
+          song.image.forEach((img: any) => {
+            let src = img.link || img.url || (typeof img === 'string' ? img : '');
+            if (src) {
+              // 🚀 Auto-convert http → https for images too
+              if (src.startsWith('http://')) {
+                src = src.replace('http://', 'https://');
+              }
+              artwork.push({ src, sizes: '500x500', type: 'image/jpeg' });
+            }
+          });
+        } else if (typeof song.image === 'string') {
+          let src = song.image;
+          if (src.startsWith('http://')) {
+            src = src.replace('http://', 'https://');
+          }
+          artwork.push({ src: src, sizes: '500x500', type: 'image/jpeg' });
+        }
+      }
+
+      navigator.mediaSession.metadata = new MediaMetadata({
+        title: song.name || song.title || 'Unknown Title',
+        artist: song.primaryArtists || song.artist || 'Unknown Artist',
+        album: song.album?.name || song.album || 'Unknown Album',
+        artwork: artwork.length > 0 ? artwork : undefined
+      });
+    }
+  }
+
+  private static updatePositionState() {
+    if ('mediaSession' in navigator && this.duration > 0) {
+      navigator.mediaSession.setPositionState({
+        duration: this.duration,
+        playbackRate: this.audio.playbackRate,
+        position: this.audio.currentTime
+      });
+    }
+  }
 }