feat: synced snapshots feature, sync playback time of current track

Author: D3SOX

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This documents the user-facing changes for each version
 
+## 0.7
+
+- Add synced snapshot mode (disables automatic snapshots while active)
+- Manual and synced snapshots now include the playback position of the current track
+- Improve extension metadata, readme and screenshots
+
 ## 0.6.4
 
 - Shorten queue warning description

README.md

@@ -2,49 +2,61 @@
 
 <h1>Queue Manager</h1>
 
-Do you hate it when Spotify randomly decides your queue is gone — or just want to manage queues more easily? Spicetify Queue Manager snapshots your current queue (including local files), lets you restore it later, and export snapshots to playlists.
+This extension probably serves a kinda niche purpose but if you are like me and always queue a bunch of songs, swap them around, want to play a different genre or mood but still retain the same queue for later, this is for you.
+
+It also helps when Spotify forgets your queue or reshuffles it unexpectedly.
+
+With this extension you can manage queues more easily. It snapshots your current queue, lets you restore it later, and export snapshots to playlists.
+
+This can be done by:
+
+- Automatically capturing snapshots on a schedule or when the queue changes.
+- Manually creating snapshots
+- Creating synced snapshots that automatically stay in sync with your queue, allowing you to switch between different ones and have your queue instantly replaced with the one from the snapshot (including playback position).
+
+The extension adds an icon to the topbar right side of the player. Clicking it opens a modal with all the snapshots and allows you to manage settings for customizing the behavior of the extension. (see below)
+There is also a hotkey of `Ctrl+Alt+Q` to open it.
+
+# Screenshots
+
 
 | | |
 |---|---|
 | <img height="750" alt="image" src="https://github.com/user-attachments/assets/f0802551-2acd-4bcd-8f8d-2bb33ef3e95a" /> | <img width="488" height="499" alt="image" src="https://github.com/user-attachments/assets/114a00cc-4571-41fc-9f62-3d8b139318d3" /> |
 | Main interface | Settings |
 
+
 </div>
 
 ## Status
