diff options
Diffstat (limited to 'pd/portaudio/docs')
24 files changed, 2373 insertions, 0 deletions
diff --git a/pd/portaudio/docs/index.html b/pd/portaudio/docs/index.html new file mode 100644 index 00000000..7d9b248d --- /dev/null +++ b/pd/portaudio/docs/index.html @@ -0,0 +1,60 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="PortAudio Docs, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Docs</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Documentation</h1></center> +</td> +</tr> +</table></center> + +<p>Copyright 2000 Phil Burk and Ross Bencina +<br> +<h3> +<a href="portaudio_h.txt">API Reference</a></h3> + +<blockquote>The Application Programmer Interface is documented in "portaudio.h".</blockquote> + +<h3> +<a href="pa_tutorial.html">Tutorial</a></h3> + +<blockquote>Describes how to write audio programs using the PortAudio API.</blockquote> + +<h3> +<a href="pa_impl_guide.html">Implementation Guide</a></h3> + +<blockquote>Describes how to write an implementation of PortAudio for a +new computer platform.</blockquote> + +<h3> +<a href="portaudio_icmc2001.pdf">Paper Presented at ICMC2001</a> (PDF)</h3> + +<blockquote>Describes the PortAudio API and discusses implementation issues. +Written July 2001.</blockquote> + +<h3> +<a href="latency.html">Improving Latency</a></h3> + +<blockquote>How to tune your computer to achieve the lowest possible audio +delay.</blockquote> + +<h3> +<a href="proposals.html">Proposed Changes</a></h3> + +<blockquote>Describes API changes being considered by the developer community. +Feedback welcome.</blockquote> +<a href="http://www.portaudio.com/">Return to PortAudio Home Page</a> +</body> +</html> diff --git a/pd/portaudio/docs/latency.html b/pd/portaudio/docs/latency.html new file mode 100644 index 00000000..87f1d122 --- /dev/null +++ b/pd/portaudio/docs/latency.html @@ -0,0 +1,192 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +<a href="http://www.portaudio.com">PortAudio</a> Latency</h1></center> +</td> +</tr> +</table></center> + +<p>This page discusses the issues of audio latency for <a href="http://www.portaudio.com">PortAudio</a> +. It offers suggestions on how to lower latency to improve the responsiveness +of applications. +<blockquote><b><a href="#what">What is Latency?</a></b> +<br><b><a href="#portaudio">PortAudio and Latency</a></b> +<br><b><a href="#macintosh">Macintosh</a></b> +<br><b><a href="#unix">Unix</a></b> +<br><b><a href="#windows">WIndows</a></b></blockquote> +By Phil Burk, Copyright 2002 Phil Burk and Ross Bencina +<h2> +<a NAME="what"></a>What is Latency?</h2> +Latency is basically longest time that you have to wait before you obtain +a desired result. For digital audio output it is the time between making +a sound in software and finally hearing it. +<p>Consider the example of pressing a key on the ASCII keyboard to play +a note. There are several stages in this process which each contribute +their own latency. First the operating system must respond to the keypress. +Then the audio signal generated must work its way through the PortAudio +buffers. Then it must work its way through the audio card hardware. Then +it must go through the audio amplifier which is very quick and then travel +through the air. Sound travels at abous one foot per millisecond through +air so placing speakers across the room can add 5-20 msec of delay. +<p>The reverse process occurs when recording or responding to audio input. +If you are processing audio, for example if you implement a software guitar +fuzz box, then you have both the audio input and audio output latencies +added together. +<p>The audio buffers are used to prevent glitches in the audio stream. +The user software writes audio into the output buffers. That audio is read +by the low level audio driver or by DMA and sent to the DAC. If the computer +gets busy doing something like reading the disk or redrawing the screen, +then it may not have time to fill the audio buffer. The audio hardware +then runs out of audio data, which causes a glitch. By using a large enough +buffer we can ensure that there is always enough audio data for the audio +hardware to play. But if the buffer is too large then the latency is high +and the system feels sluggish. If you play notes on the keyboard then the +"instrument" will feel unresponsive. So you want the buffers to be as small +as possible without glitching. +<h2> +<a NAME="portaudio"></a>PortAudio and Latency</h2> +The only delay that PortAudio can control is the total length of its buffers. +The Pa_OpenStream() call takes two parameters: numBuffers and framesPerBuffer. +The latency is also affected by the sample rate which we will call framesPerSecond. +A frame is a set of samples that occur simultaneously. For a stereo stream, +a frame is two samples. +<p>The latency in milliseconds due to this buffering is: +<blockquote><tt>latency_msec = 1000 * numBuffers * framesPerBuffer / framesPerSecond</tt></blockquote> +This is not the total latency, as we have seen, but it is the part we can +control. +<p>If you call Pa_OpenStream() with numBuffers equal to zero, then PortAudio +will select a conservative number that will prevent audio glitches. If +you still get glitches, then you can pass a larger value for numBuffers +until the glitching stops. if you try to pass a numBuffers value that is +too small, then PortAudio will use its own idea of the minimum value. +<p>PortAudio decides on the minimum number of buffers in a conservative +way based on the frameRate, operating system and other variables. You can +query the value that PortAudio will use by calling: +<blockquote><tt>int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate +);</tt></blockquote> +On some systems you can override the PortAudio minimum if you know your +system can handle a lower value. You do this by setting an environment +variable called PA_MIN_LATENCY_MSEC which is read by PortAudio when it +starts up. This is supported on the PortAudio implementations for Windows +MME, Windows DirectSound, and Unix OSS. +<h2> +<a NAME="macintosh"></a>Macintosh</h2> +The best thing you can do to improve latency on Mac OS 8 and 9 is to turn +off Virtual Memory. PortAudio V18 will detect that Virtual Memory is turned +off and use a very low latency. +<p>For Mac OS X the latency is very low because Apple Core Audio is so +well written. You can set the PA_MIN_LATENCY_MSEC variable using: +<blockquote><tt>setenv PA_MIN_LATENCY_MSEC 4</tt></blockquote> + +<h2> +<a NAME="unix"></a>Unix</h2> +PortAudio under Unix currently uses a backgroud thread that reads and writes +to OSS. This gives you decent but not great latency. But if you raise the +priority of the background thread to a very priority then you can get under +10 milliseconds latency. In order to raise your priority you must run the +PortAudio program as root! You must also set PA_MIN_LATENCY_MSEC using +the appropriate command for your shell. +<h2> +<a NAME="windows"></a>Windows</h2> +Latency under Windows is a complex issue because of all the alternative +operating system versions and device drivers. I have seen latency range +from 8 milliseconds to 400 milliseconds. The worst case is when using Windows +NT. Windows 98 is a little better, and Windows XP can be quite good if +properly tuned. +<p>The underlying audio API also makes a lot of difference. If the audio +device has its own DirectSound driver then DirectSound can often provide +better latency than WMME. But if a real DirectSound driver is not available +for your device then it is emulated using WMME and the latency can be very +high. That's where I saw the 400 millisecond latency. The ASIO implementation +is generally very good and will give the lowest latency if available. +<p>You can set the PA_MIN_LATENCY_MSEC variable to 50, for example, by +entering in MS-DOS: +<blockquote><tt>set PA_MIN_LATENCY_MSEC=50</tt></blockquote> +If you enter this in a DOS window then you must run the PortAudio program +from that same window for the variable to have an effect. You can add that +line to your C:\AUTOEXEC.BAT file and reboot if you want it to affect any +PortAudio based program. +<p>For Windows XP, you can set environment variables as follows: +<ol> +<li> +Select "Control Panel" from the "Start Menu".</li> + +<li> +Launch the "System" Control Panel</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Click on the "Environment Variables" button.</li> + +<li> +Click "New" button under User Variables.</li> + +<li> +Enter PA_MIN_LATENCY_MSEC for the name and some optimistic number for the +value.</li> + +<li> +Click OK, OK, OK.</li> +</ol> + +<h3> +Improving Latency on Windows</h3> +There are several steps you can take to improve latency under windows. +<ol> +<li> +Avoid reading or writng to disk when doing audio.</li> + +<li> +Turn off all automated background tasks such as email clients, virus scanners, +backup programs, FTP servers, web servers, etc. when doing audio.</li> + +<li> +Disconnect from the network to prevent network traffic from interrupting +your CPU.</li> +</ol> +<b>Important: </b>Windows XP users can also tune the OS to favor background +tasks, such as audio, over foreground tasks, such as word processing. I +lowered my latency from 40 to 10 milliseconds using this simple technique. +<ol> +<li> +Select "Control Panel" from the "Start Menu".</li> + +<li> +Launch the "System" Control Panel</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Click on the "Settings" button in the Performance area.</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Select "Background services" in the Processor Scheduling area.</li> + +<li> +Click OK, OK.</li> +</ol> +Please let us know if you have others sugestions for lowering latency. +<br> +<br> +</body> +</html> diff --git a/pd/portaudio/docs/pa_impl_guide.html b/pd/portaudio/docs/pa_impl_guide.html new file mode 100644 index 00000000..50abc304 --- /dev/null +++ b/pd/portaudio/docs/pa_impl_guide.html @@ -0,0 +1,197 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +<a href="http://www.portaudio.com">PortAudio</a> Implementation Guide</h1></center> +</td> +</tr> +</table></center> + +<p>This document describes how to implement the PortAudio API on a new +computer platform. Implementing PortAudio on a new platform, makes it possible +to port many existing audio applications to that platform. +<p>By Phil Burk +<br>Copyright 2000 Phil Burk and Ross Bencina +<p>Note that the license says: <b>"Any person wishing to distribute modifications +to the Software is requested to send the modifications to the original +developer so that they can be incorporated into the canonical version."</b>. +So when you have finished a new implementation, please send it back to +us at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>" +so that we can make it available for other users. Thank you! +<h2> +Download the Latest PortAudio Implementation</h2> +Always start with the latest implementation available at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>". +Look for the nightly snapshot under the CVS section. +<h2> +Select an Existing Implementation as a Basis</h2> +The fastest way to get started is to take an existing implementation and +translate it for your new platform. Choose an implementation whose architecture +is as close as possible to your target. +<ul> +<li> +DirectSound Implementation - pa_win_ds - Uses a timer callback for the +background "thread". Polls a circular buffer and writes blocks of data +to keep it full.</li> + +<li> +Windows MME - pa_win_wmme - Spawns an actual Win32 thread. Writes blocks +of data to the HW device and waits for events that signal buffer completion.</li> + +<li> +Linux OSS - pa_linux - Spawns a real thread that writes to the "/dev/dsp" +stream using blocking I/O calls.</li> +</ul> +When you write a new implementation, you will be using some code that is +in common with all implementations. This code is in the folder "pa_common". +It provides various functions such as parameter checking, error code to +text conversion, sample format conversion, clipping and dithering, etc. +<p>The code that you write will go into a separate folder called "pa_{os}_{api}". +For example, code specific to the DirectSound interface for Windows goes +in "pa_win_ds". +<h2> +Read Docs and Code</h2> +Famialiarize yourself with the system by reading the documentation provided. +here is a suggested order: +<ol> +<li> +User Programming <a href="pa_tutorial.html">Tutorial</a></li> + +<li> +Header file "pa_common/portaudio.h" which defines API.</li> + +<li> +Header file "pa_common/pa_host.h" for host dependant code. This definces +the routine you will need to provide.</li> + +<li> +Shared code in "pa_common/pa_lib.c".</li> + +<li> +Docs on Implementation of <a href="pa_impl_startstop.html">Start/Stop</a> +code.</li> +</ol> + +<h2> +Implement Output to Default Device</h2> +Now we are ready to crank some code. For instant gratification, let's try +to play a sine wave. +<ol> +<li> +Link the test program "pa_tests/patest_sine.c" with the file "pa_lib.c" +and the implementation specific file you are creating.</li> + +<li> +For now, just stub out the device query code and the audio input code.</li> + +<li> +Modify PaHost_OpenStream() to open your default target device and get everything +setup.</li> + +<li> +Modify PaHost_StartOutput() to start playing audio.</li> + +<li> +Modify PaHost_StopOutput() to stop audio.</li> + +<li> +Modify PaHost_CloseStream() to clean up. Free all memory that you allocated +in PaHost_OpenStream().</li> + +<li> +Keep cranking until you can play a sine wave using "patest_sine.c".</li> + +<li> +Once that works, try "patest_pink.c", "patest_clip.c", "patest_sine8.c".</li> + +<li> +To test your Open and Close code, try "patest_many.c".</li> + +<li> +Now test to make sure that the three modes of stopping are properly supported +by running "patest_stop.c".</li> + +<li> +Test your implementation of time stamping with "patest_sync.c".</li> +</ol> + +<h2> +Implement Device Queries</h2> +Now that output is working, lets implement the code for querying what devices +are available to the user. Run "pa_tests/pa_devs.c". It should print all +of the devices available and their characteristics. +<h2> +Implement Input</h2> +Implement audio input and test it with: +<ol> +<li> +patest_record.c - record in half duplex, play back as recorded.</li> + +<li> +patest_wire.c - full duplex, copies input to output. Note that some HW +may not support full duplex.</li> + +<li> +patest_fuzz.c - plug in your guitar and get a feel for why latency is an +important issue in computer music.</li> + +<li> +paqa_devs.c - try to open every device and use it with every possible format</li> +</ol> + +<h2> +Debugging Tools</h2> +You generally cannot use printf() calls to debug real-time processes because +they disturb the timing. Also calling printf() from your background thread +or interrupt could crash the machine. So PA includes a tool for capturing +events and storing the information while it is running. It then prints +the events when Pa_Terminate() is called. +<ol> +<li> +To enable trace mode, change TRACE_REALTIME_EVENTS in "pa_common/pa_trace.h" +from a (0) to a (1).</li> + +<li> +Link with "pa_common/pa_trace.c".</li> + +<li> +Add trace messages to your code by calling:</li> + +<br><tt> void AddTraceMessage( char *msg, int data );</tt> +<br><tt>for example</tt> +<br><tt> AddTraceMessage("Pa_TimeSlice: past_NumCallbacks ", +past->past_NumCallbacks );</tt> +<li> +Run your program. You will get a dump of events at the end.</li> + +<li> +You can leave the trace messages in your code. They will turn to NOOPs +when you change TRACE_REALTIME_EVENTS back to (0).</li> +</ol> + +<h2> +Delivery</h2> +Please send your new code along with notes on the implementation back to +us at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>". +We will review the implementation and post it with your name. If you had +to make any modifications to the code in "pa_common" or "pa_tests" <b>please</b> +send us those modifications and your notes. We will try to merge your changes +so that the "pa_common" code works with <b>all</b> implementations. +<p>If you have suggestions for how to make future implementations easier, +please let us know. +<br>THANKS! +<br> +</body> +</html> diff --git a/pd/portaudio/docs/pa_impl_startstop.html b/pd/portaudio/docs/pa_impl_startstop.html new file mode 100644 index 00000000..0f2d0ce5 --- /dev/null +++ b/pd/portaudio/docs/pa_impl_startstop.html @@ -0,0 +1,190 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Implementation</h1></center> +</td> +</tr> +</table></center> + +<h2> +Starting and Stopping Streams</h2> +PortAudio is generally executed in two "threads". The foreground thread +is the application thread. The background "thread" may be implemented as +an actual thread, an interrupt handler, or a callback from a timer thread. +<p>There are three ways that PortAudio can stop a stream. In each case +we look at the sequence of events and the messages sent between the two +threads. The following variables are contained in the internalPortAudioStream. +<blockquote><tt>int past_IsActive; +/* Background is still playing. */</tt> +<br><tt>int past_StopSoon; /* Stop +when last buffer done. */</tt> +<br><tt>int past_StopNow; /* +Stop IMMEDIATELY. */</tt></blockquote> + +<h3> +Pa_AbortStream()</h3> +This function causes the background thread to terminate as soon as possible +and audio I/O to stop abruptly. +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td>sets <tt>StopNow</tt></td> + +<td></td> +</tr> + +<tr> +<td></td> + +<td>sees <tt>StopNow</tt>, </td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<h3> +Pa_StopStream()</h3> +This function stops the user callback function from being called and then +waits for all audio data written to the output buffer to be played. In +a system with very low latency, you may not hear any difference between +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td>sets StopSoon</td> + +<td></td> +</tr> + +<tr> +<td></td> + +<td>stops calling user callback</td> +</tr> + +<tr> +<td></td> + +<td>continues until output buffer empty</td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<h3> +User callback returns one.</h3> +If the user callback returns one then the user callback function will no +longer be called. Audio output will continue until all audio data written +to the output buffer has been played. Then the audio I/O is stopped, the +background thread terminates, and the stream becomes inactive. +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td></td> + +<td>callback returns 1</td> +</tr> + +<tr> +<td></td> + +<td>sets StopSoon</td> +</tr> + +<tr> +<td></td> + +<td>stops calling user callback</td> +</tr> + +<tr> +<td></td> + +<td>continues until output buffer empty</td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<br> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_asio.html b/pd/portaudio/docs/pa_tut_asio.html new file mode 100644 index 00000000..1c3e5bfa --- /dev/null +++ b/pd/portaudio/docs/pa_tut_asio.html @@ -0,0 +1,55 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for ASIO (Windows or Macintosh)</h2> + +<blockquote>ASIO is a low latency audio API from Steinberg. To compile +an ASIO application, you must first <a href="http://www.steinberg.net/developers/ASIO2SDKAbout.phtml">download +the ASIO SDK</a> from Steinberg. You also need to obtain ASIO drivers for +your audio device. +<p>Note: I am using '/' as a file separator below. On Macintosh replace +'/' with ':'. On Windows, replace '/' with '\'. +<p> To use ASIO with the PortAudio library add the following source +files to your project: +<blockquote> +<pre>pa_asio/pa_asio.cpp</pre> +</blockquote> +and also these files from the ASIO SDK: +<blockquote> +<pre>common/asio.cpp +host/asiodrivers.cpp +host/asiolist.cpp</pre> +</blockquote> +and add these directories to the path for include files +<blockquote> +<pre>asiosdk2/host/pc (for Windows) +asiosdk2/common +asiosdk2/host</pre> +</blockquote> +You may try compiling the "pa_tests/patest_saw.c" file first because it +is the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_callback.html b/pd/portaudio/docs/pa_tut_callback.html new file mode 100644 index 00000000..f5ccaf0f --- /dev/null +++ b/pd/portaudio/docs/pa_tut_callback.html @@ -0,0 +1,91 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Writing a Callback Function</h2> + +<blockquote>To write a program using PortAudio, you must include the "portaudio.h" +include file. You may wish to read "<a href="portaudio_h.txt">portaudio.h</a>" +because it contains a complete description of the PortAudio functions and +constants. +<blockquote> +<pre>#include "portaudio.h"</pre> +</blockquote> +The next task is to write your custom callback function. It is a function +that is called by the PortAudio engine whenever it has captured audio data, +or when it needs more audio data for output. +<p>Your callback function is often called by an interrupt, or low level +process so you should not do any complex system activities like allocating +memory, or reading or writing files, or printf(). Just crunch numbers and +generate audio signals. What is safe or not safe will vary from platform +to platform. On the Macintosh, for example, you can only call "interrupt +safe" routines. Also do not call any PortAudio functions in the callback +except for Pa_StreamTime() and Pa_GetCPULoad(). +<p>Your callback function must return an int and accept the exact parameters +specified in this typedef: +<blockquote> +<pre>typedef int (PortAudioCallback)( + void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData );</pre> +</blockquote> +Here is an example callback function from the test file "patests/patest_saw.c". +It calculates a simple left and right sawtooth signal and writes it to +the output buffer. Notice that in this example, the signals are of <tt>float</tt> +data type. The signals must be between -1.0 and +1.0. You can also use +16 bit integers or other formats which are specified during setup. You +can pass a pointer to your data structure through PortAudio which will +appear as <tt>userData</tt>. +<blockquote> +<pre>int patestCallback( void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData ) +{ + unsigned int i; +/* Cast data passed through stream to our structure type. */ + paTestData *data = (paTestData*)userData; + float *out = (float*)outputBuffer; + + for( i=0; i<framesPerBuffer; i++ ) + { + /* Stereo channels are interleaved. */ + *out++ = data->left_phase; /* left */ + *out++ = data->right_phase; /* right */ + + /* Generate simple sawtooth phaser that ranges between -1.0 and 1.0. */ + data->left_phase += 0.01f; + /* When signal reaches top, drop back down. */ + if( data->left_phase >= 1.0f ) data->left_phase -= 2.0f; + + /* higher pitch so we can distinguish left and right. */ + data->right_phase += 0.03f; + if( data->right_phase >= 1.0f ) data->right_phase -= 2.0f; + } + return 0; +}</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_init.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_devs.html b/pd/portaudio/docs/pa_tut_devs.html new file mode 100644 index 00000000..1756992c --- /dev/null +++ b/pd/portaudio/docs/pa_tut_devs.html @@ -0,0 +1,65 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Querying for Available Devices</h2> + +<blockquote>There are often several different audio devices available in +a computer with different capabilities. They can differ in the sample rates +supported, bit widths, etc. PortAudio provides a simple way to query for +the available devices, and then pass the selected device to Pa_OpenStream(). +For an example, see the file "pa_tests/pa_devs.c". +<p>To determine the number of devices: +<blockquote> +<pre>numDevices = Pa_CountDevices();</pre> +</blockquote> +You can then query each device in turn by calling Pa_GetDeviceInfo() with +an index. +<blockquote> +<pre>for( i=0; i<numDevices; i++ ) { + pdi = Pa_GetDeviceInfo( i );</pre> +</blockquote> +It will return a pointer to a <tt>PaDeviceInfo</tt> structure which is +defined as: +<blockquote> +<pre>typedef struct{ + int structVersion; + const char *name; + int maxInputChannels; + int maxOutputChannels; +/* Number of discrete rates, or -1 if range supported. */ + int numSampleRates; +/* Array of supported sample rates, or {min,max} if range supported. */ + const double *sampleRates; + PaSampleFormat nativeSampleFormat; +}PaDeviceInfo;</pre> +</blockquote> +If the device supports a continuous range of sample rates, then numSampleRates +will equal -1, and the sampleRates array will have two values, the minimum +and maximum rate. +<p>The device information is allocated by Pa_Initialize() and freed by +Pa_Terminate() so you do not have to free() the structure returned by Pa_GetDeviceInfo().</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_util.html">previous</a> | <a href="pa_tut_rw.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_explore.html b/pd/portaudio/docs/pa_tut_explore.html new file mode 100644 index 00000000..91c08a5b --- /dev/null +++ b/pd/portaudio/docs/pa_tut_explore.html @@ -0,0 +1,42 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Exploring PortAudio</h2> + +<blockquote>Now that you have a good idea of how PortAudio works, you can +try out the test programs. +<ul> +<li> +For an example of playing a sine wave, see "pa_tests/patest_sine.c".</li> + +<li> +For an example of recording and playing back a sound, see "pa_tests/patest_record.c".</li> +</ul> +I also encourage you to examine the source for the PortAudio libraries. +If you have suggestions on ways to improve them, please let us know. if +you want to implement PortAudio on a new platform, please let us know as +well so we can coordinate people's efforts.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_rw.html">previous</a> | next</font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_init.html b/pd/portaudio/docs/pa_tut_init.html new file mode 100644 index 00000000..91bfa8d9 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_init.html @@ -0,0 +1,43 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Initializing PortAudio</h2> + +<blockquote>Before making any other calls to PortAudio, you must call <tt>Pa_Initialize</tt>(). +This will trigger a scan of available devices which can be queried later. +Like most PA functions, it will return a result of type <tt>paError</tt>. +If the result is not <tt>paNoError</tt>, then an error has occurred. +<blockquote> +<pre>err = Pa_Initialize(); +if( err != paNoError ) goto error;</pre> +</blockquote> +You can get a text message that explains the error message by passing it +to +<blockquote> +<pre>printf( "PortAudio error: %s\n", Pa_GetErrorText( err ) );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_callback.html">previous</a> | <a href="pa_tut_open.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_mac.html b/pd/portaudio/docs/pa_tut_mac.html new file mode 100644 index 00000000..bf3dafd1 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_mac.html @@ -0,0 +1,41 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Macintosh</h2> + +<blockquote>To compile a Macintosh application with the PortAudio library, +add the following source files to your project: +<blockquote> +<pre>pa_mac:pa_mac.c +pa_common:pa_lib.c +pa_common:portaudio.h +pa_common:pa_host.h</pre> +</blockquote> +Also add the Apple <b>SoundLib</b> to your project. +<p>You may try compiling the "pa_tests:patest_saw.c" file first because +it is the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_mac_osx.html b/pd/portaudio/docs/pa_tut_mac_osx.html new file mode 100644 index 00000000..3af8c140 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_mac_osx.html @@ -0,0 +1,46 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Macintosh OS X</h2> + +<blockquote>To compile a Macintosh OS X CoreAudio application with the +PortAudio library: +<p>Create a new ProjectBuilder project. You can use a "Tool" project to +run the PortAudio examples. +<p>Add the following source files to your Project: +<blockquote> +<pre>pa_mac_core/pa_mac_core.c +pa_common/pa_lib.c +pa_common/portaudio.h +pa_common/pa_host.h +pa_common/pa_convert.c</pre> +</blockquote> +Add the Apple CoreAudio.framework to your project by selecting "Add FrameWorks..." +from the Project menu. +<p>Compile and run the "pa_tests:patest_saw.c" file first because it is +the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_open.html b/pd/portaudio/docs/pa_tut_open.html new file mode 100644 index 00000000..1621ef30 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_open.html @@ -0,0 +1,52 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Opening a Stream using Defaults</h2> + +<blockquote>The next step is to open a stream which is similar to opening +a file. You can specify whether you want audio input and/or output, how +many channels, the data format, sample rate, etc. There are two calls for +opening streams, <tt>Pa_OpenStream</tt>() and <tt>Pa_OpenDefaultStream</tt>(). +<p><tt>Pa_OpenStream()</tt> takes extra parameters which give you +more control. You can normally just use <tt>Pa_OpenDefaultStream</tt>() +which just calls <tt>Pa_OpenStream()</tt> <tt>with</tt> some reasonable +default values. Let's open a stream for stereo output, using floating +point data, at 44100 Hz. +<blockquote> +<pre>err = Pa_OpenDefaultStream( + &stream, /* passes back stream pointer */ + 0, /* no input channels */ + 2, /* stereo output */ + paFloat32, /* 32 bit floating point output */ + 44100, /* sample rate */ + 256, /* frames per buffer */ + 0, /* number of buffers, if zero then use default minimum */ + patestCallback, /* specify our custom callback */ + &data ); /* pass our data through to callback */</pre> +</blockquote> +If you want to use 16 bit integer data, pass <tt>paInt16</tt> instead of +<tt>paFloat32</tt>.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_init.html">previous</a> | <a href="pa_tut_run.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_oss.html b/pd/portaudio/docs/pa_tut_oss.html new file mode 100644 index 00000000..1bb76f25 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_oss.html @@ -0,0 +1,46 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Unix OSS</h2> + +<blockquote>[Skip this page if you are not using Unix and OSS] +<p>We currently support the <a href="http://www.opensound.com/">OSS</a> +audio drivers for Linux, Solaris, and FreeBSD. We hope to someday support +the newer ALSA drivers. +<ol> +<li> +cd to pa_unix_oss directory</li> + +<li> +Edit the Makefile and uncomment one of the tests. You may try compiling +the "patest_sine.c" file first because it is very simple.</li> + +<li> +gmake run</li> +</ol> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_pc.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_over.html b/pd/portaudio/docs/pa_tut_over.html new file mode 100644 index 00000000..baa99205 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_over.html @@ -0,0 +1,92 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Overview of PortAudio</h2> + +<blockquote>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, Unix running OSS, SGI, BeOS, 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. +<p>Here are the steps to writing a PortAudio application: +<ol> +<li> +Write a callback function that will be called by PortAudio when audio processing +is needed.</li> + +<li> +Initialize the PA library and open a stream for audio I/O.</li> + +<li> +Start the stream. Your callback function will be now be called repeatedly +by PA in the background.</li> + +<li> +In your callback you can read audio data from the inputBuffer and/or write +data to the outputBuffer.</li> + +<li> +Stop the stream by returning 1 from your callback, or by calling a stop +function.</li> + +<li> +Close the stream and terminate the library.</li> +</ol> +</blockquote> + +<blockquote>There is also <a href="pa_tut_rw.html">another interface</a> +provided that allows you to generate audio in the foreground. You then +simply write data to the stream and the tool will not return until it is +ready to accept more data. This interface is simpler to use but is usually +not preferred for large applications because it requires that you launch +a thread to perform the synthesis. Launching a thread may be difficult +on non-multi-tasking systems such as the Macintosh prior to MacOS X. +<p>Let's continue by building a simple application that will play a sawtooth +wave. +<p>Please select the page for the specific implementation you would like +to use: +<ul> +<li> +<a href="pa_tut_pc.html">Windows (WMME or DirectSound)</a></li> + +<li> +<a href="pa_tut_mac.html">Macintosh SoundManager for OS 7,8,9</a></li> + +<li> +<a href="pa_tut_mac_osx.html">Macintosh CoreAudio for OS X</a></li> + +<li> +<a href="pa_tut_asio.html">ASIO on Windows or Macintosh</a></li> + +<li> +<a href="pa_tut_oss.html">Unix OSS</a></li> +</ul> +or continue with the <a href="pa_tut_callback.html">next page of the programming +tutorial</a>.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tutorial.html">previous</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_pc.html b/pd/portaudio/docs/pa_tut_pc.html new file mode 100644 index 00000000..87e5f9a0 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_pc.html @@ -0,0 +1,78 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Windows (WMME or DirectSound)</h2> + +<blockquote>To compile PortAudio for Windows, you can choose between two +options. One implementation uses the DirectSound API. The other uses the +Windows MultiMedia Extensions API (aka WMME or WAVE). +<p>Some advantages of using DirectSound are that DirectSound may have lower +latency than WMME, and supports effects processing plugins. But one disadvantage +is that DirectSound is not installed on all PCs, and is not well supported +under Windows NT. So WMME is the best choice for most projects. +<p>For either implementation add the following source files to your project: +<blockquote> +<pre><b>pa_common\pa_lib.c +pa_common\portaudio.h +pa_common\pa_host.h</b></pre> +</blockquote> +Link with the system library "<b>winmm.lib</b>". For Visual C++: +<ol> +<li> +select "Settings..." from the "Project" menu,</li> + +<li> +select the project name in the tree on the left,</li> + +<li> +choose "All Configurations" in the popup menu above the tree,</li> + +<li> +select the "Link" tab,</li> + +<li> +enter "winmm.lib", without quotes, as the first item in the "Object/library +modules:" field.</li> +</ol> +<b>WMME</b> - To use the WMME implementation, add the following source +files to your project: +<blockquote><b><tt>pa_win_wmme/pa_win_wmme.c</tt></b></blockquote> +<b>DirectSound</b> - If you want to use the DirectSound implementation +of PortAudio then you must have a recent copy of the free +<a href="http://www.microsoft.com/directx/download.asp">DirectX</a> +SDK for Developers from Microsoft installed on your computer. To compile +an application add the following source files to your project: +<blockquote> +<pre><b>pa_win_ds\dsound_wrapper.c +pa_win_ds\pa_dsound.c</b></pre> +</blockquote> +Link with the system library "<b>dsound.lib</b>" using the procedure described +above for "winmm.lib".</blockquote> + +<blockquote>You might try compiling the "pa_tests\patest_saw.c" file first +because it is the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_run.html b/pd/portaudio/docs/pa_tut_run.html new file mode 100644 index 00000000..5c70d089 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_run.html @@ -0,0 +1,56 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Starting and Stopping a Stream</h2> + +<blockquote>The stream will not start running until you call Pa_StartStream(). +Then it will start calling your callback function to perform the audio +processing. +<blockquote> +<pre>err = Pa_StartStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +At this point, audio is being generated. You can communicate to your callback +routine through the data structure you passed in on the open call, or through +global variables, or using other interprocess communication techniques. +Please be aware that your callback function may be called at interrupt +time when your foreground process is least expecting it. So avoid sharing +complex data structures that are easily corrupted like double linked lists. +<p>In many of the tests we simply sleep for a few seconds so we can hear +the sound. This is easy to do with Pa_Sleep() which will sleep for some +number of milliseconds. Do not rely on this function for accurate scheduling. +it is mostly for writing examples. +<blockquote> +<pre>/* Sleep for several seconds. */ +Pa_Sleep(NUM_SECONDS*1000);</pre> +</blockquote> +When you are through, you can stop the stream from the foreground. +<blockquote> +<pre>err = Pa_StopStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +You can also stop the stream by returning 1 from your custom callback function.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_open.html">previous</a> | <a href="pa_tut_term.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_rw.html b/pd/portaudio/docs/pa_tut_rw.html new file mode 100644 index 00000000..93c7b8bb --- /dev/null +++ b/pd/portaudio/docs/pa_tut_rw.html @@ -0,0 +1,79 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Blocking Read/Write Functions</h2> + +<blockquote>[Note: These functions are not part of the official PortAudio +API. They are simply built on top of PortAudio as an extra utility. Also +note that they are under evaluation and their definition may change.] +<p>There are two fundamentally different ways to design an audio API. One +is to use callback functions the way we have already shown. The callback +function operates under an interrupt or background thread This leaves the +foreground application free to do other things while the audio just runs +in the background. But this can sometimes be awkward. +<p>So we have provided an alternative technique that lets a program generate +audio in the foreground and then just write it to the audio stream as if +it was a file. If there is not enough room in the audio buffer for more +data, then the write function will just block until more room is available. +This can make it very easy to write an audio example. To use this tool, +you must add the files "pablio/pablio.c" and "pablio/ringbuffer.c" to your +project. You must also: +<blockquote> +<pre>#include "pablio.h"</pre> +</blockquote> +Here is a short excerpt of a program that opens a stream for input and +output. It then reads a block of samples from input, and writes them to +output, in a loop. The complete example can be found in "pablio/test_rw.c". +<blockquote> +<pre> #define SAMPLES_PER_FRAME (2) + #define FRAMES_PER_BLOCK (1024) + SAMPLE samples[SAMPLES_PER_FRAME * FRAMES_PER_BLOCK]; + PaError err; + PABLIO_Stream *aStream; + +/* Open simplified blocking I/O layer on top of PortAudio. */ + err = OpenAudioStream( &rwbl, SAMPLE_RATE, paFloat32, + (PABLIO_READ_WRITE | PABLIO_STEREO) ); + if( err != paNoError ) goto error; + +/* Process samples in the foreground. */ + for( i=0; i<(NUM_SECONDS * SAMPLE_RATE); i++ ) + { + /* Read one block of data into sample array from audio input. */ + ReadAudioStream( aStream, samples, FRAMES_PER_BLOCK ); + /* + ** At this point you could process the data in samples array, + ** and write the result back to the same samples array. + */ + /* Write that same frame of data to output. */ + WriteAudioStream( aStream, samples, FRAMES_PER_BLOCK ); + } + + CloseAudioStream( aStream );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_devs.html">previous</a> | <a href="pa_tut_explore.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_term.html b/pd/portaudio/docs/pa_tut_term.html new file mode 100644 index 00000000..1c72209f --- /dev/null +++ b/pd/portaudio/docs/pa_tut_term.html @@ -0,0 +1,47 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Terminating PortAudio</h2> + +<blockquote>You can start and stop a stream as many times as you like. +But when you are done using it, you should close it by calling:</blockquote> + +<blockquote> +<blockquote> +<pre>err = Pa_CloseStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +Then when you are done using PortAudio, you should terminate the whole +system by calling: +<blockquote> +<pre>Pa_Terminate();</pre> +</blockquote> +That's basically it. You can now write an audio program in 'C' that will +run on multiple platforms, for example PCs and Macintosh. +<p>In the rest of the tutorial we will look at some additional utility +functions, and a different way of using PortAudio that does not require +the use of a callback function.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_run.html">previous</a> | <a href="pa_tut_util.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tut_util.html b/pd/portaudio/docs/pa_tut_util.html new file mode 100644 index 00000000..f4b54750 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_util.html @@ -0,0 +1,55 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Utility Functions</h2> + +<blockquote>Here are several more functions that are not critical, but +may be handy when using PortAudio. +<p>Pa_StreamActive() returns one when the stream in playing audio, zero +when not playing, or a negative error number if the stream is invalid. +The stream is active between calls to Pa_StartStream() and Pa_StopStream(), +but may also become inactive if the callback returns a non-zero value. +In the latter case, the stream is considered inactive after the last buffer +has finished playing. +<blockquote> +<pre>PaError Pa_StreamActive( PortAudioStream *stream );</pre> +</blockquote> +Pa_StreamTime() returns the number of samples that have been generated. +PaTimeStamp is a double precision number which is a convenient way to pass +big numbers around even though we only need integers. +<blockquote> +<pre>PaTimestamp Pa_StreamTime( PortAudioStream *stream );</pre> +</blockquote> +The "CPU Load" is a fraction of total CPU time consumed by the stream's +audio processing. A value of 0.5 would imply that PortAudio and the sound +generating callback was consuming roughly 50% of the available CPU time. +This function may be called from the callback function or the application. +<blockquote> +<pre>double Pa_GetCPULoad( PortAudioStream* stream );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> | <a href="pa_tut_term.html">previous</a> +| <a href="pa_tut_devs.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/pa_tutorial.html b/pd/portaudio/docs/pa_tutorial.html new file mode 100644 index 00000000..1371c44f --- /dev/null +++ b/pd/portaudio/docs/pa_tutorial.html @@ -0,0 +1,46 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<p>Copyright 2000 Phil Burk and Ross Bencina +<h2> +Table of Contents</h2> + +<blockquote><a href="pa_tut_over.html">Overview of PortAudio</a> +<br><a href="pa_tut_mac.html">Compiling for Macintosh OS 7,8,9</a> +<br><a href="pa_tut_mac_osx.html">Compiling for Macintosh OS X</a> +<br><a href="pa_tut_pc.html">Compiling for Windows (DirectSound and WMME)</a> +<br><a href="pa_tut_asio.html">Compiling for ASIO on Windows or Mac OS +8,9</a> +<br><a href="pa_tut_oss.html">Compiling for Unix OSS</a> +<br><a href="pa_tut_callback.html">Writing a Callback Function</a> +<br><a href="pa_tut_init.html">Initializing PortAudio</a> +<br><a href="pa_tut_open.html">Opening a Stream using Defaults</a> +<br><a href="pa_tut_run.html">Starting and Stopping a Stream</a> +<br><a href="pa_tut_term.html">Cleaning Up</a> +<br><a href="pa_tut_util.html">Utilities</a> +<br><a href="pa_tut_devs.html">Querying for Devices</a> +<br><a href="pa_tut_rw.html">Blocking Read/Write Functions</a> +<br><a href="pa_tut_explore.html">Exploring the PortAudio Package</a></blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | contents | +previous | <a href="pa_tut_over.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio/docs/portaudio_h.txt b/pd/portaudio/docs/portaudio_h.txt new file mode 100644 index 00000000..6d60086f --- /dev/null +++ b/pd/portaudio/docs/portaudio_h.txt @@ -0,0 +1,425 @@ +#ifndef PORT_AUDIO_H +#define PORT_AUDIO_H + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* + * PortAudio Portable Real-Time Audio Library + * PortAudio API Header File + * Latest version available at: http://www.audiomulch.com/portaudio/ + * + * Copyright (c) 1999-2000 Ross Bencina and Phil Burk + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files + * (the "Software"), to deal in the Software without restriction, + * including without limitation the rights to use, copy, modify, merge, + * publish, distribute, sublicense, and/or sell copies of the Software, + * and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * Any person wishing to distribute modifications to the Software is + * requested to send the modifications to the original developer so that + * they can be incorporated into the canonical version. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR + * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * + */ + +typedef int PaError; +typedef enum { + paNoError = 0, + + paHostError = -10000, + paInvalidChannelCount, + paInvalidSampleRate, + paInvalidDeviceId, + paInvalidFlag, + paSampleFormatNotSupported, + paBadIODeviceCombination, + paInsufficientMemory, + paBufferTooBig, + paBufferTooSmall, + paNullCallback, + paBadStreamPtr, + paTimedOut, + paInternalError +} PaErrorNum; + +/* + Pa_Initialize() is the library initialisation function - call this before + using the library. +*/ + +PaError Pa_Initialize( void ); + +/* + Pa_Terminate() is the library termination function - call this after + using the library. +*/ + +PaError Pa_Terminate( void ); + +/* + Return host specific error. + This can be called after receiving a paHostError. +*/ +long Pa_GetHostError( void ); + +/* + Translate the error number into a human readable message. +*/ +const char *Pa_GetErrorText( PaError errnum ); + +/* + Sample formats + + These are formats used to pass sound data between the callback and the + stream. Each device has a "native" format which may be used when optimum + efficiency or control over conversion is required. + + Formats marked "always available" are supported (emulated) by all devices. + + The floating point representation uses +1.0 and -1.0 as the respective + maximum and minimum. + +*/ + +typedef unsigned long PaSampleFormat; +#define paFloat32 ((PaSampleFormat) (1<<0)) /*always available*/ +#define paInt16 ((PaSampleFormat) (1<<1)) /*always available*/ +#define paInt32 ((PaSampleFormat) (1<<2)) /*always available*/ +#define paInt24 ((PaSampleFormat) (1<<3)) +#define paPackedInt24 ((PaSampleFormat) (1<<4)) +#define paInt8 ((PaSampleFormat) (1<<5)) +#define paUInt8 ((PaSampleFormat) (1<<6)) /* unsigned 8 bit, 128 is "ground" */ +#define paCustomFormat ((PaSampleFormat) (1<<16)) + +/* + Device enumeration mechanism. + + Device ids range from 0 to Pa_CountDevices()-1. + + Devices may support input, output or both. Device 0 is always the "default" + device and should support at least stereo in and out if that is available + on the taget platform _even_ if this involves kludging an input/output + device on platforms that usually separate input from output. Other platform + specific devices are specified by positive device ids. +*/ + +typedef int PaDeviceID; +#define paNoDevice -1 + +typedef struct{ + int structVersion; + const char *name; + int maxInputChannels; + int maxOutputChannels; +/* Number of discrete rates, or -1 if range supported. */ + int numSampleRates; +/* Array of supported sample rates, or {min,max} if range supported. */ + const double *sampleRates; + PaSampleFormat nativeSampleFormats; +} PaDeviceInfo; + + +int Pa_CountDevices(); +/* + Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() + + Return the default device ID or paNoDevice if there is no devices. + The result can be passed to Pa_OpenStream(). + + On the PC, the user can specify a default device by + setting an environment variable. For example, to use device #1. + + set PA_RECOMMENDED_OUTPUT_DEVICE=1 + + The user should first determine the available device ID by using + the supplied application "pa_devs". +*/ +PaDeviceID Pa_GetDefaultInputDeviceID( void ); +PaDeviceID Pa_GetDefaultOutputDeviceID( void ); + +/* + PaTimestamp is used to represent a continuous sample clock with arbitrary + start time useful for syncronisation. The type is used in the outTime + argument to the callback function and the result of Pa_StreamTime() +*/ + +typedef double PaTimestamp; + +/* + Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure + referring to the device specified by id. + If id is out of range the function returns NULL. + + The returned structure is owned by the PortAudio implementation and must + not be manipulated or freed. The pointer is guaranteed to be valid until + between calls to Pa_Initialize() and Pa_Terminate(). +*/ + +const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID devID ); + +/* + PortAudioCallback is implemented by clients of the portable audio api. + + inputBuffer and outputBuffer are arrays of interleaved samples, + the format, packing and number of channels used by the buffers are + determined by parameters to Pa_OpenStream() (see below). + + framesPerBuffer is the number of sample frames to be processed by the callback. + + outTime is the time in samples when the buffer(s) processed by + this callback will begin being played at the audio output. + See also Pa_StreamTime() + + userData is the value of a user supplied pointer passed to Pa_OpenStream() + intended for storing synthesis data etc. + + return value: + The callback can return a nonzero value to stop the stream. This may be + useful in applications such as soundfile players where a specific duration + of output is required. However, it is not necessary to utilise this mechanism + as StopStream() will also terminate the stream. A callback returning a + nonzero value must fill the entire outputBuffer. + + NOTE: None of the other stream functions may be called from within the + callback function except for Pa_GetCPULoad(). + +*/ + +typedef int (PortAudioCallback)( + void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData ); + + +/* + Stream flags + + These flags may be supplied (ored together) in the streamFlags argument to + the Pa_OpenStream() function. + + [ suggestions? ] +*/ + +#define paNoFlag (0) +#define paClipOff (1<<0) /* disable defult clipping of out of range samples */ +#define paDitherOff (1<<1) /* disable default dithering */ +#define paPlatformSpecificFlags (0x00010000) +typedef unsigned long PaStreamFlags; + +/* + A single PortAudioStream provides multiple channels of real-time + input and output audio streaming to a client application. + Pointers to PortAudioStream objects are passed between PortAudio functions. +*/ + +typedef void PortAudioStream; +#define PaStream PortAudioStream + +/* + Pa_OpenStream() opens a stream for either input, output or both. + + stream is the address of a PortAudioStream pointer which will receive + a pointer to the newly opened stream. + + inputDevice is the id of the device used for input (see PaDeviceID above.) + inputDevice may be paNoDevice to indicate that an input device is not required. + + numInputChannels is the number of channels of sound to be delivered to the + callback. It can range from 1 to the value of maxInputChannels in the + device input record for the device specified in the inputDevice parameter. + If inputDevice is paNoDevice numInputChannels is ignored. + + inputSampleFormat is the format of inputBuffer provided to the callback + function. inputSampleFormat may be any of the formats described by the + PaSampleFormat enumeration (see above). PortAudio guarantees support for + the sound devices native formats (nativeSampleFormats in the device info + record) and additionally 16 and 32 bit integer and 32 bit floating point + formats. Support for other formats is implementation defined. + + inputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or stream processing. + inputDriverInfo is never required for correct operation. If not used + inputDriverInfo should be NULL. + + outputDevice is the id of the device used for output (see PaDeviceID above.) + outputDevice may be paNoDevice to indicate that an output device is not required. + + numOutputChannels is the number of channels of sound to be supplied by the + callback. See the definition of numInputChannels above for more details. + + outputSampleFormat is the sample format of the outputBuffer filled by the + callback function. See the definition of inputSampleFormat above for more + details. + + outputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or stream processing. + outputDriverInfo is never required for correct operation. If not used + outputDriverInfo should be NULL. + + sampleRate is the desired sampleRate for input and output + + framesPerBuffer is the length in sample frames of all internal sample buffers + used for communication with platform specific audio routines. Wherever + possible this corresponds to the framesPerBuffer parameter passed to the + callback function. + + numberOfBuffers is the number of buffers used for multibuffered + communication with the platform specific audio routines. This parameter is + provided only as a guide - and does not imply that an implementation must + use multibuffered i/o when reliable double buffering is available (such as + SndPlayDoubleBuffer() on the Macintosh.) + + streamFlags may contain a combination of flags ORed together. + These flags modify the behavior of the + streaming process. Some flags may only be relevant to certain buffer formats. + + callback is a pointer to a client supplied function that is responsible + for processing and filling input and output buffers (see above for details.) + + userData is a client supplied pointer which is passed to the callback + function. It could for example, contain a pointer to instance data necessary + for processing the audio buffers. + + return value: + Apon success Pa_OpenStream() returns PaNoError and places a pointer to a + valid PortAudioStream in the stream argument. The stream is inactive (stopped). + If a call to Pa_OpenStream() fails a nonzero error code is returned (see + PAError above) and the value of stream is invalid. + +*/ + +PaError Pa_OpenStream( PortAudioStream** stream, + PaDeviceID inputDevice, + int numInputChannels, + PaSampleFormat inputSampleFormat, + void *inputDriverInfo, + PaDeviceID outputDevice, + int numOutputChannels, + PaSampleFormat outputSampleFormat, + void *outputDriverInfo, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PaStreamFlags streamFlags, + PortAudioCallback *callback, + void *userData ); + + +/* + Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that + opens the default input and/or ouput devices. Most parameters have + identical meaning to their Pa_OpenStream() counterparts, with the following + exceptions: + + If either numInputChannels or numOutputChannels is 0 the respective device + is not opened (same as passing paNoDevice in the device arguments to Pa_OpenStream() ) + + sampleFormat applies to both the input and output buffers. +*/ + +PaError Pa_OpenDefaultStream( PortAudioStream** stream, + int numInputChannels, + int numOutputChannels, + PaSampleFormat sampleFormat, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PortAudioCallback *callback, + void *userData ); + +/* + Pa_CloseStream() closes an audio stream, flushing any pending buffers. +*/ + +PaError Pa_CloseStream( PortAudioStream* ); + +/* + Pa_StartStream() and Pa_StopStream() begin and terminate audio processing. + Pa_StopStream() waits until all pending audio buffers have been played. + Pa_AbortStream() stops playing immediately without waiting for pending + buffers to complete. +*/ + +PaError Pa_StartStream( PortAudioStream *stream ); + +PaError Pa_StopStream( PortAudioStream *stream ); + +PaError Pa_AbortStream( PortAudioStream *stream ); + +/* + Pa_StreamActive() returns one when the stream is playing audio, + zero when not playing, or a negative error number if the + stream is invalid. + The stream is active between calls to Pa_StartStream() and Pa_StopStream(), + but may also become inactive if the callback returns a non-zero value. + In the latter case, the stream is considered inactive after the last + buffer has finished playing. +*/ + +PaError Pa_StreamActive( PortAudioStream *stream ); + +/* + Pa_StreamTime() returns the current output time for the stream in samples. + This time may be used as a time reference (for example syncronising audio to + MIDI). +*/ + +PaTimestamp Pa_StreamTime( PortAudioStream *stream ); + +/* + The "CPU Load" is a fraction of total CPU time consumed by the + stream's audio processing. + A value of 0.5 would imply that PortAudio and the sound generating + callback was consuming roughly 50% of the available CPU time. + This function may be called from the callback function or the application. +*/ +double Pa_GetCPULoad( PortAudioStream* stream ); + +/* + Use Pa_GetMinNumBuffers() to determine minimum number of buffers required for + the current host based on minimum latency. + On the PC, for the DirectSound implementation, latency can be optionally set + by user by setting an environment variable. + For example, to set latency to 200 msec, put: + + set PA_MIN_LATENCY_MSEC=200 + + in the AUTOEXEC.BAT file and reboot. + If the environment variable is not set, then the latency will be determined + based on the OS. Windows NT has higher latency than Win95. +*/ + +int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate ); + +/* + Sleep for at least 'msec' milliseconds. + You may sleep longer than the requested time so don't rely + on this for accurate musical timing. +*/ +void Pa_Sleep( long msec ); + +/* + Return size in bytes of a single sample in a given PaSampleFormat + or paSampleFormatNotSupported. +*/ +PaError Pa_GetSampleSize( PaSampleFormat format ); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif /* PORT_AUDIO_H */ diff --git a/pd/portaudio/docs/portaudio_icmc2001.pdf b/pd/portaudio/docs/portaudio_icmc2001.pdf Binary files differnew file mode 100644 index 00000000..dd074b7d --- /dev/null +++ b/pd/portaudio/docs/portaudio_icmc2001.pdf diff --git a/pd/portaudio/docs/proposals.html b/pd/portaudio/docs/proposals.html new file mode 100644 index 00000000..0f9b8cb6 --- /dev/null +++ b/pd/portaudio/docs/proposals.html @@ -0,0 +1,36 @@ +<HTML> +<HEAD> +<TITLE>Proposed Changes to PortAudio API</TITLE> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252"> +<META content="Phil Burk, Ross Bencina" name=Author> +<META content="Changes being discussed by the community of PortAudio deveopers." +name=Description> +<META +content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis," +name=KeyWords> +</HEAD> +<BODY LINK="#0000ff" VLINK="#800080"> +<CENTER> +<TABLE bgColor=#fada7a cols=1 width="100%"> + <TBODY> + <TR> + <TD> + <CENTER> + <H1>Proposed Changes to PortAudio API</H1> + </CENTER> +</TD></TR></TBODY></TABLE></CENTER> +<P><A href="http://www.portaudio.com/">PortAudio Home Page</A></P> + +<P>Updated: July 27, 2002 </P> +<H2>The Proposals Have Moved</H2> + +<p> +All PortAudio Enhancement Proposal documentation has moved. On the web site, it is now located at: +<A HREF="http://www.portaudio.com/docs/proposals">http://www.portaudio.com/docs/proposals</A> + +On the CVS server it is now located in a module named "pa_proposals". +</p> + + +</BODY> +</HTML> diff --git a/pd/portaudio/docs/releases.html b/pd/portaudio/docs/releases.html new file mode 100644 index 00000000..aec80a1c --- /dev/null +++ b/pd/portaudio/docs/releases.html @@ -0,0 +1,339 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="PortAudio is a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Release Notes</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio - Release Notes</h1></center> +</td> +</tr> +</table></center> + +<p>Link to <a href="http://www.portaudio.com">PortAudio Home Page</a> +<h2> +<b>V18 - 5/6/02</b></h2> + +<blockquote>All source code and documentation now under <a href="http://www.portaudio.com/usingcvs.html">CVS</a>. +<p>Ran most of the code through <a href="http://astyle.sourceforge.net/">AStyle</a> +to cleanup ragged indentation caused by using different editors. Used this +command: +<br><tt> astyle --style=ansi -c -o --convert-tabs --indent-preprocessor +*.c</tt></blockquote> + +<blockquote>Added "pa_common/pa_convert.c" for Mac OS X. Start of new conversion +utilities. +<p><b>ASIO</b> +<ul> +<li> +New Pa_ASIO_Adaptor_Init function to init Callback adpatation variables,</li> + +<li> +Cleanup of Pa_ASIO_Callback_Input</li> + +<li> +Break apart device loading to debug random failure in Pa_ASIO_QueryDeviceInfo</li> + +<li> +Deallocate all resources in PaHost_Term for cases where Pa_CloseStream +is not called properly</li> + +<li> +New Pa_ASIO_loadDriver that calls CoInitialize on each thread on Windows. +Allows use by multiple threads.</li> + +<li> +Correct error code management in PaHost_Term, removed various compiler +warning</li> + +<li> +Add Mac includes for <Devices.h> and <Timer.h></li> + +<li> +Pa_ASIO_QueryDeviceInfo bug correction, memory allocation checking, better +error handling</li> +</ul> +<b>Mac OS X</b> +<ul> +<li> +Major cleanup and improvements.</li> + +<li> +Fixed device queries for numChannels and sampleRates,</li> + +<li> +Audio input works if using same CoreAudio device (some HW devices make +separate CoreAudio devices).</li> + +<li> +Added paInt16, paInt8, format using new "pa_common/pa_convert.c" file.</li> + +<li> +Return error if opened in mono mode cuz not supported.</li> + +<li> +Check for getenv("PA_MIN_LATEWNCY_MSEC") to set latency externally.</li> + +<li> +Use getrusage() instead of gettimeofday() for CPU Load calculation.</li> +</ul> +<b>Windows MME</b> +<ul> +<li> +Fixed bug that caused TIMEOUT in Pa_StopStream(). Added check for past_StopSoon() +in Pa_TimeSlice(). Thanks Julien Maillard.</li> + +<li> +Detect Win XP versus NT, use lower latency.</li> + +<li> +Fix DBUG typo;</li> + +<li> +removed init of CurrentCount which was not compiling on Borland</li> + +<li> +general cleanup, factored streamData alloc and cpu usage initialization</li> + +<li> +stopped counting WAVE_MAPPER when there were no audio cards plugged in</li> +</ul> +<b>Windows DirectSound</b> +<ul> +<li> +Detect Win XP and Win 2K properly when determining latency.</li> +</ul> +<b>Unix OSS</b> +<ul> +<li> +Use high real-time priority if app is running with root priveledges. Lowers +latency.</li> + +<li> +Added watch dog thread that prevents real-time thread from hogging CPU +and hanging the computer.</li> + +<li> +Check error return from read() and write().</li> + +<li> +Check CPU endianness instead of assuming Little Endian.</li> +</ul> +</blockquote> + +<h2> +<b>V17 - 10/15/01</b></h2> + +<blockquote><b>Unix OSS</b> +<ul> +<li> +Set num channels back to two after device query for ALSA. This fixed a +bug in V16 that sometimes caused a failure when querying for the sample +rates. Thanks Stweart Greenhill.</li> +</ul> +</blockquote> + +<blockquote> +<h4> +<b>Macintosh Sound Manager</b></h4> + +<ul> +<li> +Use NewSndCallBackUPP() for CARBON compatibility.</li> +</ul> +</blockquote> + +<h2> +<b>V16 - 9/27/01</b></h2> + +<blockquote><b>Added Alpha implementations for ASIO, SGI, and BeOS!</b> +<br> +<li> +CPULoad is now calculated based on the time spent to generate a known number +of frames. This is more accurate than a simple percentage of real-time. +Implemented in pa_unix_oss, pa_win_wmme and pa_win_ds.</li> + +<li> +Fix dither and shift for recording PaUInt8 format data.</li> + +<li> +Added "patest_maxsines.c" which tests <tt>Pa_GetCPULoad().</tt></li> +</blockquote> + +<blockquote> +<h4> +Windows WMME</h4> + +<ul> +<li> +sDevicePtrs now allocated using <tt>GlobalAlloc()</tt>. This prevents a +crash in Pa_Terminate() on Win2000. Thanks Mike Berry for finding this. +Thanks Mike Berry.</li> + +<li> +Pass process instead of thread to <tt>SetPriorityClass</tt>(). This fixes +a bug that caused the priority to not be increased. Thanks to Alberto di +Bene for spotting this.</li> +</ul> + +<h4> +Windows DirectSound</h4> + +<ul> +<li> +Casts for compiling with __MWERKS__ CodeWarrior.</li> +</ul> + +<h4> +UNIX OSS</h4> + +<ul> +<li> +Derived from Linux OSS implementation.</li> + +<li> +Numerous patches from Heiko Purnhagen, Stephen Brandon, etc.</li> + +<li> +Improved query mechanism which often bailed out unnecessarily.</li> + +<li> +Removed sNumDevices and potential related bugs,</li> + +<li> +Use <tt>getenv("PA_MIN_LATENCY_MSEC")</tt> in code to set desired latency. +User can set by entering:</li> + +<br> <tt>export PA_MIN_LATENCY_MSEC=40</tt></ul> + +<h4> +Macintosh Sound Manager</h4> + +<ul> +<li> +Pass unused event to WaitNextEvent instead of NULL to prevent Mac OSX crash. +Thanks Dominic Mazzoni.</li> + +<li> +Use requested number of input channels.</li> + +<br> </ul> +</blockquote> + +<h2> +<b>V15 - 5/29/01</b></h2> + +<blockquote> +<ul> +<li> +<b>New Linux OSS Beta</b></li> +</ul> + +<h4> +Windows WMME</h4> + +<ul> +<li> + sDevicePtrs now allocated based on sizeof(pointer). Was allocating +too much space.</li> + +<li> + Check for excessive numbers of channels. Some drivers reported bogus +numbers.</li> + +<li> +Apply Mike Berry's changes for CodeWarrior on PC including condition including +of memory.h, and explicit typecasting on memory allocation.</li> +</ul> + +<h4> +Macintosh Sound Manager</h4> + +<ul> +<li> +ScanInputDevices was setting sDefaultOutputDeviceID instead of sDefaultInputDeviceID.</li> + +<li> +Device Scan was crashing for anything other than siBadSoundInDevice, but +some Macs may return other errors! Caused failure to init on some G4s under +OS9.</li> + +<li> +Fix TIMEOUT in record mode.</li> + +<li> +Change CARBON_COMPATIBLE to TARGET_API_MAC_CARBON</li> +</ul> +</blockquote> + +<h2> +<b>V14 - 2/6/01</b></h2> + +<blockquote> +<ul> +<li> +Added implementation for Windows MultiMedia Extensions (WMME) by Ross and +Phil</li> + +<li> +Changed Pa_StopStream() so that it waits for the buffers to drain.</li> + +<li> +Added Pa_AbortStream() that stops immediately without waiting.</li> + +<li> +Added new test: patest_stop.c to test above two mods.</li> + +<li> +Fixed Pa_StreamTime() so that it returns current play position instead +of the write position. Added "patest_sync.c" to demo audio/video sync.</li> + +<li> +Improved stability of Macintosh implementation. Added timeouts to prevent +hangs.</li> + +<li> +Added Pa_GetSampleSize( PaSampleFormat format );</li> + +<li> +Changes some "int"s to "long"s so that PA works properly on Macintosh which +often compiles using 16 bit ints.</li> + +<li> +Added Implementation Guide</li> +</ul> +</blockquote> + +<h2> +<b>V12 - 1/9/01</b></h2> + +<blockquote> +<ul> +<li> +Mac now scans for and queries all devices. But it does not yet support +selecting any other than the default device.</li> + +<li> +Blocking I/O calls renamed to separate them from the PortAudio API.</li> + +<li> +Cleaned up indentation problems with tabs versus spaces.</li> + +<li> +Now attempts to correct bogus sample rate info returned from DirectSound +device queries.</li> +</ul> +</blockquote> + +</body> +</html> |