How Waveward Handles a Truncated Audacity .aup Document

Audacity 1.x and 2.x projects are an XML document (.aup) plus a _data folder of audio block files. The .aup stores project structure and references to those blocks; it does not contain the audio samples. I wrote a parser for that document in Waveward. If the file ended inside a tag, or with elements still open, Waveward used to refuse the open as unreadable.

That refusal throws away a prefix that may still be usable, but opening the file is not the same as getting the whole project back. Waveward now keeps the complete entries it can still parse, and only the audio those entries still name in the _data folder. A cut that falls before any usable entry, a block the document never finished naming, or a block file that is missing is not recovered; missing blocks play as silence and are counted. The AUP to MP3 page puts this as "usually not all of it," and says a file that stops part-way opens up to its last complete entry, with a note of what is missing.

Two save paths, and why they are not the same

I read Audacity's save code at the public tags the page cites. I did not run Audacity to watch a save fail.

In Audacity 2.1.3's Project.cpp, if the project file already exists it is renamed to a safety name — the file name plus .bak, or plus ~ under GTK — and the new document is then opened under the real name (saveFile.Open(mFileName, "wb"), around line 3797). That is a write in place. The backup is removed only after the write succeeds (line 3873). If writing throws, the incomplete file is deleted and the backup is renamed back (lines 3814–3818). The AUP to MP3 page also attributes this pattern to 1.3.14 and 2.0.6; I did not read those two tags myself. From that in-place open, a crash or power cut during the write itself — a path the caught-exception rollback does not cover — can leave a new .aup that stops part-way, with the previous save beside it as .aup.bak (or .aup~ on Linux). That is an inference from the write path, not a failure I reproduced.

Audacity 2.4.2's ProjectFileManager.cpp still does the .bak / ~ rename, but writes the document through XMLFileWriter, described there as a temporary file renamed into place. Because the live .aup is not overwritten in the same way, that 2.4.2 path should not be taken as leaving a half-written .aup. An unfinished save can still leave the .bak beside the project: 2.4.2 removes that copy only after a successful save, and a failure that it handles is written to put the copy back. The same file also refuses to open a path ending in .aup.bak, with the warning "You are trying to open an automatically created backup file."

An interrupted copy or download is a different failure: the file can end early, or turn into zero bytes, without any .bak from a save. I have not watched that happen either; it is a cause the page names, not a case I ran.

What Waveward keeps, and what it still refuses

When the document ends early, Waveward opens it from the complete prefix and reports that the file stops part-way. That report also mentions a copy named song.aup.bak (or song.aup~ on Linux) next to it as the likely previous save. Waveward accepts .aup.bak and .aup~ as project documents, after the .aup itself, and reads them only. The audio still has to come from the _data folder; a later edit may already have removed some of those blocks, and those play as silence.

The project's tests require a document that ends early to open from its complete prefix, a half-written <waveblock> to be dropped rather than kept as empty audio, a complete document with zeros appended not to be treated as damaged, and a mismatched end tag in the middle still to be refused. I did not run those tests, and I did not reopen the files myself.

The recovery page says the same for an old .aup: if it stops part-way, it opens up to its last complete entry, and the .aup.bak opens there too. Integrity check, rebuild, and earlier database saves on that page still apply only to .aup3 and .aup4. People who land on the AUP3 to MP3 converter with an Audacity 2 .aup are sent to the AUP to MP3 page: that converter treats the old format as a different kind of project, a small XML file plus its _data folder, which Audacity 4 cannot import.

Takeaways

• Waveward can use a truncated .aup up to its last complete entry. It cannot promise the rest of the project, or any audio the remaining entries do not still name.
• The Audacity 2.1.3 save path I read writes the new document in place after renaming the previous save to .aup.bak (or .aup~). Audacity 2.4.2 keeps the rename but commits through a temporary file, so the same partial overwrite should not be assumed.
• Audacity 2.4.2 will not open .aup.bak. Waveward will, together with the _data folder.
• A document that ends early is a different failure from one that is wrong in the middle. A mismatched tag should still be refused.

Disclosure: I built it. Waveward is my project; the save-and-backup steps quoted above are from Audacity 2.1.3 and 2.4.2, not from code I wrote.