npm - wavesurf - Versions diffs - 1.1.0 → 1.2.1 - Mend

wavesurf 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -300,12 +300,36 @@ Displays a track with waveform visualization:
   }}
   lazyLoad={true}
   showTime={true}
+  standalone={false}  // Use local audio instead of global context
   className=""
   renderHeader={(song, isPlaying) => <CustomHeader />}
   renderControls={(song, isPlaying) => <CustomControls />}
 />
 ```
+#### Standalone Mode
+By default, `WaveformPlayer` uses the global `AudioPlayerProvider` context and works with the `MiniPlayer`. If you want a simpler setup—individual players that don't share state and don't show the mini player bar—use standalone mode:
+```tsx
+// No AudioPlayerProvider needed
+<WaveformPlayer
+  song={song}
+  standalone={true}
+/>
+```
+**When to use standalone mode:**
+- Simple pages with just one or two tracks
+- Embedded players that shouldn't affect the rest of your site
+- When you don't want the persistent mini player bar
+**Standalone mode behavior:**
+- Each player manages its own audio element
+- Clicking play on one song automatically pauses others (even in standalone mode)
+- No MiniPlayer appears
+- Volume fade-in and persistence are not applied
 ### MiniPlayer
 Persistent playback bar:
@@ -321,6 +345,75 @@ Persistent playback bar:
 />
 ```
+#### Persisting Across Route Changes
+To keep the MiniPlayer visible and audio playing while users navigate between pages, place both `AudioPlayerProvider` and `MiniPlayer` in your **root layout**—not in individual pages.
+**Next.js App Router:**
+```tsx
+// app/layout.tsx
+import { AudioPlayerProvider, MiniPlayer } from 'wavesurf';
+import 'wavesurf/styles.css';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AudioPlayerProvider>
+          <Header />
+          <main>{children}</main>
+          <Footer />
+          <MiniPlayer />
+        </AudioPlayerProvider>
+      </body>
+    </html>
+  );
+}
+```
+**Next.js Pages Router:**
+```tsx
+// pages/_app.tsx
+import { AudioPlayerProvider, MiniPlayer } from 'wavesurf';
+import 'wavesurf/styles.css';
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <AudioPlayerProvider>
+      <Component {...pageProps} />
+      <MiniPlayer />
+    </AudioPlayerProvider>
+  );
+}
+```
+**React Router:**
+```tsx
+// App.tsx
+import { AudioPlayerProvider, MiniPlayer } from 'wavesurf';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import 'wavesurf/styles.css';
+function App() {
+  return (
+    <AudioPlayerProvider>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/album/:id" element={<Album />} />
+        </Routes>
+      </BrowserRouter>
+      <MiniPlayer />
+    </AudioPlayerProvider>
+  );
+}
+```
+**Why this works:** React Context state persists as long as the provider component stays mounted. By placing it in the root layout, the audio state survives page transitions. If you put the provider inside a page component, it unmounts on navigation and loses the current song.
 ### ShareButtons
 Social sharing for tracks:

package/dist/index.d.mts CHANGED Viewed

@@ -123,6 +123,12 @@ interface WaveformPlayerProps {
     renderHeader?: (song: Song, isPlaying: boolean) => React.ReactNode;
     /** Custom render function for additional controls */
     renderControls?: (song: Song, isPlaying: boolean) => React.ReactNode;
+    /**
+     * Standalone mode - play audio locally without global context/MiniPlayer.
+     * Use this when you want a simple player without the persistent mini player bar.
+     * (default: false)
+     */
+    standalone?: boolean;
 }
 /**
  * Position of the mini player.
@@ -195,7 +201,7 @@ interface AudioPlayerProviderProps {
 declare function AudioPlayerProvider({ children, config: userConfig, }: AudioPlayerProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAudioPlayer(): AudioPlayerContextValue;
-declare function WaveformPlayer({ song, waveformConfig: userWaveformConfig, lazyLoad, showTime, className, renderHeader, renderControls, }: WaveformPlayerProps): react_jsx_runtime.JSX.Element;
+declare function WaveformPlayer({ song, waveformConfig: userWaveformConfig, lazyLoad, showTime, className, renderHeader, renderControls, standalone, }: WaveformPlayerProps): react_jsx_runtime.JSX.Element;
 declare function MiniPlayer({ position, showVolume, showClose, onClose, className, waveformConfig: userWaveformConfig, }: MiniPlayerProps): react_jsx_runtime.JSX.Element | null;

package/dist/index.d.ts CHANGED Viewed

@@ -123,6 +123,12 @@ interface WaveformPlayerProps {
     renderHeader?: (song: Song, isPlaying: boolean) => React.ReactNode;
     /** Custom render function for additional controls */
     renderControls?: (song: Song, isPlaying: boolean) => React.ReactNode;
