An .aup3 file is an ordinary SQLite 3
database. These facts come from Audacity’s source code (version 3.7.1), which is the
format’s only definition.
Identifying the file
The file starts with SQLite’s 16-byte string SQLite format 3\0. Two header
fields mark it as Audacity’s. Both are big-endian, as every SQLite header field is.
| Offset | Size | Field | Value |
|---|---|---|---|
| 60 | 4 | user_version | The project format version, packed. See below. |
| 68 | 4 | application_id | 41 55 44 59, the characters AUDY |
Audacity checks both when opening a file. A different application_id gives
the error “This is not an Audacity project file”, and a user_version newer
than the running Audacity’s own version is refused.
The format version
user_version holds four numbers, one per byte:
| Bits | Field | Meaning |
|---|---|---|
| 31 to 24 | Major | Audacity major version |
| 23 to 16 | Minor | Audacity minor version |
| 15 to 8 | Revision | Revision |
| 7 to 0 | ModLevel | Modification level |
So 03 07 00 00 is format 3.7.0.0. Audacity writes the base version of its
release, major.minor.0.0, as the most compatible form.
Tables
A project has three tables, created on first use with
CREATE TABLE IF NOT EXISTS.
project
The last saved state of the project. It has one row, with id 1.
| Column | Type | Meaning |
|---|---|---|
id | INTEGER PRIMARY KEY | Always 1 |
dict | BLOB | The name dictionary of the binary XML |
doc | BLOB | The fields of the project document |
autosave
The same three columns. When a row with id 1 exists, it holds the
unsaved current state, and Audacity loads it to recover from a crash. It is deleted
when the project is saved cleanly.
sampleblocks
One row per block of audio. See sample blocks.
| Column | Type |
|---|---|
blockid | INTEGER PRIMARY KEY AUTOINCREMENT |
sampleformat | integer |
summin, summax, sumrms | REAL |
summary256, summary64k, samples | BLOB |
On loading, Audacity deletes any sampleblocks row not referred to by the
document it has read. When any are deleted, the project is treated as recovered.
Database settings
Audacity sets the page size to 65,536 bytes, with a VACUUM when the
database has data, and it opens its connections in one of two configurations.
| Setting | Safe configuration | Fast configuration |
|---|---|---|
busy_timeout | 5000 | 5000 |
locking_mode | SHARED | SHARED |
synchronous | NORMAL | OFF |
journal_mode | WAL | OFF |
wal_autocheckpoint | 0 | not set |
While a project is open, SQLite keeps a .aup3-wal file beside it. Audacity’s
source also lists a -shm suffix, but only builds without its
NO_SHM setting use one, and that setting is on everywhere except Windows.
Copying a project needs those files too until it has been closed.