refactor(web): 明确错误处理逻辑

Author: apoint123

crates/ffmpeg_wasm/build.rs

@@ -27,6 +27,7 @@ fn main() {
         "_wasm_decoder_set_compute_peaks",
         "_wasm_decoder_get_frame_min",
         "_wasm_decoder_get_frame_max",
+        "_wasm_get_last_error",
     ];
     let exports_json = serde_json::to_string(&exports).unwrap();
 

web/src/audio-core/core/audio-renderer.ts

@@ -7,12 +7,10 @@ export class AudioRenderer {
 	private gainNode: GainNode | null;
 	private _isWorkletLoaded = false;
 	private initPromise: Promise<void> | null = null;
-	private stWasmBytes: ArrayBuffer | null = null;
 
 	constructor(
 		private audioCtx: AudioContext,
 		private workletUrl: string,
-		private stWasmUrl: string,
 		gainNode?: GainNode,
 	) {
 		this.gainNode = gainNode || null;
@@ -35,11 +33,6 @@ export class AudioRenderer {
 			return;
 		}
 
-		if (!this.stWasmBytes) {
-			const resp = await fetch(this.stWasmUrl);
-			this.stWasmBytes = await resp.arrayBuffer();
-		}
-
 		if (!this.initPromise) {
 			this.initPromise = this.audioCtx.audioWorklet.addModule(this.workletUrl);
 		}
@@ -68,16 +61,13 @@ export class AudioRenderer {
 		tempo: number,
 		pitch: number,
 		rate: number,
+		stWasmBytes: ArrayBuffer,
 	): Promise<void> {
 		return new Promise((resolve, reject) => {
 			if (!this._isWorkletLoaded || !this.workletNode) {
 				return reject(new Error("Worklet not loaded"));
 			}
 
-			if (!this.stWasmBytes) {
-				return reject(new Error("SoundTouch Wasm binary not loaded"));
-			}
-
 			const currentInitId = ++this.initCounter;
 			this.workletNode.port.onmessage = (event: MessageEvent<WorkletEvent>) => {
 				const data = event.data;
@@ -87,6 +77,11 @@ export class AudioRenderer {
 					data.payload.initId === currentInitId
 				) {
 					resolve();
+				} else if (
+					data.type === "INIT_ERROR" &&
+					data.payload.initId === currentInitId
+				) {
+					reject(new Error(`Worklet INIT failed: ${data.payload.message}`));
 				} else {
 					this.onMessage?.(data);
 				}
@@ -99,7 +94,7 @@ export class AudioRenderer {
 				payload: {
 					sharedBuffer,
 					channels,
-					wasmBytes: this.stWasmBytes,
+					wasmBytes: stWasmBytes,
 					initId: currentInitId,
 					tempo,
 					pitch,

web/src/audio-core/engine.ts

@@ -14,7 +14,7 @@ import {
 	type PlayerCover,
 	type QueueConfig,
 } from "./types";
-import { TypedEventTarget } from "./utils";
+import { getErrorMessage, TypedEventTarget } from "./utils";
 
 const TIMEUPDATE_INTERVAL_MS = 250;
 
@@ -33,6 +33,12 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 	private audioController: MainAudioController | null = null;
 	private sharedBuffer: SharedArrayBuffer | null = null;
 
+	private _assetsPreloaded = false;
+	private ffmpegWasmBlobUrl: string | null = null;
+	private soundtouchWasmBuffer: ArrayBuffer | null = null;
+	private preloadPromise: Promise<void> | null = null;
+	private abortController: AbortController | null = null;
+
 	private _state: EngineState = "idle";
 	private _duration = 0;
 	private _metadata: Record<string, string> = {};
@@ -64,7 +70,6 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 		this.renderer = new AudioRenderer(
 			config.audioContext,
 			config.assets.workletUrl,
-			config.assets.soundtouchWasmUrl,
 			config.gainNode,
 		);
 
@@ -211,10 +216,68 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 		this.renderer.setRate(this._rate);
 	}
 
+	public async preloadAssets(): Promise<void> {
+		if (this._assetsPreloaded) {
+			return;
+		}
+
+		if (this.preloadPromise) {
+			return this.preloadPromise;
+		}
+
+		this.abortController = new AbortController();
+		const signal = this.abortController.signal;
+
+		this.preloadPromise = (async () => {
+			try {
+				const [ffmpegWasmBuffer, stWasmBuffer] = await Promise.all([
+					this.fetchAndValidateWasm(this.config.assets.ffmpegWasmUrl, signal),
+					this.fetchAndValidateWasm(
+						this.config.assets.soundtouchWasmUrl,
+						signal,
+					),
+					this.pingResource(this.config.assets.workerUrl, signal),
+					this.pingResource(this.config.assets.workletUrl, signal),
+				]);
+
+				const blob = new Blob([ffmpegWasmBuffer], { type: "application/wasm" });
+				this.ffmpegWasmBlobUrl = URL.createObjectURL(blob);
+
+				this.soundtouchWasmBuffer = stWasmBuffer;
+				this._assetsPreloaded = true;
+			} catch (e) {
+				if (e instanceof DOMException && e.name === "AbortError") {
+					return;
+				}
+				const msg = getErrorMessage(e);
+				this.handleError(
+					EngineErrorCode.Network,
+					`Asset preload failed: ${msg}`,
+				);
+				throw e;
+			} finally {
+				this.preloadPromise = null;
+			}
+		})();
+
+		return this.preloadPromise;
+	}
+
 	/**
 	 * Loads a file, prepares the multithreading environment, and extracts metadata.
 	 */
 	public async loadFile(file: File): Promise<void> {
+		if (!this._assetsPreloaded) {
+			await this.preloadAssets();
+		}
+
+		if (!this.ffmpegWasmBlobUrl || !this.soundtouchWasmBuffer) {
+			const msg =
+				"Assets are missing even after preload was called. Engine cannot proceed.";
+			this.handleError(EngineErrorCode.Network, msg);
+			throw new Error(msg);
+		}
+
 		const currentSessionId = ++this.loadSessionId;
 		this.reset();
 
@@ -223,46 +286,56 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 		const channels = this.renderer.maxChannels;
 		const sampleRate = this.renderer.sampleRate;
 
-		await this.renderer.initialize(channels);
+		try {
+			await this.renderer.initialize(channels);
 
-		if (this.loadSessionId !== currentSessionId) {
-			return;
-		}
+			if (this.loadSessionId !== currentSessionId) {
+				return;
+			}
 
-		this.sharedBuffer = allocateAudioQueueMemory(
-			sampleRate,
-			channels,
-			this.queueConfig,
-		);
+			this.sharedBuffer = allocateAudioQueueMemory(
+				sampleRate,
+				channels,
+				this.queueConfig,
+			);
 
-		this.audioController = createMainController(this.sharedBuffer);
+			this.audioController = createMainController(this.sharedBuffer);
 
-		await this.renderer.bindQueue(
-			this.sharedBuffer,
-			channels,
-			this._tempo,
-			this._pitch,
-			this._rate,
-		);
+			await this.renderer.bindQueue(
+				this.sharedBuffer,
+				channels,
+				this._tempo,
+				this._pitch,
+				this._rate,
+				this.soundtouchWasmBuffer,
+			);
 
-		if (this.loadSessionId !== currentSessionId) {
-			return;
-		}
+			if (this.loadSessionId !== currentSessionId) {
+				return;
+			}
 
-		const loadPromise = new Promise<void>((resolve, reject) => {
-			this.loadResolve = resolve;
-			this.loadReject = reject;
-		});
+			const loadPromise = new Promise<void>((resolve, reject) => {
+				this.loadResolve = resolve;
+				this.loadReject = reject;
+			});
 
-		this.workerClient.init(
-			file,
-			sampleRate,
-			channels,
-			this.sharedBuffer,
-			this.config.assets.ffmpegWasmUrl,
-		);
+			this.workerClient.init(
+				file,
+				sampleRate,
+				channels,
+				this.sharedBuffer,
+				this.ffmpegWasmBlobUrl,
+			);
 
-		await loadPromise;
+			await loadPromise;
+		} catch (e) {
+			const msg = getErrorMessage(e);
+			this.handleError(
+				EngineErrorCode.Decode,
+				`Engine initialization failed: ${msg}`,
+			);
+			throw e;
+		}
 	}
 
 	public async play(): Promise<void> {
@@ -301,13 +374,23 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 	}
 
 	public destroy(): void {
+		if (this.abortController) {
+			this.abortController.abort();
+			this.abortController = null;
+		}
 		this.stopTimeupdate();
 		this.workerClient.destroy();
 		this.renderer.destroyNode();
 		this.sharedBuffer = null;
 		this.audioController = null;
 		this.resetState();
 		this._state = "idle";
+		if (this.ffmpegWasmBlobUrl) {
+			URL.revokeObjectURL(this.ffmpegWasmBlobUrl);
+			this.ffmpegWasmBlobUrl = null;
+		}
+		this.soundtouchWasmBuffer = null;
+		this._assetsPreloaded = false;
 	}
 
 	private reset(): void {
@@ -322,6 +405,39 @@ export class FFmpegAudioEngine extends TypedEventTarget<EngineEventMap> {
 	//#endregion
 
 	//#region Internal Callbacks & Utils
+	private async fetchAndValidateWasm(
+		url: string,
+		signal: AbortSignal,
+	): Promise<ArrayBuffer> {
+		const resp = await fetch(url, { signal });
+		if (!resp.ok) {
+			throw new Error(`HTTP ${resp.status} - ${resp.statusText}`);
+		}
+
+		const buffer = await resp.arrayBuffer();
+
+		if (buffer.byteLength < 4) {
+			throw new Error(`File too small to be a valid WASM: ${url}`);
+		}
+		const view = new DataView(buffer);
+		const magic = view.getUint32(0, false);
+		if (magic !== 0x0061736d /* \0asm */) {
+			throw new Error(
+				`Invalid WASM magic number detected. Server might have returned a 404 HTML page for: ${url}`,
+			);
+		}
+
+		return buffer;
+	}
+
+	private async pingResource(url: string, signal: AbortSignal): Promise<void> {
+		const resp = await fetch(url, { signal });
+		if (!resp.ok) {
+			throw new Error(`Failed to load resource (HTTP ${resp.status}): ${url}`);
+		}
+		await resp.arrayBuffer();
+	}
+
 	private handleWorkerInitDone(payload: {
 		duration: number;
 		metadata: Record<string, string>;

web/src/audio-core/utils/error.ts

@@ -0,0 +1,23 @@
+export function getErrorMessage(e: unknown): string {
+	if (e instanceof Error) {
+		return e.message;
+	}
+
+	if (typeof e === "string") {
+		return e;
+	}
+
+	if (e != null && typeof e === "object") {
+		if ("message" in e && typeof e.message === "string") {
+			return e.message;
+		}
+
+		try {
+			return JSON.stringify(e);
+		} catch {
+			return String(e);
+		}
+	}
+
+	return String(e);
+}

web/src/audio-core/utils/index.ts

@@ -1 +1,2 @@
+export * from "./error";
 export * from "./TypedEventTarget";