Android中文API（122） —— AudioRecord

前言

　　本章內容是android.media.AudioRecord，版本爲Android 3.1 r1，翻譯來自"chenwei"，這位朋友在沒有加入翻譯組狀況下匿名投稿，這裏整理後代爲發佈！歡迎你們一塊兒參與Android API的翻譯，聯繫我over140@gmail.com。
 

 

聲明

　　歡迎轉載，但請保留文章原始出處:)
 

　　　農民伯伯：http://over140.blog.51cto.com/

　　　　Android中文翻譯組：http://goo.gl/6vJQl
 

 

結構

繼承關係

public class AudioRecord extends Object

 

　　java.lang.Object

android.media.AudioRecord

 

類概述

　　AudioRecord類在Java應用程序中管理音頻資源，用來記錄從平臺音頻輸入設備產生的數據。 經過AudioRecord對象來完成"pulling"（讀取）數據。 應用經過如下幾個方法負責當即從AudioRecord對象讀取： read(byte[], int, int)， read(short[], int, int)或read(ByteBuffer, int). 不管使用哪一種音頻格式，使用AudioRecord是最方便的。

　　在建立AudioRecord對象時，AudioRecord會初始化，並和音頻緩衝區鏈接，用來緩衝新的音頻數據。 根據構造時指定的緩衝區大小，來決定AudioRecord可以記錄多長的數據。 從硬件設備讀取的數據，應小於整個記錄緩衝區。

 

內部類

　　　　interface          AudioRecord.OnRecordPositionUpdateListener

　　接口定義爲：當AudioRecord 收到一個由setNotificationMarkerPosition(int)設置的通知標誌，或由 setPositionNotificationPeriod(int)設置的週期更新記錄的進度狀態時，回調此接口。

 

常量

　　　　public static final int ERROR

　　表示操做失敗。

                   常量值: -1 (0xffffffff)

 

　　public static final int ERROR_BAD_VALUE

　　表示使用了一個不合理的值致使的失敗。

      　　常量值: -2 (0xfffffffe)

 

　　public static final int ERROR_INVALID_OPERATION

　　表示不恰當的方法致使的失敗。

      　　常量值: -3 (0xfffffffd)

 

　　public static final int RECORDSTATE_RECORDING

　　指示AudioRecord錄製狀態爲「正在錄製」。

      　　常量值: 3 (0x00000003)

 

　　public static final int RECORDSTATE_STOPPED

　　指示AudioRecord錄製狀態爲「不在錄製」。

      　　常量值: 1 (0x00000001)

 

　　public static final int STATE_INITIALIZED

　　指示AudioRecord準備就緒。

      　　常量值: 1 (0x00000001)

 

　　public static final int STATE_UNINITIALIZED

　　指示AudioRecord狀態沒有初始化成功。

      　　常量值: 0 (0x00000000)

 

　　public static final int SUCCESS

　　表示操做成功。

      　　常量值: 0 (0x00000000)

 

構造函數

　　public AudioRecord (int audioSource, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes)

　　類構造函數。

         參數

                   audioSource     錄製源。 請見MediaRecorder.AudioSource錄製源定義。

sampleRateInHz      默認採樣率，單位Hz。 44100Hz是當前惟一能保證在全部設備上工做的採樣率，在一些設備上還有22050, 16000或11025。

channelConfig          描述音頻通道設置。 請見CHANNEL_IN_MONO 和 CHANNEL_IN_STEREO。 CHANNEL_IN_MONO保證能在全部設備上工做。

audioFormat             音頻數據保證支持此格式。 請見ENCODING_PCM_16BIT 和ENCODING_PCM_8BIT。

bufferSizeInBytes    在錄製過程當中，音頻數據寫入緩衝區的總數（字節）。 從緩衝區讀取的新音頻數據總會小於此值。 getMinBufferSize(int, int, int)返回AudioRecord 實例建立成功後的最小緩衝區。 設置的值比getMinBufferSize()還小則會致使初始化失敗。

                   異常

                            IllegalArgumentException

 

