shank-wavesurfer 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# ShankWavesurfer
+
+ShankWavesurfer is a Vite + vanilla TypeScript audio player library that mounts into one root element and ships with an integrated dark instrument style UI, waveform view, spectrogram view, local file support, remote URL loading, zoomable timeline navigation, drag selection, and region playback controls.
+
+## Quick Start
+
+```ts
+import { ShankWavesurfer } from "shank-wavesurfer";
+
+const player = new ShankWavesurfer("player-root");
+await player.load("http://127.0.0.1:8080/a.mp3");
+```
+
+You can also load a local file object:
+
+```ts
+const player = new ShankWavesurfer(document.getElementById("player-root") as HTMLElement);
+const file = new File([], "demo.mp3");
+await player.load(file);
+```
+
+## Implemented Features
+
+- Single call mount API with `constructor(root: string | HTMLElement)`.
+- Public methods: `load`, `play`, `pause`, `stop`, `destroy`.
+- Integrated Chinese UI. Consumers only provide a root div.
+- Local audio through file picker and drag and drop.
+- Remote URL loading through the hidden `<audio>` element.
+- Web Audio graph based on `AudioContext`, `MediaElementAudioSourceNode`, `ChannelSplitterNode`, `ChannelMergerNode`, and `AnalyserNode`.
+- Bottom transport controls for play, pause, stop, current time, total time, volume, visualization mode, and channel mode.
+- Waveform and spectrogram canvas rendering.
+- Stereo, left, and right channel display modes.
+- Shared timeline when both channels are shown.
+- Click to seek and immediately play.
+- Mouse wheel zoom on the main chart and timeline.
+- Full overview timeline with current zoom window overlay.
+- Drag selection with custom right click menu containing `播放` `循环播放` `取消选中`.
+- IndexedDB overview cache.
+- PCM 解码后统一生成波形与 STFT 时频谱数据。
+- 已加入大文件分析基础设施：`ffmpeg.wasm` 运行时封装 + 远程文件大小探测工具。
+- Worker driven overview/STFT matrix generation.
+- Responsive canvas sizing with `ResizeObserver`.
+
+## Demo
+
+The demo entrypoint is [index.html](/data/project/shank-wavesurfer/index.html) and mounts the player into `#player-root` through [src/main.ts](/data/project/shank-wavesurfer/src/main.ts).
+
+## Architecture Notes
+
+- [src/lib/ShankWavesurfer.ts](/data/project/shank-wavesurfer/src/lib/ShankWavesurfer.ts) contains the public class, DOM mounting, interaction model, render loop, timeline logic, and audio graph wiring.
+- [src/lib/overview.worker.ts](/data/project/shank-wavesurfer/src/lib/overview.worker.ts) consumes decoded PCM and generates waveform peaks plus STFT spectrogram data off the main thread.
+- [src/lib/cache.ts](/data/project/shank-wavesurfer/src/lib/cache.ts) stores and restores overview data from IndexedDB.
+- [src/lib/style.ts](/data/project/shank-wavesurfer/src/lib/style.ts) injects the instrument styled CSS directly into the document.
+
+## Large File Strategy And Tradeoffs
+
+This project now uses a real PCM-based visualization pipeline:
+
+1. Playback still uses the browser `<audio>` element for native streaming.
+2. Visualization generation fetches/reads the source as an `ArrayBuffer`, decodes it to PCM, then sends the channel data to a worker.
+3. The worker computes both waveform peaks and STFT spectrogram data from the same PCM source.
+4. IndexedDB stores the resulting overview so repeat loads can skip recomputation.
+
+Tradeoffs and browser constraints:
+
+- True waveform + STFT generation requires full decode access to the audio source.
+- For very large files, browser memory usage can become substantial because PCM must exist at least transiently during decode and worker transfer.
+- Remote URLs require CORS access that permits fetching the file body, not only media-element playback.
+- The library no longer fakes spectrogram data when decode succeeds; if decode/fetch is blocked, visualization generation will fail honestly instead of drawing a fake heatmap.
+
+This is more accurate than the earlier byte-statistics approach, but less forgiving on huge files because real PCM analysis is fundamentally more expensive.
+
+## Large File Roadmap (in progress)
+
+A more aggressive large-file path is now being introduced:
+
+- `src/lib/large-file-analysis.ts` provides an `ffmpeg.wasm` runtime wrapper.
+- It is intended for future segmented local-file and HTTP Range based analysis workflows.
+- The current player still uses the direct decode path for rendering, but the project now contains the required runtime layer for migrating toward segmented analysis of files larger than ~50MB.
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+Build outputs:
+
+- Demo build: `dist/demo`
+- Library build: `dist/lib`
+
+## Notes
+
+- Remote visualization depends on the target server exposing the audio with compatible CORS headers.
+- The library injects its own CSS and hidden audio element, so no extra markup is required beyond the root container.

