react-audio-wavekit 0.1.8 → 0.2.1

package/README.md

@@ -32,7 +32,7 @@ Visualize existing audio files (mp3, wav, etc.) with playhead and seek support.
 
 ![AudioWaveform](https://react-audio-wavekit.netlify.app/audio-wave-form.png)
 
-Static waveform visualization with playhead and click-to-seek.
+Static waveform visualization with playhead and drag-to-seek.
 
 [▶ Demo](https://react-audio-wavekit.netlify.app/?path=/story/waveform-audiowaveform--default)
 
@@ -41,7 +41,12 @@ Static waveform visualization with playhead and click-to-seek.
   blob={audioBlob}
   currentTime={currentTime}
   duration={duration}
-  onSeek={(time) => (audioRef.current.currentTime = time)}
+  onSeekStart={() => audio.pause()}
+  onSeekDrag={(time) => setCurrentTime(time)}
+  onSeekEnd={(time) => {
+    audio.currentTime = time;
+    audio.play();
+  }}
 />
 ```
 
@@ -51,7 +56,10 @@ Static waveform visualization with playhead and click-to-seek.
 | `peaks` | `number[]` | - | Pre-computed peaks (0-1 range, skips decoding) |
 | `currentTime` | `number` | - | Current playback time in seconds |
 | `duration` | `number` | - | Total audio duration in seconds |
-| `onSeek` | `(time: number) => void` | - | Callback when user clicks on waveform |
+| `onSeek` | `(time: number) => void` | - | Callback for simple click-to-seek |
+| `onSeekStart` | `() => void` | - | Callback when drag starts (pause playback) |
+| `onSeekDrag` | `(time: number) => void` | - | Callback during drag (real-time updates) |
+| `onSeekEnd` | `(time: number) => void` | - | Callback when drag ends (resume playback) |
 | `suspense` | `boolean` | `false` | Enable React Suspense mode |
 | `appearance` | `AudioWaveformAppearance` | - | See [Appearance Options](#appearance-options) |
 

package/dist/index.d.ts

@@ -29,8 +29,14 @@ declare interface AudioWaveformProps extends React.CanvasHTMLAttributes<HTMLCanv
     currentTime?: number;
     /** Total audio duration in seconds (required for playhead positioning) */
     duration?: number;
-    /** Callback when user clicks/seeks on waveform */
+    /** Callback when user clicks/seeks on waveform (simple seek) */
     onSeek?: (time: number) => void;
+    /** Callback when drag-to-seek starts (use to pause playback) */
+    onSeekStart?: () => void;
+    /** Callback during drag-to-seek with current time (real-time updates) */
+    onSeekDrag?: (time: number) => void;
+    /** Callback when drag-to-seek ends (use to resume playback) */
+    onSeekEnd?: (time: number) => void;
 }
 
 declare interface AudioWaveformRef {
@@ -38,8 +44,8 @@ declare interface AudioWaveformRef {
 }
 
 /**
- * 실시간 오디오 주파수 시각화 컴포넌트
- * MediaRecorder의 오디오를 Web Audio API로 분석하여 바 형태로 렌더링
+ * Real-time audio frequency visualization component
+ * Analyzes MediaRecorder audio via Web Audio API and renders as bars
  */
 export declare const LiveRecorder: ForwardRefExoticComponent<LiveRecorderProps & RefAttributes<LiveRecorderRef>>;
 
@@ -102,7 +108,7 @@ declare interface LiveStreamingRecorderCanvasProps extends HTMLAttributes<HTMLCa
     className?: string;
     /** Inline styles for canvas element */
     style?: React.CSSProperties;
-    /** Waveform appearance configuration (barColor, barWidth, etc.) - scrollbar 설정은 Root에서만 유효 */
+    /** Waveform appearance configuration (barColor, barWidth, etc.) - scrollbar settings only apply in Root */
     appearance?: LiveStreamingRecorderAppearance;
 }
 

package/dist/recorder/live-streaming/recorder/recorder-compound.cjs

@@ -30,7 +30,7 @@ const LiveStreamingRecorderRoot = react.forwardRef(
           theme: themeClassName,
           visibility: hidden ? "hidden" : "auto",
           autoHide: "leave",
-          // 마우스가 영역을 벗어나면 숨김 (가장 대중적인 UX)
+          // Hide when mouse leaves area (most common UX)
           autoHideDelay: 400,
           dragScroll: true,
           clickScroll: true

package/dist/recorder/live-streaming/recorder/recorder-compound.js

@@ -28,7 +28,7 @@ const LiveStreamingRecorderRoot = forwardRef(
           theme: themeClassName,
           visibility: hidden ? "hidden" : "auto",
           autoHide: "leave",
-          // 마우스가 영역을 벗어나면 숨김 (가장 대중적인 UX)
+          // Hide when mouse leaves area (most common UX)
           autoHideDelay: 400,
           dragScroll: true,
           clickScroll: true

package/dist/waveform/index.cjs

@@ -9,7 +9,19 @@ const getInitialSampleCount = () => {
   if (typeof window === "undefined") return 500;
   return Math.max(500, Math.ceil(window.innerWidth));
 };
-const AudioWaveform = react.forwardRef(function AudioWaveform2({ blob, peaks: precomputedPeaks, appearance, suspense = false, currentTime, duration, onSeek, ...props }, ref) {
+const AudioWaveform = react.forwardRef(function AudioWaveform2({
+  blob,
+  peaks: precomputedPeaks,
+  appearance,
+  suspense = false,
+  currentTime,
+  duration,
+  onSeek,
+  onSeekStart,
+  onSeekDrag,
+  onSeekEnd,
+  ...props
+}, ref) {
   const [decodedPeaks, setDecodedPeaks] = react.useState(null);
   const [error, setError] = react.useState(null);
   const blobRef = react.useRef(null);
@@ -63,6 +75,9 @@ const AudioWaveform = react.forwardRef(function AudioWaveform2({ blob, peaks: pr
       currentTime,
       duration,
       onSeek,
+      onSeekStart,
+      onSeekDrag,
+      onSeekEnd,
       ...props
     }
   );

package/dist/waveform/index.js

@@ -7,7 +7,19 @@ const getInitialSampleCount = () => {
   if (typeof window === "undefined") return 500;
   return Math.max(500, Math.ceil(window.innerWidth));
 };
-const AudioWaveform = forwardRef(function AudioWaveform2({ blob, peaks: precomputedPeaks, appearance, suspense = false, currentTime, duration, onSeek, ...props }, ref) {
+const AudioWaveform = forwardRef(function AudioWaveform2({
+  blob,
+  peaks: precomputedPeaks,
+  appearance,
+  suspense = false,
+  currentTime,
+  duration,
+  onSeek,
+  onSeekStart,
+  onSeekDrag,
+  onSeekEnd,
+  ...props
+}, ref) {
   const [decodedPeaks, setDecodedPeaks] = useState(null);
   const [error, setError] = useState(null);
   const blobRef = useRef(null);
@@ -61,6 +73,9 @@ const AudioWaveform = forwardRef(function AudioWaveform2({ blob, peaks: precompu
       currentTime,
       duration,
       onSeek,
+      onSeekStart,
+      onSeekDrag,
+      onSeekEnd,
       ...props
     }
   );

package/dist/waveform/waveform-renderer.cjs

@@ -3,10 +3,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const jsxRuntime = require("react/jsx-runtime");
 const react = require("react");
 const constants = require("../constants.cjs");
-const WaveformRenderer = react.forwardRef(function WaveformRenderer2({ peaks, appearance, currentTime, duration, onSeek, onClick, style, ...props }, ref) {
+const WaveformRenderer = react.forwardRef(function WaveformRenderer2({ peaks, appearance, currentTime, duration, onSeek, onSeekStart, onSeekDrag, onSeekEnd, onClick, style, ...props }, ref) {
   const canvasRef = react.useRef(null);
   const sizeRef = react.useRef({ width: 0, height: 0 });
   const rafRef = react.useRef(0);
+  const isDraggingRef = react.useRef(false);
   react.useImperativeHandle(ref, () => ({
     canvas: canvasRef.current
   }));
@@ -77,18 +78,62 @@ const WaveformRenderer = react.forwardRef(function WaveformRenderer2({ peaks, ap
   react.useEffect(() => {
     drawWaveform();
   }, [drawWaveform]);
+  const getTimeFromPosition = react.useCallback(
+    (clientX) => {
+      const canvas = canvasRef.current;
+      if (!canvas || !duration || duration <= 0) return 0;
+      const rect = canvas.getBoundingClientRect();
+      const x = clientX - rect.left;
+      const ratio = Math.max(0, Math.min(x / rect.width, 1));
+      return ratio * duration;
+    },
+    [duration]
+  );
+  react.useEffect(() => {
+    const handleMouseMove = (e) => {
+      if (!isDraggingRef.current) return;
+      const time = getTimeFromPosition(e.clientX);
+      onSeekDrag?.(time);
+    };
+    const handleMouseUp = (e) => {
+      if (!isDraggingRef.current) return;
+      isDraggingRef.current = false;
+      document.body.style.cursor = "";
+      document.body.style.userSelect = "";
+      const time = getTimeFromPosition(e.clientX);
+      onSeekEnd?.(time);
+    };
+    if (onSeekDrag || onSeekEnd) {
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+    }
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove);
+      document.removeEventListener("mouseup", handleMouseUp);
+    };
+  }, [getTimeFromPosition, onSeekDrag, onSeekEnd]);
+  const handleMouseDown = react.useCallback(
+    (e) => {
+      if (!duration || duration <= 0) return;
+      if (onSeekStart || onSeekDrag || onSeekEnd) {
+        isDraggingRef.current = true;
+        document.body.style.cursor = "grabbing";
+        document.body.style.userSelect = "none";
+        onSeekStart?.();
+        const time = getTimeFromPosition(e.clientX);
+        onSeekDrag?.(time);
+      }
+    },
+    [duration, onSeekStart, onSeekDrag, onSeekEnd, getTimeFromPosition]
+  );
   const handleClick = react.useCallback(
     (e) => {
+      if (onSeekStart || onSeekDrag || onSeekEnd) return;
       if (!onSeek || !duration || duration <= 0) return;
-      const canvas = canvasRef.current;
-      if (!canvas) return;
-      const rect = canvas.getBoundingClientRect();
-      const x = e.clientX - rect.left;
-      const clickRatio = x / rect.width;
-      const newTime = Math.max(0, Math.min(clickRatio * duration, duration));
-      onSeek(newTime);
+      const time = getTimeFromPosition(e.clientX);
+      onSeek(time);
     },
-    [onSeek, duration]
+    [onSeek, duration, onSeekStart, onSeekDrag, onSeekEnd, getTimeFromPosition]
   );
   const handleKeyDown = react.useCallback(
     (e) => {
@@ -120,25 +165,27 @@ const WaveformRenderer = react.forwardRef(function WaveformRenderer2({ peaks, ap
     const mins = Math.floor(seconds / 60);
     const secs = Math.floor(seconds % 60);
     if (mins > 0) {
-      return `${mins}분 ${secs}초`;
+      return `${mins} minute${mins > 1 ? "s" : ""} ${secs} second${secs !== 1 ? "s" : ""}`;
     }
-    return `${secs}초`;
+    return `${secs} second${secs !== 1 ? "s" : ""}`;
   };
-  const isInteractive = !!onSeek && !!duration && duration > 0;
+  const isInteractive = (!!onSeek || !!onSeekStart || !!onSeekDrag || !!onSeekEnd) && !!duration && duration > 0;
+  const isDragEnabled = !!onSeekStart || !!onSeekDrag || !!onSeekEnd;
   return /* @__PURE__ */ jsxRuntime.jsx(
     "canvas",
     {
       ref: canvasRef,
       role: isInteractive ? "slider" : "img",
-      "aria-label": isInteractive ? "오디오 탐색" : "오디오 파형",
+      "aria-label": isInteractive ? "Audio seek" : "Audio waveform",
       "aria-valuemin": isInteractive ? 0 : void 0,
       "aria-valuemax": isInteractive ? Math.floor(duration) : void 0,
       "aria-valuenow": isInteractive ? Math.floor(currentTime ?? 0) : void 0,
       "aria-valuetext": isInteractive ? `${formatTimeForScreen(currentTime ?? 0)} / ${formatTimeForScreen(duration)}` : void 0,
       tabIndex: isInteractive ? 0 : -1,
+      onMouseDown: isDragEnabled ? handleMouseDown : void 0,
       onClick: handleClick,
       onKeyDown: isInteractive ? handleKeyDown : void 0,
-      style: { cursor: isInteractive ? "pointer" : void 0, ...style },
+      style: { cursor: isInteractive ? isDragEnabled ? "grab" : "pointer" : void 0, ...style },
       ...props
     }
   );

package/dist/waveform/waveform-renderer.js

@@ -1,10 +1,11 @@
 import { jsx } from "react/jsx-runtime";
 import { forwardRef, useRef, useImperativeHandle, useCallback, useEffect } from "react";
 import { DEFAULT_WAVEFORM_APPEARANCE, DEFAULT_PLAYHEAD_APPEARANCE } from "../constants.js";
-const WaveformRenderer = forwardRef(function WaveformRenderer2({ peaks, appearance, currentTime, duration, onSeek, onClick, style, ...props }, ref) {
+const WaveformRenderer = forwardRef(function WaveformRenderer2({ peaks, appearance, currentTime, duration, onSeek, onSeekStart, onSeekDrag, onSeekEnd, onClick, style, ...props }, ref) {
   const canvasRef = useRef(null);
   const sizeRef = useRef({ width: 0, height: 0 });
   const rafRef = useRef(0);
+  const isDraggingRef = useRef(false);
   useImperativeHandle(ref, () => ({
     canvas: canvasRef.current
   }));
@@ -75,18 +76,62 @@ const WaveformRenderer = forwardRef(function WaveformRenderer2({ peaks, appearan
   useEffect(() => {
     drawWaveform();
   }, [drawWaveform]);
+  const getTimeFromPosition = useCallback(
+    (clientX) => {
+      const canvas = canvasRef.current;
+      if (!canvas || !duration || duration <= 0) return 0;
+      const rect = canvas.getBoundingClientRect();
+      const x = clientX - rect.left;
+      const ratio = Math.max(0, Math.min(x / rect.width, 1));
+      return ratio * duration;
+    },
+    [duration]
+  );
+  useEffect(() => {
+    const handleMouseMove = (e) => {
+      if (!isDraggingRef.current) return;
+      const time = getTimeFromPosition(e.clientX);
+      onSeekDrag?.(time);
+    };
+    const handleMouseUp = (e) => {
+      if (!isDraggingRef.current) return;
+      isDraggingRef.current = false;
+      document.body.style.cursor = "";
+      document.body.style.userSelect = "";
+      const time = getTimeFromPosition(e.clientX);
+      onSeekEnd?.(time);
+    };
+    if (onSeekDrag || onSeekEnd) {
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+    }
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove);
+      document.removeEventListener("mouseup", handleMouseUp);
+    };
+  }, [getTimeFromPosition, onSeekDrag, onSeekEnd]);
+  const handleMouseDown = useCallback(
+    (e) => {
+      if (!duration || duration <= 0) return;
+      if (onSeekStart || onSeekDrag || onSeekEnd) {
+        isDraggingRef.current = true;
+        document.body.style.cursor = "grabbing";
+        document.body.style.userSelect = "none";
+        onSeekStart?.();
+        const time = getTimeFromPosition(e.clientX);
+        onSeekDrag?.(time);
+      }
+    },
+    [duration, onSeekStart, onSeekDrag, onSeekEnd, getTimeFromPosition]
+  );
   const handleClick = useCallback(
     (e) => {
+      if (onSeekStart || onSeekDrag || onSeekEnd) return;
       if (!onSeek || !duration || duration <= 0) return;
-      const canvas = canvasRef.current;
-      if (!canvas) return;
-      const rect = canvas.getBoundingClientRect();
-      const x = e.clientX - rect.left;
-      const clickRatio = x / rect.width;
-      const newTime = Math.max(0, Math.min(clickRatio * duration, duration));
-      onSeek(newTime);
+      const time = getTimeFromPosition(e.clientX);
+      onSeek(time);
     },
-    [onSeek, duration]
+    [onSeek, duration, onSeekStart, onSeekDrag, onSeekEnd, getTimeFromPosition]
   );
   const handleKeyDown = useCallback(
     (e) => {
@@ -118,25 +163,27 @@ const WaveformRenderer = forwardRef(function WaveformRenderer2({ peaks, appearan
     const mins = Math.floor(seconds / 60);
     const secs = Math.floor(seconds % 60);
     if (mins > 0) {
-      return `${mins}분 ${secs}초`;
+      return `${mins} minute${mins > 1 ? "s" : ""} ${secs} second${secs !== 1 ? "s" : ""}`;
     }
-    return `${secs}초`;
+    return `${secs} second${secs !== 1 ? "s" : ""}`;
   };
-  const isInteractive = !!onSeek && !!duration && duration > 0;
+  const isInteractive = (!!onSeek || !!onSeekStart || !!onSeekDrag || !!onSeekEnd) && !!duration && duration > 0;
+  const isDragEnabled = !!onSeekStart || !!onSeekDrag || !!onSeekEnd;
   return /* @__PURE__ */ jsx(
     "canvas",
     {
       ref: canvasRef,
       role: isInteractive ? "slider" : "img",
-      "aria-label": isInteractive ? "오디오 탐색" : "오디오 파형",
+      "aria-label": isInteractive ? "Audio seek" : "Audio waveform",
       "aria-valuemin": isInteractive ? 0 : void 0,
       "aria-valuemax": isInteractive ? Math.floor(duration) : void 0,
       "aria-valuenow": isInteractive ? Math.floor(currentTime ?? 0) : void 0,
       "aria-valuetext": isInteractive ? `${formatTimeForScreen(currentTime ?? 0)} / ${formatTimeForScreen(duration)}` : void 0,
       tabIndex: isInteractive ? 0 : -1,
+      onMouseDown: isDragEnabled ? handleMouseDown : void 0,
       onClick: handleClick,
       onKeyDown: isInteractive ? handleKeyDown : void 0,
-      style: { cursor: isInteractive ? "pointer" : void 0, ...style },
+      style: { cursor: isInteractive ? isDragEnabled ? "grab" : "pointer" : void 0, ...style },
       ...props
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-audio-wavekit",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "license": "CC0-1.0",
   "type": "module",
   "main": "dist/index.cjs",
@@ -42,7 +42,9 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
+    "react-dom": ">=18.0.0",
+    "overlayscrollbars": "^2.0.0",
+    "overlayscrollbars-react": "^0.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.8",
@@ -68,8 +70,6 @@
     "vitest": "^4.0.15"
   },
   "dependencies": {
-    "mpg123-decoder": "^1.0.3",
-    "overlayscrollbars": "^2.13.0",
-    "overlayscrollbars-react": "^0.5.6"
+    "mpg123-decoder": "^1.0.3"
   }
 }