portaudio-18.1.orig/ 0002755 0001750 0000062 00000000000 10074507675 015007 5 ustar mikael staff 0000000 0000000 portaudio-18.1.orig/docs/ 0000755 0001750 0000062 00000000000 07700016420 015716 5 ustar mikael staff 0000000 0000000 portaudio-18.1.orig/docs/pa_impl_startstop.html 0000644 0001750 0001750 00000007162 07465451052 022536 0 ustar mikael mikael 0000000 0000000
PortAudio Implementation |
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.
int past_IsActive; /* Background is still playing. */
int past_StopSoon; /* Stop when last buffer done. */
int past_StopNow; /* Stop IMMEDIATELY. */
Foreground Thread | Background Thread |
sets StopNow | |
sees StopNow, | |
clears IsActive, stops thread | |
waits for thread to exit | |
turns off audio I/O |
Foreground Thread | Background Thread |
sets StopSoon | |
stops calling user callback | |
continues until output buffer empty | |
clears IsActive, stops thread | |
waits for thread to exit | |
turns off audio I/O |
Foreground Thread | Background Thread |
callback returns 1 | |
sets StopSoon | |
stops calling user callback | |
continues until output buffer empty | |
clears IsActive, stops thread | |
waits for thread to exit | |
turns off audio I/O |
Proposed Changes to PortAudio API |
Updated: July 27, 2002
All PortAudio Enhancement Proposal documentation has moved. On the web site, it is now located at: http://www.portaudio.com/docs/proposals On the CVS server it is now located in a module named "pa_proposals".
portaudio-18.1.orig/docs/pa_tut_init.html 0000644 0001750 0001750 00000003216 07465451052 021305 0 ustar mikael mikael 0000000 0000000
PortAudio Tutorial |
Before making any other calls to PortAudio, you must call Pa_Initialize(). This will trigger a scan of available devices which can be queried later. Like most PA functions, it will return a result of type paError. If the result is not paNoError, then an error has occurred.home | contents | previous | next portaudio-18.1.orig/docs/pa_tutorial.html 0000644 0001750 0001750 00000003732 07465451052 021314 0 ustar mikael mikael 0000000 0000000You can get a text message that explains the error message by passing it toerr = Pa_Initialize(); if( err != paNoError ) goto error;printf( "PortAudio error: %s\n", Pa_GetErrorText( err ) );
PortAudio Tutorial |
Copyright 2000 Phil Burk and Ross Bencina
Overview of PortAudiohome | contents | previous | next portaudio-18.1.orig/docs/pa_tut_open.html 0000644 0001750 0001750 00000005662 07535106000 021276 0 ustar mikael mikael 0000000 0000000
Compiling for Macintosh OS 7,8,9
Compiling for Macintosh OS X
Compiling for Windows (DirectSound and WMME)
Compiling for ASIO on Windows or Mac OS 8,9
Compiling for Unix OSS
Writing a Callback Function
Initializing PortAudio
Opening a Stream using Defaults
Starting and Stopping a Stream
Cleaning Up
Utilities
Querying for Devices
Blocking Read/Write Functions
Exploring the PortAudio Package
PortAudio Tutorial |
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.home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_explore.html 0000644 0001750 0001750 00000003104 07465451052 022014 0 ustar mikael mikael 0000000 0000000First declare a variable to receive the stream pointer:
There are two calls for opening streams, Pa_OpenStream() and Pa_OpenDefaultStream(). Pa_OpenStream() takes extra parameters which give you more control. You can normally just use Pa_OpenDefaultStream() which just calls Pa_OpenStream() with some reasonable default values. Let's open a stream for stereo output, using floating point data, at 44100 Hz.PortAudioStream *stream;If you want to use 16 bit integer data, pass paInt16 instead of paFloat32.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 */
PortAudio Tutorial |
Now that you have a good idea of how PortAudio works, you can try out the test programs.home | contents | previous | next portaudio-18.1.orig/docs/index.html 0000644 0001750 0001750 00000004310 07640011152 020055 0 ustar mikael mikael 0000000 0000000I 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.
- For an example of playing a sine wave, see "pa_tests/patest_sine.c".
- For an example of recording and playing back a sound, see "pa_tests/patest_record.c".
PortAudio Documentation |
Copyright 2000 Phil Burk and Ross Bencina
The Application Programmer Interface is documented in "portaudio.h".
Describes how to write audio programs using the PortAudio API.
Describes how to write an implementation of PortAudio for a new computer platform.
Describes the PortAudio API and discusses implementation issues. Written July 2001.
Describes API changes being considered by the developer community. Feedback welcome.
Reference documents for the Application Programmer Interface for V19 generated by doxygen.
How to tune your computer to achieve the lowest possible audio delay.Return to PortAudio Home Page portaudio-18.1.orig/docs/pa_tut_term.html 0000644 0001750 0001750 00000003410 07465451052 021305 0 ustar mikael mikael 0000000 0000000
PortAudio Tutorial |
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:
home | contents | previous | next portaudio-18.1.orig/docs/latency.html 0000644 0001750 0001750 00000020263 07465451052 020426 0 ustar mikael mikael 0000000 0000000Then when you are done using PortAudio, you should terminate the whole system by calling:err = Pa_CloseStream( stream ); if( err != paNoError ) goto error;That's basically it. You can now write an audio program in 'C' that will run on multiple platforms, for example PCs and Macintosh.Pa_Terminate();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.
PortAudio Latency |
This page discusses the issues of audio latency for PortAudio . It offers suggestions on how to lower latency to improve the responsiveness of applications.
What is Latency?By Phil Burk, Copyright 2002 Phil Burk and Ross Bencina
PortAudio and Latency
Macintosh
Unix
WIndows
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.
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.
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.
The latency in milliseconds due to this buffering is:
latency_msec = 1000 * numBuffers * framesPerBuffer / framesPerSecondThis is not the total latency, as we have seen, but it is the part we can control.
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.
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:
int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate );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.
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:
setenv PA_MIN_LATENCY_MSEC 4
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.
You can set the PA_MIN_LATENCY_MSEC variable to 50, for example, by entering in MS-DOS:
set PA_MIN_LATENCY_MSEC=50If 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.
For Windows XP, you can set environment variables as follows:
PortAudio Implementation Guide |
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.
By Phil Burk
Copyright 2000 Phil Burk and Ross Bencina
Note that the license says: "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.". So when you have finished a new implementation, please send it back to us at "http://www.portaudio.com" so that we can make it available for other users. Thank you!
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".
If you have suggestions for how to make future implementations easier,
please let us know.
THANKS!
portaudio-18.1.orig/docs/pa_tut_rw.html 0000644 0001750 0001750 00000007610 07465451052 020774 0 ustar mikael mikael 0000000 0000000
PortAudio Tutorial |
[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.]home | contents | previous | next portaudio-18.1.orig/docs/releases.html 0000644 0001750 0001750 00000017363 07465454164 020610 0 ustar mikael mikael 0000000 0000000There 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.
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:
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".#include "pablio.h"#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 );
PortAudio - Release Notes |
Link to PortAudio Home Page
All source code and documentation now under CVS.Ran most of the code through AStyle to cleanup ragged indentation caused by using different editors. Used this command:
astyle --style=ansi -c -o --convert-tabs --indent-preprocessor *.c
Added "pa_common/pa_convert.c" for Mac OS X. Start of new conversion utilities.ASIO
Mac OS X
- New Pa_ASIO_Adaptor_Init function to init Callback adpatation variables,
- Cleanup of Pa_ASIO_Callback_Input
- Break apart device loading to debug random failure in Pa_ASIO_QueryDeviceInfo
- Deallocate all resources in PaHost_Term for cases where Pa_CloseStream is not called properly
- New Pa_ASIO_loadDriver that calls CoInitialize on each thread on Windows. Allows use by multiple threads.
- Correct error code management in PaHost_Term, removed various compiler warning
- Add Mac includes for <Devices.h> and <Timer.h>
- Pa_ASIO_QueryDeviceInfo bug correction, memory allocation checking, better error handling
Windows MME
- Major cleanup and improvements.
- Fixed device queries for numChannels and sampleRates,
- Audio input works if using same CoreAudio device (some HW devices make separate CoreAudio devices).
- Added paInt16, paInt8, format using new "pa_common/pa_convert.c" file.
- Return error if opened in mono mode cuz not supported.
- Check for getenv("PA_MIN_LATEWNCY_MSEC") to set latency externally.
- Use getrusage() instead of gettimeofday() for CPU Load calculation.
Windows DirectSound
- Fixed bug that caused TIMEOUT in Pa_StopStream(). Added check for past_StopSoon() in Pa_TimeSlice(). Thanks Julien Maillard.
- Detect Win XP versus NT, use lower latency.
- Fix DBUG typo;
- removed init of CurrentCount which was not compiling on Borland
- general cleanup, factored streamData alloc and cpu usage initialization
- stopped counting WAVE_MAPPER when there were no audio cards plugged in
Unix OSS
- Detect Win XP and Win 2K properly when determining latency.
- Use high real-time priority if app is running with root priveledges. Lowers latency.
- Added watch dog thread that prevents real-time thread from hogging CPU and hanging the computer.
- Check error return from read() and write().
- Check CPU endianness instead of assuming Little Endian.
Unix OSS
- 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.
Macintosh Sound Manager
- Use NewSndCallBackUPP() for CARBON compatibility.
Added Alpha implementations for ASIO, SGI, and BeOS!
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. Fix dither and shift for recording PaUInt8 format data. Added "patest_maxsines.c" which tests Pa_GetCPULoad().
Windows WMME
- sDevicePtrs now allocated using GlobalAlloc(). This prevents a crash in Pa_Terminate() on Win2000. Thanks Mike Berry for finding this. Thanks Mike Berry.
- Pass process instead of thread to SetPriorityClass(). This fixes a bug that caused the priority to not be increased. Thanks to Alberto di Bene for spotting this.
Windows DirectSound
- Casts for compiling with __MWERKS__ CodeWarrior.
UNIX OSS
- Derived from Linux OSS implementation.
- Numerous patches from Heiko Purnhagen, Stephen Brandon, etc.
- Improved query mechanism which often bailed out unnecessarily.
- Removed sNumDevices and potential related bugs,
- Use getenv("PA_MIN_LATENCY_MSEC") in code to set desired latency. User can set by entering:
export PA_MIN_LATENCY_MSEC=40Macintosh Sound Manager
- Pass unused event to WaitNextEvent instead of NULL to prevent Mac OSX crash. Thanks Dominic Mazzoni.
- Use requested number of input channels.
- New Linux OSS Beta
Windows WMME
- sDevicePtrs now allocated based on sizeof(pointer). Was allocating too much space.
- Check for excessive numbers of channels. Some drivers reported bogus numbers.
- Apply Mike Berry's changes for CodeWarrior on PC including condition including of memory.h, and explicit typecasting on memory allocation.
Macintosh Sound Manager
- ScanInputDevices was setting sDefaultOutputDeviceID instead of sDefaultInputDeviceID.
- 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.
- Fix TIMEOUT in record mode.
- Change CARBON_COMPATIBLE to TARGET_API_MAC_CARBON
- Added implementation for Windows MultiMedia Extensions (WMME) by Ross and Phil
- Changed Pa_StopStream() so that it waits for the buffers to drain.
- Added Pa_AbortStream() that stops immediately without waiting.
- Added new test: patest_stop.c to test above two mods.
- Fixed Pa_StreamTime() so that it returns current play position instead of the write position. Added "patest_sync.c" to demo audio/video sync.
- Improved stability of Macintosh implementation. Added timeouts to prevent hangs.
- Added Pa_GetSampleSize( PaSampleFormat format );
- Changes some "int"s to "long"s so that PA works properly on Macintosh which often compiles using 16 bit ints.
- Added Implementation Guide
portaudio-18.1.orig/docs/pa_tut_asio.html 0000644 0001750 0001750 00000006733 07623460774 021313 0 ustar mikael mikael 0000000 0000000
- Mac now scans for and queries all devices. But it does not yet support selecting any other than the default device.
- Blocking I/O calls renamed to separate them from the PortAudio API.
- Cleaned up indentation problems with tabs versus spaces.
- Now attempts to correct bogus sample rate info returned from DirectSound device queries.
PortAudio Tutorial |
ASIO is a low latency audio API from Steinberg. To compile an ASIO application, you must first download the ASIO SDK from Steinberg. You also need to obtain ASIO drivers from the manufacturer of your audio hardware.Note: I am using '/' as a file separator below. On Macintosh replace '/' with ':'. On Windows, replace '/' with '\'.
You may try compiling the "pa_tests/patest_saw.c" file first because it is the simplest.
Several files are common to all PortAudio implementations. Add the following source files to your project:
pa_common/pa_lib.cTo use ASIO with the PortAudio library add the following:
pa_common/portaudio.h
pa_common/pa_host.hpa_asio/pa_asio.cpp
Note: there is a bug in the Macintosh ASIO code. Mac users should read the file "pa_asio:readme_asio_sdk_patch.txt" for information on how to fix the bug.Add these files from the ASIO SDK downloaded from Steinberg:
host/asiodrivers.cppThe ASIO drivers should be in a folder called "ASIO Drivers" beneath your application.
host/mac/asioshlib.cpp
host/mac/codefragements.cpp
Add these files from the ASIO SDK downloaded from Steinberg:
host/asiodrivers.cpp
host/asiolist.cpp
common/asio.cpp
Add these directories to the path for include files:
host
host/pc
common
and link with the system library "winmm.lib". For MS Visual C++:home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_callback.html 0000644 0001750 0001750 00000011372 07465451052 022100 0 ustar mikael mikael 0000000 0000000
- select "Settings..." from the "Project" menu,
- select the project name in the tree on the left,
- choose "All Configurations" in the popup menu above the tree,
- select the "Link" tab,
- enter "winmm.lib", without quotes, as the first item in the "Object/library modules:" field.
PortAudio Tutorial |
To write a program using PortAudio, you must include the "portaudio.h" include file. You may wish to read "portaudio.h" because it contains a complete description of the PortAudio functions and constants.home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_util.html 0000644 0001750 0001750 00000004443 07465451052 021322 0 ustar mikael mikael 0000000 0000000The 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.#include "portaudio.h"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().
Your callback function must return an int and accept the exact parameters specified in this typedef:
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 float 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 userData.typedef int (PortAudioCallback)( void *inputBuffer, void *outputBuffer, unsigned long framesPerBuffer, PaTimestamp outTime, void *userData );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; }
PortAudio Tutorial |
Here are several more functions that are not critical, but may be handy when using PortAudio.home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_mac.html 0000644 0001750 0001750 00000002700 07465451052 021077 0 ustar mikael mikael 0000000 0000000Pa_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.
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.PaError Pa_StreamActive( 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.PaTimestamp Pa_StreamTime( PortAudioStream *stream );double Pa_GetCPULoad( PortAudioStream* stream );
PortAudio Tutorial |
To compile a Macintosh application with the PortAudio library, add the following source files to your project:home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_oss.html 0000644 0001750 0001750 00000002774 07465451052 021156 0 ustar mikael mikael 0000000 0000000Also add the Apple SoundLib to your project.pa_mac:pa_mac.c pa_common:pa_lib.c pa_common:portaudio.h pa_common:pa_host.hYou may try compiling the "pa_tests:patest_saw.c" file first because it is the simplest.
PortAudio Tutorial |
[Skip this page if you are not using Unix and OSS]home | contents | previous | next portaudio-18.1.orig/docs/pa_tut_devs.html 0000644 0001750 0001750 00000005175 07465451052 021311 0 ustar mikael mikael 0000000 0000000We currently support the OSS audio drivers for Linux, Solaris, and FreeBSD. We hope to someday support the newer ALSA drivers.
- cd to pa_unix_oss directory
- Edit the Makefile and uncomment one of the tests. You may try compiling the "patest_sine.c" file first because it is very simple.
- gmake run
PortAudio Tutorial |
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".home | contents | previous | next portaudio-18.1.orig/docs/portaudio_h.txt 0000644 0001750 0001750 00000034533 07465451052 021164 0 ustar mikael mikael 0000000 0000000 #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 */ portaudio-18.1.orig/docs/pa_tut_over.html 0000644 0001750 0001750 00000006242 07465451052 021317 0 ustar mikael mikael 0000000 0000000To determine the number of devices:
You can then query each device in turn by calling Pa_GetDeviceInfo() with an index.numDevices = Pa_CountDevices();It will return a pointer to a PaDeviceInfo structure which is defined as:for( i=0; i<numDevices; i++ ) { pdi = Pa_GetDeviceInfo( i );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.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;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().
PortAudio Tutorial |
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.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.
There is also another interface 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.home | contents | previous portaudio-18.1.orig/docs/portaudio_icmc2001.pdf 0000644 0001750 0001750 00000143430 07465451052 022102 0 ustar mikael mikael 0000000 0000000 %PDF-1.1 %âãÏÓ 2 0 obj << /D [1 0 R /XYZ null 67 null] >> endobj 3 0 obj << /D [1 0 R /XYZ null 626 null] >> endobj 4 0 obj << /D [1 0 R /XYZ null 612 null] >> endobj 5 0 obj << /D [1 0 R /XYZ null 398 null] >> endobj 6 0 obj << /D [1 0 R /XYZ null 385 null] >> endobj 7 0 obj << /D [1 0 R /XYZ null 264 null] >> endobj 8 0 obj << /D [1 0 R /XYZ null 202 null] >> endobj 9 0 obj << /D [1 0 R /XYZ null 391 null] >> endobj 10 0 obj << /D [1 0 R /XYZ null 378 null] >> endobj 11 0 obj << /D [1 0 R /XYZ null 353 null] >> endobj 12 0 obj << /D [1 0 R /XYZ null 292 null] >> endobj 13 0 obj << /D [1 0 R /XYZ null 219 null] >> endobj 14 0 obj << /D [1 0 R /XYZ null 138 null] >> endobj 15 0 obj << /D [1 0 R /XYZ null 125 null] >> endobj 16 0 obj << /CreationDate (D:191010723144925) /Producer (\376\377\000A\000c\000r\000o\000b\000a\000t\000 \000D\000i\000s\000t\000i\000l\000l\000e\000r\000 \0003\000.\0000\0001\000 \000f\000o\000r\000 \000W\000i\000n\000d\000o\000w\000s) /Creator (FrameMaker 5.5.3L15a) >> endobj 17 0 obj << /D [1 0 R /XYZ null null null] >> endobj 18 0 obj << /D [1 0 R /XYZ null null null] >> endobj 19 0 obj << /I << /Title (Flow98310) >> /F 20 0 R >> endobj 21 0 obj << /Length 7928 /Filter /LZWDecode >> stream €Š€ÐP¼Œ3DC4b2"0˜€Äl7 F¨äb.ÆÊ†Ø$JL 9à„"À€^G)ÂŒç1±ŒÃ€Òc‚ŤZ8ΔaˆÄPr0˜éeÒ¡* ÂapÐPä\8ŸIëÖàÒw>ÇáœBG%Ãç÷€Üs;ÐEAHÜPhŒ‘HÈeI¦ .(àa8E#ñË'N2BÛñÏ.(1äò¹ü ´f(1d²˜Šn, 7d†”ã¸€ß‘Ñ ÂÜö´ÞuË °Zà£U~hu|¿{NÏF8¡h§(Ús /(3òÚÓn\ÃHx\£)ªUQ.•³) *.ƒAR€ù§oêò(NÐdÓ´¬8ÄËa°P0¼l8ò£AÁõèÈÂ@á@Þ #pà:°¡¨P:Ü26ë¼ÓÄc \ɇ,X“ -ë̳pttÁ°8ÎØ²jDX£LT_2l[¢þHèÚ8 ãN3BoŠ*K `¬Š…%° tzÅ»ƒÄɰ㤬Ýí´JðI tç #|玄ç*¹JC»7ãt~(¡”M3Éc»¶ãB”€b¤ Á í"Áòl1ÃÑ%Ä:M;$… Ã9ŽæËT!CÊÓÇácત¡ê¶sõ !„½ESœX0‘üôÌüNJsøÒ3H!D&££OÌñå1KÒt…¨ìÚ-¸ÚÕR’lP7ŒÑM=Cpøàà©ÓÕ>3ÓSe3O²}E7Õ›äú#á›î…×iÊvº®p aE/ÕéEÉuûˆ¡”ñÁÕ;¥»X¬v¢ãv”êÆb±3A,8ȦF¬#O~ä7¦B)xòÿ–8ÎN#&d/+¤¿OÑ6:ÆSèã+¢ÔSÖChTY^B2ŽÚ8ÆÍâÌ^˜1¨é¬bê2‘¨S9‰¬Ä9ÆFy+¾:L;©ßÒÜ»….Oòè»a°"†É´â‚˜§ !0U;çÍwæ°*{>5·,Úý•°Qk±ZÎÄ^LPê3ÓW=0ChÚ:ÃK½ (ÎD6°ücˆ¿¼gÒ´ô+±'±S•I~ó6³%-R休LUwrÒvb:¬PÉÆ Ú0ÃŒ>;z#tã*ú>Oèí°¨ƒÀ1cpê6µ-ÍXé±wG¢7/CRò#cŽbÃ@aRçÿ³§ôäWê¤f¦œñ”çxjžIJ=ÿ²·ò›Áý?ép¤Öh#Sìl-µ#Ca·Nj½o1%Ì´Y"Ÿ^H™h1Sñ”À }gHÁ8'èáQRÃ^´Å¾D:¾Ÿ:Lð‘CAbjHDÉ‘&ïC¼^Êq%ÂgÛ¹:€Ø»¦ôRš4éžBúSƒ¢§S麛¥ýè p@à¿,w$CâI§}oÑè˜!²Nh]{ ® A²_7‡uœÂkbd£‚€ŠdÞ Á„mÕäÆâ[ù:Kéæ„Gºä›5nÞ$˜p¦oÑZ²[¬Ñè˜åŒ\™"Êdá½9^–K¿1,ÝR në!#Á“ˆÕG#½$ÀLet's continue by building a simple application that will play a sawtooth wave.
Please select the page for the specific implementation you would like to use:
or continue with the next page of the programming tutorial.