package/dist/lib/assets/overview.worker-DszIAZnU.js

@@ -0,0 +1 @@
+(function(){"use strict";const S=self;S.onmessage=t=>{const n=t.data;n.type==="generate"&&O(n)};async function O(t){try{const n=Math.max(512,t.sampleCount),o=[...t.waveformLeft],r=[...t.waveformRight],e=await P(t),a={version:2,key:t.sourceKey,duration:t.duration,sampleCount:n,left:o,right:r,spectrogram:e,method:"pcm-stft-overview-progressive",complete:!0,generatedAt:Date.now()};S.postMessage({type:"done",requestId:t.requestId,data:a})}catch(n){S.postMessage({type:"error",requestId:t.requestId,error:n instanceof Error?n.message:"PCM/STFT 生成失败"})}}async function P(t){const r=new Array(153600).fill(0),e=new Array(96*1600).fill(0),a=b(t.leftChannel),l=b(t.rightChannel),u=B(2048),f=t.sampleRate/2;for(let c=0;c<1600;c+=96){const i=Math.min(1600,c+96),s=new Array((i-c)*96).fill(0),m=new Array((i-c)*96).fill(0);for(let h=c;h<i;h+=1){const M=Math.floor(h/Math.max(1,1599)*Math.max(0,t.leftChannel.length-2048)),p=a?null:C(t.leftChannel,M,2048,512,u),d=l?null:C(t.rightChannel,M,2048,512,u);for(let I=0;I<96;I+=1){const w=Math.floor(F(I/96,1024)),R=Math.max(w+1,Math.floor(F((I+1)/96,2048/2))),v=p?_(p,w,R):-110,U=d?_(d,w,R):-110,T=(h-c)*96+I,A=h*96+I,E=a?0:y(v),N=l?0:y(U);s[T]=E,m[T]=N,r[A]=E,e[A]=N}}S.postMessage({type:"chunk",requestId:t.requestId,sourceKey:t.sourceKey,startColumn:c,endColumn:i,bins:96,columns:1600,left:s,right:m,sampleRate:t.sampleRate,maxFrequencyHz:f,progress:i/Math.max(1,1600)}),await q()}return{bins:96,columns:1600,left:r,right:e,sampleRate:t.sampleRate,maxFrequencyHz:f}}function C(t,n,o,r,e){const l=new Float32Array(o/2);for(let u=0;u<3;u+=1){const f=n+(u-1)*r,c=new Float32Array(o),i=new Float32Array(o);for(let s=0;s<o;s+=1){const m=Z(f+s,0,t.length-1);c[s]=(t[m]??0)*e[s]}D(c,i);for(let s=0;s<l.length;s+=1)l[s]+=Math.sqrt(c[s]*c[s]+i[s]*i[s])}for(let u=0;u<l.length;u+=1)l[u]/=3;return l}function _(t,n,o){let r=0,e=0;for(let l=n;l<Math.min(t.length,o);l+=1)r+=t[l]*t[l],e+=1;const a=r/Math.max(1,e);return 10*Math.log10(a+1e-12)}function y(t){const n=x((t- -110)/92,0,1);return Math.round(Math.pow(n,.85)*255)}function F(t,n){return Math.pow(x(t,0,1),1.8)*n}function B(t){const n=new Float32Array(t);for(let o=0;o<t;o+=1)n[o]=.5*(1-Math.cos(2*Math.PI*o/(t-1)));return n}function D(t,n){const o=t.length;let r=0;for(let e=0;e<o;e+=1){e<r&&(g(t,e,r),g(n,e,r));let a=o>>1;for(;r>=a&&a>=2;)r-=a,a>>=1;r+=a}for(let e=2;e<=o;e<<=1){const a=e>>1,l=-2*Math.PI/e,u=Math.cos(l),f=Math.sin(l);for(let c=0;c<o;c+=e){let i=1,s=0;for(let m=0;m<a;m+=1){const h=c+m,M=h+a,p=i*t[M]-s*n[M],d=i*n[M]+s*t[M];t[M]=t[h]-p,n[M]=n[h]-d,t[h]+=p,n[h]+=d;const I=i*u-s*f,w=i*f+s*u;i=I,s=w}}}}function g(t,n,o){const r=t[n];t[n]=t[o],t[o]=r}function b(t,n=.002,o=35e-5){let r=0,e=0,a=0;const l=Math.max(1,Math.floor(t.length/2e4));for(let f=0;f<t.length;f+=l){const c=t[f]??0,i=Math.abs(c);if(r=Math.max(r,i),e+=c*c,a+=1,r>n)return!1}return Math.sqrt(e/Math.max(1,a))<=o}function x(t,n,o){return Math.min(o,Math.max(n,t))}function Z(t,n,o){return Math.min(o,Math.max(n,t|0))}function q(){return new Promise(t=>setTimeout(t,0))}})();

