Editing through Github.com

A link for GitHub is shown either on the right-hand side or in an overflow menu of any page:

Once you are on GitHub, you will see a pencil in the top right of the file.

You now can make your changes to the page.

Once you are done, press Propose Changes

This brings you to a page where you can review your changes. If you are satisfied, click Create Pull Request.

After you click "create pull request", it will show up on https://github.com/audacity/audacity-support/pulls and await review by an Audacity team member.

Editing through a local editor

You can edit Markdown in any text editor. More advanced editors like VSCode may show useful shortcuts and visualizations for easier and faster editing, but in principle, even the simplest text editors like Windows Notepad can be used to create them.

To get started, first clone the repository, either using git clone https://github.com/audacity/audacity-support.git by clicking the code button on https://github.com/audacity/audacity-support and opening it in GitHub Desktop

Once it's cloned, you'll find the files of support.audacityteam.org in the main branch, and the files of plugins.audacityteam.org in the plugins branch. Any additional branches have been split off from the main branch to preserve documentation for previous versions of Audacity.

Technical notes

Outside from the syntax requirements, there are some more technical things you need to be aware of:

• The sidebar menu is handled through SUMMARY.md, not the file structure itself. If you want the page you created to show up in the sidebar, you will need to update this file accordingly. That said: Try to match the structure of SUMMARY.md with the folder structure.

• While you technically can work directly in your fork's main/plugins branch, it is highly recommended to make a new branch based on upstream/main or upstream/plugins instead for your changes. This way, you can always fast-forward merge the latest changes into your fork.

• When updating your fork's side-branches to the latest state of main, rebase it if possible.

General

The goal of the user guide is to provide explanations on how to perform various tasks in Audacity.

Features vs tasks

Documenting features seems like the obvious thing to do: Audacity has various menus, so better have a list of what every option in that menu does. However, this leads to the situation where some pages are completely unfindable as a reader already needs to know where certain options are in the menu in order to find out what the page would be called. For example, the feature containing the slider for the recording and playback volumes is called Mixer Toolbar. But nobody except the people most intimately familiar with Audacity know it's called that!

To combat this, try to write your guides as a way towards a goal, or a task. The above example, instead of naming the page after the feature, name it after the task it does, so: Setting recording and playback levels

Tasks aren't necessarily tied to individual features. For example, Noise reduction & removal can talk about several tools as once as they all are means towards a common goal.

If a feature has many different modes or options that are unrelated to the task you're describing, avoid making long lists of what all the feature can do. Focus on the task-related ones instead.

If a feature has several ways to access it, use the most accessible option. For example, for an "how to play audio" article, simply mention the big green play button and the shortcut Space. Don't also mention Transport > Playing > Play/Stop.

