017 - Method for Retrieving Actual Stream Sample Rate

Enhancement Proposals Index, PortAudio Home Page

Updated: December 3, 2002

Status

This proposal is sufficiently well defined to be implemented. It is implemented in the v19-devel branch.

Background

In some environments, the hardware sample rate may only approximate the well-known rate (such as 44.1khz) at which it is supposed to operate. Implementations of Pa_OpenStream() and Pa_OpenDeafaultStream() may choose to open the stream with such a sample rate, even if it does not exactly match the user's request. If this occurs, there is currently (V18) no way for the client to discover the actual sample rate at which the stream operates, even if this information is provided by the host API.

Proposal

Provide a method to to retrieve the actual sample rate of the stream. This will be achieved by adding a sample rate field to the new PaStreamInfo structure defined in 003 - Improve Latency Specification Interface

/** A structure containing unchanging information about an open stream.
 @see Pa_GetStreamInfo
*/

typedef struct PaStreamInfo{
	...

    /** The sample rate of the stream in Hertz (samples per second). In cases
     where the hardware sample rate is inaccurate and PortAudio is aware of it,
     the value of this field may be different from the sampleRate parameter
     passed to Pa_OpenStream(). If information about the actual hardware sample
     rate is not available, this field will have the same value as the sampleRate
     parameter passed to Pa_OpenStream().
    */
    double sampleRate;

	...
} PaStreamInfo;

Discussion

Initially the following function was proposed, however it was decided that it was better to place actual latency and sample rate information in a common structure to simplify the API for casual users.

/** Retrieve the actual sample rate of a stream. In cases where the hardware 
 sample rate is inaccurate and PortAudio is aware of it, the return value 
 may be different from the sample rate passed to Pa_OpenStream(). 
 If information about the actual hardware sample rate is not available, 
 the sample rate passed to Pa_OpenStream() will be returned.

 @param stream A pointer to a valid PortAudio stream.

 @return The actual sampling rate of the stream, or zero (0) if an error 
 occured.
*/
double Pa_GetStreamSamplingRate( PaStream *stream );

Impact Analysis

This proposal makes additional information about a stream available to clients and does not effect existing client code.