@@ -916,9 +916,9 @@ Source: the project lint pass in `packages/lint/src/project.ts`, `packages/lint/
 
 ### `duplicate_audio_track`
 
-**Warning.** Two audible elements overlap on the same track index, so their audio doubles up.
+**Warning.** Two audible clips overlap in time on the same `data-track-index`. Both play at once: the render mixes every audible clip whatever its track, and `data-track-index` only picks the Studio lane, so Studio draws the two over each other in that lane. An overlap like this is either an accidental duplicate or two sounds sharing one lane.
 
-**Fix:** Use non-overlapping time windows or different track indices.
+**Fix:** If both should sound (a whoosh into a hit), give one its own `data-track-index`; the mix does not change. If one is a leftover duplicate, remove it or move it so the windows do not overlap.
 
 ### `texture_mask_asset_not_found`
 
 
@@ -1307,6 +1307,23 @@ describe("audio-aware project rules", () => {
       expect(codes).toContain("duplicate_audio_track");
     });
 
+    it("says both clips still play, since the track index only picks the Studio lane", async () => {
+      const sfx = (id: string, start: string, duration: string) =>
+        `<audio id="${id}" src="${id}.wav" data-start="${start}" data-duration="${duration}" data-track-index="6"></audio>`;
+      const project = makeProject(
+        composition(sfx("whoosh", "5.13", "0.7") + sfx("land", "5.79", "0.34")),
+      );
+      const { results } = await lintProject(project);
+      const finding = results
+        .flatMap((result) => result.result.findings)
+        .find((f) => f.code === "duplicate_audio_track");
+      expect(finding?.message).toContain("whoosh.wav at 5.13-5.83s and land.wav at 5.79-6.13s");
+      expect(finding?.message).toContain("Both play at once whatever their track");
+      expect(finding?.fixHint).toContain(
+        "give one its own data-track-index; the mix does not change",
+      );
+    });
+
     it("stays quiet when one of the overlapping videos is muted", async () => {
       const codes = await codesFor(
         composition(video('data-has-audio="true"', 0) + video("muted", 2)),
 
@@ -929,8 +929,9 @@ function lintDuplicateAudioTracks(projectDir: string, rootHtml: string): Hyperfr
         findings.push({
           code: "duplicate_audio_track",
           severity: "warning",
-          message: `Multiple audible <audio>/<video> elements on track ${a.trackIndex} overlap (${a.src} at ${formatSeconds(a.start)}-${formatSeconds(a.end)}s, ${b.src} at ${formatSeconds(b.start)}-${formatSeconds(b.end)}s). This causes layered audio playback.`,
-          fixHint: "Use non-overlapping time windows or different track indices.",
+          message: `Audible clips overlap on Studio track ${a.trackIndex}: ${a.src} at ${formatSeconds(a.start)}-${formatSeconds(a.end)}s and ${b.src} at ${formatSeconds(b.start)}-${formatSeconds(b.end)}s. Both play at once whatever their track (the render mixes every audible clip; data-track-index only picks the Studio lane), and Studio draws them over each other in that lane.`,
+          fixHint:
+            "If both should sound (a whoosh into a hit), give one its own data-track-index; the mix does not change. If one is a leftover duplicate, remove it or move it so the windows do not overlap.",
         });
       }
     }
Original file line number	Diff line number	Diff line change
`@@ -929,8 +929,9 @@ function lintDuplicateAudioTracks(projectDir: string, rootHtml: string): Hyperfr`
`929`	`929`	`findings.push({`
`930`	`930`	`code: "duplicate_audio_track",`
`931`	`931`	`severity: "warning",`
`932`		- message: `Multiple audible <audio>/<video> elements on track ${a.trackIndex} overlap (${a.src} at ${formatSeconds(a.start)}-${formatSeconds(a.end)}s, ${b.src} at ${formatSeconds(b.start)}-${formatSeconds(b.end)}s). This causes layered audio playback.`,
`933`		`- fixHint: "Use non-overlapping time windows or different track indices.",`
	`932`	+ message: `Audible clips overlap on Studio track ${a.trackIndex}: ${a.src} at ${formatSeconds(a.start)}-${formatSeconds(a.end)}s and ${b.src} at ${formatSeconds(b.start)}-${formatSeconds(b.end)}s. Both play at once whatever their track (the render mixes every audible clip; data-track-index only picks the Studio lane), and Studio draws them over each other in that lane.`,
	`933`	`+ fixHint:`
	`934`	`+ "If both should sound (a whoosh into a hit), give one its own data-track-index; the mix does not change. If one is a leftover duplicate, remove it or move it so the windows do not overlap.",`
`934`	`935`	`});`
`935`	`936`	`}`
`936`	`937`	`}`