There are some exceptions to this, especially when documenting more "advanced" features like Macros which need extensive guiding about how to operate it. Instead of a linear "go here, then here and there, and then you're done", split them up into sub-tasks (for macros: creating macros, editing macros, etc.) and keep these unrelated tasks on one page. Avoid breaking it down to the point where you are explaining individual buttons (don't say "the cancel button cancels the effect without applying it")

Target audience

Audacity's user base consists largely of casual users. As such, you can't expect the readers of your guide to understand even fairly common audio terms (for example: compressor or loudness vs volume), unless it's directly connected to the topic you're writing about.

For example, if you write a guide about compressing and expanding audio, you don't need to hold yourself up on explaining what a compressor is, since the only people who'll ever end up reading that guide are people who already know about that. However, if you were to mention a compressor on a page about general audio editing, you would need to explain what a compressor is good for.

That said: If it's possible to describe a feature without needing to resort to lingo, use it even if it's slightly less accurate. For example, "punch-in repair" would be the accurate term for Re-recording a section, but also is way harder to understand and thus to find.

Scope

While there's a lot of things you can write about in relation to Audacity, keep in mind that this site is focused on user guides (or how-to guides, or tutorials - they all have the same idea). We want to minimize work on contributors while maximizing impact, so guides should be kept as general as possible. Only use qualifiers such as "for podcasters" or "for musicians" if their use case shares almost no resemblance to what everyone else would be doing anyway.

Writing style

You can address the reader directly ("you"). You should remain impartial in the process though, so no "I" or "my".

The overall tone should be friendly but not patronizing, and the language should have a healthy middleground between casual and technical.

Page titles

Titles should reflect the task you're trying to teach. For example, if you're teaching how to add reverb, the title should be "Adding reverb"

The title should be concise (try keeping it below 60 characters).

Page titles should be written in sentence case. So generally, the first is capitalized while everything else is not, except proper nouns and acronyms ("Audacity", "FFMPEG").

Introductions

Underneath the title is a field for page descriptions. These descriptions are the first thing users see of the article when looking at Google, or seeing an embed to it somewhere.

As such, they should give a good summary of what the page is going to be: In a few words, how will a goal be achieved? What features will be used?

Instructions

Instructions should be written in a step-by-step list where useful. For example:

1. Do This

2. then that

3. then a third thing

If you need to interrupt the steps for explanations, you can either do

1. Do this

2. then that (shift+enter) Note: This is an explanation on a new line

3. then a third thing

Instructions for different Operating Systems

If instructions are different depending on the operating system or other factors, you can use tabs, like this:

Tabs aren't part of standard Markdown, so they probably won't show up properly if you're using github or a local editor. They'll show up just fine on Gitbook though.

Technical explanations, asides, and manual backups

If a task has a main way of working, but may benefit from additional context, you can use the Expandable block:

Images

You can take screenshots using the clipping tool or tools like ShareX. ShareX has the advantage that it has built-in tools like arrows, step-by-step bubbles and labels which can help you visualize several steps at once.

With images, there always is a tradeoff between easy maintainability, clarity and context. So crop them as much as possible without losing important context, and use them in a way that makes updating them as painless as possible.

Info boxes

Gitbook offers 4 types of info boxes.

These info boxes aren't part of standard markdown, so if you're not using gitbook itself, but edit through Github or a local editor, they will look a bit silly in your preview (but show up correctly here).

Video Tutorials

If an image is worth a thousand words, a video tutorial can be worth a million: At it's best, it can tell the entire story the written guide would make in a way that always has all necessary context and requires no lengthy description of where to find things.

However, video tutorials can go out-of-date incredibly quickly and then cause a lot of confusion among viewers.

Because of this, a video tutorial must follow these rules to be added to an Audacity Support page:

• The video must clearly state what version of Audacity it's referring to in the beginning.

• The video must be in the language of the Audacity Support page it's meant to be embedded in. Right now, that's English only.

• The video must be a dedicated Audacity tutorial or how-to guide.

• The video must refer to Audacity Support as the place to get up-to-date help from.

• The video must not contain a sponsorship read, and it is preferred to have the video completely ad-free.

• The video should be licensed Creative Commons-Attribution (see YouTube help). This way, if your video goes out of date, other people can update only the part of your video that goes out of date.

• The video and the Audacity Support page it's supposed to be embedded in should match the steps they take. If the video tutorials goes on a tangent unrelated to the initial task, the written guide may omit the tangent and instead place the contents of the tangent in a "See also" section.

Best Practices for Videos

The following points are considered best practice for video tutorials:

• Start with the purpose and version number and then go straight into the content: "To do XYZ in Audacity 4.2.0, first go to..."

• Use a script which you follow when making your video. This will automatically eliminate the following two points, and also get you a long way towards making subtitles.

• Avoid going off-topic, eg "hey guys, and welcome back to another video! my sister's aunt's nephew requested I make a tutorial so he can cook his eggs using Audacity to which I said..."

• Go through your tutorial linearly step-by-step, and avoid jumping back to earlier sections much later in the video. For example, if you are in Step 9 already, jumping back with a "oh yeah, I forgot to add that in Step 3, you need to also do..." is majorly confusing.

• Add subtitles to your videos. Not only do they make your tutorial more accessible to deaf people, they also are useful to people who have trouble understanding your dialect or accent, or who want to auto-translate the subtitles into their own language.

• Use chapters on YouTube to mark major steps in your video. They work by putting the following in your video description:

0:00 Intro 
0:30 Step 1. Clicking here 
0:45 Step 2. Sliding there 
1:00 Step 3. Cha-cha-cha

(note: the first timestamp must be 0:00)

About this document

This is a living document. It contains the best practices, as determined by the community. Feel free to discuss additions and changes on the discussions page, or in the discord.

• Synchronizing with claps

Writing Tutorials and User Guides

Gitbook works a bit like a wiki in that you can edit all pages freely, but unlike a wiki, it uses git's "everyone has their own branch" principle. That is to say that the changes you make are independent of everyone else's changes, and won't show up on the main (live) website until the branches are merged.

To some degree, this means that you can do whatever you want in your branch. That said, there's some things which make things easier for everyone involved:

Making Video Tutorials

Video tutorials are highly appreciated as part of a guide. You can upload them to YouTube (or Vimeo/Dailymotion/...) and embed them in your guides, or in other people's guides, like this:

Audacity can record and playback audio on your Windows PC using one of the following three alternative interfaces:

• MME

• Windows DirectSound

• Windows WASAPI

ASIO (Audio Stream Input / Output) is an additional proprietary interface to record and playback audio in Microsoft Windows. ASIO bypasses the Windows audio mixing components to provide lower latency direct communication between computer audio software and hardware. Most audio recording interfaces manufacturers provide a driver to support ASIO.

• ASIO supports 24-bit sampling which is only otherwise available using Windows WASAPI or WDM-KS (Windows Driver Model Kernel Streaming). 24-bit sampling allows greater dynamic range, lower theoretical noise floor and greater resolution at lower audible volumes.

• An unmixed ASIO output is "bit identical" to the original source.

• Multiple physical input and output channels of the hardware are accessed over one single device.

Windows DirectSound interface protocol support multi-channel recording on some sound devices, but not the very low latencies that are possible on ASIO.

https://manual.audacityteam.org/man/asio_audio_interface.html

• https://gist.github.com/SteveALee/da24c2be633340b8791066dd98eb5d0b

Contrast this page to:

Heading 1

(shows up in the outline)

Heading 2

(also shows up in the outline)

Heading 3

(does not show up in the outline)

Headings can be used anywhere, including inside other blocks.

Inline text formatting options

These can be used anywhere.

Lists

• Unordered

• List

1. Ordered

2. List

• Task

• List

• List with

  1. sub-items

  2. can have

     • changing list styles

• ...

Lists can be used anywhere, including inside other blocks. They can only include inline content and other (nested) lists.

Infoboxes, quotes and code blocks

Infoboxes:

A quote block

These blocks can be used inside of Tabs. The code block can also be used in Expandables, but cannot have other blocks inside it. The quote block and infobox can have headings, inline content and lists inside it.

Images and files

Image block:

Attached file:

Embeds

Embeds cannot be used inside of other blocks except the Tabs block, nor can other blocks be placed inside them.

Tables

Tables cannot be used inside other blocks except the Tabs block, nor can other blocks be placed inside them. Inline content works inside of text columns only.

Tabs

Tabs cannot be used inside other blocks. Tabs can have most other blocks inside them, except of other tabs, expandables, and API blocks.

Expandable (Details block)

Expandables cannot be inside other blocks. Expandables can have headings, lists, code blocks, and inline content inside them.

Drawings

A Gitbook-specific drawing thing, generating SVGs. Likely useless when using Markdown.

LaTeX

Cannot be placed inside of other blocks except the Tabs block. That said, an inline variant is available which can go pretty much anywhere.

Web API methods

API title

GET https://example.com/example

shows itself up in the outline. Example of all available parameters follows:

Path Parameters

Query Parameters

Headers

Cookies

Request Body

Cannot be used inside other blocks. Can only contain plain text. Unfortunately very tailored towards web APIs only.

• https://alphamanual.audacityteam.org/man/Sync-Locked_Track_Groups

If you know Audacity well, but don't want to write tutorials, you can help users out directly. The most active communities in this regard are:

• The Audacity Forum,

• the Discord community, and

• the Audacity subreddit.

(this probably is a category on its own, but let's write it on this page for now)

• Making new tracks

• Use case: spoken word with music in the background

• Mute & Solo

• Moving clips & Sync lock

• Splitting a recording into several tracks

What are the main uses for Macros?

Macros in Audacity can be used for:

• Batch processing: Apply one or more effects to multiple audio files and export the processed audio into a new file.

  To use this select the Apply Macro to: Files... button in the Macros Palette or the Manage Macros dialog.

  For more detail on batch processing please see this page.

• Effects automation: where the selected audio in the track or tracks in the current project is subjected to the same prescribed sequence of effects, and optionally, a file exported from the entire audio.

• Effect presets: where selected, commonly used, effects are stored with your preferred settings for quick re-use.

How to access Macros

You can manage and apply Macros using the Tools Menu:

• Tools > Macros... to manage Macros: to create, edit and test them

• Tools > Apply Macro > Palette... for a toolbox of Macros

• Tools > Apply Macro > named Macro to apply one named Macro

There are some examples of Macros and tips on using them.

Manage Macros

Use Tools > Macros... if you need to create a new Macro or to edit an existing Macro.

Macros Palette dialog

Use the Shrink button to show a reduced Macros Palette dialog which lists the existing Macros.

This dialog is also available directly via Tools > Apply Macro > Palette...

Apply Macro to

Both the Manage Macros dialog and the Macro Palette dialog have Apply Macro to buttons:

• Project applies the selected Macro to the current project.

• Files... applies the selected Macro to selected external audio files that are in a single directory.

For more details see the Macros Palette page.

Macro Command Parameters

Commands that call Effects, Generators, Analyzers or Tools, use the same familiar graphical interface (GUI) as appears when they are used from the normal top level menus.

Many of the other commands provide a simple GUI comprised of checkboxes and text entry boxes. Typical examples can be seen in the Scriptables I and Scriptables II menus.

Please see Manage Macros for more details.

Sharing a Macro

You can export a Macro as a TXT file using the Export button in Manage Macros and send it to another user, or copy it to another computer for use there

You can import another user's Macro, or a copied macro of your own, into your Macros folder by using the Import button in Manage Macros.

Where Macros are stored

Each Macro is automatically saved as a separate text file with TXT extension in the Macros folder in Audacity's folder for application data:

• Windows: Users\<username>\AppData\Roaming\audacity\Macros

• Mac: ~/Library/Application Support/audacity/Macros

• Linux: ~/.audacity-data/Macros

Macros Examples

See the Macros Examples page for examples of using Macros

TODO

Using Transifex to translate Audacity

• Click the JOIN THIS PROJECT button on the right side.

• Select the language you would like to contribute to from the dropdown.

• Click Join Project (if the language is Available to join) or Request Language if the language you want to contribute to is not available yet.

Once you have been approved as a translator you will receive a notification by email. After that you will see the project in your Dashboard and you can start to contribute.

• Click Translate at the top right side

• Select Audacity from the Resource Overview panel to start editing

• Select the string to translate and type the corresponding translation

• Click Save Translation and select the next string to translate.

Translate Audacity using a standalone application

Each language translation is stored in a PO file. For example it.po is the Italian translation and ko.po is the Korean translation.

These are some programs you can use to edit PO files:

If there is no translation PO file for your language create a new one using the following steps:

• Open poEdit and select Create new... (Create new translation from POT Template)

• Select the audacity.pot file and click on Open

• poEdit will ask you about the Translation Language. Select the language from the dropdown and click OK.

• Select Translation > Properties... and verify that the Character option is set to UTF-8 otherwise poEdit will not save any translations with non-English characters.

• Translate each one of the entries using the Translation textbox

• Select File > Save to save as a PO file. Select a destination folder and type a name for the file. Click on Save. poEdit will save a .po file plus a .mo file for use in Audacity.

Update an existing translation of Audacity

If you want to update an existing translation

• Download the PO file for your language, for example it.po or open a previously translated PO file from your computer.

• Open poEdit and select Browse files (Open and edit translation files)

• Select the existing PO file for your language and click on Open

• Select Translation > Update from POT file... and look for the audacity.pot file you downloaded previously. This will update your PO file with the latest strings from the downloaded POT file.

• Translate each one of the entries using the Translation textbox

• Select File > Save to save as a PO file. Select a destination folder and type a name for the file. Click on Save. poEdit will save a .po file plus a .mo file for use in Audacity.

Submitting a translation

• To submit a translation, please send the completed .po file to the audacity-translation mailing list. A member of Audacity Team will commit the file and send a message to the list confirming this.

Test a translation in Audacity

2. On Windows, open the “Languages” directory inside the unzipped Audacity folder, then open the directory with the same name as your .po file. On Mac OS X, right-click or control-click over Audacity.app > Show Package Contents then open the relevant LPROJ directory inside the “Resources” directory. On GNU/Linux, open the relevant “locale” directory in usr/share/ or usr/local/share.

4. Rename the saved .mo file to “Audacity.mo”, and paste it into the directory you opened or created.

5. Open Audacity and in Preferences > Interface, choose your language and click OK. You should now see your translations.

Further information

Testing Audacity is one of the best ways to find bugs.

Nightly builds

You can download the latest master build from https://audacityteam.org/nightly. These builds reflect the state the master branch. Anything in the master branch has passed at least a quick round of QA to validate that the features the change touched still work for the common use cases.

Before features go into the master branch, they live in pull requests. Each pull request comes with its own builds, available through the "Checks" tab inside the PR and then the "Artifacts" dropdown in the top right. Additionally, you can get builds which are still in development from https://github.com/audacity/audacity/actions. Both methods require a Github account.

When you do find something that breaks, make sure to file a bug (or comment on the pull request that introduces the bug if it's unmerged)!

Alpha, Beta and Release builds

Before each release, a branch is split off master named "release-x.x.x". This release branch contains all features which will be part of the next Audacity release. Bug fixes which go towards this release will be made inside this branch. You can get builds for it via https://github.com/audacity/audacity/actions; the nightly link will continue to give you master branch builds.

During the release process we may designate certain builds as "alpha" or "beta" and release them on https://github.com/audacity/audacity/releases. This is to invite testing from a wider audience.

Tools

Audacity comes with some tools to aid you with testing.

Macros

See https://manual.audacityteam.org/man/macros.html - these can make it easier for you to do repeated tasks.

Journaling

Journaling is a feature that records all your actions and lets you replay them. This feature is currently under development and not really ready.

1. start Audacity in journaling mode, <<TODO: HOW??>> do a certain task, and then close Audacity again. This will generate a journal file, which you can find in <<WHERE>>.

2. Copy the journal file to a new folder (eg: QA-tests) and name it so that you can easily find it again.

3. Launch Audacity from the command line, like this:

path\to\audacity.exe -j QA-tests\yourtest.txt

path/to/audacity -j QA-tests/yourtest.txt

path/to/audacity -j QA-tests/yourtest.txt

We maintain a list of free VSTs and similar plugins on plugins.audacityteam.org. You can find, test and add plugins to the list.

To do this, you can get access to the plugins space via https://www.audacityteam.org/gitbook-plugins and then edit the relevant sections.

Exact details can be found here: https://plugins.audacityteam.org/contributing/adding-plugins-to-this-site

Audacity is being developed on Github. Most information necessary to contributing code can be found there, such as building instructions.

These help articles have been created by the following people:

• Leo Wattenberg

• Gonzalo Guzmán

• (add your name here if you're editing some pages!)

License

Contents on this page are licensed under the Creative Commons - Attribution license. This does not necessarily apply to embedded videos.

Contributors of the old Manual

manual.audacityteam.org has been made possible by a tremendous amount of effort from the following people:

• Gale Andrews

• Richard Ash

• David Bailes

• Christian Brochec

• Matt Brubeck

• John Colket

• James Crook

• Steve Daulton

• Scott Granneman

• Greg Kozikowski

• Leland Lucius

• Dominic Mazzoni

• Edgar Musgrove

• Tony Oetzmann

• Alexandre Prokoudine

• Peter Sampson

• Martyn Shaw

• Vidyashankar Vella

• Bill Wharrie

• Leo Wattenberg

Translators:

• Carmelo Battaglia (Italian)

• Leo Clijsen (Dutch)

• Olivier Humbert (French)

• André Leu (French)

• Thomas De Rocker (Dutch)

• Daniel Winzen (German)

Some of their efforts have been ported over to this site.