-🚧 Beta. Core features are implemented and undergoing polish.
+
+🚧 Late Beta. Core features are implemented and undergoing polish. Beta testing would be appreciated.
 
 For changes, see [CHANGELOG.md](https://github.com/D3SOX/spicetify-queue-manager/blob/master/CHANGELOG.md)
 
 ## Installation
+
 - Open the [Spicetify Marketplace](https://github.com/spicetify/marketplace/wiki/Installation).
 - Search for "Queue Manager" (You might have to click on "Load more" first)
 - Install & reload
 
-## What it does
-- Save your current queue as named snapshots
-- Automatically create snapshots on a schedule or when the queue changes
-- Restore a snapshot to replace your current queue
-- Export any snapshot to a playlist
-- Manage all snapshots in a simple queue manager UI
-- Works with local files (not only the Web API)
-
-## Why
-Spotify can sometimes clear or reshuffle your queue unexpectedly. This extension preserves your listening state by periodically recording `Spicetify.Queue` and providing quick restore/export actions.
-
 ## Development
-Requires Spicetify CLI and pnpm.
+
+Requires [Spicetify CLI](https://spicetify.app) and [pnpm](https://pnpm.io).
 
 ```bash
 pnpm install
-pnpm watch   # or: pnpm build
+pnpm build   # or: pnpm watch
+spicetify extensions queue-manager.js
 spicetify apply -n
 ```
 
 This project is built with [Spicetify Creator](https://spicetify.app/docs/development/spicetify-creator)
 
 ## Notes
-- If something looks off, open DevTools and inspect `Spicetify.Queue` to help debug.
+
+- If something looks off, open DevTools and inspect the console log any errors and send the contents of `Spicetify.Queue` to help debug.
 
 ## License
+
 [GNU General Public License v3.0](./LICENSE)

manifest.json

@@ -2,8 +2,11 @@
   {
     "name": "Queue Manager",
     "description": "Save snapshots of your queue, restore them later, export to playlists and more",
-    "preview": "https://github.com/user-attachments/assets/7da407d1-26ec-459b-8105-4fb9b62c87ef",
+    "preview": "https://github.com/user-attachments/assets/f0802551-2acd-4bcd-8f8d-2bb33ef3e95a",
     "main": "dist/queue-manager.js",
+    "authors": [
+        { "name": "D3SOX", "url": "https://github.com/D3SOX" }
+    ],
     "readme": "README.md",
     "tags": [
       "queue",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "queue-manager",
-  "version": "0.6.4",
+  "version": "0.7",
   "private": true,
   "scripts": {
     "build": "spicetify-creator",

src/auto.ts

@@ -1,7 +1,7 @@
-import { Snapshot, Settings, AutoMode, QueueUpdateEvent } from "./types";
+import { Snapshot, Settings, AutoMode, QueueUpdateEvent, OnProgressEvent } from "./types";
 import { getQueueFromSpicetify } from "./queue";
 import { areQueuesEqual, generateId } from "./utils";
-import { addSnapshot, getSortedSnapshots, loadSnapshots, pruneAutosToMax as storagePruneAutosToMax } from "./storage";
+import { addSnapshot, getSortedSnapshots, loadSnapshots, saveSnapshots, saveSettings } from "./storage";
 import { APP_NAME } from "./appInfo";
 import { showErrorToast, showWarningToast } from "./toast";
 import { t } from "./i18n";
@@ -24,7 +24,7 @@ export function createAutoManager(getSettings: () => Settings) {
   async function runSnapshotIfChanged(s: Settings) {
     try {
       if (!s.autoEnabled) return;
-      const currentItems = await getQueueFromSpicetify();
+      const currentItems = getQueueFromSpicetify();
       if (!currentItems.length) {
         console.log(`${APP_NAME}: queue is empty, skipping auto snapshot`);
         return;
@@ -84,17 +84,11 @@ export function createAutoManager(getSettings: () => Settings) {
     if (!s.autoEnabled) return;
 
     try {
-      type EventFunc = (event: string, callback: (...args: any[]) => void) => void;
-      const events: {
-        addListener?: EventFunc;
-        removeListener: EventFunc;
-      } | undefined = (Spicetify as any)?.Player?.origin?._events;
+      const events = Spicetify?.Player?.origin?._events;
       if (!events?.addListener || !events?.removeListener) {
-        throw new Error("queue_update events API not available");
-      }
-
-
-      const onQueueUpdate = (evt: QueueUpdateEvent) => {
+        throw new Error("events API not available");
+     }
+      const onQueueUpdate: (event?: QueueUpdateEvent) => void = (evt) => {
         runSnapshotIfChanged(s);
         //console.debug(`${APP_NAME}: queue_update`, evt);
       };
@@ -165,7 +159,7 @@ export function createQueueCapacityWatcher(getSettings: () => Settings) {
       const threshold = s.queueWarnThreshold;
       if (threshold < 0 || maxSize <= 1) return;
 
-      const items = await getQueueFromSpicetify();
+      const items = getQueueFromSpicetify();
       const currentSize = items.length;
 
       // Skip if queue size hasn't increased
@@ -201,19 +195,16 @@ export function createQueueCapacityWatcher(getSettings: () => Settings) {
   function start(): void {
     stop();
     try {
-      type EventFunc = (event: string, callback: (...args: any[]) => void) => void;
-      const events: {
-        addListener?: EventFunc;
-        removeListener: EventFunc;
-      } | undefined = (Spicetify as any)?.Player?.origin?._events;
+      const events = Spicetify?.Player?.origin?._events;
       if (!events?.addListener || !events?.removeListener) {
         throw new Error("queue_update events API not available");
       }
 
-      const onQueueUpdate = (_evt: QueueUpdateEvent) => {
+      const onQueueUpdate: (event?: QueueUpdateEvent) => void = (_evt) => {
         checkAndWarnOnce();
       };
       events.addListener("queue_update", onQueueUpdate);
+      
       unsubscribe = () => {
         try { events.removeListener("queue_update", onQueueUpdate); } catch (e) {
           console.error(`${APP_NAME}: failed to remove queue_update listener (capacity watcher)`, e);
@@ -228,4 +219,137 @@ export function createQueueCapacityWatcher(getSettings: () => Settings) {
   }
 
   return { start, stop, checkAndWarnOnce };
+}
+
+export function createQueueSyncManager(getSettings: () => Settings) {
+  let unsubscribe: (() => void) | null = null;
+  let lastKnownQueue: string[] = [];
+  let isActive = false;
+  let isSuspended = false;
+
+  async function updatePlaybackPosition(progressMs: number) {
+    const s = getSettings();
+    if (!s.syncedSnapshotId || !isActive) return;
+
+    const snapshots = loadSnapshots();
+    const idx = snapshots.findIndex(snap => snap.id === s.syncedSnapshotId);
+    if (idx >= 0) {
+      snapshots[idx].playbackPosition = progressMs;
+      saveSnapshots(snapshots);
+    }
+  }
+
+  async function syncQueueToSnapshot(currentQueue: string[]) {
+    const s = getSettings();
+    if (!s.syncedSnapshotId) return;
+
+    const snapshots = loadSnapshots();
+    const idx = snapshots.findIndex(snap => snap.id === s.syncedSnapshotId);
+    if (idx >= 0) {
+      // Don't sync empty queues to prevent losing the snapshot content during queue replacements
+      if (currentQueue.length === 0) {
+        console.debug(`${APP_NAME}: skipping sync of empty queue to snapshot`);
+        return;
+      }
+      snapshots[idx].items = currentQueue.slice();
+      snapshots[idx].playbackPosition = Spicetify.Player.getProgress();
+      saveSnapshots(snapshots);
+    } else {
+      // Synced snapshot no longer exists
+      console.warn(`${APP_NAME}: synced snapshot ${s.syncedSnapshotId} no longer exists, deactivating sync mode`);
+      const newSettings = { ...s, syncedSnapshotId: undefined };
+      saveSettings(newSettings);
+
+      showWarningToast(t('toasts.syncedSnapshotNotFound'));
+    }
+  }
+
+  async function handleQueueUpdate() {
+    try {
+      const s = getSettings();
+      if (!s.syncedSnapshotId || !isActive || isSuspended) return;
+
+      const currentQueue = getQueueFromSpicetify();
+      if (!areQueuesEqual(currentQueue, lastKnownQueue)) {
+        await syncQueueToSnapshot(currentQueue);
+        lastKnownQueue = currentQueue.slice();
+      }
+    } catch (e) {
+      console.error(`${APP_NAME}: queue sync error`, e);
+    }
+  }
+
+  function stop(): void {
+    if (unsubscribe) {
+      try { unsubscribe(); } catch {}
+      unsubscribe = null;
+    }
+    isActive = false;
+    isSuspended = false;
+    lastKnownQueue = [];
+  }
+
+  function start(): void {
+    stop();
+    const s = getSettings();
+    if (!s.syncedSnapshotId) return;
+
+    try {
+      const events = Spicetify?.Player?.origin?._events;
+      if (!events?.addListener || !events?.removeListener) {
+        throw new Error("events API not available");
+      }
+
+      const onQueueUpdate: (evt?: QueueUpdateEvent) => void = (_evt) => {
+        handleQueueUpdate();
+      };
+      const onProgress = (evt?: Event) => {
+        const event = evt as OnProgressEvent;
+        updatePlaybackPosition(event.data);
+      };
+
+      events.addListener("queue_update", onQueueUpdate);
+      Spicetify.Player.addEventListener("onprogress", onProgress);
+      unsubscribe = () => {
+        try { 
+          events.removeListener("queue_update", onQueueUpdate);
+          Spicetify.Player.removeEventListener("onprogress", onProgress);
+        } catch (e) {
+          console.error(`${APP_NAME}: failed to remove listeners (sync manager)`, e);
+        }
+      };
+
+      isActive = true;
+      
+      // Initialize last known queue
+      lastKnownQueue = getQueueFromSpicetify();
+    } catch (e) {
+      console.error(`${APP_NAME}: failed to start queue sync manager`, e);
+      showErrorToast(t('toasts.failedToStartSyncManager'));
+    }
+  }
+
+  function applySync(newSettings: Settings): void {
+    const shouldBeActive = !!newSettings.syncedSnapshotId;
+    
+    if (shouldBeActive && !isActive) {
+      start();
+    } else if (!shouldBeActive && isActive) {
+      stop();
+    }
+  }
+
+  function suspend(): void {
+    isSuspended = true;
+    console.debug(`${APP_NAME}: sync manager suspended`);
+  }
+
+  async function resume(): Promise<void> {
+    isSuspended = false;
+    // After resuming, capture the current queue state so we don't sync the queue replacement
+    lastKnownQueue = getQueueFromSpicetify();
+    console.debug(`${APP_NAME}: sync manager resumed`);
+  }
+
+  return { start, stop, applySync, suspend, resume };
 }