Audacity Projects

Audacity project files store information about the entirety of the project such as the number of tracks and their time positions, details of clips within the tracks, amplitude envelope points, labels and gain and pan data.

Bill: I realize this may be a low priority, but I and a few others (based on posts on the forum) would love to see a specification of the Audacity XML.

How the .aup project file works

Bill 03Mar11: Isn't the AUP file the project file? If so, shouldn't this section be titled "AUP Project Files"?
In the paragraph below it reads as if one is exporting the AU files. I think this is misleading. One exports a project, not the individual AU files.
Changed the italic and bold settings within the parentheses in the second paragraph so that the links don't look like glossary entries.

Peter 16Mar11: actually my understanding is that the AUP file should be regarded as the "project manager" for the project (Koz often refers to it that way, or similar). So to my mind the project files are the data folders and the .au and .auf files. I changed to wording on the Exporting to try to make it clearer.

Gale: 17 Mar 11: I don't like the concepts of "master" and "manager" very much. We may have an interface called "project manager" eventually for safe moving and deletion of projects. Also the page title is "Audacity Projects" but the first phrase of the intro is "Audacity project files" and doesn't deal with the _data folder at all. I think that's more important than the exact contents of the project. some of which could be moved down.

I think there is too little here that explains why you should (or shouldn't) save a project (and how to do it) and too much in too many places about the faster/safer import thing.

I also think we should explain however briefly that the same format (with temporary folder instead of _data folder for unsaved projects) is used for the autosave file from which (hopefully) the project would be recovered if you crashed.

Peter 18Mar11:

1. I don't like the concepts of "master" and "manager": Point taken, I will remove such references in this text. I personally still find it hard to consider the AUP file as a "project file" as to my mind it is far from being complete in itself - however I bow to common and long-term usage to maintain documentation consistency (I note the Wiki page "File management tips .." uses that nomenclature).
2. I think there is too little here that explains why you should (or shouldn't) save a project (and how to do it): Good catch. I will add a draft section on this based on the text from the Wiki page noted above.
3. ... too much in too many places about the faster/safer import thing: I put this many warnings in because, with the "faster" default setting, the consequences can be serious, as we have been discussing on the Crew section of the forum and on Bugzilla on Bug 26 and its related bugs. If we were to change the default to "safer" then this page could be rewritten with most (maybe all) of the red warnings disappearing and being replaced with a "friendly" blue advice panel telling the reader about "faster" and its benefits & risks.
4. I also think we should explain however briefly that the same format (with temporary folder instead of _data folder for unsaved projects) I will add some draft text for this.

Audacity project files store information about tracks, labels and other project data. An Audacity project consists of the AUP project file and its associated _data folder which contains numerous small AU audio files in subfolders. An Audacity project cannot be played in a media player such as Windows Media Player or iTunes. To obtain playable audio files it is necessary to Export the Audacity project to WAV files, MP3 files or similar.

Audacity may increase processing speed, and save some space, by referencing external audio files rather than making a copy (this will depend on the settings that you have in your Preferences for Import/Export, see Dependencies below). Note carefully that your project will no longer work if you rename, move, delete or overwrite the original audio file(s) on which it depends.

Audacity projects contain audio clips arranged onto tracks. The project's structure is:

1. A project file - the name of the project followed by ".aup", for example "my_song.aup"
2. A _data folder with the same project name and in the same folder as the AUP file, for example "my_song_data"
3. Within that _data folder, a sub-folder structure with lots of little AU files which are segments of the recording
4. Additionally data is stored which enables Audacity to manage the graphical waveform display and carry the links to any external dependent audio files in use by the project.

Bill 03Mar11: The AUP files also contains gain, pan and envelope information. Do we want to include that? Perhaps the fourth point above should be integrated into the paragraph below since it isn't really talking about the project structure (the files and folder that make up the project), but instead the contents of the AUP file.

Peter 16Mar11: I don't really want to move the fourth point down - but I did add the extra text on "gain, pan and envelope information" to the paragraph below

The project file describes how Audacity links these AU files together to make up the clips and tracks in the project; it also contains gain, pan and envelope information. The AUP file is in XML format and can be opened in a text editor if required. The AU files are stored in a lossless, uncompressed format. Their default size is 1 MB or less. This Audacity Project Format is designed to make editing audio faster in Audacity. By updating individual AU files during editing, Audacity can change audio or move audio around in the project without copying large quantities of data from one place to another.

Audacity's project format is not compatible with any other audio program. When you Save an Audacity project, it is saved in the Audacity Project Format ; an AUP file cannot be played using an MP3 player.

The four rules for keeping your Audacity Project happy:

1. When importing an uncompressed audio file with the "Read uncompressed file directly from the original (faster)" option checked in Import / Export Preferences (and note this is the Audacity default setting), never move, rename or delete that file, unless you first copy it into the Audacity project. See File > Check Dependencies for more information.
2. Never move, delete or rename any of the files or folders inside the _data folder.
3. Never rename the AUP file or the _data folder.
If you want to rename your project (for example, to save a snapshot at a particular point), use the File > Save Project As... command.
4. Always keep the AUP file and the _data folder together in the same directory (folder).

Opening an Audacity project

When opening an Audacity project always use the File > Open command to open the <my_project_name>.aup. Do not attempt to open, import or manipulate any individual AU files.

Audio for use in Audacity, but which was not recorded in Audacity, will need to be imported using File > Import or File > Open. The Import command is used to import audio data into an already open project, whereas the Open command used on an external audio file will either open a new Audacity project, and import the audio data into it, if the current project already contains any tracks; or import the audio data into the current project if contains no tracks.

Gale:See Consistency discussion. I prefer two links, one to File and one to the anchor in File. Anyone else?

Peter 27Feb11: I did read the recent comments in the Consistency discussion before I wrote this. But I think that it may be a case of "horses for courses". In this particular instance in the little paragraph above there is already a link to the "File" menu in the first sentence for any interested reader. In the third sentence I actually want to direct the user to the actual information relevant to them at that time i.e. the import or the open. At that stage sending them back to the top of the "File" page could be confusing as they will then need to scroll down to find what they need.
But I am perfectly happy to fall into line with whatever consistency standard we finally decide on.

• Gale: I think consistency is a goal because lack of it can confuse too. Your sentence "always Open the <my_project_name>.aup file from the File menu" doesn't 100% guarantee people will use "Open". It isn't really grammatical with the "Open" capitalised either. "Choose File > Open" (linked or not) should be clearer if it is used consistently. To be both consistent and flexible, how about <anchor> after the ">" always going to the anchor, but the root menu before ">" does not have to be a link (after all, in some cases it may become tedious to repeat links, so you might only want to make a menu item into a link the first time of use.
• Peter 28Feb11: I have added my thoughts to the consistency discussion in the Wiki. When a final decision on the preferred form is reached I will ensure that this page conforms.

Dependencies

Depending on the Import/Export Preferences settings, when an uncompressed audio file such as WAV or AIFF is imported or opened, Audacity may save time by not making a copy of the file and in that case will refer externally to the original file as it manipulates the audio data within the project (while not ever making any changes to that audio file unless it is told to do so).

This external reference is the default (faster) setting for Audacity's Preferences.

Be very careful not to modify such audio files with another program (or move, re-name or delete them) while they are open in Audacity.

When a project is saved, providing that Audacity's default setting has not been changed in the project's Preferences settings, Audacity will display a dialog box showing these dependencies and give the option of copying all of the audio data into the project making it independent of external audio files and making it safe to delete, move or modify the original audio files if necessary. The project's Preferences settings can be modified so that Audacity will not ask but will always either "never copy" the dependent audio files, or "always copy" them into the project on exit from Audacity.

At any time it is possible to click on File > Check Dependencies... to see if the project depends on any external files.

Import settings: "faster" versus "safer"

There are two settings available to control the manner in which the File > Import command operates. The default setting is Read uncompressed audio files directly from the original (faster) and the other is Make a copy of uncompressed audio files before editing (safer).

The faster option: This is the default option and is set this way as the default so that Audacity can use its On-Demand Loading to operate faster and save disk space. Import of the audio will usually be faster, but Audacity will depend on the audio file remaining accessible and having the same name and location as when you imported it. The audio file is not actually imported or copied into the project in this case, rather it is accessed as an external file by Audacity.

The safer option: This is the more secure option to choose, meaning that Audacity will always have its own copy of imported files to work with. Choose this option if the Audacity project file is required to be opened on another computer, or to be sent to someone else. This option need not be chosen if an exported audio file like an MP3 or WAV file is to be sent to someone else.

It is important to understand the implications of the default setting as faster . If this is left to the default value then it is crucial that any uncompressed audio file on which your project depends is not moved, deleted or renamed. If this happens then although the project will still show the correct blue waveform in the display, there will be gaps in the project's sound as Audacity will be unable to find the external audio file(s) on which the project depends.

If plenty of disk space is available and the time taken to make the full import is not an issue, then it is strongly recommended that this Preference be set to the safer option. This way the project will then always remain independent of external audio files.

Saving an Audacity Project

Saving an Audacity project lets you save unfinished work and re-open it later in Audacity exactly as it was, with all edits and recorded/imported tracks preserved. This is a different process from using one of the Export commands in the File Menu. Export creates an audio file like WAV or MP3. Use Export whenever you want to hear your work in media players or to burn CDs, because no other programs can open Audacity project files.

There is no need to save a project. If you don't, the necessary audio data is stored in the temporary folder specified in the Directories tab of Preferences until exiting the program. At that point, Audacity offers the choice of saving a project or not.

Some benefits of saving a project:

• No need to re-import or re-record files
• Fast loading, even of multiple long tracks
• Audio data always preserved in lossless quality. This is useful if you have already exported to a lossy audio format like MP3 but decide to edit the file further. Editing and re-exporting the project saves the additional quality loss of re-editing the exported MP3.

Exporting Audio

Neither the .aup project file or the .au files in the _data folder can be used in other programs or devices. To use the project's audio outside Audacity, choose File > Export... which brings you to the File Export Dialog. Here you can choose from various standard audio file formats according to your purpose. The two most common formats which can be played almost anywhere are

• WAV: a lossless format giving perfect quality, ideal for burning to Audio CDs
• MP3: a lossy format, but small enough to send over the internet or store on portable devices.

To export as MP3, don't forget to add the LAME MP3 library to your computer. Add the FFmpeg library to your computer to export to AAC or WMA which are used in iTunes and Windows Media Player respectively.

How to move an Audacity Project

Peter 27Feb11: I am still not sure whether this section on moving Audacity projects really belongs on this page - or if it deserves a page of its own, linked to from this "Audacity Projects" page. Any comments?

Ed 27Feb11 Have not looked at how "long" the page is without editornote divs but unless really too long I would keep it here. Especially considering "complex structure as described above" which would have to change to a page referal

Moving Audacity projects can be tricky due to their complex structure as described above. Any project can be moved on the same computer by making a copy of the project with the Save Project As... command.

Simple Projects

For a simple single track project (that does not have gain or pan settings, or use an envelope to adjust the volume) one possible solution is to not to move the project. Instead, use the File > Export command to export a WAV file. This WAV file can then be copied to another computer, then the File > Import command can be used to load the WAV file into an Audacity project. Alternatively the WAV file can be sent by e-mail or via a file sharing web site to someone else who can import it into an Audacity project on their computer.

Bill 03Mar11: I find the alert div below confusing. I had to read it twice to realize you were talking about importing the WAV into the new project. I think we should lose this alert or make it clearer.

Peter 16Mar11: I've tried to make it a bit clearer - any better for you Bill?

Unless the Audacity default Preferences setting for Import has been changed to the "Safer" mode Audacity will not actually copy the WAV file into the project when you use the Import command but will instead reference it as an external audio file.

Complex Projects

For a project that has multiple tracks, or a single-track project that has gain or pan settings or uses an envelope to adjust the volume of the track, the entire project will need to be moved. To do that it is necessary to move the AUP file <my_project_name>.AUP and the _data folder <my_project_name>_data either to a second computer or to a different location on the existing computer. Ensure that the .aup file and _data folder remain together in the same folder.

As noted above, any project can be moved to a different location on the same computer using the Save Project As... command.

If you want to move a project to a different computer the project must not depend on external audio files. Use the File > Check Dependencies... command to check whether the project depends on any external files. If it does, the dialog box will give you the option to make a copy of those files within the project.

It can be difficult to e-mail complex projects to other users; to do so it is necessary to zip up the entire project structure and e-mail or share that zip file. The reason for zipping up the project is to make sure the project structure remains intact during the transfer, not to save space. A zip archive of a project is likely to be about 10% smaller than the unzipped project.

Ed 27Feb11 there are other tools besides Zip, maybe a more generic description is in order?

External files have absolute references in the AUP file and thus it is difficult to move an Audacity project that depends on external files to another computer but relatively easy to move a project to a different location on the same computer. See this article in the Wiki on Sending your work to others.

Bill 24Feb11: Sorry, Peter, but external files have absolute references in the AUP file, e.g. on Mac aliasfile="/Volumes/Disc/Path/To/ImportedFile.aiff". Thus it is impossible to move an Audacity project that depends on external files to another computer but easy to move a project to a different location on the same computer.

Gale: Not "impossible" at all on the same OS, just put the _data folder in the correct path! Please see Sending your work to others in case you want to link or there is something else you want to say here.

Bill 24Feb11: Yes, impossible unless you first copy the aliased files into the project. That appears to be what the wiki article is implying.

• Gale: The Wiki doesn't say it's "impossible" (rather, it says "you must" copy in if you want to move the project to another computer). The problem is you can't say "impossible" unless it is really is :=)

  If you did not copy the files in, then as well as putting the _data folder in the correct path, copy the external files to the other computer, creating a new folder if needs be to put them in the path stated in the .aup file. And even if I have your Volumes/Disc/Path/To/ImportedFile.aiff that I want to move from Mac to Win, I can just put that AIFF in an appropriate folder on Win, and do a find and replace on the aup file. I would not recommend that here, but it works.

Peter 24Feb11: I pruned the "4-byte FP" stuff from the .au file description - it is largely irrelevant technobabble to most users. The original text is parked here: The .au files are a lossless, uncompressed format using 4 byte floating point numbers.

Gale added a note: The summary files have the same format as the audio files, but there are fewer of them. Gale: Importing the same WAV aliased in one project and not so in another produces the same number of .auf files in the aliased project as .au files in the other project (at default blocksize)

• Peter: Gale I'm not sure I really understand this comment - or if we need to retain it on this page?

• Bill 24Feb11: I don't think we need to talk about .auf files. That's getting way too technical. FWIW, here is my understanding of .au files versus .auf files.
  • AU files contain uncompressed mono audio data, and are limited to 1 MB in size. So the amount of audio they contain is dependent on the project bit depth and sample rate. Note that AU files have the same format as the project. If it is a 16-bit PCM project the AU files will contain 16-bit PCM data.
  • Each AU file has a header that appears to contain the information for drawing the waveform. Gale cannot reproduce this on Windows, but on Mac if I import an Audacity .au file into a project I get 12,346 samples (at 16-bit depth, 44100 Hz) of garbage at the start of each file. That corresponds to the offset field in the header of the AU file of 24,716 bytes. AUF files contain only the waveform-drawing header information. This is why the waveform can still be drawn when the aliased (external) file is no longer available.
  • Each AUF files points to a chunk of the aliased file that corresponds to exactly the same chunk of audio that would be contained in an AU file if the external file were copied in instead of aliased. Thus you always get exactly the same number of AUF files as AU files.
  • I have yet to see any of these mythical "summary" files (as opposed to AUF files), either in the _data folder or referenced in an AUP file.
  • I also find it peculiar that we are left to infer all this, when a developer who understands the Audacity project format could give us a definitive answer. This is akin to the debate on whether or not Audacity does all internal processing at 32-bit, which AFAICT has not been resolved either.
    • Gale: As soon as I get full time I will try and do some research and go through this article properly. I wish I had had time to do so before, but if you were unsure about doing it yourselves, you could have asked me to prioritise merging the page. It was kind of Peter to volunteer, but it might have saved time. I have raised some disquiet about the content here in a [Manual] thread which James was Cc'd on, though he did not comment. I will ping him if I am still not happy, so we get this page sorted. All that said, I still think (without rewriting it from scratch), all "heavy" technical stuff should either be tucked away at the bottom as a technical appendix, or go to Wiki.

      As for "all internal processing at 32-bit", it was never a definitive answer but Martyn said he thought so, and it does look like it. It's just not what I understood from correspondence I had ages ago with Dominic (and I still don't think I misunderstood it).

• Peter 27Feb11: Gale, I rewrote this page and extended it as we keep getting posters on the forum who need to understand some of the intricacies of the Audacity project structure and also to understand the implications of the faster/safer import settings. It is much easier to develop a reasonable page here in the manual to point them at rather than rewriting it fresh each time on the forum postings. I shall not be unhappy if you should wish to rewrite/restructure this page at any stage in the future following your proposed research - and I will gladly help you with editorial reviews if you do.
• Gale: I appreciate your work here, Peter. However for those on 1.2 it would be much more appropriate to send them to the existing Wiki documentation than here.
• Peter 28Feb11: Thanks Gale. Yes, I agree that this page is being written for the benefit of 1.3 users (and future 2.0 users hopefully). I note from the forum that we seem to get as many, if not more, 1.3 posters these days than 1.2 (possibly helped by the retitling we did on the forum and the main Audacity site). I was aware of the File Management Tips in the Wiki, but for most readers it is far too long and far too dense - probably leading to TLDR. One of the key discussions highlighted in this rewritten Manual page is to help the reader understand the implications of "faster" versus "safer"; in the Wiki article this information is fairly well "hidden" in the dense text.