+    /**
+     * Standalone mode - play audio locally without global context/MiniPlayer.
+     * Use this when you want a simple player without the persistent mini player bar.
+     * (default: false)
+     */
+    standalone?: boolean;
 }
 /**
  * Position of the mini player.
@@ -195,7 +201,7 @@ interface AudioPlayerProviderProps {
 declare function AudioPlayerProvider({ children, config: userConfig, }: AudioPlayerProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAudioPlayer(): AudioPlayerContextValue;
-declare function WaveformPlayer({ song, waveformConfig: userWaveformConfig, lazyLoad, showTime, className, renderHeader, renderControls, }: WaveformPlayerProps): react_jsx_runtime.JSX.Element;
+declare function WaveformPlayer({ song, waveformConfig: userWaveformConfig, lazyLoad, showTime, className, renderHeader, renderControls, standalone, }: WaveformPlayerProps): react_jsx_runtime.JSX.Element;
 declare function MiniPlayer({ position, showVolume, showClose, onClose, className, waveformConfig: userWaveformConfig, }: MiniPlayerProps): react_jsx_runtime.JSX.Element | null;

package/dist/index.js CHANGED Viewed

@@ -176,10 +176,7 @@ function AudioPlayerProvider({
     if (state.isPlaying) {
       pause();
     } else {
-      const targetVolume = Math.max(state.volume, MIN_FADE_IN_VOLUME);
-      if (configRef.current.fadeInEnabled) {
-        audioRef.current.volume = 0;
-      }
+      audioRef.current.volume = state.displayVolume;
       audioRef.current.play().then(() => {
         if (typeof window !== "undefined") {
           window.dispatchEvent(
@@ -188,13 +185,10 @@ function AudioPlayerProvider({
             })
           );
         }
-        if (configRef.current.fadeInEnabled) {
-          fadeInVolume(targetVolume);
-        }
       }).catch(() => {
       });
     }
-  }, [state.isPlaying, state.currentSong, state.volume, pause, fadeInVolume]);
+  }, [state.isPlaying, state.currentSong, state.displayVolume, pause]);
   const seek = react.useCallback((time) => {
     if (!audioRef.current) return;
     audioRef.current.currentTime = time;
@@ -304,6 +298,7 @@ var DEFAULT_WAVEFORM_CONFIG = {
   height: 60,
   normalize: true
 };
+react.createContext(null);
 function WaveformPlayer({
   song,
   waveformConfig: userWaveformConfig,
@@ -311,35 +306,87 @@ function WaveformPlayer({
   showTime = true,
   className = "",
   renderHeader,
-  renderControls
+  renderControls,
+  standalone = false
 }) {
   const waveformConfig = { ...DEFAULT_WAVEFORM_CONFIG, ...userWaveformConfig };
   const containerRef = react.useRef(null);
   const wavesurferRef = react.useRef(null);
+  const localAudioRef = react.useRef(null);
   const [isReady, setIsReady] = react.useState(false);
   const [totalDuration, setTotalDuration] = react.useState(song.duration || 0);
+  const [localIsPlaying, setLocalIsPlaying] = react.useState(false);
+  const [localCurrentTime, setLocalCurrentTime] = react.useState(0);
   const { ref: wrapperRef, isVisible } = useLazyLoad({
     forceVisible: !lazyLoad
   });
-  const {
-    play: contextPlay,
-    togglePlay: contextTogglePlay,
-    seek: contextSeek,
-    currentSong,
-    isPlaying: contextIsPlaying,
-    currentTime: contextCurrentTime
-  } = useAudioPlayer();
-  const isThisSongPlaying = currentSong?.id === song.id;
-  const isPlaying = isThisSongPlaying && contextIsPlaying;
-  const currentTime = isThisSongPlaying ? contextCurrentTime : 0;
+  let contextValue = null;
+  try {
+    if (!standalone) {
+      contextValue = useAudioPlayer();
+    }
+  } catch {
+  }
+  const useStandaloneMode = standalone || !contextValue;
+  const contextPlay = contextValue?.play;
+  const contextTogglePlay = contextValue?.togglePlay;
+  const contextSeek = contextValue?.seek;
+  const contextCurrentSong = contextValue?.currentSong;
+  const contextIsPlaying = contextValue?.isPlaying ?? false;
+  const contextCurrentTime = contextValue?.currentTime ?? 0;
+  const isThisSongPlayingInContext = !useStandaloneMode && contextCurrentSong?.id === song.id;
+  const isPlaying = useStandaloneMode ? localIsPlaying : isThisSongPlayingInContext && contextIsPlaying;
+  const currentTime = useStandaloneMode ? localCurrentTime : isThisSongPlayingInContext ? contextCurrentTime : 0;
   react.useEffect(() => {
-    if (!wavesurferRef.current || !isThisSongPlaying) return;
+    if (!useStandaloneMode) return;
+    const audio = new Audio();
+    audio.preload = "metadata";
+    localAudioRef.current = audio;
+    const handleTimeUpdate = () => {
+      setLocalCurrentTime(audio.currentTime);
+    };
+    const handleEnded = () => {
+      setLocalIsPlaying(false);
+      setLocalCurrentTime(0);
+    };
+    const handleLoadedMetadata = () => {
+      setTotalDuration(audio.duration);
+    };
+    audio.addEventListener("timeupdate", handleTimeUpdate);
+    audio.addEventListener("ended", handleEnded);
+    audio.addEventListener("loadedmetadata", handleLoadedMetadata);
+    return () => {
+      audio.removeEventListener("timeupdate", handleTimeUpdate);
+      audio.removeEventListener("ended", handleEnded);
+      audio.removeEventListener("loadedmetadata", handleLoadedMetadata);
+      audio.pause();
+      audio.src = "";
+    };
+  }, [useStandaloneMode]);
+  react.useEffect(() => {
+    if (!useStandaloneMode) return;
+    const handleOtherPlayerPlay = (event) => {
+      if (event.detail !== song.id && localAudioRef.current) {
+        localAudioRef.current.pause();
+        setLocalIsPlaying(false);
+      }
+    };
+    window.addEventListener(MINI_PLAYER_PLAY_EVENT, handleOtherPlayerPlay);
+    return () => {
+      window.removeEventListener(MINI_PLAYER_PLAY_EVENT, handleOtherPlayerPlay);
+    };
+  }, [useStandaloneMode, song.id]);
+  react.useEffect(() => {
+    if (!wavesurferRef.current) return;
+    const relevantCurrentTime = useStandaloneMode ? localCurrentTime : contextCurrentTime;
+    const shouldSync = useStandaloneMode ? localIsPlaying : isThisSongPlayingInContext;
+    if (!shouldSync) return;
     const waveDuration = wavesurferRef.current.getDuration();
-    if (waveDuration > 0 && contextCurrentTime >= 0) {
-      const progress = contextCurrentTime / waveDuration;
+    if (waveDuration > 0 && relevantCurrentTime >= 0) {
+      const progress = relevantCurrentTime / waveDuration;
       wavesurferRef.current.seekTo(Math.min(progress, 1));
     }
-  }, [contextCurrentTime, isThisSongPlaying]);
+  }, [localCurrentTime, contextCurrentTime, useStandaloneMode, localIsPlaying, isThisSongPlayingInContext]);
   react.useEffect(() => {
     if (!containerRef.current || !isVisible) return;
     const hasPeaks = song.peaks && song.peaks.length > 0;
@@ -354,18 +401,24 @@ function WaveformPlayer({
       height: waveformConfig.height,
       normalize: waveformConfig.normalize,
       interact: true,
-      // Allow clicking on waveform to seek
       // Only load audio URL if we don't have peaks (needed to generate waveform)
       url: hasPeaks ? void 0 : song.audioUrl,
       peaks: hasPeaks ? [song.peaks] : void 0,
       duration: hasPeaks ? song.duration || 0 : void 0
     });
+    wavesurfer.setMuted(true);
     wavesurfer.on("ready", () => {
       setIsReady(true);
       setTotalDuration(wavesurfer.getDuration() || song.duration || 0);
+      wavesurfer.setMuted(true);
     });
     wavesurfer.on("interaction", (newTime) => {
-      if (isThisSongPlaying) {
+      if (useStandaloneMode) {
+        if (localAudioRef.current) {
+          localAudioRef.current.currentTime = newTime;
+          setLocalCurrentTime(newTime);
+        }
+      } else if (isThisSongPlayingInContext && contextSeek) {
         contextSeek(newTime);
       }
     });
@@ -387,7 +440,8 @@ function WaveformPlayer({
     song.peaks,
     song.duration,
     isVisible,
-    isThisSongPlaying,
+    useStandaloneMode,
+    isThisSongPlayingInContext,
     contextSeek,
     waveformConfig.waveColor,
     waveformConfig.progressColor,
@@ -400,12 +454,32 @@ function WaveformPlayer({
   ]);
   const handlePlayClick = react.useCallback(() => {
     if (!song.id || !song.audioUrl) return;
-    if (isThisSongPlaying) {
-      contextTogglePlay();
+    if (useStandaloneMode) {
+      if (!localAudioRef.current) return;
+      if (localIsPlaying) {
+        localAudioRef.current.pause();
+        setLocalIsPlaying(false);
+      } else {
+        if (typeof window !== "undefined") {
+          window.dispatchEvent(
+            new CustomEvent(MINI_PLAYER_PLAY_EVENT, { detail: song.id })
+          );
+        }
+        if (localAudioRef.current.src !== song.audioUrl) {
+          localAudioRef.current.src = song.audioUrl;
+        }
+        localAudioRef.current.play().catch(() => {
+        });
+        setLocalIsPlaying(true);
+      }
     } else {
-      contextPlay(song);
+      if (isThisSongPlayingInContext) {
+        contextTogglePlay?.();
+      } else {
+        contextPlay?.(song);
+      }
     }
-  }, [song, isThisSongPlaying, contextPlay, contextTogglePlay]);
+  }, [song, useStandaloneMode, localIsPlaying, isThisSongPlayingInContext, contextPlay, contextTogglePlay]);
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {