PortAudio V19 Development Status

PortAudio Home Page

Updated: February 6, 2011

UPDATE: this document is out of date.

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.

Background

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.

Implementation Status

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 (rossb@audiomulch.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.

Public API

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.

Host API Feature Implementation

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.

Feature wmme ds asio alsa jack oss mac_sm mac_core sgi
Consistent handling of underflow and overflow conditions (see proposal 001). This includes passing information about dropped buffers to the buffer adaptor.
wmme ds asio alsa jack oss mac_sm mac_core sgi
Correctly handling the paNeverDropInput OpenStream() flag. (see proposal 001)
wmme ds asio alsa jack oss mac_sm mac_core sgi
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.
wmme ds asio alsa jack oss mac_sm mac_core sgi
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
wmme ds asio alsa jack oss mac_sm mac_core sgi
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.

Tests

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.

File Name Description wmme ds asio alsa jack oss mac_sm mac_core sgi
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

Where to From Here?

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.

How Can I Help?

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.