@makuraryu/yonde 0.4.0 → 0.4.2

package/README.md

@@ -148,9 +148,11 @@ package_asset = "uisfx/sounds/cinematic/select.mp3"
 
 翻译缓存指纹包含输入内容、语言、模型、端点、提示词版本和分句规则，但不包含 API Key。音频缓存指纹包含文本、音色、语言、语速和音调。仅调整朗读顺序时，Yonde 会复用已有语音并重新合并。
 
+缓存文件采用原子写入；命中缓存时只检查文件元数据，避免 iCloud 为数千个小文件执行随机头部读取。最终拼接再按朗读顺序连续读取音频内容。
+
 翻译、语音生成和最终 MP3 合并都会显示单行进度条，包括完成比例、数量、耗时和 ETA。非交互终端按 5% 里程碑输出，避免日志刷屏。
 
-所有语音和分隔音效会统一为 24 kHz、单声道、96 kbps，最终 MP3 采用无损快速拼接，不再把数小时音频完整重编码。
+所有语音和分隔音效会统一为 24 kHz、单声道、96 kbps，最终 MP3 采用无损快速拼接，不再把数小时音频完整重编码。合并中的大临时文件写在本机临时目录，完成后再一次性写入目标位置，避免 iCloud 持续同步一个不断增长的文件。
 
 最终合并使用状态文件保护原子写入。若进程在 ffmpeg 已完成后、最终重命名前退出，下次运行会直接恢复成品；若在合并中途退出，只会重做最终合并，已经生成的翻译和 TTS 缓存不会丢失。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makuraryu/yonde",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Config-driven Bun CLI for creating bilingual Japanese listening scripts and MP3 audio",
   "type": "module",
   "bin": {

package/src/audio.ts

@@ -1,6 +1,7 @@
 import { EdgeTTS } from "node-edge-tts";
-import { lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
+import { copyFile, lstat, mkdir, mkdtemp, readdir, rename, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AppConfig, VoiceProfile } from "./config";
@@ -47,11 +48,18 @@ function specHash(spec: AudioSpec): string {
     .slice(0, 24);
 }
 
-async function synthesize(spec: AudioSpec, cacheDir: string, ffmpegPath: string): Promise<SynthesisResult> {
+async function synthesize(
+  spec: AudioSpec,
+  cacheDir: string,
+  ffmpegPath: string,
+  existingCacheNames: ReadonlySet<string>,
+): Promise<SynthesisResult> {
   const hash = specHash(spec);
   const safeId = spec.kind.replace(/[^a-zA-Z0-9_-]/g, "_");
   const output = join(cacheDir, `${safeId}-${hash}.mp3`);
-  if (await fileIsUsable(output)) return { path: output, cached: true };
+  // Cache files are atomically renamed after a successful synthesis. A single
+  // directory listing avoids thousands of slow per-file metadata reads on iCloud.
+  if (existingCacheNames.has(basename(output))) return { path: output, cached: true };
 
   const temporary = `${output}.${process.pid}.${randomUUID()}.part.mp3`;
   if (!/[\p{L}\p{N}]/u.test(spec.text)) {
@@ -111,17 +119,22 @@ export function audioMergeFingerprint(value: Omit<AudioManifest, "version" | "me
   return new Bun.CryptoHasher("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
-export function mergeStateCanRecover(value: unknown, fingerprint: string, outputPath: string): value is MergeState {
+function mergeTemporaryIsSafe(value: unknown, outputPath: string): value is MergeState {
   if (!value || typeof value !== "object") return false;
   const state = value as Partial<MergeState>;
-  const prefix = `${basename(outputPath)}.`;
+  return typeof state.temporary === "string"
+    && dirname(dirname(state.temporary)) === tmpdir()
+    && basename(dirname(state.temporary)).startsWith("yonde-merge-")
+    && basename(state.temporary) === `${basename(outputPath)}.tmp.mp3`;
+}
+
+export function mergeStateCanRecover(value: unknown, fingerprint: string, outputPath: string): value is MergeState {
+  if (!mergeTemporaryIsSafe(value, outputPath)) return false;
+  const state = value as Partial<MergeState>;
   return state.version === 1
     && state.status === "complete"
     && state.fingerprint === fingerprint
-    && typeof state.temporary === "string"
-    && dirname(state.temporary) === dirname(outputPath)
-    && basename(state.temporary).startsWith(prefix)
-    && basename(state.temporary).endsWith(".tmp.mp3");
+    && typeof state.expectedSeconds === "number";
 }
 
 async function temporaryOutputs(outputPath: string): Promise<string[]> {
@@ -145,11 +158,23 @@ async function estimateDurationSeconds(items: AudioItem[]): Promise<number> {
   return Math.max(1, bytes * 8 / 96_000);
 }
 
+async function installMergedOutput(source: string, outputPath: string): Promise<void> {
+  const staged = `${outputPath}.${process.pid}.${randomUUID()}.tmp.mp3`;
+  try {
+    await copyFile(source, staged);
+    await rename(staged, outputPath);
+  } catch (error) {
+    await rm(staged, { force: true });
+    throw error;
+  }
+}
+
 async function recoverCompletedMerge(outputPath: string, stateDir: string, fingerprint: string): Promise<boolean> {
   const statePath = join(stateDir, "audio-merge-state.json");
   const state = await readJson<unknown>(statePath);
   if (!mergeStateCanRecover(state, fingerprint, outputPath) || !(await fileIsUsable(state.temporary))) return false;
-  await rename(state.temporary, outputPath);
+  await installMergedOutput(state.temporary, outputPath);
+  await rm(dirname(state.temporary), { recursive: true, force: true });
   await rm(statePath, { force: true });
   for (const stale of await temporaryOutputs(outputPath)) await rm(stale, { force: true });
   const progress = new ProgressBar("恢复", 1);
@@ -157,6 +182,13 @@ async function recoverCompletedMerge(outputPath: string, stateDir: string, finge
   return true;
 }
 
+async function discardStaleMerge(outputPath: string, stateDir: string): Promise<void> {
+  const statePath = join(stateDir, "audio-merge-state.json");
+  const state = await readJson<unknown>(statePath);
+  if (mergeTemporaryIsSafe(state, outputPath)) await rm(dirname(state.temporary), { recursive: true, force: true });
+  await rm(statePath, { force: true });
+}
+
 async function readFfmpegProgress(stream: ReadableStream<Uint8Array>, progress: ProgressBar, totalSeconds: number): Promise<void> {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
@@ -186,7 +218,8 @@ async function runFfmpeg(
   const paths = items.map((item) => relative(stateDir, item.path));
   if (paths.some((path) => path.startsWith("..") || /[\r\n\0]/.test(path))) throw new Error("音频缓存路径超出状态目录或含控制字符");
   await atomicWrite(listPath, paths.map((path) => `file '${escapeConcatPath(path)}'`).join("\n") + "\n");
-  const temporary = `${outputPath}.${process.pid}.${randomUUID()}.tmp.mp3`;
+  const temporaryDir = await mkdtemp(join(tmpdir(), "yonde-merge-"));
+  const temporary = join(temporaryDir, `${basename(outputPath)}.tmp.mp3`);
   const mergeStatePath = join(stateDir, "audio-merge-state.json");
   const expectedSeconds = await estimateDurationSeconds(items);
   const progress = new ProgressBar("合并", expectedSeconds);
@@ -209,7 +242,7 @@ async function runFfmpeg(
   const stderr = await stderrReader;
   if (exitCode !== 0) {
     progress.fail(`退出码 ${exitCode}`);
-    await rm(temporary, { force: true });
+    await rm(temporaryDir, { recursive: true, force: true });
     await rm(mergeStatePath, { force: true });
     const detail = stderr.trim().split("\n").at(-1);
     throw new Error(`ffmpeg 合并失败，退出码 ${exitCode}${detail ? `: ${detail}` : ""}`);
@@ -222,7 +255,8 @@ async function runFfmpeg(
     expectedSeconds,
   } satisfies MergeState);
   progress.finish(`${items.length} 个片段`);
-  await rename(temporary, outputPath);
+  await installMergedOutput(temporary, outputPath);
+  await rm(temporaryDir, { recursive: true, force: true });
   await rm(mergeStatePath, { force: true });
 }
 
@@ -273,7 +307,9 @@ export async function buildAudio(
   if (!ffmpegPath) throw new Error("找不到 ffmpeg；请先安装 ffmpeg，或仅运行 --stage translate");
   const cacheDir = join(stateDir, "audio-cache");
   await mkdir(cacheDir, { recursive: true });
-  for (const entry of await readdir(cacheDir)) if (entry.endsWith(".part.mp3")) await rm(join(cacheDir, entry), { force: true });
+  const cacheEntries = await readdir(cacheDir);
+  for (const entry of cacheEntries) if (entry.endsWith(".part.mp3")) await rm(join(cacheDir, entry), { force: true });
+  const existingCacheNames = new Set(cacheEntries.filter((entry) => entry.endsWith(".mp3")));
   const outputDir = dirname(outputPath);
   await mkdir(outputDir, { recursive: true });
 
@@ -316,7 +352,7 @@ export async function buildAudio(
   let results: SynthesisResult[];
   try {
     results = await runPool(
-      entries.map(([, spec]) => () => synthesize(spec, cacheDir, ffmpegPath)),
+      entries.map(([, spec]) => () => synthesize(spec, cacheDir, ffmpegPath, existingCacheNames)),
       config.audio.concurrency,
       (result) => {
         completed += 1;
@@ -343,6 +379,7 @@ export async function buildAudio(
   };
   const mergeFingerprint = audioMergeFingerprint(manifestBody);
   if (await recoverCompletedMerge(outputPath, stateDir, mergeFingerprint)) return;
+  await discardStaleMerge(outputPath, stateDir);
   const stale = await temporaryOutputs(outputPath);
   if (stale.length) console.warn(`发现 ${stale.length} 个未完成的合并临时文件，将保留语音缓存并重新合并。`);
   for (const path of stale) await rm(path, { force: true });

package/src/main.ts

@@ -11,7 +11,7 @@ type Stage = "translate" | "audio" | "all";
 type RunArgs = { command: "run"; input: string; stage: Stage; outputDir?: string; configPath?: string };
 type CliArgs = RunArgs | { command: "init"; path: string } | { command: "config-check"; configPath?: string } | { command: "help" } | { command: "version" };
 
-const VERSION = "0.4.0";
+const VERSION = "0.4.2";
 
 export const HELP_TEXT = `Yonde ${VERSION} — 配置驱动的双语听力材料生成器