流体合成
1.1.11
|
本文档中的所有源代码示例均位于公共领域;您可以随意使用它们。本文档根据知识共享署名-相同方式共享3.0未移植许可证获得许可。要查看此许可证的副本,请访问 http://creativecommons.org/licenses/by-sa/3.0/ 。 FluidSynth库是根据GNU较小通用公共许可证发行的。 FluidSynth软件包中包含GNU较小通用公共许可证的副本。如果没有,请访问 http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt 或写信给美国自由软件基金会有限公司(Free Software Foundation,Inc.),地址为:51 Franklin Street,Fifth Floor,Boston,MA 02110-1301 USA。
FluidSynth 是基于以下内容的软件合成器: SoundFont 2 规格。合成器可以作为共享对象使用,可以在任何要使用波表合成的应用程序中轻松重用。本文档介绍了FluidSynth的基本用法。一些更高级的功能尚未讨论,但将在以后的版本中添加。
当前版本的文档不完整。与往常一样,源代码是最终参考。
SoundFont(R)是E-mu Systems,Inc.的注册商标。
什么是FluidSynth?
针对开发人员的FluidSynth 1.1.10中的更改:
FluidSynth 1.1.9中与开发人员有关的更改:
FluidSynth 1.1.8中与开发人员有关的更改:
FluidSynth 1.1.7中与开发人员有关的更改:
FLUID_SEQ_LASTEVENT
, GEN_LAST
, LAST_LOG_LEVEL
FluidSynth 1.1.6中与开发人员有关的更改:
针对开发人员的FluidSynth 1.1.5的更改:
FluidSynth 1.1.4中与开发人员有关的更改:
FluidSynth 1.1.3中与开发人员有关的更改:
FluidSynth 1.1.2中与开发人员有关的更改:
FluidSynth 1.1.1中与开发人员有关的更改:
FluidSynth 1.1.0中与开发人员有关的更改概述:
API新增功能:
必须先创建一个设置对象,然后才能使用合成器。设置对象被FluidSynth库的许多组件使用。它提供了一个统一的API,用于设置音频驱动程序,MIDI驱动程序,合成器等的参数。当前的实现定义了许多默认设置。
所有设置的名称都遵循“点名”符号。例如,“ 合成复音”是指合成器预先分配的声音(复音)的数量。设置也有一个类型。当前有三种类型:字符串,数字(双浮点数)和整数。您可以使用来更改设置的值 fluid_settings_setstr(), fluid_settings_setnum()和 fluid_settings_setint() 职能。例如:
API包含用于查询类型,当前值,默认值,范围和设置的“提示”的函数。范围是设置的最小值和最大值。这些提示提供了有关设置的其他信息。例如,字符串是否代表文件名。或者数字是否应该以对数尺度进行解释。检查 settings.h 有关所有功能的描述的API文档。
要创建合成器,请向其传递设置对象,如以下示例所示:
下表提供了合成器使用的所有设置的详细信息。
合成音频通道 | 类型 | 整数 |
默认 | 1 | |
最小-最大 | 1-128 | |
描述 | 默认情况下,合成器输出单个立体声信号。使用此选项,合成器可以输出多声道音频。设置立体声通道对的数量。所以1实际上是2个声道(立体声对)。 | |
合成音频组 | 类型 | 整数 |
默认 | 1 | |
最小-最大 | 1-128 | |
描述 | 通常与synth.audio-channels的值相同。 LADSPA效果子系统可以使用此值,在这种情况下,它可能会有所不同。 | |
合成合唱 | 类型 | 布尔值 |
默认 | 1(真) | |
描述 | 设置为1(TRUE)时,合唱效果模块被激活。否则,不会将合唱添加到输出信号。请注意,发送到合唱模块的信号量取决于SoundFont中定义的“合唱发送”发生器。 | |
synth.cpu核心 | 类型 | 整数 |
默认 | 1 | |
最小-最大 | 1-256 | |
描述 | (实验性)设置综合CPU内核的数量。如果设置为大于1的值,则将创建其他综合线程以利用多CPU或CPU核心系统。在将音频合成到文件中时,这会产生以下影响:占用更多的CPU资源进行语音处理或减少渲染时间。 | |
synth.device-id | 类型 | 整数 |
默认 | 0 | |
最小-最大 | 0-126 | |
描述 | 用于SYSEX命令(例如MIDI Tuning Standard命令)的设备标识符。仅作用于此ID或所有设备的SYSEX命令。 | |
合成转储 | 类型 | 布尔值 |
默认 | 0(假) | |
描述 | 目前不执行任何操作。 | |
合成效应通道 | 类型 | 整数 |
默认 | 2 | |
最小-最大 | 2-2 | |
描述 | ||
合成增益 | 类型 | 数 |
默认 | 0.2 | |
最小-最大 | 0.0-10.0 | |
描述 | 增益被应用于合成器的最终或主输出。默认情况下,它设置为较低的值,以避免在演奏许多音符时输出饱和。 | |
synlad.ladspa.active | 类型 | 布尔值 |
默认 | 0(假) | |
描述 | 设置为“是”时,将启用LADSPA子系统。该子系统允许加载和互连LADSPA插件。 LADSPA子系统处理合成器的输出。请注意,合成器必须在LADSPA支持下进行编译。稍后有关LADSPA子系统的更多信息。 | |
合成中音通道 | 类型 | 整数 |
默认 | 16 | |
最小-最大 | 16-256 | |
描述 | 此设置定义合成器的MIDI通道数。 MIDI标准定义了16个通道,因此MIDI硬件仅限于此数目。在内部,FluidSynth可以使用更多通道,这些通道可以映射到不同的MIDI源。 | |
synth.midi-bank-select | 类型 | 串 |
默认 | s | |
选件 | gm,gs,xg,mma | |
描述 | 此设置定义合成器如何解释Bank Select消息。
| |
合成器最小音符长度 | 类型 | 整数 |
默认 | 10 | |
最小-最大 | 0-65535 | |
描述 | 设置最小音符持续时间(以毫秒为单位)。这样可以确保真正持续时间较短的音符事件(例如打击乐音符)有更好的发声预期。设置为0以禁用此功能。 | |
合成并行渲染 | 类型 | 布尔值 |
默认 | 1(真) | |
描述 | 合成并行渲染是低延迟设置。如果启用,则允许您与其余的调用并行地调用fluid_synth_write_s16,fluid_synth_write_float,fluid_synth_nwrite_float或fluid_synth_process,并且不会因对合成器的时间密集的调用而阻塞它。如果吞吐量比延迟更重要,请关闭此功能,例如在渲染不足的情况下渲染到文件的情况下。 | |
合成复音 | 类型 | 整数 |
默认 | 256 | |
最小-最大 | 1-65535 | |
描述 | 复音定义了可以并行播放多少个声音。笔记事件会产生一个或多个声音。最好将其设置为系统可以处理的值,从而限制FluidSynth的CPU使用率。当FluidSynth的声音用尽时,它将开始为新的音符事件终止优先级较低的声音。 | |
synth.reverb.active | 类型 | 布尔值 |
默认 | 1(真) | |
描述 | 设置为1(TRUE)时,混响效果模块被激活。否则,不会将混响添加到输出信号。请注意,发送到混响模块的信号量取决于SoundFont中定义的“混响发送”生成器。 | |
合成采样率 | 类型 | 数 |
默认 | 44100 | |
最小-最大 | 22050-96000 | |
描述 | 合成器生成的音频的采样率。 | |
synth.threadsafe-api | 类型 | 布尔值 |
默认 | 1(真) | |
描述 | synth.threadsafe-api控制合成器的公共API是否受互斥锁保护。默认是打开的,如果您只知道仅从一个线程访问合成器,则将其关闭以获得更好的性能,例如,在许多嵌入式用例中可能就是这种情况。请注意,libfluidsynth本身可以使用多个线程(shell是一个,midi驱动程序是一个,midi player是一个,等等),因此通常应将其保留。另请参见合成并行渲染。 | |
合成词 | 类型 | 布尔值 |
默认 | 0(假) | |
描述 | 设置为1(TRUE)时,合成器会将有关接收到的MIDI事件的信息打印到标准输出。这对于调试很有帮助。合成器启动后,无法更改此设置。 |
合成器本身不会将任何音频写入音频输出。这使应用程序开发人员可以根据需要自己管理音频输出。下一节将更详细地描述没有音频驱动器的合成器的使用。
创建音频驱动程序非常简单:设置适当的设置并创建驱动程序对象。因为FluidSynth支持多种音频系统,所以您可能需要更改要使用的音频系统。下面的列表显示了当前支持的音频系统。它显示了Fluidsynth库使用的名称和说明。
默认的音频驱动程序取决于使用FluidSynth进行编译的设置。您可以使用以下方法获取默认驱动程序 fluid_settings_getstr_default()。要获取可用驱动程序列表,请使用 fluid_settings_foreach_option() 功能。最后,您可以使用 fluid_settings_setstr()。在大多数情况下,默认驱动程序应开箱即用。
定义音频质量和延迟的其他选项是“ 音频样本格式”,“ 音频周期大小”和“ 音频周期”。详细内容将在后面说明。
您使用创建音频驱动程序 new_fluid_audio_driver() 功能。此函数将设置和合成器对象作为参数。例如:
音频驱动程序一经创建,便会开始播放。音频驱动程序创建一个单独的线程,该线程使用合成器对象生成音频。
有许多常规的音频驱动程序设置。 音频驱动程序设置定义将使用的音频子系统。 音频周期和audio.period-size设置定义了针对计划延迟的延迟和健壮性。另一个表中记录了所使用的音频子系统的其他设置。
音频驱动程序 | 类型 | 串 |
默认 | 插孔(Linux),dsound(Windows),sndman(MacOS9),coreaudio(Mac OS X),dart(OS / 2) | |
选件 | 插孔,alsa,oss,pulseaudio,coreaudio,dsound,portaudio,sndman,dart,文件 | |
描述 | 要使用的音频系统。 | |
音频周期 | 类型 | 整型 |
默认 | 16(Linux,Mac OS X),8(Windows) | |
最小-最大 | 2-64 | |
描述 | 驱动程序使用的音频缓冲区的数量。缓冲区的数量乘以缓冲区的大小(请参阅设置audio.period-size)可确定音频驱动程序的最大延迟。 | |
音频周期大小 | 类型 | 整数 |
默认 | 64(Linux,Mac OS X),512(Windows) | |
最小-最大 | 64-8192 | |
描述 | 音频缓冲区的大小(以帧为单位)。 | |
音频实时优先 | 类型 | 整数 |
默认 | 60 | |
最小-最大 | 0-99 | |
描述 | 设置音频合成线程的实时调度优先级(0禁用高优先级调度)。 Linux是当前唯一使用不同优先级的平台。使用此选项的驱动程序:alsa,oss和pulseaudio | |
音频样本格式 | 类型 | 串 |
默认 | “ 16位” | |
选件 | “ 16bits”,“ float” | |
描述 | 音频样本的格式。目前这只是一个指示;如果音频驱动程序无法处理指定的格式,则它可能会忽略此设置。 |
下表描述了音频驱动程序特定的设置。
audio.alsa.device | 类型 | 串 |
默认 | “默认” | |
选件 | ALSA设备字符串,例如:“ hw:0”,“ plughw:1”等。 | |
描述 | 选择要使用的ALSA音频设备。 | |
audio.coreaudio.device | 类型 | 串 |
默认 | “默认” | |
描述 | 选择要使用的CoreAudio设备。 | |
audio.dart.device | 类型 | 串 |
默认 | “默认” | |
描述 | 选择要使用的Dart(OS / 2驱动程序)设备。 | |
audio.dsound.device | 类型 | 串 |
默认 | “默认” | |
描述 | 选择要使用的DirectSound(Windows)设备。 | |
audio.file.endian | 类型 | 串 |
默认 | 如果内置了libsndfile支持,则为'auto',否则为'cpu'。 | |
选件 | auto,big,cpu,little(如果未内置libsndfile支持,则仅支持“ cpu”) | |
描述 | 使用“文件”驱动程序或文件渲染器将音频存储到文件时,定义字节顺序。 'auto'使用给定文件类型的默认值,'cpu'使用CPU字节顺序,'big'使用大字节序字节顺序,'little'使用小字节序字节顺序。 | |
audio.file.format | 类型 | 串 |
默认 | s16 | |
选件 | double,float,s16,s24,s32,s8,u8(如果未内置libsndfile支持,则仅支持's16') | |
描述 | 在将音频渲染到文件时定义音频格式。 'double'是64位浮点,'float'是32位浮点,'s16'是16位带符号PCM,'s24'是24位带符号PCM,'s32'是32位带符号PCM,'s8'是8位有符号PCM,'u8'是8位无符号PCM。 | |
audio.file.name | 类型 | 串 |
默认 | 如果内置了libsndfile支持,则为'fluidsynth.wav',否则为'fluidsynth.raw'。 | |
描述 | 指定在将音频渲染到文件时将音频存储到的文件名。 | |
audio.file.type | 类型 | 串 |
默认 | 如果内置了libsndfile支持,则为'auto',否则为'raw'。 | |
选件 | aiff,au,auto,avr,caf,flac,htk,iff,mat,oga,paf,pvf,raw,sd2,sds,sf,voc,w64,wav,xi(实际类型列表可能有所不同,具体取决于使用libsndfile库,如果未内置libsndfile支持,则“ raw”是唯一可用的类型。 | |
描述 | 设置音频将被存储到的文件的文件类型。 “自动”会尝试从audio.file.name文件扩展名确定文件类型,如果扩展名与任何类型都不匹配,则会回退到“ wav”。 | |
audio.jack.autoconnect | 类型 | 布尔值 |
默认 | 0(假) | |
描述 | 如果为1(TRUE),则FluidSynth输出将自动连接到插孔系统音频输出。 | |
audio.jack.id | 类型 | 串 |
默认 | 流体合成 | |
描述 | 创建Jack客户端连接时使用的ID。 | |
audio.jack.multi | 类型 | 布尔值 |
默认 | 0(假) | |
描述 | 如果为1(TRUE),则当synth.audio-channels大于1时,将启用多声道Jack输出。 | |
audio.jack.server | 类型 | 串 |
默认 | ||
描述 | 要连接的杰克服务器。默认为空字符串,该字符串使用默认的Jack服务器。 | |
audio.oss.device | 类型 | 串 |
默认 | / dev / dsp | |
描述 | 用于OSS音频输出的设备。 | |
audio.portaudio.device | 类型 | 串 |
默认 | PortAudio默认 | |
描述 | 用于PortAudio驱动程序输出的设备。请注意,“ PortAudio默认”是一个特殊值,可输出到默认PortAudio设备。 | |
audio.pulseaudio.device | 类型 | 串 |
默认 | “默认” | |
描述 | 用于PulseAudio驱动程序输出的设备 | |
audio.pulseaudio.server | 类型 | 串 |
默认 | “默认” | |
描述 | 服务器用于PulseAudio驱动程序输出 |
可以在不创建音频驱动程序的情况下使用合成器对象。如果使用FluidSynth的应用程序自行管理音频输出,则这是理想的。合成器具有几个API函数,可用于获取音频输出:
fluid_synth_write_s16() 用编码为带符号的16位(字节序取决于机器)填充两个缓冲区(左右通道)。 fluid_synth_write_float() 用32位浮点样本填充左右音频缓冲区。对于多声道音频输出,该功能 fluid_synth_nwrite_float() 必须使用。
功能 fluid_synth_process() 仍处于试验阶段,因此不建议使用它,但它可能会在将来的版本中成为通用接口。
在产生任何声音之前,合成器需要一个SoundFont。
SoundFonts装有 fluid_synth_sfload() 功能。该函数获取SoundFont文件的路径和一个布尔值,以指示在加载SoundFont之后是否应更新MIDI通道的预设。当布尔值是TRUE时,将刷新所有MIDI通道库和程序号,这可能会导致从新加载的SoundFont中选择新乐器。
合成器可以加载任意数量的SoundFonts。加载的SoundFonts被视为堆栈,其中每个新加载的SoundFont都放置在堆栈的顶部。通过库号和程序号选择预设时,将从堆栈顶部开始搜索SoundFonts。如果不同SoundFonts中的预设具有相同的库和程序号,则使用最近加载的SoundFont中的预设。的 fluid_synth_program_select() 可以用于明确选择预设,也可以将库偏移应用到每个SoundFont fluid_synth_set_bank_offset(),以确保每个预设都有唯一的库号和程序号。
的 fluid_synth_sfload() 函数返回加载的SoundFont的唯一标识符,如果出现错误,则返回-1。此标识符用于后续管理功能: fluid_synth_sfunload() 删除SoundFont, fluid_synth_sfreload() 重新加载SoundFont。重新加载SoundFont时,它将保留其ID和在SoundFont堆栈上的位置。
提供了其他API函数来获取已加载的SoundFonts的数量并获取指向SoundFont的指针。
一旦合成器启动并运行并且加载了SoundFont,大多数人就会想对它做一些有用的事情。例如发出声音。 MIDI信息可以使用 fluid_synth_noteon(), fluid_synth_noteoff(), fluid_synth_cc(), fluid_synth_pitch_bend(), fluid_synth_pitch_wheel_sens()和 fluid_synth_program_change() 职能。为了方便起见,还有一个 fluid_synth_bank_select() 功能(库选择消息通常使用控制更改消息发送)。
下面的示例显示一个通用的图形按钮,单击该按钮便会发出注释:
FluidSynth可以处理从硬件MIDI端口或其他应用程序接收到的实时MIDI事件。为此,客户端必须创建一个MIDI输入驱动程序。这与音频驱动程序的创建过程非常相似:您可以在设置实例中初始化一些属性,然后调用 new_fluid_midi_driver() 函数提供了一个回调函数,当接收到MIDI事件时将调用该函数。当前支持以下MIDI驱动程序:
有许多常规的MIDI驱动程序设置。 midi.driver设置定义将使用的MIDI子系统。下表列出了所使用的MIDI子系统的其他设置。
midi.driver | 类型 | 串 |
默认 | alsa_seq(Linux),winmidi(Windows),jack(Mac OS X) | |
选件 | alsa_raw,alsa_seq,coremidi,jack,midishare,oss,winmidi | |
描述 | 所使用的MIDI系统。 | |
实时实时 | 类型 | 整数 |
默认 | 50 | |
最小-最大 | 0-99 | |
描述 | 设置MIDI线程的实时调度优先级(0禁用高优先级调度)。 Linux是当前唯一使用不同优先级的平台。使用此选项的驱动程序:alsa_raw,alsa_seq,oss |
下表定义了MIDI驱动程序特定的设置。
midi.alsa.device | 类型 | 串 |
默认 | “默认” | |
描述 | 用于RAW ALSA MIDI驱动程序的ALSA MIDI设备。 | |
midi.alsa_seq.device | 类型 | 串 |
默认 | “默认” | |
描述 | 用于ALSA定序器驱动程序的ALSA定序器设备。 | |
midi.alsa_seq.id | 类型 | 串 |
默认 | pid | |
描述 | 向ALSA音序器驱动程序注册端口时使用的ID。如果设置为“ pid”,则ID将为“ FLUID Synth(PID)”,其中PID是音频线程的FluidSynth进程ID,否则将使用提供的字符串代替PID。 | |
midi.jack.id | 类型 | 串 |
默认 | 液体合成中期 | |
描述 | 与Jack MIDI驱动程序一起使用的客户端ID。 | |
midi.jack.server | 类型 | 串 |
默认 | ||
描述 | 用于Jack MIDI驱动程序连接的Jack服务器。如果为空字符串,则将使用默认服务器。 | |
midi.oss.device | 类型 | 串 |
默认 | / dev / midi | |
描述 | 用于OSS MIDI驱动程序的设备。 | |
midi.portname | 类型 | 串 |
默认 | ||
描述 | 由coremidi和alsa_seq驱动程序用于在MIDI子系统中注册的端口名。 |
通过MIDI File Player界面,FluidSynth可用于播放MIDI文件。尽管目前尚不完整,但它遵循的是高级实现。初始化合成器后,创建将合成器实例传递到的播放器 new_fluid_player()。然后,您可以使用以下命令向播放器添加一些SMF文件名 fluid_player_add(),最后致电 fluid_player_play() 开始播放。您可以通过致电查看播放器是否完成播放 fluid_player_get_status(),或等待播放器终止使用 fluid_player_join().
MIDI播放器使用的设置记录在下面。
播放器重置合成器 | 类型 | 布尔值 |
默认 | 1(真) | |
描述 | 如果为true,则在开始新的MIDI歌曲之前重置合成器,因此上一首歌曲的状态不会影响新歌曲。请将其关闭以无缝播放歌曲。 | |
玩家计时源 | 类型 | 串 |
默认 | '样品' | |
选项 | “样本”,“系统” | |
描述 | 确定播放器音序器的定时源。 “采样”使用采样时钟(已输出多少音频)来对事件进行排序,在这种情况下,音频与MIDI事件同步。 “系统”使用系统时钟,音频和MIDI不能完全同步。 |
而不是如本节所述创建音频驱动程序 加载和播放MIDI文件 人们可能会选择使用文件渲染器,这是合成MIDI文件的最快方法。
Various output files 类型s are supported, 如果 compiled with libsndfile. Those can be specified via the settings
object as well. Refer to the documentation of the audio.file.*
选项.
FluidSynth也可以直接从内存中的缓冲区播放MIDI文件。如果需要从流(例如stdin,网络或高级文件接口)中播放文件,则可以先将整个文件加载到缓冲区中,然后再使用此方法。使用与上述相同的技术,而不是调用 fluid_player_add(),将其加载到内存中并调用 fluid_player_add_mem() 代替。一旦您将缓冲区传递给 fluid_player_add_mem(),它已被复制,因此您可以再次使用它或立即释放它(如果分配了它,则有责任释放它)。
MIDI路由器是MIDI输入后面的另一个处理层。它处理传入的MIDI事件并为合成器生成控制事件。它可用于在将事件发送到合成器之前过滤或修改事件。创建后,MIDI路由器是透明的,仅传递所有MIDI事件。必须添加路由器“规则”以实际使用其功能。
MIDI路由器用法的一些示例:
MIDI驱动程序API在midi线程和合成器之间有清晰的分隔。这为添加Midi路由器模块打开了大门。
来自MIDI播放器的MIDI事件不会通过MIDI路由器。
与使用MIDI文件播放器相比,FluidSynth的音序器可以更灵活地播放MIDI事件,而MIDI文件播放器希望将事件存储为标准MIDI文件。使用定序器,您可以逐一提供事件,并提供可选的时间戳以进行调度。
客户端程序应首先使用函数初始化音序器实例 new_fluid_sequencer2()。有一个补充功能 delete_fluid_sequencer() 删除它。创建音序器实例后,可以使用以下方式注册目标 fluid_sequencer_register_fluidsynth() 用于合成器目标,并且可以选择使用 fluid_sequencer_register_client() 为客户端目标提供合适的回调函数。可以使用取消注册 fluid_sequencer_unregister_client()。初始化后,可以通过以下方式发送事件 fluid_sequencer_send_now() 并计划与未来 fluid_sequencer_send_at()。注册函数返回标识符,可以使用以下命令将其用作事件的目的地 fluid_event_set_dest().
功能 fluid_sequencer_get_tick() 返回当前的播放位置。程序可以使用来选择以毫秒为单位的新时标 fluid_sequencer_set_time_scale().
下面的示例使用Fluidsynth音序器实现一种音乐盒。 FluidSynth内部时钟用于安排音符的重复序列。下一个序列是使用触发回调函数的计时器事件在当前序列结束之前提前安排的。调度时间始终是绝对值,以避免滑移。
Shell界面允许您将简单的文本命令发送到合成器,解析命令文件或从stdin或其他输入流中读取命令。要查找当前支持的命令列表,请检查fluid_cmd.c文件或在fluidsynth命令行外壳中键入“ help”。
shell提示 | 类型 | 串 |
默认 | ” | |
描述 | 在转储模式下,我们将提示设置为“”。 ui无法轻松处理以cr结尾的行。更改提示不能通过命令完成,因为当前的shell无法处理空参数。 | |
shell.port | 类型 | 数 |
默认 | 9800 | |
最小-最大 | 1-65535 | |
描述 | 该外壳程序可以在客户端/服务器模式下使用。此设置控制服务器使用哪个TCP / IP端口。 |