javax.sound.sampled
介面 SourceDataLine

所有父級介面：

DataLine, Line

public interface SourceDataLine
extends DataLine

源資料行是可以寫入資料的資料行。它充當其混頻器的源。應用程序將音頻位元組寫入源資料行，這樣可處理位元組緩衝並將它們傳遞給混頻器。混頻器可以將這些樣本與取自其他源的樣本混合起來，然後將該混合物傳遞到輸出埠號之類別的目標（它可表示聲卡上的音頻輸出設備）。

注意，此介面的命名約定反映了資料行及其混頻器之間的關係。從應用程序的角度來看，源資料行可能充當音頻資料的目標。

可以通過使用適當 DataLine.Info 物件調用 Mixer 的 getLine 方法從混頻器獲得源資料行。

SourceDataLine 介面提供將音頻資料寫入資料行的緩衝區中的方法。播放或混合音頻的應用程序應該以足夠快的速度將資料寫入源資料行，以防緩衝區下溢（排空），下溢可能導致單擊時音頻資料中出現可感知的間斷。應用程序可以使用在 DataLine 介面中定義的 available 方法來確定當前在資料行緩衝區中列隊的資料量。可以不受阻塞地寫入緩衝區的資料量是緩衝區大小和已列隊資料量之間的差值。如果由於下溢而導致音頻輸出的傳遞停止，則產生 STOP 事件。恢復音頻輸出時產生 START 事件。

從以下版本開始：

1.3

另請參見：

Mixer, DataLine, TargetDataLine

巢狀類別摘要

從介面 javax.sound.sampled.DataLine 繼承的巢狀類別/介面

DataLine.Info

方法摘要

void	open(AudioFormat format) 打開具有指定格式的行，這樣可使行獲得所有所需的系統資源並變得可操作。
void	open(AudioFormat format, int bufferSize) 打開具有指定格式和建議緩衝區大小的行，這樣可使該行獲得所有所需系統資源並變得可操作。
int	write(byte[] b, int off, int len) 通過此源資料行將音頻資料寫入混頻器。

從介面 javax.sound.sampled.DataLine 繼承的方法

available, drain, flush, getBufferSize, getFormat, getFramePosition, getLevel, getLongFramePosition, getMicrosecondPosition, isActive, isRunning, start, stop

從介面 javax.sound.sampled.Line 繼承的方法

addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

方法詳細資訊

open

void open(AudioFormat format,
          int bufferSize)
          throws LineUnavailableException

打開具有指定格式和建議緩衝區大小的行，這樣可使該行獲得所有所需系統資源並變得可操作。

以位元組為單位指定緩衝區大小，但該大小必須表示整數形式的樣本幀數。使用不滿足此要求的所請求緩衝區大小調用此方法可能導致 IllegalArgumentException。已打開的行的實際緩衝區大小可能與所請求緩衝區大小不同。實際設置的值可以通過後續調用 DataLine.getBufferSize() 來查詢。

如果此操作成功，則將該行標記為 open，並向行的偵聽器指派一個 OPEN 事件。

在已經打開的行上調用此方法是非法的，並且可能導致 IllegalStateException。

注意，有些行一旦關閉就無法重新打開。試圖重新打開這樣的行總是導致 LineUnavailableException。

參數：

format - 所需的音頻格式

bufferSize - 所需的緩衝區大小

拋出：

LineUnavailableException - 如果由於資源限制而無法打開行

IllegalArgumentException - 如果緩衝區大小不表示整數形式的樣本幀數，或者 format 未完全指定或是無效的

IllegalStateException - 如果行已經打開

SecurityException - 如果由於安全限制而無法打開行

另請參見：

open(AudioFormat), Line.open(), Line.close(), Line.isOpen(), LineEvent

open

void open(AudioFormat format)
          throws LineUnavailableException

打開具有指定格式的行，這樣可使行獲得所有所需的系統資源並變得可操作。

該實作選擇緩衝區大小，此大小是以位元組為單位來測量的，但它不包括整數形式的樣本幀數。系統選擇的緩衝區大小可以通過後續調用 DataLine.getBufferSize() 來查詢。

如果此操作成功，則將該行標記為 open，並向行的偵聽器指派一個 OPEN 事件。

在已經打開的行上調用此方法是非法的，並且可能導致 IllegalStateException。

注意，有些行一旦關閉就無法重新打開。試圖重新打開這樣的行總是導致 LineUnavailableException。

參數：

format - 所需音頻格式

拋出：

LineUnavailableException - 如果由於資源限制而無法打開行

IllegalArgumentException - 如果 format 未完全指定的或是無效的

IllegalStateException - 如果行已經打開

SecurityException - 如果由於安全限制而無法打開行

另請參見：

open(AudioFormat, int), Line.open(), Line.close(), Line.isOpen(), LineEvent

write

int write(byte[] b,
          int off,
          int len)

通過此源資料行將音頻資料寫入混頻器。所請求的資料位元組數是從指定的陣列中讀取的（從陣列中給定的偏移量開始），並且將被寫入資料行的緩衝區。如果調用者試圖寫入多於當前可寫入資料量的資料（參見 available），則此方法在寫入所請求資料量之前一直阻塞。即使要寫入的請求資料量大於資料行的緩衝區大小，此方法也適用。不過，如果在寫入請求的資料量之前資料行已關閉、停止或刷新，則該方法不再阻塞，但它會返回至今為止寫入的位元組數。

可以使用 DataLine 介面的 available 方法確認可不受阻塞地寫入的位元組數。（在保證可以不受阻塞地寫入此位元組數時，不保證試圖寫入其他資料不會發生阻塞。）

要寫入的位元組數必須表示整數形式的樣本幀數，比如：

[ bytes written ] % [frame size in bytes ] == 0
返回值將始終滿足此要求。寫入表示非整數形式的樣本幀數的位元組數的請求無法完成，並且可能導致 IllegalArgumentException。

參數：

b - 套件含要寫入資料行的資料的位元組陣列

len - 陣列中的有效資料的長度，以位元組為單位（即要寫入的請求資料量，以位元組為單位）

off - 陣列開始處的偏移量，以位元組為單位

返回：

實際寫入的位元組數

拋出：

IllegalArgumentException - 如果所請求位元組數不表示整數形式的樣本幀數，或者 len 為負

ArrayIndexOutOfBoundsException - 如果 off 為負，或者 off+len 大於陣列 b 的長度。

另請參見：

TargetDataLine.read(byte[], int, int), DataLine.available()