Difference between revisions of "Developer Guide"

From Audacity Wiki
Jump to: navigation, search
(Added some MS links - will add more links later)
(Intro: 44100)
 
(58 intermediate revisions by 9 users not shown)
Line 1: Line 1:
Getting Audacity building on Linux is usually
+
{{intro|1=Links and brief explanations for developers}}
trouble-free because the right tools are there in the environment, or
 
can be found and installed easily.  The same isn't really true for
 
Windows and the win/compile.txt file provided with the Audacity source code assumes you know quite a lot
 
about how stuff works under the bonnet, and about Visual S0tudio.
 
  
  
=Windows Set Up=
+
'''See Also:'''
 +
* [[For_Developers]]
  
''Edit-hint: Please help us improve this text.''
+
''Yep, we've two or more similar pages doing much the same thing in different ways - and pointing to each other.  Our code does much the same thing too :-)''
  
'''It can help to work in stages.  It's probably not advisable to try to do all four steps in one session:'''
 
  
* First get comfortable with Microsoft's visual studio, MSVC 2005, downloadable from Microsoft {{external|[http://msdn2.microsoft.com/en-gb/express/aa700735.aspx here]}}. To develop in C/C++ for windows you also need a second download from the Microsoft site, which is the "Platform SDK", or if you are on Vista you'll need the new "Windows SDK". Download links:
+
==Intro==
  
