Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
There are several ways to contribute to Audacity. All of them tremendously help out other Audacity users.
Tutorials are an awesome way to help out Audacity users. So if you know how to use Audacity, you might be just the right person to teach others! You can either write guides, or make videos.
Audacity welcomes contributions to both and , whether it's a small spelling correction or an entirely new guide. If you're not sure what to start with, check out some good first issues:
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:
Best practice
Do one task per branch. Want to make a new guide on a new feature? Make a new branch. Want to remove all instances of the oxford comma? Make another branch. You can click the branch icon in the top bar to make new branches.
Doing so makes it easier to understand what your changes are exactly, and should one of your changes be rejected, most of your other work won't get blocked by it.
When editing on Gitbook, you can edit existing pages, but you cannot create new ones. If you'd like to make a page about a new topic, write to LWinterberg in the . You also can hand in Markdown files or Word documents to him directly to add. This restriction does not apply when , however, there are other when editing through GitHub.
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:
We have some requirements for which video tutorials are accepted into Audacity Support pages (see the for more info)
Only submit complete pages. Your progress is saved automatically, so if you want to call it for the day, simply close the page and continue the next day. If you accidentally hit "submit", simply start editing again to convert your branch to a draft branch again.
Be aware of the others, to avoid duplicate work. You may connect with other editors in our discord servers.
Follow the Style Guide, to give this entire site a somewhat uniform style.
These are the rules designed to give the entire user guide a somewhat unified style. You may apply them with some freedom.
The goal of the user guide is to provide explanations on how to perform various tasks in Audacity.
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:
Tasks aren't necessarily tied to individual features. For example, 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")
Rule of thumb: If a feature is easy to use, but hard to find, document it like a task, ie answering the question "how do I do x". If a feature is hard to use, document how to use the feature as a series of sub-tasks if possible.
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 , but also is way harder to understand and thus to find.
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.
Caution: The following topics are out of scope:
Audio-related content beyond Audacity, like: "how to build a quiet recording booth"
Reviews and recommendations of software/plugins/...
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.
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").
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 should be written in a step-by-step list where useful. For example:
Do This
then that
then a third thing
If you need to interrupt the steps for explanations, you can either do
Do this
then that (shift+enter) Note: This is an explanation on a new line
then a third thing
If instructions are different depending on the operating system or other factors, you can use tabs, like this:
Windows Instructions
MacOS instructions
Linux instructions
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.
If a task has a main way of working, but may benefit from additional context, you can use the Expandable block:
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.
Gitbook offers 4 types of info boxes.
Warning: Use these for information where things might go wrong and the user might get undesired results. These boxes should be started with
Caution: or Warning: depending on which feels more appropriate in terms of urgency
Danger: Use these for super important information only, where ignoring the danger box would lead the user to irreparable damages (lost data, broken audio, ...). These boxes should be started with
Danger: for super important info
Success: Use these for things the reader should do. These should be started with
Best practice: or Do: for best practices
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).
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 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..."
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.
Due to licensing restrictions Audacity cannot be distributed with built-in support for ASIO. However You can build Audacity for your personal use and include ASIO support.
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 or WDM-KS (Windows Driver Model Kernel Streaming). 24-bit sampling allows greater dynamic range, lower theoretical 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 interface protocol support multi-channel recording on some sound devices, but not the very low latencies that are possible on ASIO.
Technical documentation about the internals of Audacity.
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.
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)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 and then edit the relevant sections.
Exact details can be found here:
TODO
(this probably is a category on its own, but let's write it on this page for now)
Any page of both support.audacityteam.org and plugins.audacityteam.org can be edited either on Gitbook (see Writing Tutorials and User Guides for instructions) or using Markdown syntax on GitHub.
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.
Best Practice: Frequently switch between the Code and Preview tabs in GitHub to get a general sense of what your edit will look like.
Also, if you haven't already, now is a great time to familiarize yourself with the .
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 and await review by an Audacity team member.
You can edit Markdown in any text editor. More advanced editors like 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.
Caution: Avoid using office suites like Microsoft Word, LibreOffice or Google Docs to edit Markdown. They tend to use very different formatting options, which don't transfer to plain text. As a rule of thumb, if it doesn't save in .txt or .md, it's not the right app to use as a Markdown editor.
To get started, first clone the repository, either using git clone by clicking the code button on 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.
Further information on using git with VScode can be found in the .
Outside from the , there are some more technical things you need to be aware of:
The sidebar menu is handled through , 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.
Testing Audacity is one of the best ways to find bugs.
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 (or comment on the pull request that introduces the bug if it's unmerged)!
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 ; 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 . This is to invite testing from a wider audience.
Audacity comes with some tools to aid you with testing.
See - these can make it easier for you to do repeated tasks.
Journaling is a feature that records all your actions and lets you replay them. This feature is currently under development and not really ready.
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>>.
Copy the journal file to a new folder (eg: QA-tests) and name it so that you can easily find it again.
Launch Audacity from the command line, like this:
Answering user questions is the most direct way of helping users. It also will net you the most "thank you"s
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 .
Pages under this section are just stubs. Feel free to work on them. Check out the and for more info
path\to\audacity.exe -j QA-tests\yourtest.txtpath/to/audacity -j QA-tests/yourtest.txtpath/to/audacity -j QA-tests/yourtest.txt
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!)
Contents on this page are licensed under the license. This does not necessarily apply to embedded videos.
has been made possible by a tremendous amount of effort from the following people:
Gale Andrews
Richard Ash
David Bailes
Christian Brochec
Translators:
Carmelo Battaglia (Italian)
Leo Clijsen (Dutch)
Olivier Humbert (French)
André Leu (French)
Some of their efforts have been ported over to this site.
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
Thomas De Rocker (Dutch)
Daniel Winzen (German)
A page showing the Markdown for all the basic and fancy options there are. Also compares it to Github's Markdown. This block is the page description.
Contrast this page to:
(shows up in the outline)
(also shows up in the outline)
(does not show up in the outline)
Headings can be used anywhere, including inside other blocks.
Bold,
Italics,
Code,
Strikethrough,
,
,
,
page link: ,
page anchor link: ,
colored text,
colored background,
both colored,
LaTeX:
These can be used anywhere.
Unordered
List
Ordered
List
List with
sub-items
can have
Lists can be used anywhere, including inside other blocks. They can only include inline content and other (nested) lists.
Infoboxes:
Caution
Danger
Success
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.
Inline image:
Image block:
Attached file:
Embeds cannot be used inside of other blocks except the Tabs block, nor can other blocks be placed inside them.
Any table but the most simple option will be converted into HTML, rather than markdown when edited through gitbook.
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.
Cards and tables can be converted into each other.
content of first tab
content of second tab
content of third tab
Tabs cannot be used inside other blocks. Tabs can have most other blocks inside them, except of other tabs, expandables, and API blocks.
Expandables cannot be inside other blocks. Expandables can have headings, lists, code blocks, and inline content inside them.
A Gitbook-specific drawing thing, generating SVGs. Likely useless when using Markdown.
Cannot be placed inside of other blocks except the Tabs block. That said, an inline variant is available which can go pretty much anywhere.
GET https://example.com/example
shows itself up in the outline. Example of all available parameters follows:
Cannot be used inside other blocks. Can only contain plain text. Unfortunately very tailored towards web APIs only.
The above line is a divider.
Translating Audacity is the best way to get involved right in Audacity's UI without having to code.
...
text
text
text
id
String
Description
id*
String
Description
id
String
Description
id
String
Description
id
String
Description
Card 1 top. Card has an image on top.
Card 1 mid
Card 1 bottom
Card 3 top. With inline formatting.
Card 3 mid
Card 3 bottom
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.
To speed up your workflow, various shortcuts are available, which you can see by pressing the overflow menu in the Transifex editor:
The most important one of these probably is Tab, which saves your string and automatically moves you onto the next.
And that's it! Happy translating!
The translator community exists in two places:
If you have any questions, or want to get notified of upcoming releases in need of translation you can do so here.
Audacity uses GitHub and you can explore the available translations at https://github.com/audacity/audacity/tree/master/locale
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:
Download the audacity.pot file from Audacity GitHub
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.
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.
Download the audacity.pot file from Audacity GitHub
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.
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.
You can get an up-to-date alpha version of Audacity, NOT suitable for production use, but good for checking translations on, in the nightly version: https://audacityteam.org/nightly. From there, you’ll find there are choices of builds for different platforms. Download the right one for your platform.
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.
If creating a new translation, create a new directory for your language using the correct language code from the wxWidgets . For example, the code for Punjabi is “pa”, so on Windows, create “Audacity\Languages\pa”.
Rename the saved .mo file to “Audacity.mo”, and paste it into the directory you opened or created.
Open Audacity and in Preferences > Interface, choose your language and click OK. You should now see your translations.
Please read Translating Audacity for more tips on translating the Audacity source code, and to learn how the Audacity software is translated.
A Macro is a sequence of pre-configured commands (mainly effects) in a set order that can be applied automatically to projects or audio files.
ZoomIn.png
transport toolbar.png
Trim.png// a code blockcode blocks <b style="some_css: 23px;" class="and other things"> also supports syntax highlighting</b>{
// good Response
}{
// not found Response
}{
// error Response
}
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.
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.
Use Tools > Macros... if you need to create a new Macro or to edit an existing Macro.
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...
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.
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.
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.
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
See the Macros Examples page for examples of using Macros
