【Minim】音乐加工厂：AudioOutput 类

AudioOutput 是神马？

AudioOutput是与计算机声卡输出的连接。

通常，我们连接的设备是计算机的扬声器。你可使用AudioOutput，通过将UGens添加到输出对象来实时声音合成。

倘若要从 Minim 获取AudioOutput，你可以调用以下五种方法之一：

 AudioOutput getLineOut()
 
 // type 指定为 Minim.MONO 或 Minim.STEREO
 AudioOutput getLineOut(int type)
 
 // bufferSize 是你获得输出的左、右和混合缓冲区的大小
 AudioOutput getLineOut(int type, int bufferSize)
 
 // sampleRate 是对某采样率输出的请求
 AudioOutput getLineOut(int type, int bufferSize, float sampleRate)
 
 // bitDepth 是对某位深度输出的请求
 AudioInput getLineOut(int type, int bufferSize, float sampleRate, int bitDepth)
 

如果请求的参数不存在，Minim 则会报错并返回null。 故我们常用上面列出的前两种方法。

除直接将UGens添加到输出外，你还可以在将来的某时间安排输出播放“notes”。在编写算法音乐和声音时，这可能非常强大。有关更多信息，请参阅playNote方法。

Related:

Minim
UGen
playNote ( )

Example:

Here.

AudioOutput 旗下：Fields

我是一文不值，狗屁不如。你呢，就有如狗屁，值得一闻！——金庸 《鹿鼎记》

• left
• mix
• right

接下来，好吧，我们详细解释一番……

left——左声道

Description:

AudioBuffer包含左声道样本。若其为单声道声音，则其包含单声道音频。

Signature:

AudioBuffer left

Related:

AudioBuffer

Example:

Here.

mix——混合声道

Description:

AudioBuffer包含左右声道的混合样本。 若其为单声道声音，则mix包含与left相同的样本。

Signature:

AudioBuffer mix

Related:

AudioBuffer

Example:

Here.

right——右声道

Description:

AudioBuffer包含右声道样本。 若其为单声道声音，则right包含与left相同的样本。

Signature:

AudioBuffer right

Related:

AudioBuffer

Example:

Here.

AudioInput 旗下：Methods

书到用时方恨少，肉到肥时方恨多。——金庸 《鹿鼎记》

好吧，我们有些啥：

• addListener()
• bufferSize()
• getBalance()
• getDurationFactor)
• getFormat()
• getGain()
• getNoteOffset()
• getPan()
• getTempo()
• getVolume()
• isMuted()
• mute()
• pauseNotes()
• playNote()
• removeListener()
• resumeNotes()
• sampleRate()
• setBalance()
• setDurationFactor()
• setGain()
• setNoteOffset()
• setPan()
• setTempo()
• setVolume()
• shiftBalance()
• shiftGain()
• shiftPan()
• shiftVolume()
• type()
• unmute()

那么，我们知道些啥：

addListener()——兼听则明

Description:

添加一个AudioListener到声音以生成对象，每次该对象生成新的样本缓冲区，程序都会调用其的samples方法。

Signature:

void addListener(AudioListener listener)

Parameters:

listener — 将监听此的AudioListener

Returns:

None

Related:

AudioListener

Example:

Here.

bufferSize()——内部缓冲区大小

Description:

此声音对象的内部缓冲区大小。这是 left/right/mix AudioBuffers的大小，也是添加到此声音对象的AudioListeners的样本缓冲区的大小。

Signature:

int bufferSize()

Returns:

int：样本帧中，声音对象的内部缓冲区大小

Example:

Here.

getBalance()——只可制衡不可掣肘

Description:

返回当前平衡值，其在 [-1,1] 范围内。

通常，平衡仅适用于立体声音频源，因为它描述了对左右声道各需应用多少衰减。 若是没有平衡控制，则程序不执行任何操作。

Signature:

float getBalance()

Returns:

float：若平衡控制不可用，则返回当前平衡值或零

Related:

setBalance ( )
shiftBalance ( )

Example:

None available

getDurationFactor()——持续时间因子

Description:

返回此输出的持续时间因子的当前值。

Signature:

float getDurationFactor()

Returns:

float：当前持续时间因子

Related:

setDurationFactor ( )

Example:

None available

getFormat()——获取音频属性

Description:

返回一个AudioFormat对象，以描述此声音生成对象的音频属性。

在进行声音分析或某些综合时，这通常是有用的信息，但一般你不需要了解什么特殊的格式。

Signature:

AudioFormat getFormat()

Returns:

描述此声音对象的AudioFormat

Related:

Example:

Here.

getGain()——获取增益

Description:

返回当前增益。 如果增益控制不可用，则返回零。注意，增益与AudioBuffer的level()不同！

增益以分贝为单位描述声音的当前音量，这是一个对数而非线性的音阶。 增益为0dB时，表示声音未被放大或衰减。 负增益值会降低声音的音量，正值会增加声音的音量。