公共方法

　　　　public int getAudioFormat ()

　　　　返回設置的音頻數據格式。 請見ENCODING_PCM_16BIT 和ENCODING_PCM_8BIT。

 

　　　　public int getAudioSource ()

　　　　返回音頻錄製源。

　　　　　　參見

                            MediaRecorder.AudioSource

 

　　　　public int getChannelConfiguration ()

　　　　返回設置的頻道設置。 請見CHANNEL_IN_MONO和CHANNEL_IN_STEREO。

 

　　　　public int getChannelCount ()

　　　　返回設置的頻道數目。

 

　　　　public static int getMinBufferSize (int sampleRateInHz, int channelConfig, int audioFormat)

　　　　返回成功建立AudioRecord對象所須要的最小緩衝區大小。 注意：這個大小並不保證在負荷下的流暢錄製，應根據預期的頻率來選擇更高的值，AudioRecord實例在推送新數據時使用此值。

　　　　　　參數

                            sampleRateInHz      默認採樣率，單位Hz。

                            channelConfig           描述音頻通道設置。

請見CHANNEL_IN_MONO和CHANNEL_IN_STEREO。

                            audioFormat             音頻數據保證支持此格式。參見ENCODING_PCM_16BIT。

　　　　　　返回值

　　若是硬件不支持錄製參數，或輸入了一個無效的參數，則返回ERROR_BAD_VALUE，若是硬件查詢到輸出屬性沒有實現，或最小緩衝區用byte表示，則返回ERROR。

　　　　　　參見

                            更多信息請見有效的設置參數

 

　　　　public int getNotificationMarkerPosition ()

　　　　返回通知，標記框架中的位置。

 

　　　　public int getPositionNotificationPeriod ()

　　　　返回通知，更新框架中的時間位置。

 

　　　　public int getRecordingState ()

　　　　返回AudioRecord實例的錄製狀態。

　　　　　　參見

                       RECORDSTATE_STOPPED

         　　  RECORDSTATE_RECORDING

 

　　　　public int getSampleRate ()

　　　　返回設置的音頻數據樣本採樣率，單位Hz。

 

　　　　public int getState ()

　　　　返回AudioRecord實例的狀態。 這點很是有用，用在AudioRecord 實例建立成功後，檢查初始化屬性。 它能確定請求到了合適的硬件資源。

　　　　　　參見

                 　　STATE_INITIALIZED

          　　 STATE_UNINITIALIZED

 

　　　　public int read (short[] audioData, int offsetInShorts, int sizeInShorts)

　　　　從音頻硬件錄製緩衝區讀取數據。

           　　參數

                            audioData        寫入的音頻錄製數據。

                            offsetInShorts           目標數組 audioData 的起始偏移量。

                            sizeInShorts              請求讀取的數據大小。

　　　　　　返回值

　　返回short型數據，表示讀取到的數據，若是對象屬性沒有初始化，則返回ERROR_INVALID_OPERATION，若是參數不能解析成有效的數據或索引，則返回ERROR_BAD_VALUE。 返回數值不會超過sizeInShorts。

 

　　　　public int read (byte[] audioData, int offsetInBytes, int sizeInBytes)

　　　　從音頻硬件錄製緩衝區讀取數據。

                   參數

                            audioData        寫入的音頻錄製數據。

                            offsetInBytes            audioData的起始偏移值，單位byte。

                            sizeInBytes                讀取的最大字節數。

                   返回值

　　讀入緩衝區的總byte數，若是對象屬性沒有初始化，則返回ERROR_INVALID_OPERATION，若是參數不能解析成有效的數據或索引，則返回ERROR_BAD_VALUE。 讀取的總byte數不會超過sizeInBytes。

 

　　　　public int read (ByteBuffer audioBuffer, int sizeInBytes)

　　　　從音頻硬件錄製緩衝區讀取數據，直接複製到指定緩衝區。 若是audioBuffer不是直接的緩衝區，此方法老是返回0。

                   參數

                            audioBuffer               存儲寫入音頻錄製數據的緩衝區。

                            sizeInBytes                請求的最大字節數。

                   返回值

