Split Translate and Speech into separate stages with TTS word timestamps

apps/api/src/app.ts

@@ -93,7 +93,7 @@ app.route("/api", createQuizRoutes(booksDir))
 app.route("/api", createPackageRoutes(booksDir, webAssetsDir, configPath, taskService))
 app.route("/api", createPromptRoutes(promptsDir, booksDir))
 app.route("/api", createTextCatalogRoutes(booksDir))
-app.route("/api", createTTSRoutes(booksDir, configPath))
+app.route("/api", createTTSRoutes(booksDir, configPath, taskService))
 app.route(
   "/api",
   createStageRoutes(stageService, eventBus, booksDir, promptsDir, webAssetsDir, configPath)

apps/api/src/routes/books.test.ts

@@ -529,8 +529,8 @@ describe("POST /books/:label/stages/run", () => {
         "X-Gemini-API-Key": "gm-test",
       },
       body: JSON.stringify({
-        fromStage: "text-and-speech",
-        toStage: "text-and-speech",
+        fromStage: "translate",
+        toStage: "speech",
       }),
     })
 

apps/api/src/routes/pages.test.ts

@@ -669,7 +669,7 @@ describe("Page routes", () => {
     }
   }
 
-  /** Assert that all caption + text-and-speech node data and step_runs were cleared. */
+  /** Assert that all caption + translate/speech node data and step_runs were cleared. */
   function expectAllDownstreamCleared(dir: string, bookLabel: string) {
     const s = createBookStorage(bookLabel, dir)
     try {
@@ -689,7 +689,7 @@ describe("Page routes", () => {
     }
   }
 
-  /** Assert that text-and-speech (but NOT image-captioning) node data and step_runs were cleared. */
+  /** Assert that translate/speech (but NOT image-captioning) node data and step_runs were cleared. */
   function expectTextAndSpeechCleared(dir: string, bookLabel: string) {
     const s = createBookStorage(bookLabel, dir)
     try {
@@ -711,7 +711,7 @@ describe("Page routes", () => {
   }
 
   describe("PUT /api/books/:label/pages/:pageId/sectioning clears downstream", () => {
-    it("clears caption + text-and-speech data on sectioning save", async () => {
+    it("clears caption + translate/speech data on sectioning save", async () => {
       seedDownstreamData(tmpDir, label)
 
       const data = {
@@ -748,7 +748,7 @@ describe("Page routes", () => {
   })
 
   describe("PUT /api/books/:label/pages/:pageId/rendering clears downstream", () => {
-    it("clears caption + text-and-speech data on rendering save", async () => {
+    it("clears caption + translate/speech data on rendering save", async () => {
       seedDownstreamData(tmpDir, label)
 
       const data = {
@@ -775,7 +775,7 @@ describe("Page routes", () => {
   })
 
   describe("POST clone clears downstream", () => {
-    it("clears caption + text-and-speech data on section clone", async () => {
+    it("clears caption + translate/speech data on section clone", async () => {
       seedDownstreamData(tmpDir, label)
 
       const res = await app.request(
@@ -789,7 +789,7 @@ describe("Page routes", () => {
   })
 
   describe("POST delete clears downstream", () => {
-    it("clears caption + text-and-speech data on section delete", async () => {
+    it("clears caption + translate/speech data on section delete", async () => {
       // Need at least 2 sections so delete is valid
       const s = createBookStorage(label, tmpDir)
       try {
@@ -839,7 +839,7 @@ describe("Page routes", () => {
   })
 
   describe("POST crop (images) clears downstream", () => {
-    it("clears caption + text-and-speech data on image crop", async () => {
+    it("clears caption + translate/speech data on image crop", async () => {
       seedDownstreamData(tmpDir, label)
 
       // Minimal valid PNG (1x1 pixel)
@@ -867,7 +867,7 @@ describe("Page routes", () => {
     })
   })
 
-  describe("PUT image-captioning clears text-and-speech downstream", () => {
+  describe("PUT image-captioning clears translate/speech downstream", () => {
     it("clears text-catalog/translations/TTS but keeps image-captioning", async () => {
       seedDownstreamData(tmpDir, label)
 

apps/api/src/routes/pages.ts

@@ -327,9 +327,9 @@ async function executeAiImageGeneration(params: AiImageGenParams): Promise<{
   }
 }
 
-/** Clear caption + downstream text-and-speech data when images change. */
+/** Clear caption + downstream translate/speech data when images change. */
 function clearCaptionData(storage: Storage): void {
-  storage.clearNodesByType(["image-captioning", "text-catalog", "text-catalog-translation", "tts"])
+  storage.clearNodesByType(["image-captioning", "text-catalog", "text-catalog-translation", "tts", "tts-timestamps"])
   storage.clearStepRuns(["image-captioning", "text-catalog", "catalog-translation", "tts"])
 }
 
@@ -736,7 +736,7 @@ export function createPageRoutes(
 
       const version = storage.putNodeData("image-captioning", pageId, parsed.data)
       // Caption change cascades to text-catalog/translations/TTS
-      storage.clearNodesByType(["text-catalog", "text-catalog-translation", "tts"])
+      storage.clearNodesByType(["text-catalog", "text-catalog-translation", "tts", "tts-timestamps"])
       storage.clearStepRuns(["text-catalog", "catalog-translation", "tts"])
       return c.json({ version })
     } finally {

apps/api/src/routes/tts.test.ts

@@ -344,3 +344,57 @@ describe("POST /books/:label/tts/generate-one", () => {
     )
   })
 })
+
+describe("DELETE /books/:label/tts", () => {
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "adt-tts-route-"))
+    configPath = path.join(tmpDir, "config.yaml")
+    writeConfig()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    tmpDir = ""
+    configPath = ""
+  })
+
+  it("clears both tts and tts-timestamps data", async () => {
+    const label = "delete-tts"
+    seedBook(label)
+
+    // Seed TTS and tts-timestamps data
+    const storage = createBookStorage(label, tmpDir)
+    try {
+      storage.putNodeData("tts", "en", {
+        entries: [{ textId: "pg001_t001", fileName: "pg001_t001.wav" }],
+        generatedAt: new Date().toISOString(),
+      })
+      storage.putNodeData("tts-timestamps", "en", {
+        entries: {
+          pg001_t001: {
+            textId: "pg001_t001",
+            language: "en",
+            words: [{ word: "Hello", start: 0, end: 0.5 }],
+            duration: 0.5,
+          },
+        },
+        generatedAt: new Date().toISOString(),
+      })
+    } finally {
+      storage.close()
+    }
+
+    const app = createTTSRoutes(tmpDir, configPath)
+    const res = await app.request(`/books/${label}/tts`, { method: "DELETE" })
+
+    expect(res.status).toBe(200)
+
+    const after = createBookStorage(label, tmpDir)
+    try {
+      expect(after.getLatestNodeData("tts", "en")).toBeNull()
+      expect(after.getLatestNodeData("tts-timestamps", "en")).toBeNull()
+    } finally {
+      after.close()
+    }
+  })
+})