Signature:

float getGain()

Returns:

float：如果增益控制不可用，返回当前增益或零，增益以分贝表示

Related:

setGain ( )
shiftGain ( )

Example:

None available

getNoteOffset()——音符偏移值

Description:

返回此输出的音符偏移的当前值。

Signature:

float getNoteOffset()

Returns:

float：当前音符偏移量

Related:

setNoteOffset ( )

Example:

Here.

getPan——获取平移

Description:

返回当前的平移值。

通常只有单声道音频源才能使用平移，因其描述了单声道信号在立体声场中的位置。其值将在 [-1,1] 范围内，其中-1表示将声音仅放在左扬声器中，1表示将声音仅放在右扬声器中。

Signature:

float getPan()

Returns:

float：如果平移控制不可用，返回当前平移值或零

Related:

setPan ( )
shiftPan ( )

Example:

None available

getTempo()——我要我的节奏

Description:

返回AudioOuput的当前速度。其速度以BPM（每分钟节拍）计。

Signature:

float getTempo()

Returns:

float：当前的节奏

Related:

setTempo ( )

Example:

Here.

getVolume()——获取音量

Description:

返回当前音量。 如果音量控制不可用，则返回零。注意，音量与AudioBuffer的level()不同！

Signature:

float getVolume()

Returns:

若音量控制不可用，则为当前音量或零

Related:

setVolume ( )
shiftVolume ( )

Example:

None available

isMuted()——是否静音

Description:

如果声音静音，则返回true。

Signature:

boolean isMuted()

Returns:

boolean：目前的静音状态

Related:

mute ( )
unmute ( )

Example:

None available

mute()——静音吧

Description:

静音。

Signature:

void mute()

Returns:

None

Related:

unmute ( )
isMuted ( )

Example:

None available

pauseNotes()——暂停音符

Description:

AudioOutput在其Thread中处理自己的音符队列，因此若你想一次性排列大量音符，则需要在排列之前使用pauseNotes方法。

如果不这样做，时间轴会出现微小的偏差，因为每个音符的开始时间会随逐个音符发生偏离。 当添加完所有音符后，你应调用resumeNotes以允许AudioOutput再次处理音符。

Signature:

void pauseNotes()

Returns:

None

Related:

resumeNotes ( )

Example:

Here.

playNote()——播放音符

Description:

playNote是一种调度方法，其将在某个时间（或立即）播放的“note”，其中“note”是实现 Instrument接口的类的实例。 Instrument接口要求你实现一个noteOn方法，其接收浮点型持续时间值，并在该Instrument开始发出声音时调用，而当该Instrument应停止发声时，则调用noteOff方法。

没有Instrument参数的playNote版本将创建一个默认Instrument的实例，其根据输入的参数播放正弦音。

为了便于编写算法音乐，音符的开始时间和持续时间以节拍计，而不是以秒为单位。默认情况下，AudioOutput的速度为 60 BPM（每分钟节拍），这意味着节拍相当于秒。如果你想基于秒时间来思考编写音符播放的代码，那么就不要改变输出的速度。

要记住的另一件事是，AudioOutput在其Thread中处理自己的音符队列，因此若你想一次性排列大量音符，则需要在排列之前使用pauseNotes方法。如果你不这样做，时间轴会出现微小的偏差，因为每个音符的开始时间会随逐个音符发生偏离。 当添加完所有音符后，你应调用resumeNotes以允许AudioOutput再次处理音符。

Signature:

void playNote(float startTime, float duration, Instrument instrument)
void playNote(float startTime, float duration, float hz)
void playNote(float startTime, float duration, String pitchName)
void playNote(float startTime, float hz)
void playNote(float startTime, String pitchName)
void playNote(float hz)
void playNote(String pitchName)
void playNote()

Parameters:

startTime — float：音符的开始播放时间，以节拍计
duration — float：音符播放持续时间，以节拍计
instrument — 将播放音符的乐器
hz — float：以赫兹为单位，音符播放频率
pitchName — String：播放音符的音高名称（例如“A4”或“Bb3”）

Returns:

None

Related:

Instrument
setTempo ( )
setNoteOffset ( )
setDurationFactor ( )
pauseNotes ( )
resumeNotes ( )

Example:

Here.

removeListener()——删除音频监听器

Description:

删除先前添加到此声音对象的AudioListener。

Signature:

void removeListener(AudioListener listener)

Parameters:

listener — 应该停止监听的AudioListener

Returns:

None

Related:

AudioListener

Example:

Here.

resumeNotes()——恢复音符

Description:

恢复音符处理。

Signature:

void resumeNotes()

Returns:

None

Related:

pauseNotes ( )

Example:

Here.

sampleRate()——获取采样率

Description:

返回此声音对象的采样率。

Signature:

float sampleRate()

Returns:

float：此声音对象的采样率

