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.

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.

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.