PortAudio詳解（2015年12月1日更新）

PortAudio詳解

整理者：赤子玄心

QQ：280604597

Email：280604597@qq.com

你們有什麼不明白的地方，或者想要詳細瞭解的地方能夠聯繫我，我會認真回覆的

1   簡介

PortAudio是一個免費、跨平臺、開源的音頻I/O庫。看到I/O可能就想到了文件，可是PortAudio操做的I/O不是文件，而是音頻設備。它可以簡化C/C++的音頻程序的設計實現，可以運行在Windows、Macintosh OS X和UNIX之上（Linux的各類版本也不在話下）。使用PortAudio能夠在不一樣的平臺上遷移應用程序，好比你能夠把你基於PortAudio的應用程序發展一個Android版本啊。

PortAudio的API很是簡單，經過一個一個簡單的回調函數或者阻塞的讀/寫接口來錄製或者播放聲音。PortAudio自帶了不少示例程序，好比播放正弦波形的音頻信號，處理音頻輸入，錄製回放音頻，列舉音頻設備。

 

PortAudio使用的是本身定義的License，關鍵點在於：

一、容許在你的項目或程序中無償使用PortAudio，商業軟件也是無償使用的。

二、能夠不開源你的源碼。

三、禁止刪除PortAudio中的版權信息。

四、若是你修復了PortAudio中的bug，請通知社區。

五、若是你的程序由於PortAudio而崩潰，咱們不負任何責任。

 

PortAudio的最新版本是V19。本文討論的就是該版本。

2   PortAudio V19庫編譯

2.1 準備

PortAudio官網：

http://www.portaudio.com/

 

PortAudio庫API英文詳解：

http://www.portaudio.com/docs/v19-doxydocs/portaudio_8h.html#a443ad16338191af364e3be988014cbbe

 

DirectX SDK下載：

http://www.microsoft.com/en-us/download/details.aspx?id=6812

 

PortAudio下載：

http://portaudio.com/docs/v19-doxydocs/compile_windows.html

 

ASIO SDK下載：

http://download.csdn.net/detail/linyiqinggood/6778175

 

PortAudio是採集和播放音頻的開源庫，能夠用於Linux和windows，在windows下依賴DirectX庫（Directshow）用於驅動聲卡，因此必須安裝DirectX sdk庫。

安裝DirectX sdk庫參考：

http://blog.sina.com.cn/s/blog_b5c2c06f01016cu5.html

portaudioV19的安裝集合包下載地址：

http://download.csdn.net/detail/yanmy2012/4655561

2.2 編譯方式

Windows編譯參考http://portaudio.com/docs/v19-doxydocs/compile_windows.html

其餘的編譯方式http://portaudio.com/docs/v19-doxydocs/pages.html

 

因爲V19 相對於V18改了很是多的地方，因此只編譯V19的庫，例程只有較新的才能在V19中編譯經過，有些會顯示找不到類型和函數申明。

2.3 編譯過程

下面列出的步驟來創建PortAudio成一個dll和lib文件。獲得的DLL文件可能包含全部五個目前的win32 PortAudio的API：MME，DirectSound的，WASAPI，WDM / KS和ASIO，根據下面的步驟9中設置的預處理器定義。PortAudio能夠被編譯使用Visual C + + Express版是由微軟免費提供。若是你有一個C + +開發環境，只需下載並安裝。這些指令已經成功觀察到使用Visual Studio 2010和。

1)   PortAudio爲Windows須要的文件dsound.h的和dsconf.h。下載並安裝DirectX SDK 得到這些文件。若是你安裝了DirectX SDK！的DirectSound的庫和頭文件的自動加到 Visual C + +中。

若是你獲得一個錯誤說缺乏dsound.h，或dsconf.h的，你能夠添加這些路徑。或者，您能夠複製dsound.h和dsconf.h，到portaudio\。還應該有一個名爲「dsound.lib」C:\Program Files\Microsoft SDKs\Windows\v6.0A\Lib文件。

2)   支持ASIO，下載ASIO SDK在http://www.steinberg.net/en/company/developer.html。 SDK是免費的，但您將須要與斯坦伯格創建一個開發者賬號,因此我提供了下載文件，這個也是從網上收回來的。複製整個ASIOSDK2的到src文件夾\hostapi\ASIO\。重命名它，從ASIOSDK2到ASIOSDK。

3)   若是您的Visual Studio 6.0，7.0（VC.NET/2001）或7.1（VC.2003），打開portaudio.dsp並轉換若是須要的話。

