{"id":19289471,"url":"https://github.com/audacity/audacity-project-tools","last_synced_at":"2025-04-22T05:31:26.184Z","repository":{"id":65715839,"uuid":"440211679","full_name":"audacity/audacity-project-tools","owner":"audacity","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-12T12:56:06.000Z","size":5066,"stargazers_count":19,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-01T20:00:09.647Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/audacity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-12-20T15:07:38.000Z","updated_at":"2025-03-29T23:42:09.000Z","dependencies_parsed_at":"2024-01-12T16:53:00.807Z","dependency_job_id":"cb2a0e57-69ed-4d37-bb7a-61858a2a607e","html_url":"https://github.com/audacity/audacity-project-tools","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/audacity%2Faudacity-project-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/audacity%2Faudacity-project-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/audacity%2Faudacity-project-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/audacity%2Faudacity-project-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/audacity","download_url":"https://codeload.github.com/audacity/audacity-project-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250175061,"owners_count":21387131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T22:15:48.069Z","updated_at":"2025-04-22T05:31:26.179Z","avatar_url":"https://github.com/audacity.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# audacity-project-tools\n\n`audacity-project-tools` is a utility application to work with corrupted Audacity projects. \n\nInternally, the AUP3 file is an SQLite3 database. Such databases are complex binary files that can be corrupted in a few scenarios:\n* OS file sync has failed internally;\n* Uncommitted WAL file is removed;\n* Hardware-level corruption.\n\nAudacity will fail with an error while opening a corrupted project. The common errors are:\n* sqlite.rc 11 - database structure is corrupted;\n* sqlite.rc 101 - sample block is missing. \n\nOn top of that, there were odd cases, like a half-written project blob.\n\n## Audacity Project Internals\n\nThe Audacity 3 project structure is in a binary XML format. Schema is similar to the schema used by previous Audacity versions. After every user action project, Audacity serializes the project as a blob into the `autosave` table. When a user saves the project - Audacity removes the row from the `autosave` table and stores the project to the `project` table. Both tables use the same schema: there are two blobs. One contains \"dictionary\" data, a list of tag and attribute names; the second holds the project structure. During the startup Audacity checks if the `autosave` table contains any data. If it does, the application shows the dialog that allows the user to \"recover\" from the `autosave` or discard it.\n\nAudacity stores samples in blocks of up to 1Mb inside the `sampleblocks` table. Each block stores around 5 seconds of mono audio data on the default settings. Audacity never updates blocks. Instead, Audacity creates new blocks when the data changes. For this reason, sample block IDs are not guaranteed to be monotonic or continuous inside a track. If the project structure itself is corrupted, there is no generic way to restore the data.\n\n## Using the `audacity-project-tools`\n\n`audacity-project-tools` is a command-line utility that allows executing a few different commands in the following order:\n* `-drop_autosave`: removes an `autosave` table if any. The chances are that dropping this table can help recover a more consistent project.\n* `-check_integrity`: performs an integrity check on the database, effectively running `PRAGMA integrity_check;`\n* `-extract_project`: extracts the project structure as a text-based XML file from both `autosave` and `project` tables.\n* `-recover_db`: attempts to recover the database file using \".recover\" command of the `sqlite3` binary. The database will be a correct Audacity project file, passing `-check_integrity`. However, internal consistency is left unchecked. This mode is a must for error code 11 failures.\n* `-freelist_corrupt`: forces `-recover_db` to consider the database freelist to be corrupt.\n* `-recover_project`: replaces all the missing blocks with silence. Helps to work with \"error code 101\" issues.\n* `-compact`: removes all the unused blocks and compacts the database.\n* `-extract_clips`: extract all the clips as mono wave files. Requires a project to be intact.\n* `-extract_sample_blocks`: extract sample blocks as separate wav files. It can be used if the project table is corrupted.\n* `-extract_as_mono_track`: extract sample blocks as a single mono wav file.\n* `-extract_as_stereo_track`: extract sample blocks as a single stereo wav file. Channels are based on the parity of the block_id.\n* `-analyze_project`: prints information about tracks and clips in the project.\n\n`audacity-project-tools` will never modify the original file. If mode requires the modification of the database, the tool will create a copy. All the output goes to the same directory as the project file has.\n\nExample:\n```\n$ audacity-project-tools -recover_db -recover_project broken.aup3`\n$ ls \n  broken.aup3 broken.recovered.aup3\n```\n\n## Building\n\n`audacity-project-tools` requires a C++17 compliant compiler with the complete C++17 library. The build requires \u003cfilesystem\u003e and floating-point versions of `from_chars`.\n\nCMake and Conan are required to configure the project. Conan 2.0 is not supported ATM.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faudacity%2Faudacity-project-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faudacity%2Faudacity-project-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faudacity%2Faudacity-project-tools/lists"}