Audacity 4.0.2 came out on 2 November 2026, a fix release ahead of 4.1. I maintain a browser tool that reads, recovers and downgrades Audacity project files, so a new upstream release raises two questions the same day:

  1. Did anything change that my code depends on?
  2. What will people now ask, and what can I truthfully answer?

This post is about how I answered both, because "just update the copy" is how a tool ends up making claims that quietly go stale.

Question 1: did the format gates move?

My downgrade feature exists because Audacity 3.7 refuses a newer project at exactly two gates, both checked before it reads a single track:

  1. SQLite's PRAGMA user_version, a packed Major<<24 | Minor<<16 | Revision<<8 | ModLevel.
  2. The version attribute on the project document's root, the XML schema version. Audacity 4 writes 2.0.0; the downgrade rewrites it to a value 3.7 accepts.

If 4.0.2 changed either, the downgrade would need new code. So instead of guessing from release notes, I read the compare between the 4.0.1 and 4.0.2 tags. Per my notes from that read:

  • It touches ProjectFileIO.cpp (compaction keeps the saved document's blocks; WriteXML drops its recording flag), plus Sequence and WaveTrack.
  • It does not touch AUDACITY_FILE_FORMAT_VERSION, which is still "2.0.0" at the 4.0.2 tag, nor the version files of the embedded au3-project libraries, nor WaveClip.cpp.

That last file matters because the downgrade also rewrites some clip attributes. Not touching it means those rewrites are as they were in 4.0.1. The downgrade code compares versions generically, so it needed no change.

The useful habit: name the specific files and constants your code depends on, and check those in the compare. "The release notes don't mention format changes" is weaker than "the one constant I rely on is identical at both tags."

Question 2: "Does updating repair my project?"

A fix release called out corruption fixes, so I expected people to ask whether installing it repairs files that are already damaged. The short answer I put on the page is no: an update stops damage from happening again; a file already damaged stays as it is.

What the fixes were, as the pull requests describe them:

  • PR 12544: before the fix, a clip one sample long was removed on load, and its samples were removed from the sample-block table, while the saved project document still referenced them. A later open then points at a block that doesn't exist.
  • PR 12539: Audacity 4 never called for autosave while recording. The fix restores it. A crash mid-take in an earlier version therefore left an autosave copy that doesn't contain that take.

The first bug produces exactly the failure a recovery tool sees: a document that references a missing sample block. What can the tool do about it?

  • It can report the missing block, and the number of samples it estimates are gone.
  • It can play and export the project with that gap as silence. Audacity encodes silence as a non-positive block id meaning "that many samples of nothing", so a rebuilt project can fill the hole in a form Audacity understands.
  • It cannot bring back audio that was deleted from the block table. That audio isn't in the file any more.

Don't claim more than the code does

This is the part I care about most. It's easy to write "recovers your audio". It's more accurate to write what the code actually does. The tool plays what a saved, autosaved or earlier document places on the timeline. A sample block that no document references is counted but never mixed. Someone who needs those orphaned blocks should use the official command-line tool's option that writes a file's sample blocks out as WAV files without needing a document.

So the page says that, in those words, and names the other tool.

Pin the copy to the code

The risk with a page like this is drift: someone changes recover.ts, and the FAQ still promises the old behaviour. So tests read the page and the code together:

it("promises silence for a missing block only because the report and rebuild do that", () => { const recover = readFileSync(join(SRC, "lib", "aup", "recover.ts"), "utf8"); expect(recover).toContain("will be filled with silence"); expect(faq.answer).toContain("the gap plays and exports as silence"); }); it("never claims the page lifts audio no document places", () => { expect(faq.answer).toContain("plays what a saved, autosaved or earlier document places on the timeline"); const recover = readFileSync(join(SRC, "lib", "aup", "recover.ts"), "utf8"); expect(recover).toContain("orphanBlockCount: health.orphanBlockCount"); // counted... const timeline = readFileSync(join(SRC, "lib", "aup", "timeline.ts"), "utf8"); expect(timeline).not.toMatch(/orphan/i); // ...never mixed });

Other tests pin the version claim: the page quotes the document version it rewrites, and that quote is compared with the exported constant the downgrade uses, so changing one without the other fails the build. The same facts are also mirrored into the machine-readable summary the site publishes for AI assistants, and tests check that too.

These are string-level tests, so they are crude. They catch a claim drifting away from the code, not whether the claim was right in the first place. For that, the sources (the release page, both pull requests, the tagged source file) are listed on the page so a reader can check them.

Limits

  • I read the compare between the two tags on the day of release. A later point release can change the answer, which is why the pages cite tag names and dates rather than "the latest version".
  • "No" to "does updating repair my project?" is about files already damaged. It doesn't say anything about whether a particular file is damaged.
  • I haven't reproduced the upstream bugs myself; the description of them comes from the pull requests.

Takeaways

  • When upstream ships, list the files and constants you depend on and check exactly those in the diff between tags.
  • Answer the "will updating fix it?" question directly. Prevention and repair are different, and users conflate them.
  • Say what your tool can't recover, and point at a tool that can.
  • Make tests read both the copy and the code, so a claim can't outlive the behaviour behind it.
  • Date everything, and cite tags, not "latest".

If you want to see how the page words it, it's the Audacity project recovery page. Disclosure: I built it. Projects are read in your browser and aren't uploaded.