PortAudio Home Page
Updated: February 6, 2011
This document was used to track V19 development status during initial development. Development is now coordinated via TRAC tickets and the wiki. Visit the V19ReleasePlan page for current status information.
For some years PortAudio development proceeded incrementally - bugs were fixed, new implementations were created and a few features were added. Around the time of the original V18 release in 2001 a big list of requested features existed, and there were many separate implementations of the PortAudio API, some with more cut-and-paste commonality than code sharing. Due to a combination of forces, most notably the desire to support multiple Host APIs in a single PortAudio build, it was decided to develop a new unified common infrastructure (support library) with which to implement V19. At that time the feature requests were developed into a set of enhancement proposals which describe the new (Version 2.0) PortAudio API now documented in V19's portaudio.h. The proposals have been stable since 2003. The common infrastructure is implemented in the v19-devel CVS branch, and the version 2.0 API is well documented, and available as part of the doxygen generated documentation.
Although each proposal is relatively small when taken in isolation, the overall scale of required changes from V18 to V19 is substantial. The new common infrastructure imposes a new interface for implementations. This new interface increases reliability and consistency and reduces development effort, but calls for considerable refactoring (some would say redevelopment) of existing PortAudio implementations relative to the V18 code base.
At the time of writing, a substantial portion of V19 functionality has been implemented for Windows (MME, DirectSound, and ASIO) for Linux (ALSA, OSS, and JACK), and for Mac OSX Core Audio. Platforms which were well supported with V18 which are not currently supported by V19 are SGI AL and pre-OSX Macintosh (Sound Manager). The V19 ASIO implementation has not been back-ported to the Macintosh, however it would require little effort to do so if the need arose.
The amount of development required to move from V18 release to V19 release has proven to be a significant obstacle to completing the V19 release. In hindsight it may have been preferable to plan an incremental change schedule for migrating implementations from V18 to the new version 2.0 API. However hindsight is of little benefit to us now, and we need a plan to finalise the V19 release, the remainder of this document is part of that plan.
The lists below attempt to clearly document the status of the current V19 development effort, in order to assist planning the V19 release. The original development status table was expressed in terms of the enhancement proposals, some of which included multiple features. In some cases features were spread accross multiple proposals. This new status table attempts to break the status down into finer grained features whose status can be easily verified. Developers are requested to report status to Ross Bencina (email@example.com), and to suggest new items for pending features not listed here. All unfinished features listed here, as well as other unfinished tasks should be listed as doxygen @todo items in the source code so that we can more easily track development status with the doxygen todo list.
Items marked green have been implemented, yellow are unknown, and red are not implemented.
With some possible exceptions (such as (1) addition of new backward compatible structure fields, (2) additional error codes, and (3) documentation refinements), the API defined in portaudio.h is complete and will not change between now and the V19 release. For this reason, clients who wish to use V19 now and take advantage of the existing functionality may safely do so without hazard of major changes between now and the final V19 release.
The list below describe API features which must be implemented by each implementation. In most cases the implementation status of these features will only effect clients who make use of these features, they do not effect the functioning of other aspects of the API.
All features marked green are thought to be implemented correctly, however this does not preclude bugs. Some features marked red may be partially implemented or include placeholder hacks which may make them appear to work in some situations. The status of features marked yellow is not presently known - developers who wrote or understand the code are requested to clarify and report the status of the entries marked yellow. Features marked white are not applicable (for example it's not possible to implement the blocking API with Jack).
Key: wmme - Windows Multimedia API (MME), ds - Windows DirectSound, asio - Steinberg ASIO (Mac and PC, Mac not tested under V19 as of September 17 2003), alsa - Advanced Linux Sound Architecture, oss - Open Sound System (Unix), mac_sm - Macintosh Sound Manager (Carbon, pre-OS X), mac_core - Mac OS X Core Audio, sgi - Silicon Graphics AL.
|Consistent handling of underflow and overflow conditions (see proposal 001). This includes passing information about dropped buffers to the buffer adaptor.
|Correctly handling the paNeverDropInput OpenStream() flag. (see proposal 001)
|basic PaDeviceInfo support (structVersion, name, hostApi) (see proposal 002)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|maxInputChannels and maxOutputChannels fields of PaDeviceInfo (see proposal 002)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|defaultSampleRate field of PaDeviceInfo (see proposal 002)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_IsFormatSupported() (see proposal 002)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_IsFormatSupported() when paUseHostApiSpecificDeviceSpecification or hostApiSpecificStreamInfo is used (see proposal 002)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Calculate buffer settings based on suggestedLatency in inputParameters and outputParameters to Pa_OpenStream() (see proposal 003)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|defaultLowInputLatency, defaultLowOutputLatency fields of PaDeviceInfo (see proposal 003)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|defaultHighInputLatency, defaultHighOutputLatency fields of PaDeviceInfo (see proposal 003)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|inputLatency and outputLatency fields of PaStreamInfo (see proposal 003)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|framesPerBuffer value of paFramesPerBufferUnspecified (0) for OpenStream() to indicate variable implementation specified frames per buffer (see proposal 004)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_ReadStream() (see proposal 005)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_WriteStream() (see proposal 005)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_GetStreamReadAvailable() (see proposal 005)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pa_GetStreamWriteAvaliable() (see proposal 005)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|basic PaHostApiInfo support (structVersion, type, name) (see proposal 007)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|deviceCount, defaultInputDevice, defaultOutputDevice fields of PaHostApiInfo (see proposal 007)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Host API Specific Pa_OpenStream() Parameters (see proposal 008) - platform specific extension, not required||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|All predictable host API errors cleanly recovered from and mapped to PortAudio error codes (see proposal 009)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|All unexpected host API errors mapped to paUnanticipatedHostError using PaUtil_SetLastHostErrorInfo() (see proposal 009)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|implement IsStopped() correctly (see proposal 010 and pa_stream.h)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|implement IsActive() correctly (see proposal 010 and pa_stream.h)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|correctly handle paContinue result from callback (see proposal 010)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|correctly handle paComplete result from callback (play out all enqueued buffers) (see proposal 010)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|correctly handle paAbort result from callback (abort enqued buffers if possible) (see proposal 010)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|correctly implement Pa_StopStrem() to play out all enqueued buffers||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|implement Pa_AbortStream() to abort enqueued buffers where possible, and stop as quickly as possible||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|implement Pa_GetStreamTime() (see proposal 015) enhancement proposal says stream time increases while stream is open, not just while running, not sure if alsa implementation observes this.||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|pass correctly filled timeInfo field to the buffer adaptor (pa_process) (see proposal 015)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|place actual sample rate in the sampleRate field of PaStreamInfo (see proposal 017)
not clear whether this field should be updated as the stream runs, or whether this should be the sample rate reported by the host API, and we need another field for detected/estimated sample rate.
|call the stream finished callback (stream->streamRepresentation.streamFinishedCallback) at the appropriate times (see proposal 019)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Prime buffers during Pa_StartStream if the paPrimeOutputBuffersUsingStreamCallback flag is set, zero them if it isn't set (see proposal 020)
implementations which use the non-integer block adaption features of pa_process (asio and ?) are blocked waiting for pa_process to support priming with complex buffer adaption
|Pass paPrimingOutput to stream callback when priming the buffers in response to paPrimeOutputBuffersUsingStreamCallback (see proposal 020)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|Pass paInputUnderflow to stream callback when priming a full duplex stream's buffers in response to paPrimeOutputBuffersUsingStreamCallback (see proposal 020)||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
If there is a specific feature which has been implemented, but is not listed above, please report it so it can be added to the list.
The above status report needs to be taken in the context of the V18 release, the features it implemented (and didn't implement), and the quality and consistency of its implementations. For example many features listed above were not part of the V18 API, some were not consistently implemented accross all platforms, and some of the bug-like items were also present in V18. So the overall conclusion is that V19 is in pretty good shape. The V19 API is functional on all platforms, in many cases to a level that matches or surpasses V18.
The following table indicates the status of running each test in /pa_tests with each Host API. Red means a test fails, green means the test passes and yellow means the test result is unknown (perhaps you'd like to run the test and report the result for us).
Note that these tests don't yet cover every feature of the V19 API. The tests from the V18-patch branch have been ported to the V19 API and are included in the list below, which should give some indication of the degree to which V19-devel currently implements the V18 feature set.
|Tests adapted from V18-patch|
|paqa_devs.c||Self Testing Quality Assurance app for PortAudio Try to open each device and run through all the possible configurations||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|paqa_errs.c||Self Testing Quality Assurance app for PortAudio Do lots of bad things to test error reporting||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest1.c||Ring modulate the audio input with a sine wave for 20 seconds||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_buffer.c||Test opening streams with different buffer sizes||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_clip.c||Play a sine wave for several seconds at an amplitude that would require clipping||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_dither.c||Attempt to hear difference between dithered and non-dithered signal||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_hang.c||Play a sine then hang audio callback to test watchdog||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_latency.c||Hear the latency caused by big buffers. Play a sine wave and change frequency based on letter input||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_leftright.c||Play different tone sine waves that alternate between left and right channel||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_longsine.c||Play a sine wave until ENTER hit||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_many.c||Start and stop the PortAudio Driver multiple times||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_maxsines.c||How many sine waves can we calculate and play in less than 80% CPU Load||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_mono.c||not yet ported to V19 api||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_multi_sine.c||Play a different sine wave on each channel||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_pink.c||Generate Pink Noise using Gardner method||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_record.c||Record input into an array; Save array to a file; Playback recorded data||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_ringmix.c||Ring modulate inputs to left output, mix inputs to right output||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_saw.c||Play a simple (aliasing) sawtooth wave||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_sine.c||Play a sine wave for several seconds||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_sine8.c||Test 8 bit data: play a sine wave for several seconds [some 8 bit formats not yet supported in pa_converters.c]||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_sine_formats.c||Play a sine wave for several seconds. Test various data formats [some 8 bit formats not yet supported in pa_converters.c]||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_sine_time.c||Play a sine wave for several seconds, pausing in the middle. Uses the Pa_GetStreamTime() call||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_stop.c||Test different ways of stopping audio||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_sync.c||Test time stamping and synchronization of audio and video||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_toomanysines.c||Play more sine waves than we can handle in real time as a stress test||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_two_rates.c||not yet ported to V19 api||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_underflow.c||Simulate an output buffer underflow condition. Tests whether the stream can be stopped when underflowing buffers||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_wire.c||Pass input directly to output||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|New tests for V19|
|patest_callbackstop.c||Test the paComplete callback result code||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_prime.c||Test stream priming mode||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_read_record.c||Record input into an array; Save array to a file; Playback recorded data. Implemented using the blocking API (Pa_ReadStream(), Pa_WriteStream() )||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_start_stop.c||Play a sine wave for several seconds start and stop the stream multiple times||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_stop_playout.c||Test whether all queued samples are played when Pa_StopStream() is used with a callback or read/write stream, or when the callback returns paComplete.||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_write_sine.c||Play a sine wave for several seconds using the blocking API (Pa_WriteStream())||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_in_overflow.c||Count input overflows (using paInputOverflow flag) under overloaded and normal conditions||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
|patest_out_underflow.c||Count output underflows (using paOutputUnderflow flag) under overloaded and normal conditions||wmme||ds||asio||alsa||jack||oss||mac_sm||mac_core||sgi|
It remains to be decided whether every item above must be marked complete before V19 is released. However there will need to be more than one platform totally complete before we can consider releasing anything. For the time being, the focus is on completing the uncompleted tasks listed on this page.
There are many ways in which you can help with V19 development. To begin with, simply try using it - the more people that use PortAudio V19, the more quickly we can find and fix problems. Read the documentation and let us know if anything is confusing or unclear. Try compiling and running the tests which are known to work (see pa_tests/README.txt). Let us know about any problems you encounter. If you want to help out with development there are a number of simple tasks that you can work on, for example: write one of the missing sample converters in pa_converters.c, fix an existing test (see pa_tests/README.txt), or write a new test. If you know something about one of the host APIs that we already support, review our code to see if we could be doing something better. There's also the todo list. We're looking for developers to help port the Macintosh and SGI versions from V18 to V19 - there's a template for new implementations in pa_skeleton.c and you can look to the existing MME, DirectSound, ASIO, ALSA and JACK implementations for guidance. It's always a good idea to in check with existing developers on the mailing list before beginning a large task.