package/dist/lib/assets/worker-BAOIWoxA.js

@@ -0,0 +1 @@
+(function(){"use strict";const i="https://unpkg.com/@ffmpeg/core@0.12.9/dist/umd/ffmpeg-core.js";var E;(function(t){t.LOAD="LOAD",t.EXEC="EXEC",t.FFPROBE="FFPROBE",t.WRITE_FILE="WRITE_FILE",t.READ_FILE="READ_FILE",t.DELETE_FILE="DELETE_FILE",t.RENAME="RENAME",t.CREATE_DIR="CREATE_DIR",t.LIST_DIR="LIST_DIR",t.DELETE_DIR="DELETE_DIR",t.ERROR="ERROR",t.DOWNLOAD="DOWNLOAD",t.PROGRESS="PROGRESS",t.LOG="LOG",t.MOUNT="MOUNT",t.UNMOUNT="UNMOUNT"})(E||(E={}));const f=new Error("unknown message type"),a=new Error("ffmpeg is not loaded, call `await ffmpeg.load()` first"),u=new Error("failed to import ffmpeg-core.js");let r;const O=async({coreURL:t,wasmURL:n,workerURL:e})=>{const o=!r;try{t||(t=i),importScripts(t)}catch{if((!t||t===i)&&(t=i.replace("/umd/","/esm/")),self.createFFmpegCore=(await import(t)).default,!self.createFFmpegCore)throw u}const s=t,c=n||t.replace(/.js$/g,".wasm"),p=e||t.replace(/.js$/g,".worker.js");return r=await self.createFFmpegCore({mainScriptUrlOrBlob:`${s}#${btoa(JSON.stringify({wasmURL:c,workerURL:p}))}`}),r.setLogger(R=>self.postMessage({type:E.LOG,data:R})),r.setProgress(R=>self.postMessage({type:E.PROGRESS,data:R})),o},m=({args:t,timeout:n=-1})=>{r.setTimeout(n),r.exec(...t);const e=r.ret;return r.reset(),e},l=({args:t,timeout:n=-1})=>{r.setTimeout(n),r.ffprobe(...t);const e=r.ret;return r.reset(),e},D=({path:t,data:n})=>(r.FS.writeFile(t,n),!0),S=({path:t,encoding:n})=>r.FS.readFile(t,{encoding:n}),I=({path:t})=>(r.FS.unlink(t),!0),L=({oldPath:t,newPath:n})=>(r.FS.rename(t,n),!0),N=({path:t})=>(r.FS.mkdir(t),!0),A=({path:t})=>{const n=r.FS.readdir(t),e=[];for(const o of n){const s=r.FS.stat(`${t}/${o}`),c=r.FS.isDir(s.mode);e.push({name:o,isDir:c})}return e},k=({path:t})=>(r.FS.rmdir(t),!0),w=({fsType:t,options:n,mountPoint:e})=>{const o=t,s=r.FS.filesystems[o];return s?(r.FS.mount(s,n,e),!0):!1},b=({mountPoint:t})=>(r.FS.unmount(t),!0);self.onmessage=async({data:{id:t,type:n,data:e}})=>{const o=[];let s;try{if(n!==E.LOAD&&!r)throw a;switch(n){case E.LOAD:s=await O(e);break;case E.EXEC:s=m(e);break;case E.FFPROBE:s=l(e);break;case E.WRITE_FILE:s=D(e);break;case E.READ_FILE:s=S(e);break;case E.DELETE_FILE:s=I(e);break;case E.RENAME:s=L(e);break;case E.CREATE_DIR:s=N(e);break;case E.LIST_DIR:s=A(e);break;case E.DELETE_DIR:s=k(e);break;case E.MOUNT:s=w(e);break;case E.UNMOUNT:s=b(e);break;default:throw f}}catch(c){self.postMessage({id:t,type:E.ERROR,data:c.toString()});return}s instanceof Uint8Array&&o.push(s.buffer),self.postMessage({id:t,type:n,data:s},o)}})();

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { ShankWavesurfer } from "./lib/ShankWavesurfer";
+export { LargeFileAnalysisRuntime, probeRemoteFileSize } from "./lib/large-file-analysis";
+export type { ChannelMode, OverviewData, SelectionRange, ViewMode } from "./lib/types";

