Proposed Enhancements to PortAudio

PortAudio Home Page

Updated: April 26, 2004


This document links to a series of proposals currently being considered by the PortAudio developer community. Most of the proposals propose changes to the definition of the PortAudio API or to the way that PortAudio behaves in specific circumstances, some proposals (such as the style guide) are concerned with the way in which PortAudio is implemented.

The proposals are intended to capture the current state of discussions - when finalised they will be treated as specifications that will guide implementation. The authors are the various members of the PortAudio community and are too numerous to mention here. Please refer to the mailing list archives to see who said what.

Open Proposals

The following table lists the proposals currently under consideration. The majority of the listed proposals have undergone considerable peer review and are considerd complete. Most have been fully or partially implemented for at least one platform in the v19-devel CVS branch. Until version 19 is released there is a small possibility that the content of these proposals may change in response to implementation experience. If you think something is missing, could be improved, or would just like to comment please do so on the PortAudio mailing list.

Proposal Status
001 - Pass Underflow/Overflow Information to the Stream Callback complete
002 - Improve Device Formats Query Interface complete
003 - Improve Latency Specification Interface complete
004 - Allow Callbacks to Accept Variable Number of Frames per Buffer complete
005 - Blocking Read/Write Interface complete
006 - Non-Interleaved Buffers complete
007 - Support for Multiple Host APIs in a Single PortAudio Build complete
008 - Host API Specific Pa_OpenStream() Parameters complete
009 - Handling of Host API Specific Error Codes complete
010 - Clarify Stream State Machine and State Querying Functions complete
011 - Rename Existing Symbols such as Pa_GetCPULoad(), PaDeviceID etc. for Consistency complete
012 - Additional Pa_Terminate() Behavior complete
013 - Refactor Implementation Infrastructure complete but could always expand
014 - Implementation Style Guidelines stable but open for discussion - used in v19-devel
015 - Improve Callback Timestamp Info complete
016 - Use Structs for Pa_OpenStream() Parameters complete
017 - Method for Retrieving Actual Stream Sample Rate complete
018 - Version Information Interface complete
019 - Notify Client When All Buffers Have Played complete
020 - Allow Callback to Prime Stream complete
021 - New Directory Structure under discussion
022 - Well Defined Sample Conversion Semantics under discussion

Potential enhancements which have not yet been developed into proposals are listed here.

Status Summary

Due to the interdependency of many of the proposed enhancements, we plan to introduce all currently proposed API enhancements simultaneously as part of release 19. The CVS repository currently contains a branch named portaudio-v19-devel where enhancements are being implemented.

All listed proposals have been reviewed and discussed by the PortAudio developer comunity. All proposals pertaining to API changes are defined in sufficient detail to be implemented. Both the 014 - Implementation Style Guidelines and 013 - Refactor Implementation Infrastructure proposals only effect implementors and do not effect the API definition itself. Refinement of these proposals is desirable but not critical to the development of release 19.

Development status is documented on the development status page.

Client Impact

Some of the proposed changes will break existing client code. Usually these breakages involve renaming of constant identifiers or function calls. In a small number of cases additional parameters will be added to existing API functions. Concerned readers are advised to consult the Impact Analysis section of each proposal for further details.