tunzo-player 1.0.24 → 1.0.27

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,6 +37,8 @@ export declare class Player {
     static setQuality(index: number): void;
     static getQueue(): any[];
     static getPlaylist(): any[];
+    private static enableBackgroundMode;
+    private static disableBackgroundMode;
     private static setupMediaSession;
     private static updateMediaSessionMetadata;
     private static updatePositionState;

package/dist/core/player.js

@@ -1,7 +1,18 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Player = void 0;
 const rxjs_1 = require("rxjs");
+const capacitor_background_mode_1 = require("@anuradev/capacitor-background-mode");
+const keep_awake_1 = require("@capacitor-community/keep-awake");
 class Player {
     /** Initialize with playlist and quality */
     static initialize(playlist, quality = 3) {
@@ -28,11 +39,14 @@ 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);
+            this.enableBackgroundMode();
             if ('mediaSession' in navigator) {
                 navigator.mediaSession.playbackState = 'playing';
             }
@@ -48,6 +62,22 @@ class Player {
         // 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 = () => {
@@ -61,6 +91,7 @@ class Player {
     static pause() {
         this.audio.pause();
         this.isPlaying = false;
+        this.disableBackgroundMode();
         if ('mediaSession' in navigator) {
             navigator.mediaSession.playbackState = 'paused';
         }
@@ -163,6 +194,43 @@ class Player {
         return this.playlist;
     }
     // -------------------------------------------------------------------------
+    // Capacitor Background Mode & Keep Awake
+    // -------------------------------------------------------------------------
+    static enableBackgroundMode() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield keep_awake_1.KeepAwake.keepAwake();
+                yield capacitor_background_mode_1.BackgroundMode.enable({
+                    title: "Tunzo Player",
+                    text: "Playing music in background",
+                    icon: "ic_launcher",
+                    color: "042730",
+                    resume: true,
+                    hidden: false,
+                    bigText: true,
+                    disableWebViewOptimization: true
+                });
+            }
+            catch (err) {
+                // Plugin might not be installed or on web
+            }
+        });
+    }
+    static disableBackgroundMode() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield keep_awake_1.KeepAwake.allowSleep();
+                // We might want to keep background mode enabled if we want to resume later,
+                // but for battery saving, we can disable it or move to background.
+                // await BackgroundMode.disable(); 
+                yield capacitor_background_mode_1.BackgroundMode.moveToBackground();
+            }
+            catch (err) {
+                // Plugin might not be installed or on web
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
     // Native Media Session (Lock Screen Controls)
     // -------------------------------------------------------------------------
     static setupMediaSession() {
@@ -186,20 +254,28 @@ class Player {
                 if (Array.isArray(song.image)) {
                     // Assuming image array contains objects with url/link and quality
                     song.image.forEach((img) => {
-                        const src = img.link || img.url || (typeof img === 'string' ? 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') {
-                    artwork.push({ src: song.image, sizes: '500x500', type: 'image/jpeg' });
+                    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 || '',
+                album: ((_a = song.album) === null || _a === void 0 ? void 0 : _a.name) || song.album || 'Unknown Album',
                 artwork: artwork.length > 0 ? artwork : undefined
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tunzo-player",
-    "version": "1.0.24",
+    "version": "1.0.27",
     "description": "A music playback service for Angular and Ionic apps with native audio control support.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -29,6 +29,8 @@
         "access": "public"
     },
     "dependencies": {
+        "@anuradev/capacitor-background-mode": "^7.2.1",
+        "@capacitor-community/keep-awake": "^7.1.0",
         "rxjs": "^7.8.2"
     }
 }

package/src/core/player.ts

@@ -1,4 +1,6 @@
 import { BehaviorSubject } from 'rxjs';
+import { BackgroundMode } from '@anuradev/capacitor-background-mode';
+import { KeepAwake } from '@capacitor-community/keep-awake';
 
 export class Player {
   private static audio = new Audio();
@@ -42,11 +44,14 @@ 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);
+      this.enableBackgroundMode();
       if ('mediaSession' in navigator) {
         navigator.mediaSession.playbackState = 'playing';
       }
@@ -64,6 +69,24 @@ export class Player {
     // 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
@@ -81,6 +104,7 @@ export class Player {
   static pause() {
     this.audio.pause();
     this.isPlaying = false;
+    this.disableBackgroundMode();
     if ('mediaSession' in navigator) {
       navigator.mediaSession.playbackState = 'paused';
     }
@@ -201,6 +225,40 @@ export class Player {
     return this.playlist;
   }
 
+  // -------------------------------------------------------------------------
+  // Capacitor Background Mode & Keep Awake
+  // -------------------------------------------------------------------------
+
+  private static async enableBackgroundMode() {
+    try {
+      await KeepAwake.keepAwake();
+      await BackgroundMode.enable({
+        title: "Tunzo Player",
+        text: "Playing music in background",
+        icon: "ic_launcher",
+        color: "042730",
+        resume: true,
+        hidden: false,
+        bigText: true,
+        disableWebViewOptimization: true
+      });
+    } catch (err) {
+      // Plugin might not be installed or on web
+    }
+  }
+
+  private static async disableBackgroundMode() {
+    try {
+      await KeepAwake.allowSleep();
+      // We might want to keep background mode enabled if we want to resume later,
+      // but for battery saving, we can disable it or move to background.
+      // await BackgroundMode.disable(); 
+      await BackgroundMode.moveToBackground();
+    } catch (err) {
+      // Plugin might not be installed or on web
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Native Media Session (Lock Screen Controls)
   // -------------------------------------------------------------------------
@@ -226,20 +284,28 @@ export class Player {
         if (Array.isArray(song.image)) {
           // Assuming image array contains objects with url/link and quality
           song.image.forEach((img: any) => {
-            const src = img.link || img.url || (typeof img === 'string' ? 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') {
-          artwork.push({ src: song.image, sizes: '500x500', type: 'image/jpeg' });
+          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 || '',
+        album: song.album?.name || song.album || 'Unknown Album',
         artwork: artwork.length > 0 ? artwork : undefined
       });
     }