package/dist/lib/lib/ShankWavesurfer.d.ts

@@ -0,0 +1,127 @@
+export declare class ShankWavesurfer {
+    private readonly root;
+    private readonly shell;
+    private readonly stage;
+    private readonly mainCanvas;
+    private readonly overlayCanvas;
+    private readonly timelineCanvas;
+    private readonly audio;
+    private readonly fileInput;
+    private readonly statusTextEl;
+    private readonly sourceTextEl;
+    private readonly cacheTextEl;
+    private readonly timeTextEl;
+    private readonly selectionTextEl;
+    private readonly dropIndicatorEl;
+    private readonly volumeSlider;
+    private readonly contextMenu;
+    private readonly cache;
+    private readonly workers;
+    private readonly audioGraph;
+    private readonly resizeObserver;
+    private readonly cleanupCallbacks;
+    private readonly spectrogramLeftCanvas;
+    private readonly spectrogramRightCanvas;
+    private readonly spectrogramLeftContext;
+    private readonly spectrogramRightContext;
+    private readonly spectrogramLeftReady;
+    private readonly spectrogramRightReady;
+    private viewMode;
+    private channelMode;
+    private overview;
+    private pendingOverview;
+    private currentSource;
+    private activeRequestId;
+    private selection;
+    private loopSelection;
+    private regionPlaybackEnd;
+    private zoom;
+    private viewportStart;
+    private pointerMode;
+    private dragAnchorTime;
+    private dragAnchorX;
+    private panAnchorX;
+    private panAnchorViewportStart;
+    private timelineDragMode;
+    private timelineWindowGrabOffset;
+    private suppressAutoViewportFollow;
+    private previousVolumeBeforeMute;
+    private dragDepth;
+    private needsRender;
+    private destroyed;
+    private rafId;
+    private canvasCssWidth;
+    private canvasCssHeight;
+    private timelineCssWidth;
+    private timelineCssHeight;
+    constructor(root: string | HTMLElement);
+    load(input: string | File): Promise<void>;
+    play(): Promise<void>;
+    pause(): void;
+    stop(): void;
+    destroy(): void;
+    private renderTemplate;
+    private bindEvents;
+    private handleWorkerMessage;
+    private applyOverview;
+    private waitForMetadata;
+    private handleStagePointerDown;
+    private handleStagePointerMove;
+    private handleStagePointerUp;
+    private handleStagePointerCancel;
+    private handleStageContextMenu;
+    private handleStageWheel;
+    private handleTimelinePointerDown;
+    private handleTimelinePointerMove;
+    private handleTimelinePointerUp;
+    private handleTimelineWheel;
+    private handleDragEnter;
+    private handleDragOver;
+    private handleDragLeave;
+    private handleDrop;
+    private seekTo;
+    private playSelection;
+    private clearSelection;
+    private zoomAround;
+    private centerViewportOn;
+    private ensurePlayheadVisible;
+    private startRenderLoop;
+    private enforceSelectionPlayback;
+    private render;
+    private renderPlaceholder;
+    private getPanels;
+    private renderGrid;
+    private renderPanelShell;
+    private renderWaveformPanel;
+    private renderWaveformShape;
+    private renderSpectrogramPanel;
+    private getSpectrogramAxisWidth;
+    private renderFrequencyAxis;
+    private renderOverlay;
+    private renderTimeline;
+    private resetSpectrogram;
+    private paintFullSpectrogramFromOverview;
+    private paintSpectrogramChunk;
+    private paintSpectrogramColumn;
+    private handleResize;
+    private getWindowBounds;
+    private getStageInteractiveWidth;
+    private getStageRelativeX;
+    private positionToViewportTime;
+    private timeToViewportX;
+    private safeDuration;
+    private setStatus;
+    private setCacheStatus;
+    private updatePlayToggleButton;
+    private updateVolumeButton;
+    private updateChannelButtons;
+    private updateTimeReadout;
+    private updateSelectionLabel;
+    private isOverviewCompatible;
+    private hideContextMenu;
+    private markDirty;
+    private query;
+    private queryAll;
+    private getRelativeX;
+    private listen;
+}