Related:

Example:

None available

setBalance()——设置平衡

Description:

设置平衡值。该值应在 [-1,1] 范围内。若是没有平衡控制，则程序不执行任何操作。

Signature:

void setBalance(float value)

Parameters:

value — float：新的平衡值

Returns:

None

Related:

getBalance ( )
shiftBalance ( )

Example:

None available

setDurationFactor()——设定持续时间因子

Description:

AudioOutput的持续时间因子定义了在排列之前如何缩放传递给playNote调用的持续时间。若你持续时间因子为0.5，且你将持续时间为2的音符排列，则实际持续时间将变为1。如果你希望先将长度较长而持续时间非常短的一长串音符排列，这可能很有用。

默认情况下，持续时间因子为1。

Signature:

void setDurationFactor(float durationFactor)

Parameters:

durationFactor — float：持续时间因子

Returns:

None

Related:

getDurationFactor ( )

Example:

None available

setGain()——设置增益

Description:

设置增益值。若是没有增益控制，则程序不执行任何操作。

Signature:

void setGain(float value)

Parameters:

value — float：新增益值，单位为分贝

Returns:

None

Related:

getGain ( )
shiftGain ( )

Example:

None available

setNoteOffset()——设定音符偏移值

Description:

当在代码中编写出乐谱时，通常较易按部分来考虑音乐，其所有playNote调用都具有相对于该部分开头的开始时间。setNoteOffset方法通过让你设置一个时间值，而所有传递给playNote调用的开始时间都将加上其值。因此，若音符偏移值设置为16，则意味着所有playNote开始时间将相对于“now”的第16拍。

默认情况下，音符偏移值为0。

Signature:

void setNoteOffset(float noteOffset)

Parameters:

noteOffset — float：所有传递给playNote调用的开始时间添加的时间值

Returns:

None

Related:

getNoteOffset ( )

Example:

None available

setPan()——设置平移

Description:

设置平移值。其值应在 [-1,1] 范围内。若是没有平移控制，则程序不执行任何操作。

Signature:

void setPan(float value)

Parameters:

value — float：新平移值

Returns:

None

Related:

getPan ( )
shiftPan ( )

Example:

None available

setTempo()——

Description:

AudioOutput的速度控制其如何解释playNote方法的开始时间和持续时间参数。默认情况下，AudioOutput的速度为60 BPM（每分钟节拍数），这意味着一个节拍持续为一秒钟。 速度设置为120 BPM意味着一个节拍持续半秒。 当速度改变时，其只会影响改变后的playNote方法的调用。

Signature:

void setTempo(float tempo)

Parameters:

tempo — float：AudioOutput的新速度，以BPM计 (每分钟节拍数)

Returns:

None

Related:

getTempo ( )

Example:

Here.

setVolume()——设置音量

Description:

设置音量值。若是音量控制不可用，则程序不执行任何操作。

Signature:

void setVolume(float value)

Parameters:

value — float：新音量值，通常在 [0,1] 范围内

Returns:

None

Related:

getVolume ( )
shiftVolume ( )

Example:

None available

shiftBalance()——转换平衡

Description:

将平衡从一个值转换为另一个值。

Signature:

void shiftBalance(float from, float to, int millis)

Parameters:

from — float：起始平衡
to — float：最终平衡
millis — int：过渡时间，以毫秒为单位

Returns:

None

Related:

getBalance ( )
setBalance ( )

Example:

None available

shiftGain()——转换增益

Description:

将增益从一个值转换为另一个值。

Signature:

void shiftGain(float from, float to, int millis)

Parameters:

from — float：起始增益
to — float：最终增益
millis — int：过渡时间，以毫秒为单位

Returns:

None

Related:

getGain ( )
setGain ( )

Example:

None available

shiftPan()——转换平移

Description:

将平移从一个值转换为另一个值。

Signature:

void shiftPan(float from, float to, int millis)

Parameters:

from — float：起始平移
to — float：最终平移
millis — int：过渡时间，以毫秒为单位

Returns:

None

Related:

getPan ( )
setPan ( )

Example:

None available

shiftVolume()——转换音量

Description:

将音量从一个值转换为另一个值。

Signature:

void shiftVolume(float from, float to, int millis)

Parameters:

from — float：起始音量
to — float：最终音量
millis — int：过渡时间，以毫秒为单位

Returns:

None

Related:

getVolume ( )
setVolume ( )

Example:

None available

type()——通道数

Description:

类型是一个整数型，用于描述此声音对象具有的通道数。

Signature:

int type()

Returns:

若为单声道，Minim.MONO；若为立体声，Minim.STEREO

Related:

Example:

None available

unmute()——取消静音

Description:

取消静音。

Signature:

void unmute()

Returns:

None

Related:

mute ( )
isMuted ( )

Example:

None available

Last…

我虽不专心，但不抛弃。——《鹿鼎记》