4)   若是你有Visual Studio 2005中的Visual C + + 2008 Express Edition或Visual Studio 2010中，雙擊portaudio.sln的文件位於在build \ MSVC \。這樣作將打開Visual Studio或Visual C + +。點擊「Finish」若是出現一個嚮導。sln文件中包含四種配置：Win32和Win64的發佈和調試的變種。

對於Visual Studio 2005中的Visual C + + 2008 Express版或Visual Studio 2010中

5)   打開項目 - > portaudio「屬性」，在樹視圖中選擇「配置屬性」。

6)   選擇「配置」中的「配置」組合框。選擇「全部平臺」

7)   設置幾個選項：

C/C＋＋—〉優化—〉省略框架指針= YES

C/C＋＋—〉代碼生成—〉運行時庫/MT

可選：C/C＋＋—〉代碼生成—〉浮點模型=快速

注：對於大多數用戶來講，它是沒有必要顯式地設置結構成員對齊，默認狀況下應該正常工做。然而，一些語言要求，例如，4字節對齊。若是您有portaudio.h結構的成員沒有被正確讀取或寫入的問題，可能有必要顯式地設置這個值由C/C＋＋—〉代碼生成—〉結構成員對齊，將其設置爲一個適當的值（四是共同的價值）。若是你的編譯器是可配置的，你應該確保它被設置爲使用相同的結構成員對齊值所使用的PortAudio構建。

當你設置完這些參數後點擊「肯定」。

預處理器定義

因爲預處理器定義是不一樣的，每一個配置和平臺，你須要編輯這些單獨爲每一個配置/平臺組合，你想修改的「配置」和「平臺」組合框。

8)   爲了抑制的PortAudio運行調試控制檯輸出項目—〉屬性—〉配置屬性—〉C/C＋＋—〉預處理器。在該領域的預處理器定義，找到PA_ENABLE_DEBUG_OUTPUT並刪除它。控制檯將不輸出調試信息。

9)   你須要明確地定義你想使用的音頻API的預處理器定義。對於Windows提供的API定義是：

PA_USE_ASIO

PA_USE_DS（DirectSound的）

PA_USE_WMME（MME）

PA_USE_WASAPI

PA_USE_WDMKS

PA_USE_SKELETON

對於每一個這樣的，值爲0表示不該列入這個API的支持。值1表示應該包括這個API的支持。

設置預處理器定義時，build是配置每一個平臺的過程。按照這些說明build你感興趣的每個配置/平臺組合。

以上宏在「項目—〉屬性—〉配置屬性—〉C/C＋＋—〉預處理器—〉預處理器定義」中定義的。

10)  從「生成」菜單上單擊「生成」 - >「生成解決方案」。對於32位編譯的dll文件建立的這個過程（portaudio_x86.dll）中能夠找到的目錄生成\ MSVC \ WIN32 \發佈。64位編譯的DLL文件被稱爲portaudio_x64.dll，被髮如今目錄中生成\ MSVC \ X64 \發佈。

11)  如今，任何項目須要portaudio能夠與portaudio_x86.lib（或_x64），包括您可能要添加/刪除一些DLL 相關的頭（portaudio.h，和/或pa_asio.h，pa_x86_plain_converters.h），入口點。如今，這6個項目是否是從portaudio.h：

最後會生成portaudio_x86.lib和portaudio_x86.dll，各兩個分別是Debug和Release的，不一樣配置下使用不一樣dll和lib。

安裝完以後就是測試，源代碼文件夾test文件夾下有測試代碼，因爲V19 相對於V18改了很是多的地方，因此只編譯V19的庫，例程只有較新的才能在V19中編譯經過，有些會顯示找不到類型和函數申明。

patest_record.c代碼，運行過程當中會有5秒的嘟嘟聲（由的算法產生的float點型級別的聲波），這樣就證實了已經安裝成功。

#include "portaudio.h"

#define SAMPLE_RATE (44100)

#define FRAMES_PER_BUFFER (1024)

#define NUM_SECONDS (5)

#define NUM_CHANNELS (2)

#define DITHER_FLAG (0)

#if 1

#define PA_SAMPLE_TYPE paFloat32

typedef float SAMPLE;

#define SAMPLE_SILENCE (0.0f)

#define PRINTF_S_FORMAT "%.8f"

#elif 1

#define PA_SAMPLE_TYPE paInt16

typedef short SAMPLE;

#define SAMPLE_SILENCE (0)

#define PRINTF_S_FORMAT "%d"

#elif 0

#define PA_SAMPLE_TYPE paInt8

typedef char SAMPLE;

#define SAMPLE_SILENCE (0)

#define PRINTF_S_FORMAT "%d"

#else

#define PA_SAMPLE_TYPE paUInt8

typedef unsigned char SAMPLE;

