Tutorial Quick-Links:

• TutorialDir/BlockingReadWrite
• TutorialDir/Compile/Linux
• TutorialDir/Compile/MacintoshCoreAudio
• TutorialDir/Compile/Windows
• TutorialDir/Compile/WindowsASIOMSVC
• TutorialDir/Compile/WindowsMinGW
• TutorialDir/Exploring
• TutorialDir/InitializingPortAudio
• TutorialDir/OpenDefaultStream
• TutorialDir/QueryingDevices
• TutorialDir/StartStopAbort
• TutorialDir/TerminatingPortAudio
• TutorialDir/TutorialStart
• TutorialDir/UtilityFunctions
• TutorialDir/WritingACallback

Overview of PortAudio

PortAudio is a library that provides streaming audio input and output. It is a cross-platform API (Application Programming Interface) that works on Windows, Macintosh OS X, Linux and perhaps other platforms by the time you read this. This means that you can write a simple 'C' program to process or generate an audio signal, and that program can run on several different types of computer just by recompiling the source code. Perhaps more importantly, PortAudio is simple to use -- much simpler than many native I/O interfaces -- without sacrificing control or important performance issues such as latency.

Note: Currently, you can use either V19 or V18 of the PortAudio API. We strongly recommend using V19. But if you are supporting an old computer running, for example, Mac OS 8, then you may be better off with V18.

Here are the steps to writing a PortAudio application:

• Write a callback function that will be called by PortAudio when audio processing is needed.
• Initialize the PA library and open a stream for audio I/O.
• Start the stream. Your callback function will be now be called repeatedly by PA in the background.
• In your callback you can read audio data from the inputBuffer and/or write data to the outputBuffer.
• Stop the stream by returning 1 from your callback, or by calling a stop function.
• Close the stream and terminate the library.

In addition to this "Callback" architecture, V19 also supports a "Blocking I/O" model which uses read and write calls which may be more familiar to non-audio programmers. Note that at this time, not all APIs support this functionality.

Ed: should I mention Pablio? I don't think it works with V19.

This Tutorial

In this tutorial, we'll show how to use the callback architecture to play a sawtooth wave. Much of the tutorial is taken from the file patest_saw.c, which is part of the PortAudio distribution. When you're done with this tutorial, you'll be armed with the basic knowledge you need to write an audio program. If you need more sample code, look in the "test" directory of the PortAudio distribution. Another great source of info is the  portaudio.h Doxygen page, which documents the entire V19 API.

If you are upgrading from V18, you may want to see our  Proposed Enhancements to PortAudio, which describes the differences between V18 and V19.

Compiling

First thing you'll need to know, after you've gotten PortAudio from the Subversion Repository is how to compile your application, which of course, depends on your environment:

ED: not actually sure this is how it should be organized, since it's possible to compile for multiple interfaces.

• Windows
  • Compiling with MinGW/Cigwin
  • Windows
  • Windows ASIO with MicroSoft Visual C
• Mac OS X
  • Core Audio
• POSIX
  • Linux (Alsa/Jack/OSS)
• Others?

Many platforms with GCC/make can use the simple ./configure && make combination and simply use the resulting libraries in their code.

Once you understand how PortAudio works, you might be interested in Exploring PortAudio.

TODO:

• Complete tutorial with utility and info about querying devices/opening non-default devices

Next:Writing A Callback Function