fix(性能): 优化主进程波形分析卡顿

Author: coderDJing

package.json

@@ -1,6 +1,6 @@
 {
   "name": "frkb",
-  "version": "1.2.4-rc.202609100927",
+  "version": "1.2.4-rc.202609101109",
   "description": "Track Studio — Rapid Audio Organization Tool",
   "license": "PolyForm-Noncommercial-1.0.0",
   "main": "./out/main/index.js",

src/main/libraryCacheDb/unifiedDisplayWaveformCache.ts

@@ -1,4 +1,5 @@
-import { deflateSync, inflateSync } from 'node:zlib'
+import { promisify } from 'node:util'
+import { deflate, inflate } from 'node:zlib'
 import {
   UNIFIED_DISPLAY_WAVEFORM_CACHE_VERSION,
   UNIFIED_DISPLAY_WAVEFORM_PARAMETER_VERSION,
@@ -40,6 +41,8 @@ type UnifiedDisplayWaveformRow = {
 
 const TABLE = 'unified_display_waveform_cache'
 const MAGIC = 'UDW1'
+const deflateAsync = promisify(deflate)
+const inflateAsync = promisify(inflate)
 
 const normalizeMeta = (row: unknown): UnifiedDisplayWaveformMeta | null => {
   if (!isSqliteRow(row)) return null
@@ -81,16 +84,16 @@ const toBuffer = (value: unknown): Buffer | null => {
   return null
 }
 
-const writeHeader = (payload: Buffer, header: Record<string, unknown>) => {
+const writeHeader = async (payload: Buffer, header: Record<string, unknown>) => {
   const headerBuffer = Buffer.from(JSON.stringify(header), 'utf8')
   const prefix = Buffer.alloc(8)
   prefix.write(MAGIC, 0, 4, 'ascii')
   prefix.writeUInt32LE(headerBuffer.byteLength, 4)
-  return deflateSync(Buffer.concat([prefix, headerBuffer, payload]))
+  return await deflateAsync(Buffer.concat([prefix, headerBuffer, payload]))
 }
 
-const readPayload = (compressed: Buffer) => {
-  const decoded = inflateSync(compressed)
+const readPayload = async (compressed: Buffer) => {
+  const decoded = await inflateAsync(compressed)
   if (decoded.byteLength < 8 || decoded.subarray(0, 4).toString('ascii') !== MAGIC) return null
   const headerLength = decoded.readUInt32LE(4)
   const payloadStart = 8 + headerLength
@@ -121,9 +124,9 @@ const readPayload = (compressed: Buffer) => {
   return { header, readBytes }
 }
 
-function encodeUnifiedDisplayWaveformCacheData(
+async function encodeUnifiedDisplayWaveformCacheData(
   data: UnifiedDisplayWaveformDetailData
-): Buffer | null {
+): Promise<Buffer | null> {
   if (!data || data.version !== UNIFIED_DISPLAY_WAVEFORM_CACHE_VERSION) return null
   if (data.parameterVersion !== UNIFIED_DISPLAY_WAVEFORM_PARAMETER_VERSION) return null
   if (!data.height?.length || !data.attack?.length || !data.colorIndex?.length) return null
@@ -160,10 +163,10 @@ function encodeUnifiedDisplayWaveformCacheData(
   })
 }
 
-function decodeUnifiedDisplayWaveformCacheData(
+async function decodeUnifiedDisplayWaveformCacheData(
   meta: UnifiedDisplayWaveformMeta,
   payload: Buffer
-): UnifiedDisplayWaveformDetailData | null {
+): Promise<UnifiedDisplayWaveformDetailData | null> {
   if (!meta || !payload) return null
   if (
     meta.cacheVersion !== UNIFIED_DISPLAY_WAVEFORM_CACHE_VERSION ||
@@ -172,7 +175,7 @@ function decodeUnifiedDisplayWaveformCacheData(
   ) {
     return null
   }
-  const decoded = readPayload(payload)
+  const decoded = await readPayload(payload)
   if (!decoded) return null
   const height = decoded.readBytes(decoded.header.heightLength)
   const attack = decoded.readBytes(decoded.header.attackLength)
@@ -329,7 +332,7 @@ export async function loadUnifiedDisplayWaveformCacheData(
       await removeUnifiedDisplayWaveformCacheEntry(listRoot, filePath)
       return null
     }
-    const decoded = decodeUnifiedDisplayWaveformCacheData(meta, payload)
+    const decoded = await decodeUnifiedDisplayWaveformCacheData(meta, payload)
     if (!decoded) {
       await removeUnifiedDisplayWaveformCacheEntry(listRoot, filePath)
       return null
@@ -350,7 +353,7 @@ export async function upsertUnifiedDisplayWaveformCacheEntry(
   const db = getLibraryDb()
   const keys = resolveCacheKeys(listRoot, filePath)
   if (!db || !keys || !data) return false
-  const payload = encodeUnifiedDisplayWaveformCacheData(data)
+  const payload = await encodeUnifiedDisplayWaveformCacheData(data)
   if (!payload) return false
   try {
     const upsertMain = db.prepare(

src/main/services/keyAnalysis/background.ts

@@ -1,4 +1,4 @@
-import nodeFs from 'node:fs'
+import type { Dirent } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { EventEmitter } from 'node:events'
@@ -286,13 +286,13 @@ export const createKeyAnalysisBackground = (deps: KeyAnalysisBackgroundDeps) =>
     return roots
   }
 
-  const resolveSongListRootsFromFs = (): string[] => {
+  const resolveSongListRootsFromFs = async (): Promise<string[]> => {
     const rootDir = store.databaseDir
     if (!rootDir) return []
     const libraryRoot = path.join(rootDir, 'library')
-    let libraryEntries: nodeFs.Dirent[] = []
+    let libraryEntries: Dirent[] = []
     try {
-      libraryEntries = nodeFs.readdirSync(libraryRoot, { withFileTypes: true })
+      libraryEntries = await fs.readdir(libraryRoot, { withFileTypes: true })
     } catch {
       return []
     }
@@ -305,9 +305,9 @@ export const createKeyAnalysisBackground = (deps: KeyAnalysisBackgroundDeps) =>
         continue
       }
       const libraryDir = path.join(libraryRoot, libraryEntry.name)
-      let songListEntries: nodeFs.Dirent[] = []
+      let songListEntries: Dirent[] = []
       try {
-        songListEntries = nodeFs.readdirSync(libraryDir, { withFileTypes: true })
+        songListEntries = await fs.readdir(libraryDir, { withFileTypes: true })
       } catch {
         continue
       }
@@ -335,13 +335,13 @@ export const createKeyAnalysisBackground = (deps: KeyAnalysisBackgroundDeps) =>
       .map(([, root]) => root)
   }
 
-  const refreshBackgroundRoots = (): string[] => {
+  const refreshBackgroundRoots = async (): Promise<string[]> => {
     const now = Date.now()
     const shouldRefresh =
       now - backgroundRootsLastRefresh >= BACKGROUND_FS_REFRESH_MS || backgroundRoots.length === 0
     if (!shouldRefresh) return backgroundRoots
     const nodeRoots = resolveSongListRoots()
-    const fsRoots = resolveSongListRootsFromFs()
+    const fsRoots = await resolveSongListRootsFromFs()
     const nextRoots = mergeSongListRoots(nodeRoots, fsRoots)
     const signature = nextRoots.join('|')
     if (signature !== backgroundRootsSignature) {
@@ -378,7 +378,7 @@ export const createKeyAnalysisBackground = (deps: KeyAnalysisBackgroundDeps) =>
   }
 
   const cleanupOrphanedCovers = async () => {
-    const roots = refreshBackgroundRoots()
+    const roots = await refreshBackgroundRoots()
     if (roots.length === 0) return
 
     const audioExts = getAudioExtensions()
@@ -522,7 +522,7 @@ export const createKeyAnalysisBackground = (deps: KeyAnalysisBackgroundDeps) =>
   const collectBackgroundFsCandidates = async (limit: number): Promise<string[]> => {
     const results: string[] = []
     if (limit <= 0 || !store.databaseDir || deps.hasForegroundWork()) return results
-    const roots = refreshBackgroundRoots()
+    const roots = await refreshBackgroundRoots()
     if (roots.length === 0) return results
     const audioExts = getAudioExtensions()
     if (audioExts.size === 0) return results

src/main/workers/keyAnalysisWorker.ts

@@ -1,5 +1,6 @@
 import { parentPort } from 'node:worker_threads'
 import type { MixxxWaveformData } from '../waveformCodec'
+import { collectTransferableArrayBuffers } from './transferableBuffers'
 import { COMPACT_VISUAL_WAVEFORM_COLOR_RAW_RATE } from '../../shared/compactVisualWaveform'
 import {
   buildUnifiedDisplayWaveformDetailFromMixxx,
@@ -689,5 +690,5 @@ parentPort?.on('message', async (job: KeyJob) => {
     })
   }
 
-  parentPort?.postMessage(response)
+  parentPort?.postMessage(response, collectTransferableArrayBuffers(response.result))
 })

src/main/workers/transferableBuffers.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { collectTransferableArrayBuffers } from './transferableBuffers'
+
+describe('collectTransferableArrayBuffers', () => {
+  it('collects nested typed-array buffers once', () => {
+    const shared = new ArrayBuffer(16)
+    const other = new Uint8Array(8)
+    const result = collectTransferableArrayBuffers({
+      bands: [new Uint8Array(shared), new Uint8Array(shared, 4, 4)],
+      detail: { height: other }
+    })
+
+    expect(result).toHaveLength(2)
+    expect(result).toContain(shared)
+    expect(result).toContain(other.buffer)
+  })
+
+  it('skips pooled Node buffers and handles cycles', () => {
+    const sharedWithBuffer = new ArrayBuffer(8)
+    const cyclic: Record<string, unknown> = {
+      typed: new Uint8Array(sharedWithBuffer),
+      payload: Buffer.from(sharedWithBuffer)
+    }
+    cyclic.self = cyclic
+
+    expect(collectTransferableArrayBuffers(cyclic)).toEqual([])
+  })
+})

src/main/workers/transferableBuffers.ts

@@ -0,0 +1,39 @@
+const isTransferableArrayBuffer = (value: unknown): value is ArrayBuffer =>
+  value instanceof ArrayBuffer
+
+/**
+ * 收集 worker 结果中的独占 ArrayBuffer，避免大型波形在回传主进程时被结构化克隆。
+ * Buffer 可能来自 Node 共享内存池，不能安全转移，因此明确跳过。
+ */
+export const collectTransferableArrayBuffers = (value: unknown): ArrayBuffer[] => {
+  const buffers = new Set<ArrayBuffer>()
+  const blockedBuffers = new Set<ArrayBuffer>()
+  const visited = new WeakSet<object>()
+
+  const visit = (current: unknown): void => {
+    if (isTransferableArrayBuffer(current)) {
+      if (!blockedBuffers.has(current)) buffers.add(current)
+      return
+    }
+    if (ArrayBuffer.isView(current)) {
+      if (!isTransferableArrayBuffer(current.buffer)) return
+      if (Buffer.isBuffer(current)) {
+        blockedBuffers.add(current.buffer)
+        buffers.delete(current.buffer)
+      } else if (!blockedBuffers.has(current.buffer)) {
+        buffers.add(current.buffer)
+      }
+      return
+    }
+    if (!current || typeof current !== 'object' || visited.has(current)) return
+    visited.add(current)
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item)
+      return
+    }
+    for (const item of Object.values(current as Record<string, unknown>)) visit(item)
+  }
+
+  visit(value)
+  return [...buffers]
+}