#define SAMPLE_SILENCE (128)

#define PRINTF_S_FORMAT "%d"

#endif

typedef struct

{

int frameIndex;

int maxFrameIndex;

SAMPLE *recordedSamples;

}

paTestData;

static int recordCallback( const void *inputBuffer, void *outputBuffer,

unsigned long framesPerBuffer,

  const PaStreamCallbackTimeInfo* timeInfo,

PaStreamCallbackFlags statusFlags,

void *userData )

{

paTestData *data = (paTestData*)userData;

const SAMPLE *rptr = (const SAMPLE*)inputBuffer;

SAMPLE *wptr = &data->recordedSamples[data->frameIndex * NUM_CHANNELS];

long framesToCalc;

long i;

int finished;

unsigned long framesLeft = data->maxFrameIndex - data->frameIndex;

(void) outputBuffer;

(void) timeInfo;

(void) statusFlags;

(void) userData;

if( framesLeft < framesPerBuffer )

{

framesToCalc = framesLeft;

finished = paComplete;

}

else

{

framesToCalc = framesPerBuffer;

finished = paContinue;

}

if( inputBuffer == NULL )

{

for( i=0; i

{

*wptr++ = SAMPLE_SILENCE;

if( NUM_CHANNELS == 2 ) *wptr++ = SAMPLE_SILENCE;

}

}

else

{

for( i=0; i

{

*wptr++ = *rptr++;

if( NUM_CHANNELS == 2 ) *wptr++ = *rptr++;

}

}

data->frameIndex += framesToCalc;

return finished;

}

static int playCallback( const void *inputBuffer, void *outputBuffer,

unsigned long framesPerBuffer,

const PaStreamCallbackTimeInfo* timeInfo,

PaStreamCallbackFlags statusFlags,

void *userData )

{

paTestData *data = (paTestData*)userData;

SAMPLE *rptr = &data->recordedSamples[data->frameIndex * NUM_CHANNELS];

SAMPLE *wptr = (SAMPLE*)outputBuffer;

unsigned int i;

  int finished;

unsigned int framesLeft = data->maxFrameIndex - data->frameIndex;

(void) inputBuffer;

(void) timeInfo;

(void) statusFlags;

(void) userData;

if( framesLeft < framesPerBuffer )

{

for( i=0; i

{

*wptr++ = *rptr++;

if( NUM_CHANNELS == 2 ) *wptr++ = *rptr++;

}

for( ; i

{

*wptr++ = 0;

if( NUM_CHANNELS == 2 ) *wptr++ = 0;

}

data->frameIndex += framesLeft;

finished = paComplete;

}

else

{

for( i=0; i

{

  *wptr++ = *rptr++;

if( NUM_CHANNELS == 2 ) *wptr++ = *rptr++;

}

data->frameIndex += framesPerBuffer;

finished = paContinue;

}

return finished;

}

int main(void);

int main(void)

{

PaStreamParameters inputParameters,

outputParameters;

PaStream* stream;

PaError err = paNoError;

paTestData data;

int i;

int totalFrames;

int numSamples;

int numBytes;

SAMPLE max, val;

double average;

printf("patest_record.c\n"); fflush(stdout);

data.maxFrameIndex = totalFrames = NUM_SECONDS * SAMPLE_RATE;

data.frameIndex = 0;

numSamples = totalFrames * NUM_CHANNELS;

numBytes = numSamples * sizeof(SAMPLE);

data.recordedSamples = (SAMPLE *) malloc( numBytes );

if( data.recordedSamples == NULL )

{

printf("Could not allocate record array.\n");

goto done;

}

for( i=0; i

err = Pa_Initialize();

if( err != paNoError ) goto done;

inputParameters.device = Pa_GetDefaultInputDevice();

inputParameters.channelCount = 2;  

inputParameters.sampleFormat = PA_SAMPLE_TYPE;

inputParameters.suggestedLatency = Pa_GetDeviceInfo( inputParameters.device )->defaultLowInputLatency;

inputParameters.hostApiSpecificStreamInfo = NULL;

err = Pa_OpenStream(

&stream,

&inputParameters,

NULL,

SAMPLE_RATE,

FRAMES_PER_BUFFER,

paClipOff,

recordCallback,

&data );

if( err != paNoError ) goto done;

err = Pa_StartStream( stream );

if( err != paNoError ) goto done;

printf("Now recording!!\n"); fflush(stdout);

while( ( err = Pa_IsStreamActive( stream ) ) == 1 )

{

Pa_Sleep(1000);

printf("index = %d\n", data.frameIndex ); fflush(stdout);

}

if( err < 0 ) goto done;

err = Pa_CloseStream( stream );

if( err != paNoError ) goto done;

max = 0;

average = 0.0;

for( i=0; i

{

val = data.recordedSamples[i];

if( val < 0 ) val = -val;

if( val > max )

{

max = val;

}

average += val;

}

average = average / (double)numSamples;

printf("sample max amplitude = "PRINTF_S_FORMAT"\n", max );

printf("sample average = %lf\n", average );

#if 0

{

FILE *fid;

fid = fopen("recorded.raw", "wb");

if( fid == NULL )

{

printf("Could not open file.");

}

else

{

fwrite( data.recordedSamples, NUM_CHANNELS * sizeof(SAMPLE), totalFrames, fid );

fclose( fid );

printf("Wrote data to 'recorded.raw'\n");

}

}

#endif

data.frameIndex = 0;

outputParameters.device = Pa_GetDefaultOutputDevice();

outputParameters.channelCount = 2;

outputParameters.sampleFormat = PA_SAMPLE_TYPE;

outputParameters.suggestedLatency = Pa_GetDeviceInfo( outputParameters.device )->defaultLowOutputLatency;

outputParameters.hostApiSpecificStreamInfo = NULL;

printf("Begin playback.\n"); fflush(stdout);

err = Pa_OpenStream(

&stream,

NULL,

&outputParameters,

SAMPLE_RATE,

FRAMES_PER_BUFFER,

paClipOff,

playCallback,

&data );

if( err != paNoError ) goto done;

if( stream )

{

err = Pa_StartStream( stream );

if( err != paNoError ) goto done;

printf("Waiting for playback to finish.\n"); fflush(stdout);

while( ( err = Pa_IsStreamActive( stream ) ) == 1 ) Pa_Sleep(100);

if( err < 0 ) goto done;

err = Pa_CloseStream( stream );

if( err != paNoError ) goto done;

printf("Done.\n"); fflush(stdout);

}

done:

Pa_Terminate();

if( data.recordedSamples )

free( data.recordedSamples );

if( err != paNoError )

{

fprintf( stderr, "An error occured while using the portaudio stream\n" );

fprintf( stderr, "Error number: %d\n", err );

fprintf( stderr, "Error message: %s\n", Pa_GetErrorText( err ) );

err = 1;

}

return err;

}

 

 

3   函數庫

3.1 函數模板(未完成)

函數名稱	xxx
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	函數主要功能說明。
函數聲明	類型 函數名 ( 類型 參數1, 類型 參數2, …… );
函數參數	參數1，[輸入|輸出|輸入&輸出]： 參數說明。
	參數2，[輸入|輸出|輸入&輸出]： 參數說明。
	……
返回值	返回值1：返回值說明。 返回值2：返回值說明。 ……
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

3.2 Pa_Initialize(未完成)

函數名稱	Pa_Initialize
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	初始化PortAudio庫。
函數聲明	PaError Pa_Initialize ( void );
函數參數	無
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	使用PortAudio函數庫以前必須調用本函數初始化。 本函數初始化的內部數據結構，並準備底層主機的API使用。除了Pa_GetVersion()，Pa_GetVersionText()，和Pa_GetErrorText()時，該功能必須使用任何其餘PortAudio API函數以前調用。 若是本函數被調用屢次，每一次成功的調用必須有相應調用Pa_Terminate()函數相匹配。調用Pa_Initialize的對（）/ Pa_Terminate（）可能會重疊，而且不要求徹底嵌套。 若是本函數返回失敗，不須要調用Pa_Terminate()函數來銷燬。

 

 

3.3 Pa_Terminate(未完成)

函數名稱	Pa_Terminate
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	銷燬已經初始化的PortAudio庫。
函數聲明	PaError Pa_Terminate ( void );
函數參數	無
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	paNotInitialized枚舉(-10000)：沒有初始化PortAudio庫。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	本函數會銷燬由PortAudio庫分配的全部資源。 本函數必須在程序退出以前被調用，不然可能會致使嚴重的資源泄漏，如錄音設備或播放設備不可用，除非從新啓動操做系統。

 

 

3.4 Pa_GetErrorText(未完成)

函數名稱	Pa_GetErrorText
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	根據指定的錯誤碼獲取對應的錯誤信息字符串。
函數聲明	const char * Pa_GetErrorText ( PaError errorCode );
函數參數	errorCode，[輸入]： 存放錯誤碼的值。
返回值	錯誤信息字符串的內存指針。
錯誤碼	無
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	若是指定的錯誤碼是不存在的，返回的錯誤信息字符串爲"Invalid error code (value greater than zero)"。

 

 

3.5 Pa_GetVersion(未完成)

函數名稱	Pa_GetVersion
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	以整數方式獲取當前程序正在使用的PortAudio庫的版本號，例如：1900。
函數聲明	int Pa_GetVersion ( void );
函數參數	無
返回值	PortAudio庫的版本號的整數。
錯誤碼	無
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明

 

 

3.6 Pa_GetVersionText(未完成)

函數名稱	Pa_GetVersionText
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	以信息字符串方式獲取當前程序正在使用的PortAudio庫的版本號，例如："PortAudio V19-devel 13 October 2002"。
函數聲明	int Pa_GetVersionText ( void );
函數參數	無
返回值	PortAudio庫的版本號的信息字符串的內存指針。
錯誤碼	無
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	獲取到信息字符串所佔用的內存由Pa_Terminate()函數自動釋放，不須要手動釋放，不然會出現未知錯誤。

 

 

3.7 Pa_GetDeviceCount(未完成)

函數名稱	Pa_GetDeviceCount
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	獲取可用的音頻設備的數量。
函數聲明	PaDeviceIndex Pa_GetDeviceCount ( void );
函數參數	無
返回值	大於等於0：成功，可用的音頻設備的數量。 小於0：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明

 

 

3.8 Pa_GetDeviceInfo(未完成)

函數名稱	Pa_GetDeviceInfo
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	根據音頻設備的索引號獲取音頻設備的相關信息。
函數聲明	const PaDeviceInfo * Pa_GetDeviceInfo ( PaDeviceIndex device );
函數參數	device，[輸入]： 存放音頻設備的索引號。 音頻設備的索引號範圍從0開始，到Pa_GetDeviceCount()函數返回的音頻設備的數量減一。
返回值	NULL：失敗，音頻設備的索引號超出範圍。 其餘：音頻設備信息結構體的內存指針。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	獲取到音頻設備信息結構體所佔用的內存由Pa_Terminate()函數自動釋放，不須要手動釋放，不然會出現未知錯誤。 若是不知道該用哪一個音頻輸入設備，能夠調用Pa_GetDefaultInputDevice()函數獲取默認的音頻輸入設備。 若是不知道該用哪一個音頻輸出設備，能夠調用Pa_GetDefaultOutputDevice()函數獲取默認的音頻輸出設備。

 

 

3.9 Pa_GetDefaultInputDevice(未完成)

函數名稱	Pa_GetDefaultInputDevice
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	獲取操做系統中默認的音頻輸入設備。
函數聲明	PaDeviceIndex Pa_GetDefaultInputDevice ( void );
函數參數	無
返回值	paNoDevice宏(-1)：沒有音頻輸入設備。 大於等於0：音頻輸入設備的索引號。
錯誤碼	無
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明

 

 

3.10  Pa_GetDefaultOutputDevice(未完成)

函數名稱	Pa_GetDefaultOutputDevice
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	獲取操做系統中默認的音頻輸入設備。
函數聲明	PaDeviceIndex Pa_GetDefaultOutputDevice ( void );
函數參數	無
返回值	paNoDevice宏(-1)：沒有音頻輸出設備。 大於等於0：音頻輸出設備的索引號。
錯誤碼	無
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明

 

 

3.11  Pa_OpenStream(未完成)

函數名稱	Pa_OpenStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	使用指定的音頻輸入輸出設備打開一個音頻流句柄，用於 音頻輸入 或 音頻輸出 或 音頻輸入輸出。
函數聲明	PaError Pa_OpenStream ( PaStream ** stream, const PaStreamParameters * inputParameters, const PaStreamParameters * outputParameters, double sampleRate, unsigned long framesPerBuffer, PaStreamFlags streamFlags, PaStreamCallback * streamCallback, void * userData );
函數參數	stream，[輸出]： 存放用於存放音頻流句柄的指針變量的內存指針。 存放音頻流句柄的變量類型爲PaStream *。
	inputParameters，[輸入]： 。
	outputParameters，[輸入|輸出|輸入&輸出]： 參數說明。
	sampleRate，[輸入|輸出|輸入&輸出]： 參數說明。
	framesPerBuffer，[輸入|輸出|輸入&輸出]： 參數說明。
	streamFlags，[輸入|輸出|輸入&輸出]： 參數說明。
	streamCallback，[輸入|輸出|輸入&輸出]： 參數說明。
	userData，[輸入|輸出|輸入&輸出]： 參數說明。
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

3.12  Pa_OpenDefaultStream(未完成)

函數名稱	Pa_OpenDefaultStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	使用操做系統默認的音頻輸入輸出設備打開一個音頻流句柄，用於 音頻輸入 或 音頻輸出 或 音頻輸入輸出。
函數聲明	PaError Pa_OpenDefaultStream ( PaStream ** stream, int numInputChannels, int numOutputChannels, PaSampleFormat sampleFormat, double sampleRate, unsigned long framesPerBuffer, PaStreamCallback * streamCallback, void * userData );
函數參數	stream，[輸入]： 存放用於存放音頻流句柄的指針變量的內存指針。 存放音頻流句柄的變量類型爲PaStream *。
	numInputChannels，[輸入]： 存放音頻流的音頻輸入聲道個數，爲0表示不須要音頻輸入，爲1表示單聲道，爲2表示雙聲道立體聲。
	numOutputChannels，[輸入]： 存放音頻流的音頻輸出聲道個數，爲0表示不須要音頻輸出，爲1表示單聲道，爲2表示雙聲道立體聲。
	sampleFormat，[輸入]： 存放音頻流的採樣位數和採樣格式。能夠爲（選一至一個）： paFloat32宏(0x0001)：用一個32位有符號浮點型存儲每一個音頻數據塊。音頻數據範圍最高爲1.0，最低爲-1.0。 paInt32宏(0x0002)：用一個32位有符號整型存儲每一個音頻數據塊。音頻數據範圍最高爲2147483647，最低爲-2147483648。 paInt24宏(0x0004)：用一個24位有符號整型存儲每一個音頻數據塊。音頻數據範圍最高爲8388607，最低爲-8388608。 paInt16宏(0x0008)：用一個16位有符號整型存儲每一個音頻數據塊。音頻數據範圍最高爲32767，最低爲-32768。 paInt8宏(0x0010)：用一個8位有符號整型存儲每一個音頻數據塊。音頻數據範圍最高爲127，最低爲-128。 paUInt8宏(0x0020)：用一個8位無符號整型存儲每一個音頻數據塊。音頻數據範圍最高爲255，最低爲0。 paCustomFormat宏(0x10000)： paNonInterleaved宏(0x80000000)：
	sampleRate，[輸入]： 存放音頻的採樣頻率，單位赫茲。通常能夠爲：8000、1102五、22050、44100。
	framesPerBuffer，[輸入]： 存放當每次處理完音頻數據時，在音頻數據輸入輸出緩存中存放的每一個聲道的音頻數據塊個數。 音頻數據輸入輸出緩存在音頻數據處理回調函數中使用，若是不採用回調函數方式，本參數無心義。
	streamCallback，[輸入]： 存放音頻數據處理回調函數的內存指針，表示採用回調函數方式進行音頻輸入數據採樣，或播放音頻數據。 音頻數據處理回調函數是程序本身定義的，且會一直在另一個獨立的新線程中自動被調用執行。參考PaStreamCallback。 若是不採用回調函數方式，本參數就填NULL。   回調函數調用條件： 若是要打開的音頻流只須要音頻輸入，那麼每次當音頻輸入數據採樣完畢，就會自動調用一次音頻數據處理回調函數。 若是要打開的音頻流只須要音頻輸出，那麼每次當音頻輸出數據播放完畢，就會自動調用一次音頻數據處理回調函數。 若是要打開的音頻流須要音頻輸入和音頻輸出，那麼每次當音頻輸入數據採樣完畢，就會自動調用一次音頻數據處理回調函數。由於採樣速度和播放速度是同樣的，因此就只調用一次音頻數據處理回調函數。
	userData，[輸入]： 存放音頻數據處理回調函數被調用時，傳遞給該函數的一個程序自定義參數。
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	打開音頻流句柄後，須要調用Pa_StartStream()函數，才能讓音頻流句柄開始處理音頻數據。 若是不採用回調函數方式，能夠調用Pa_ReadStream()函數或Pa_WriteStream()函數處理音頻數據。

 

 

3.13  Pa_CloseStream(未完成)

函數名稱	Pa_CloseStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	關閉一個已經打開的音頻流句柄。
函數聲明	PaError Pa_CloseStream ( PaStream * stream );
函數參數	stream，[輸入]： 存放音頻流句柄。
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

3.14  PaStreamCallback(未完成)

函數名稱	PaStreamCallback
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	音頻數據處理回調函數。
函數聲明	int PaStreamCallback ( const void * input, void * output, unsigned long frameCount, const PaStreamCallbackTimeInfo * timeInfo, PaStreamCallbackFlags statusFlags, void * userData )
函數參數	input，[輸入]： 存放音頻數據輸入緩存的內存指針，也就是音頻設備採樣到的音頻數據。 音頻數據輸入緩存的長度計算方法（單位字節）：聲道個數×每一個聲道的音頻數據塊個數×採樣位數÷8。
	output，[輸出]： 存放音頻數據輸出緩存的內存指針，也就是須要音頻設備播放的音頻數據。 音頻數據輸出緩存的長度計算方法（單位字節）：聲道個數×每一個聲道的音頻數據塊個數×採樣位數÷8
	frameCount，[輸入]： 存放音頻數據輸入輸出緩存中存放的每一個聲道的音頻數據塊個數。
	timeInfo，[輸入|輸出|輸入&輸出]： 參數說明。
	statusFlags，[輸入|輸出|輸入&輸出]： 參數說明。
	userData，[輸入&輸出]： 存放程序自定義參數。
返回值	返回值1：返回值說明。 返回值2：返回值說明。 ……
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	音頻數據輸入輸出緩存的內存格式：   第一個字節 第二個字節 第三個字節 第四個字節 …… 單聲道 8位採樣量化 採樣1 採樣2 採樣3 採樣4 …… 聲道0 聲道0 聲道0 聲道0 ……             雙聲道 8位採樣量化 採樣1 採樣2 …… 聲道0(左) 聲道1(右) 聲道0(左) 聲道1(右) ……             單聲道 16位採樣量化 採樣1 採樣2 …… 聲道0 (低位字節) 聲道0 (高位字節) 聲道0 (低位字節) 聲道0 (高位字節) ……             雙聲道 16位採樣量化 採樣1 …… 聲道0(左) (低位字節) 聲道0(右) (高位字節) 聲道1(左) (低位字節) 聲道1(右) (高位字節) …… 就是這樣的。

 

 

3.15  Pa_StartStream(未完成)

函數名稱	Pa_StartStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	讓一個已經打開的音頻流句柄開始處理音頻數據。
函數聲明	類型 函數名 ( 類型 參數1, 類型 參數2, …… );
函數參數	參數1，[輸入|輸出|輸入&輸出]： 參數說明。
	參數2，[輸入|輸出|輸入&輸出]： 參數說明。
	……
返回值	返回值1：返回值說明。 返回值2：返回值說明。 ……
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	中止處理音頻數據須要調用Pa_StopStream()函數。

 

 

3.16  Pa_StopStream(未完成)

函數名稱	Pa_StopStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	讓一個已經打開的音頻流句柄中止處理音頻數據。
函數聲明	類型 函數名 ( 類型 參數1, 類型 參數2, …… );
函數參數	參數1，[輸入|輸出|輸入&輸出]： 參數說明。
	參數2，[輸入|輸出|輸入&輸出]： 參數說明。
	……
返回值	返回值1：返回值說明。 返回值2：返回值說明。 ……
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

3.17  Pa_ReadStream(未完成)

函數名稱	Pa_ReadStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	從一個已經打開並開始處理音頻數據的音頻流句柄，阻塞採集指定長度的音頻數據。
函數聲明	PaError Pa_ReadStream ( PaStream * stream, void * buffer, unsigned long frames );
函數參數	stream，[輸入]： 存放音頻流句柄。
	buffer，[輸出]： 存放音頻數據輸入緩存的內存指針，也就是音頻設備採樣到的音頻數據。
	frames，[輸入]： 存放音頻數據輸入緩存中存放的每一個聲道的音頻數據塊個數。 音頻數據輸入緩存的長度計算方法（單位字節）：聲道個數×每一個聲道的音頻數據塊個數×採樣位數÷8。
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

3.18  Pa_WriteStream(未完成)

函數名稱	Pa_WriteStream
頭文件	#include "PortAudio.h"
庫文件	#pragma comment(lib, "PortAudio_x86.lib或PortAudio_x64.lib")
函數功能	從一個已經打開並開始處理音頻數據的音頻流句柄，阻塞播放指定長度的音頻數據。
函數聲明	PaError Pa_WriteStream ( PaStream * stream, const void * buffer, unsigned long frames );
函數參數	stream，[輸入]： 存放音頻流句柄。
	buffer，[輸入]： 存放音頻數據輸出緩存的內存指針，也就是音頻設備採樣到的音頻數據。
	frames，[輸入]： 存放音頻數據輸出緩存中存放的每一個聲道的音頻數據塊個數。 音頻數據輸出緩存的長度計算方法（單位字節）：聲道個數×每一個聲道的音頻數據塊個數×採樣位數÷8。
返回值	paNoError枚舉(0x0000)：成功。 其餘：失敗，返回值就是錯誤碼，調用Pa_GetErrorText()函數查看錯誤碼對應的錯誤信息。
錯誤碼	EXXXX：錯誤碼說明。 EXXXX：錯誤碼說明。 ……
線程安全	是 或 否 或 未知，表示此函數多線程調用是否會產生影響
原子操做	是 或 否 或 未知，表示此函數是不是單一操做，不是多個步驟的組合
其餘說明	…… ……

 

 

4   結構體庫

4.1 結構體模板(未完成)

結構體名稱	xxx
頭文件	#include "PortAudio.h"
結構體稱呼	結構體的中文稱呼。
結構體說明	結構體主要用途說明。
相關函數	Func1()、Func2()、Func3()…
結構體聲明	struct xxx { 類型  成員變量1; 類型  成員變量2; …… };
成員變量	成員變量1： 成員變量說明。
	成員變量2： 成員變量說明。
	……
其餘說明	…… ……

 

 

4.2 PaDeviceInfo(未完成)

結構體名稱	PaDeviceInfo
頭文件	#include <xxx.h> #include <xxx.h>
結構體說明	音頻設備信息結構體，用於存放音頻設備的相關信息。
相關函數	Pa_GetDeviceInfo()、Func2()、Func3()…
結構體聲明	typedef struct PaDeviceInfo { int structVersion; const char * name; PaHostApiIndex hostApi; /**< note this is a host API index, not a type id*/     int maxInputChannels; int maxOutputChannels;   /** Default latency values for interactive performance. */ PaTime defaultLowInputLatency; PaTime defaultLowOutputLatency; /** Default latency values for robust non-interactive applications (eg. playing sound files). */ PaTime defaultHighInputLatency; PaTime defaultHighOutputLatency;   double defaultSampleRate; } PaDeviceInfo;
成員變量	structVersion： 存放本結構體的版本號，一直爲2。
	name： 存放音頻設備的名稱字符串的內存指針，例如： "Microsoft 聲音映射器 - Input"， "Speakers (Realtek HD Audio output)"。
	hostApi： note this is a host API index, not a type id.
	maxInputChannels： 存放音頻設備的最大音頻輸入聲道個數，爲0表示本設備不支持音頻輸入。
	maxOutputChannels： 存放音頻設備的最大音頻輸出聲道個數，爲0表示本設備不支持音頻輸出。
	defaultLowInputLatency： Default latency values for interactive performance.
	defaultLowOutputLatency： 成員變量說明。
	defaultHighInputLatency： Default latency values for robust non-interactive applications (eg. playing sound files).
	defaultHighOutputLatency： 成員變量說明。
	defaultSampleRate： 存放音頻設備的默認採樣頻率，單位Hz赫茲。
其餘說明

 

 

4.3 PaStreamParameters(未完成)

結構體名稱	PaStreamParameters
頭文件	#include "PortAudio.h"
結構體說明	結構體主要用途說明。
相關函數	Pa_OpenStream()、Func2()、Func3()…
結構體聲明	typedef struct PaStreamParameters {     /** A valid device index in the range 0 to (Pa_GetDeviceCount()-1)      specifying the device to be used or the special constant      paUseHostApiSpecificDeviceSpecification which indicates that the actual      device(s) to use are specified in hostApiSpecificStreamInfo.      This field must not be set to paNoDevice.     */     PaDeviceIndex device;         /** The number of channels of sound to be delivered to the      stream callback or accessed by Pa_ReadStream() or Pa_WriteStream().      It can range from 1 to the value of maxInputChannels in the      PaDeviceInfo record for the device specified by the device parameter.     */     int channelCount;       /** The sample format of the buffer provided to the stream callback,      a_ReadStream() or Pa_WriteStream(). It may be any of the formats described      by the PaSampleFormat enumeration.     */     PaSampleFormat sampleFormat;       /** The desired latency in seconds. Where practical, implementations should      configure their latency based on these parameters, otherwise they may      choose the closest viable latency instead. Unless the suggested latency      is greater than the absolute upper limit for the device implementations      should round the suggestedLatency up to the next practical value - ie to      provide an equal or higher latency than suggestedLatency wherever possible.      Actual latency values for an open stream may be retrieved using the      inputLatency and outputLatency fields of the PaStreamInfo structure      returned by Pa_GetStreamInfo().      @see default*Latency in PaDeviceInfo, *Latency in PaStreamInfo     */     PaTime suggestedLatency;       /** An optional pointer to a host api specific data structure      containing additional information for device setup and/or stream processing.      hostApiSpecificStreamInfo is never required for correct operation,      if not used it should be set to NULL.     */     void *hostApiSpecificStreamInfo;   } PaStreamParameters;
成員變量	device： 成員變量說明。
	channelCount： 成員變量說明。
	sampleFormat： 成員變量說明。
	suggestedLatency： 成員變量說明。
	hostApiSpecificStreamInfo： 成員變量說明。
其餘說明	…… ……