{| style="margin-left:25px"
+
Audacity aims to be a '''simple to use''' but '''powerful audio editor'''.
|-
 
|'''Windows Server 2003 R2 Platform SDK''' for Windows 2000/XP/Server 2003:
 
|-
 
|<span style="font-style:italic" class="plainlinks">[http://www.microsoft.com/downloads/details.aspx?FamilyId=484269E2-3B89-47E3-8EB7-1F2BE6D7123A&displaylang=en    Full Install]<BR>[http://www.microsoft.com/downloads/details.aspx?FamilyId=E15438AC-60BE-41BD-AA14-7F1E0F19CA0D&displaylang=en    ISO Install]<BR>[http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en  Web Install]</span>
 
|}
 
  
{| style="margin-left:25px"
+
About 3/4 of Audacity source code is concerned with user interface, and less than 1/4 with audio processing. The code is tangled, reflecting its history. Many people with widely varying skill levels have contributed.
|-
 
|'''Windows SDK''' for Windows XP/Server 2003/Vista:
 
|-
 
|<span style="font-style:italic" class="plainlinks">[http://www.microsoft.com/downloads/details.aspx?FamilyId=7614FE22-8A64-4DFB-AA0C-DB53035F40A0&displaylang=en ISO Install]<BR>[http://www.microsoft.com/downloads/details.aspx?FamilyId=C2B1E300-F358-4523-B479-F53D234CDCCF&displaylang=en Web Install]<BR>[http://go.microsoft.com/fwlink/?LinkId=48615&clcid=0x409 DVDs for purchase]</span>
 
|-
 
|There are instructions for using Visual C++ 2005 Express Edition with the Microsoft Platform SDK <span class="plainlinks" style="font-style:italic">[http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb here]</span>. With MSVC set up you can write 'hello world' and similar small programs just to check things out, or use some of the examples that Microsoft provide.
 
|}
 
  
* Next get a recent version of wxWidgets.  If you want to work with cutting edge code in Audacity, use wxWidgets 2.8.4.  Follow the instructions in the wxWidgets documentation to get some of the wxWidgets samples to compile.  wxWidgets has excellent documentation on its API.  Time spent reading that documentation and trying things out is time well spentThere is one detail in setting up wxWidgets which is very important.  It's setting up the $(WXWIN) environment variableIt's not set by the installer.  It must be set correctly to your wxWidgets directory if you're to compile Audacity.  wxWidgets has be compiled in many different modes, e.g. Unicode and ansi, debug and release, library or dllIf you want to work with the latest Audacity code, make sure that amongst the versions you compile is the unicode - debug - dll version.
+
: The '''audio code''' is multi-threadedThis is because audio is real time, it must be delivered at a certain rate (typically 44100 audio samples per second).  Different threads work on data at different rates, e.g. large but less frequent bursts of data from Disk IO, with buffering of various kinds between the threads to accommodate the mismatches in ratesThe code is more complex because it must both play and record at the same time.
  
* Set up for CVSFor windows get tortoisecvs from sourceforge.  This adds extra menu items to your file explorer windows.  When you right click on a folder you get additional items in the menu.  These are used for synchronising your local copy of the files with the files at Sourceforge.  Any user can read the files at sourceforge via cvs, and that's all you need at this stage.  If you have problems with accessing audacity CVS from windows send a message about it to the audacity developer list.  If we can't help you sort it out then we can at least send you an up to date snapshot of the code which will get you started.
+
: The '''GUI code''' is mostly written using wxWidgets library, which handles dialogs and common GUI controlsHOWEVER, the waveforms (in the TrackPanel) is not a standard widget, and Audacity code draws the TrackPanel itself, placing the lines and text and clickable icons.
  
'''Don't try moving onto this next step until you have at least one sample wxWidgets program compiled and running!'''
+
==Building Audacity==
  
* If you have done all the steps above, this step ''should'' go smoothly.  Open the project file for Audacity in MSVC, select the wx284Debug build of Audacity and click compile. Problems?  Try cutting and pasting the error message into a google search box. Many of the compiler and linker error messages are fairly cryptic unless you've seen them before.  Fortunately there's a lot of people out there who have, and there are messages in web searchable e-mail lists explaining what they mean and what to do.
+
Getting Audacity building on Linux is usually trouble-free because the right tools are there in the environment, or can be found and installed easily. On Windows and Mac it takes longer to set up the environment. Unless you are very experienced, you need to stay with the version of Visual Studio (Windows) and version of Xcode and OS X SDK (MacOS) indicated in the links below.  
  
=Linux/Mac Set Up=
+
* [[Building On Windows]]
 +
* [[Building On Linux]]
 +
* [[Building On Mac]]
  
See:
+
==Quick Links==
* [[CompilingAudacity|Compiling Audacity]] and
+
* [[ArchitecturalDesign|Designing Audacity]] - read and write about what goes into Audacity and how it works   
* [[CompilingAudacityForBeginners|Compiling Audacity Step by Step Guide]]
+
* [[Quality|Ensuring Quality]] - coding standards, commenting code, submitting patches...
 +
* [[Notes for Packagers]] - people building Audacity for Linux distributions and the like.
 +
* Please subscribe to our [http://lists.sourceforge.net/lists/listinfo/audacity-devel audacity-devel] mailing list to exchange your ideas with our developers or to seek help.
  
 +
==Tips for New Developers==
  
=More about Audacity=
+
* Ask lots of questions and do not be afraid to look a fool.  It is a learning process and like I tell my students, ''"if you don't understand (after a reasonable amount of effort), ask somebody who can help"''.
 +
* Note our [[CodingStandards|Coding Standards]] for Audacity (these do not apply to subordinate libraries). Most importantly, '''do not use tabs''' at all, and always use '''three spaces for indentation''' (otherwise things will not line up on different editors). We mostly use standard camel-case capitalization. Some use Hungarian notation, but not everybody.
 +
* Note the challenge of maintaining [[Quality]] in open source software. We have had many short-term contributors over the many years since 2009. This can result in "organic" interdependencies that aren't obvious, so '''any''' code change has the potential to break something. Write your own comments when you add new code.  Summarize key points, do not just say the code in words.  Choose names logically. 
 +
* Use the same tools other people are using.
 +
 
 +
==Design Topics==
 +
 
 +
Some [[Design Topics]] are worth reading when modifying and extending Audacity.
  
See:
 
 
* [[ArchitecturalDesign]]
 
* [[ArchitecturalDesign]]
 
* [[AudacityLibraries]]
 
* [[AudacityLibraries]]
 
* [[HowAudacityWorks]]
 
* [[HowAudacityWorks]]
* [[Creating your own Plug-in]]
+
* [[Creating your own Plugin]]
 +
 
 +
==Feature Planning==
 +
 
 +
* [[The Feature Requests Pipeline]]
 +
** [[Roadmap]]
 +
** [[Feature Requests]]
 +
** [[:Category:Proposal|Proposals]]
 +
 
 +
* [[:Category:Feature Planning|Feature Planning]]
 +
 
 +
==Improving and Adding Features==
 +
 
 +
Adding new features is one of the more exciting aspects of the job, but needs care so as not to destabilize what is already there. New approaches using a plug-in type of architecture can help this. Even so, there are some things that cannot always be done in an open source application due to licensing restrictions. Have a look at our [[Feature Requests]] page to see what our users most wish to see in Audacity, add your own requests, and let us know if you are interested in helping us implement the best of these.
 +
 
 +
We also have a [[Roadmap]] of planned steps in Audacity development.
 +
 
 +
== Bug Fixing ==
 +
 
 +
Although Audacity is extensively tested, especially when new features and versions are introduced, we depend heavily on users to [[Reporting Bugs|report bugs]] to us. If you are looking for bugs to fix, see [[Bug Lists]].
 +
 
 +
== Tell us about your changes ==
 +
 
 +
When you have crafted your improvement or bug fix, please tell us about it on audacity-devel. At some stage you would typically commit the changes to your own clone of Audacity on [[GitHub]] and then submit a [[GitHub Pull Requests|GitHub Pull Request]]. We may need time to respond and get the commit ready to merge, if we like your ideas. Always discuss it on audacity-devel if it is more than a couple of lines of code.
 +
 
 +
==More about Digital Audio==
 +
 
 +
There are a few articles in our [[:Category:Digital Audio Technology|Digital Audio Technology]] category on this Wiki, and there is a short explanation of digital audio basics on [https://manual.audacityteam.org/man/digital_audio.html this page] of our [https://manual.audacityteam.org/ Audacity Manual].
 +
 
 +
There are also articles on the internet ranging from beginners' guides on how sound is represented in a computer, to research papers on digital signal processing (DSP) algorithms. For some recommended sources, see [[Digital Audio Recommended Articles]].
  
=More about Digital Sound=
 
  
There are articles on the web ranging from beginners guides on how sound is represented in a computer to research papers on DSP algorithms.
+
[[Category:For Developers]]

Latest revision as of 07:48, 8 June 2022

Links and brief explanations for developers


See Also:

Yep, we've two or more similar pages doing much the same thing in different ways - and pointing to each other. Our code does much the same thing too :-)


Intro

Audacity aims to be a simple to use but powerful audio editor.

About 3/4 of Audacity source code is concerned with user interface, and less than 1/4 with audio processing. The code is tangled, reflecting its history. Many people with widely varying skill levels have contributed.

The audio code is multi-threaded. This is because audio is real time, it must be delivered at a certain rate (typically 44100 audio samples per second). Different threads work on data at different rates, e.g. large but less frequent bursts of data from Disk IO, with buffering of various kinds between the threads to accommodate the mismatches in rates. The code is more complex because it must both play and record at the same time.
The GUI code is mostly written using wxWidgets library, which handles dialogs and common GUI controls. HOWEVER, the waveforms (in the TrackPanel) is not a standard widget, and Audacity code draws the TrackPanel itself, placing the lines and text and clickable icons.

Building Audacity

Getting Audacity building on Linux is usually trouble-free because the right tools are there in the environment, or can be found and installed easily. On Windows and Mac it takes longer to set up the environment. Unless you are very experienced, you need to stay with the version of Visual Studio (Windows) and version of Xcode and OS X SDK (MacOS) indicated in the links below.

Quick Links

  • Designing Audacity - read and write about what goes into Audacity and how it works
  • Ensuring Quality - coding standards, commenting code, submitting patches...
  • Notes for Packagers - people building Audacity for Linux distributions and the like.
  • Please subscribe to our audacity-devel mailing list to exchange your ideas with our developers or to seek help.

Tips for New Developers

  • Ask lots of questions and do not be afraid to look a fool. It is a learning process and like I tell my students, "if you don't understand (after a reasonable amount of effort), ask somebody who can help".
  • Note our Coding Standards for Audacity (these do not apply to subordinate libraries). Most importantly, do not use tabs at all, and always use three spaces for indentation (otherwise things will not line up on different editors). We mostly use standard camel-case capitalization. Some use Hungarian notation, but not everybody.
  • Note the challenge of maintaining Quality in open source software. We have had many short-term contributors over the many years since 2009. This can result in "organic" interdependencies that aren't obvious, so any code change has the potential to break something. Write your own comments when you add new code. Summarize key points, do not just say the code in words. Choose names logically.
  • Use the same tools other people are using.

Design Topics

Some Design Topics are worth reading when modifying and extending Audacity.

Feature Planning

Improving and Adding Features

Adding new features is one of the more exciting aspects of the job, but needs care so as not to destabilize what is already there. New approaches using a plug-in type of architecture can help this. Even so, there are some things that cannot always be done in an open source application due to licensing restrictions. Have a look at our Feature Requests page to see what our users most wish to see in Audacity, add your own requests, and let us know if you are interested in helping us implement the best of these.

We also have a Roadmap of planned steps in Audacity development.

Bug Fixing

Although Audacity is extensively tested, especially when new features and versions are introduced, we depend heavily on users to report bugs to us. If you are looking for bugs to fix, see Bug Lists.

Tell us about your changes

When you have crafted your improvement or bug fix, please tell us about it on audacity-devel. At some stage you would typically commit the changes to your own clone of Audacity on GitHub and then submit a GitHub Pull Request. We may need time to respond and get the commit ready to merge, if we like your ideas. Always discuss it on audacity-devel if it is more than a couple of lines of code.

More about Digital Audio

There are a few articles in our Digital Audio Technology category on this Wiki, and there is a short explanation of digital audio basics on this page of our Audacity Manual.

There are also articles on the internet ranging from beginners' guides on how sound is represented in a computer, to research papers on digital signal processing (DSP) algorithms. For some recommended sources, see Digital Audio Recommended Articles.