原生 Web 集成

推荐把 wasm runtime 当成整页共享的单例。页面启动时创建一次，之后在多次解码与播放之间复用，不要把大型 wasm 模块放进每次点击的回调里重复初始化。

最小示例

import {
  createBrowserModuleLoader,
  createVgmstreamRuntimeManager,
} from '../assets/vgmstream-runtime.mjs';

const runtime = createVgmstreamRuntimeManager({
  loadModule: createBrowserModuleLoader({
    scriptUrl: '../assets/vgmstream_wasm_min.js',
    wasmUrl: '../assets/vgmstream_wasm_min.wasm',
  }),
});

async function playSelectedFile(file, audioElement) {
  const decoded = await runtime.decodeFile(file, {
    ignoreLoop: true,
    wantInfoJson: true,
    userActionAt: performance.now(),
  });

  audioElement.src = decoded.objectUrl;
  await audioElement.play();
}

时间指标建议

页面上建议只保留用户能感知的几个指标：wasm 下载、wasm 初始化、开始解码、解码耗时、开始播放，以及 WAV 输出大小。更深的诊断信息放到 DevTools console 更合适。

不要这样做

不要在每个点击处理器里新建 runtime。
不要在每次选择文件时重新下载 wasm。
不要把预热开销偷偷算进后面的播放指标里。
不要在切换当前曲目后忘记回收旧 blob URL。

Plain Web Integration

Use a single runtime manager for the whole page. Load once, reuse often, and keep the large wasm module out of per-click handlers.

Recommended flow

Create one runtime manager when the page boots.
Warm it on the first meaningful user interaction or let the first decode call warm it automatically.
Pass a File object into decodeFile(...).
Bind the returned objectUrl to an audio element.
Revoke old object URLs when switching tracks.

Minimal example

import {
  createBrowserModuleLoader,
  createVgmstreamRuntimeManager,
} from '../assets/vgmstream-runtime.mjs';

const runtime = createVgmstreamRuntimeManager({
  loadModule: createBrowserModuleLoader({
    scriptUrl: '../assets/vgmstream_wasm_min.js',
    wasmUrl: '../assets/vgmstream_wasm_min.wasm',
  }),
});

async function playSelectedFile(file, audioElement) {
  const decoded = await runtime.decodeFile(file, {
    ignoreLoop: true,
    wantInfoJson: true,
    userActionAt: performance.now(),
  });

  audioElement.src = decoded.objectUrl;
  await audioElement.play();
}

Timing guidance

Keep page-visible metrics concise: wasm fetch, wasm init, decode start, decode duration, playback start, and WAV output size. Put deeper diagnostics in DevTools console rather than in the page body.

Do not do this

Do not create a new runtime inside every click handler.
Do not fetch the wasm script again for every selected file.
Do not hide warmup cost inside a later playback metric.
Do not forget to revoke old blob URLs when replacing the current track.