　　讀入緩衝區的總byte數，若是對象屬性沒有初始化，則返回ERROR_INVALID_OPERATION，若是參數不能解析成有效的數據或索引，則返回ERROR_BAD_VALUE。 讀取的總byte數不會超過sizeInBytes。

 

　　　　public void release ()

　　　　釋放本地AudioRecord資源。 對象不能常常使用此方法，並且在調用release()後，必須設置引用爲null。

 

　　　　public int setNotificationMarkerPosition (int markerInFrames)

　　　　若是設置了setRecordPositionUpdateListener(OnRecordPositionUpdateListener)或setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler)，則通知監聽者設置位置標記。

                   參數

                            markerInFrames      在框架中快速標記位置。

                   返回值

                            返回錯誤或成功代碼，請見SUCCESS、ERROR_BAD_VALUE、ERROR_INVALID_OPERATION。

 

　　　　public int setPositionNotificationPeriod (int periodInFrames)

　　　　若是設置了setRecordPositionUpdateListener(OnRecordPositionUpdateListener)或setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler)，則通知監聽者設置時間標記。

                   參數

                            markerInFrames      在框架中快速更新時間標記。

                   返回值

                            返回錯誤或成功代碼，請見SUCCESS、ERROR_INVALID_OPERATION。

 

　　 public void setRecordPositionUpdateListener (AudioRecord.OnRecordPositionUpdateListener listener, Handler handler)

　　當以前設置的標誌已經成立，或者週期錄製位置更新時，設置處理監聽者。 使用此方法來將Handler 和別的線程聯繫起來，來接收AudioRecord 事件，比建立AudioTrack 實例更好一些。

　　參數

              handler    用來接收事件通知消息。

 

　　 public void setRecordPositionUpdateListener (AudioRecord.OnRecordPositionUpdateListener listener)

　　　　當以前設置的標誌已經成立，或者週期錄製位置更新時，設置處理監聽者。

 

　　　　public void startRecording ()

　　　　AudioRecord實例開始進行錄製。

                   異常

                            IllegalStateException

 

受保護方法

　　protected void finalize ()

　　　　通知VM回收此對象內存。 此方法只能用在運行的應用程序沒有任何線程再使用此對象，來告訴垃圾回收器回收此對象。

　　此方法用於釋放系統資源，由垃圾回收器清除此對象。 默認沒有實現，由VM來決定，但子類根據須要可重寫finalize()。 在執行期間，調用此方法可能會當即拋出未定義異常，可是能夠忽略。

　　注意：VM保證對象能夠一次或屢次調用finalize()，但並不保證finalize()會立刻執行。 例如，對象B的finalize()可能延遲執行，等待對象A的finalize()延遲迴收A的內存。 爲了安全起見，請看ReferenceQueue，它提供了更多地控制VM的垃圾回收。

 

補充

         文章精選

                   Android提升第十篇之AudioRecord實現"助聽器"

                   Android入門（9）AudioRecord和AudioTrack類的使用

                   Android多媒體學習十：利用AudioRecord類實現本身的音頻錄製程序

 

 

AudioRecord. OnRecordPositionUpdateListener

譯者署名： chenwei

版本：Android 3.1 r1

 

結構

繼承關係

public static interface AudioRecord.OnRecordPositionUpdateListener

 

android.media.AudioRecord.OnRecordPositionUpdateListener

 

類概述

         接口定義爲：當AudioRecord 收到一個由setNotificationMarkerPosition(int)設置的通知標誌，或由 setPositionNotificationPeriod(int)設置的週期更新記錄的進度狀態時，回調此接口。

 

公共方法

         public abstract void onMarkerReached (AudioRecord recorder)

         回調監聽器，通知監聽器已經到達以前設置的標記位置。

 

         public abstract void onPeriodicNotification (AudioRecord recorder)

         按照必定的週期，通知監聽器，指定的記錄已經就緒。