package/dist/lib/lib/cache.d.ts

@@ -0,0 +1,7 @@
+import type { OverviewData } from "./types";
+export declare class OverviewCache {
+    private dbPromise;
+    private open;
+    get(key: string): Promise<OverviewData | null>;
+    set(data: OverviewData): Promise<void>;
+}

package/dist/lib/lib/large-file-analysis.d.ts

@@ -0,0 +1,22 @@
+export interface AnalysisCapabilities {
+    ffmpegAvailable: boolean;
+    rangeFetchRecommended: boolean;
+    segmentedLocalRecommended: boolean;
+}
+export interface LargeFilePlan {
+    mode: "direct-decode" | "ffmpeg-segmented";
+    reason: string;
+}
+export declare class LargeFileAnalysisRuntime {
+    private ffmpeg;
+    private loadingPromise;
+    private loaded;
+    getCapabilities(): AnalysisCapabilities;
+    choosePlan(byteSize: number, sourceKind: "file" | "url"): LargeFilePlan;
+    ensureLoaded(): Promise<void>;
+    writeInput(name: string, input: File | ArrayBuffer | Uint8Array): Promise<void>;
+    exec(args: string[]): Promise<void>;
+    readFile(name: string): Promise<Uint8Array>;
+    removeFiles(names: string[]): Promise<void>;
+}
+export declare function probeRemoteFileSize(url: string): Promise<number | null>;

package/dist/lib/lib/overview.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/lib/style.d.ts

@@ -0,0 +1 @@
+export declare const SHANK_WAVESURFER_STYLES: string;

package/dist/lib/lib/types.d.ts

@@ -0,0 +1,78 @@
+export type ChannelMode = "stereo" | "left" | "right" | "dual";
+export type ViewMode = "waveform" | "spectrogram";
+export type SourceDescriptor = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "file";
+    file: File;
+};
+export interface SpectrogramData {
+    bins: number;
+    columns: number;
+    left: number[];
+    right: number[];
+    sampleRate?: number;
+    maxFrequencyHz?: number;
+}
+export interface OverviewData {
+    version: 2;
+    key: string;
+    duration: number;
+    sampleCount: number;
+    left: number[];
+    right: number[];
+    spectrogram: SpectrogramData;
+    method: string;
+    complete: boolean;
+    generatedAt: number;
+}
+export interface SelectionRange {
+    start: number;
+    end: number;
+}
+export interface SourceMeta {
+    key: string;
+    kind: "url" | "file";
+    label: string;
+    file?: File;
+    url?: string;
+    objectUrl?: string;
+}
+export interface OverviewWorkerGenerateMessage {
+    type: "generate";
+    requestId: string;
+    sourceKey: string;
+    duration: number;
+    sampleCount: number;
+    sampleRate: number;
+    waveformLeft: number[];
+    waveformRight: number[];
+    leftChannel: Float32Array;
+    rightChannel: Float32Array;
+}
+export interface OverviewWorkerChunkMessage {
+    type: "chunk";
+    requestId: string;
+    sourceKey: string;
+    startColumn: number;
+    endColumn: number;
+    bins: number;
+    columns: number;
+    left: number[];
+    right: number[];
+    sampleRate: number;
+    maxFrequencyHz: number;
+    progress: number;
+}
+export interface OverviewWorkerDoneMessage {
+    type: "done";
+    requestId: string;
+    data: OverviewData;
+}
+export interface OverviewWorkerErrorMessage {
+    type: "error";
+    requestId: string;
+    error: string;
+}
+export type OverviewWorkerResponse = OverviewWorkerChunkMessage | OverviewWorkerDoneMessage | OverviewWorkerErrorMessage;