TiXL 默认音频输入设备指南：让实时动效项目跨机器可移植的 WASAPI 输入选择机制-开发者社区

TiXL 默认音频输入设备指南：让实时动效项目跨机器可移植的 WASAPI 输入选择机制

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3

导读

TiXL（tooll3）是一款用于创建实时动态图形的开源软件，它的一大特色是让项目直接响应现场音频——麦克风、线路输入（line-in）或 "What You Hear" 回环（loopback）设备。本指南围绕audio-input-device-default手动测试场景，系统讲解"默认音频输入设备"这一关键机制：如何在项目中保持输入设备为默认（跟随每台机器当前选中的麦克风或线路输入），又如何在需要时把项目钉死到某一个具体设备；默认选择只记忆在本机、不写入项目文件，从而保证你分享出去的项目在其他人的机器上依然开箱即用。读完本文，你将掌握该功能在项目播放设置与全局设置之间的联动关系、其底层 WASAPI 设备解析逻辑，以及一套可复现的验证流程。

功能背景：项目如何响应现场音频

在 TiXL 中，项目可以通过外部音频输入实时驱动动态图形（例如节奏同步、音频反应特效）。项目的音频输入由两类设置共同决定：

项目级设置：保存在项目文件（CompositionSettings）中，跟随项目走；
机器级设置：保存在本机（CoreSettings）中，不随项目迁移。

文档audio-input-device-default所验证的正是这两种设置的边界：默认情况下，项目引用"这台机器当前的默认输入"，使共享项目具备可移植性；当你需要固定使用某个设备时，项目级设置又能显式覆盖默认值。这一设计在源码中有明确注释印证——Core/IO/CoreSettings.cs：

Machine-specific WASAPI input device used when a project leaves its AudioInputDeviceName empty ("use default input"). Kept out of the project file so shared projects stay portable.

即：机器相关的 WASAPI 输入设备保存在LocalAudioInputDeviceName字段中，刻意不写入项目文件，以保证共享项目的可移植性。

前置条件

进行本文的验证与使用前，请确认：

已打开一个 TiXL 项目；
本机至少有一个可用音频输入（麦克风、线路输入，或 "What You Hear"/loopback 设备）。

核心验证流程：六步走

以下步骤完整复现audio-input-device-default手动测试场景。该场景的 id 为audio-input-device-default，属于project-settings范围，标签为[user, essential, audio]，随 TiXL 4.2 版本加入。

第一步：将项目切换到外部音频设备

操作：打开 [ui:ProjectSettings|project play settings]（时间线工具栏中的齿轮图标）。如需要，勾选 "Specify settings for <project>"，然后将Audio Source设置为External Device。

预期结果：

出现外部设备控件（Sync Mode、BPM、增益、输入电平表、Input Device）；
Input Device下拉框显示Default Audio Input。

在源码层面，Audio Source下拉框对应CompositionSettings.AudioSources枚举，其取值为ProjectSoundTrack与ExternalDevice（见 Core/Settings/CompositionSettings.cs）。项目播放设置窗口中的 "Project Setup" 区域正是该枚举的 UI 呈现：Animation模式映射到ProjectSoundTrack（项目配乐），ExternalDevice模式才暴露外部设备控制项（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs）。

第二步：默认项下方出现"机器本地设备选择器"

操作：保持Input Device为Default Audio Input，直接看向下拉框正下方。

预期结果：

出现第二个下拉框，标签为Default Device；
出现一条提示，说明该选择按机器存储，保证共享项目可移植。

该下拉框由AudioDeviceSelector.DrawLocalDefaultDeviceCombo绘制，其数据源是CoreSettings.Config.LocalAudioInputDeviceName，切换后立即写入CoreSettings并保存（见 Editor/Gui/Audio/AudioDeviceSelector.cs）。下方的提示文本在项目设置窗口源码中为：

"Stored per machine, not in the project. Set this once and shared projects work everywhere."

（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs）。

第三步：选择本机的默认输入

操作：打开Default Device下拉框，选择一个真实有信号的输入设备（对着麦克风说话，或对 loopback 设备播放音频）。

预期结果：

Input Level电平表随输入信号响应；
关闭并重新打开播放设置后，选择仍然保留。

电平表由AudioLevelMeter.DrawAbsoluteWithinBounds绘制，其数值来自WasapiAudioInput.DecayingAudioLevel乘以增益系数（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs）。设备选择会在变更时调用AudioEngine.OnAudioDeviceChanged()使音频引擎即时切换到新设备（见 Editor/Gui/Audio/AudioDeviceSelector.cs）。

第四步：默认设置不会被写入项目

操作：保存并关闭项目。打开 [ui:Settings] → Audio，将Default Input Device改为另一个输入，然后重新打开该项目。

预期结果：

项目的音频现在跟随新的机器默认值——它没有记住你之前选的具体设备。（共享项目在其他机器上的行为相同：使用那台机器的默认值，而不是你的。）

这正是可移植性设计的核心：项目文件中的AudioInputDeviceName保持为空字符串，实际设备名只存在于本机CoreSettings。运行时由WasapiAudioInput.ResolveInputDeviceName完成解析——空的项目设备名回退到机器级配置，非空则视为显式覆盖（见 Core/Audio/WasapiAudioInput.cs）。

第五步：同一设置驱动全局设置窗口

操作：打开Settings → Audio，滚动到Default Input Device。

预期结果：

Device下拉框显示与播放设置中相同的设备；
在此处修改，会立即反映到项目播放设置的Default Device下拉框中。

全局设置窗口与项目设置窗口共用同一个AudioDeviceSelector组件，二者都读取/写入同一个CoreSettings.Config.LocalAudioInputDeviceName字段，因此天然保持同步（见 Editor/Gui/Audio/AudioDeviceSelector.cs 的类注释：该选择器是"project settings and the global settings window"共享的 WASAPI 输入设备选择器）。

第六步：项目仍可显式覆盖为具体设备

操作：回到项目播放设置，打开Input Device并选择某个具体设备名（除Default Audio Input以外的任何项）。

预期结果：

Default Device选择器消失——项目现在固定使用你点名的设备；
保存、关闭并重新打开：项目仍使用该确切设备，即使机器默认值已改变。这是项目有意覆盖默认值的行为；
将Input Device切回Default Audio Input，则恢复跟随机器默认值。

源码中，项目设备下拉框由AudioDeviceSelector.DrawProjectDeviceCombo绘制：空字符串代表 "Default Audio Input"，其余选项是具体的 WASAPI 设备名，选择后写入playback.AudioInputDeviceName（见 Editor/Gui/Audio/AudioDeviceSelector.cs）。在项目设置窗口中，当设备名非空时会提供一个"恢复默认"按钮（##resetInputDevice），点击后清空设备名、回到默认模式（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs）。

源码级原理解析：两级设备解析

要真正理解这套机制，需要看清运行时如何决定"从哪个设备采集音频"。核心入口是WasapiAudioInput.StartFrame，它在每一帧检查是否需要为 FFT 分析采集音频：

var wantsCaptureForFft = settings.Playback.AudioSource == CompositionSettings.AudioSources.ExternalDevice; var wantsCaptureForRecording = _isCaptureNeededForRecording; ... var deviceName = ResolveInputDeviceName(settings.Playback.AudioInputDeviceName);

（见 Core/Audio/WasapiAudioInput.cs）关键点有两处：

只有ExternalDevice模式才触发 FFT 采集：AudioSource为ProjectSoundTrack时，如果没有录音会话，采集会停止；
设备名解析是两级的：ResolveInputDeviceName把空的项目级设备名映射到机器级LocalAudioInputDeviceName。

ResolveInputDeviceName的完整实现：

public static string ResolveInputDeviceName(string projectDeviceName) { return string.IsNullOrEmpty(projectDeviceName) ? CoreSettings.Config.LocalAudioInputDeviceName ?? string.Empty : projectDeviceName; }

（见 Core/Audio/WasapiAudioInput.cs）这段代码就是整个可移植性设计的"翻译器"：项目要什么（projectDeviceName）→ 实际用什么（返回值）。

设备列表本身是懒加载的：首次访问WasapiAudioInput.InputDevices时才调用InitializeInputDeviceList()枚举系统 WASAPI 输入设备（见 Core/Audio/WasapiAudioInput.cs）。在 UI 层面，设备行由DrawDeviceRows遍历InputDevices渲染，悬停时还会通过反射展示WasapiDeviceInfo的完整属性（设备名、通道、采样率等）作为 tooltip（见 Editor/Gui/Audio/AudioDeviceSelector.cs）。

采集启动后，WASAPI 会使用设备的原生混音频率和最小更新周期配置 BASS，并注册ProcessDataCallback做异步音频数据处理（见 Core/Audio/WasapiAudioInput.cs）。音频系统的缓冲参数定义在 Core/Audio/AudioConfig.cs：混音器采样率MixerFrequency运行时跟随设备（默认 48000Hz）、播放缓冲 100ms、设备缓冲 20ms、FFT 缓冲 1024、频带数 32，这些常量共同决定了音频分析与视觉响应的延迟与精度。

两个 AudioSource 模式的职责划分

模式	用途	是否触发外部采集
`ProjectSoundTrack`	项目内置配乐（soundtrack clips）驱动时间线	否（除非有录音会话）
`ExternalDevice`	外部音频输入驱动实时动效、节拍同步	是（FFT 分析 + 电平表）

值得注意的是，即使AudioSource为ProjectSoundTrack，只要存在活跃的录音会话（_isCaptureNeededForRecording），系统仍会启动采集——此时若无配置设备名则静默回退到第一个可用输入设备，以保证录音仍有音频（见 Core/Audio/WasapiAudioInput.cs）。

播放设置中与输入相关的其他参数

在项目播放设置的 Audio 区域，除了设备选择外，还有一组与输入信号相关的参数（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs）：

Resync Threshold（0.001–0.1s，默认范围建议 0.02–0.05s）：音频播放与动画漂移超过该阈值时触发重新同步；
Main Volume（0–10）：项目整体输出音量，同时同步到 soundtrack 与 operator 音量字段；
Gain（0.01–100，默认 1）：调整输入信号增益，适用于现场输入电平波动的场景；
Decay（0.001–1，默认 0.9）：控制 [AudioReaction] 在 AttackMode 下的衰减影响，取值高度依赖输入信号的风格、响度与变化；
Level：输入电平表，实时反映AudioGainFactor × DecayingAudioLevel。

与相关文档的衔接

该功能的整体使用场景可参考 LivePerformances.md（文档 frontmatter 中的 related-help 指向）；
若项目设备名指定了一个当前不可用的设备，播放设置窗口会以警告色显示(NOT FOUND)标记（见 Editor/Gui/Windows/TimeLine/ProjectSettingsWindow.cs），提示设备缺失，但不会阻止项目打开——这也是默认设备机制存在的意义之一：共享项目不依赖对方机器的具体设备名。

总结与最佳实践

追求可移植性：保持Input Device = Default Audio Input，只在Settings → Audio → Default Input Device中设置本机默认设备。这样项目文件中的AudioInputDeviceName保持为空，在任何机器上都会自动跟随该机的默认输入；
需要固定设备（如演出机位固定）：在项目播放设置中直接选择具体设备名，项目将无视机器默认值、坚持使用该设备，直到你切回Default Audio Input；
多机部署：为每台机器分别配置一次本机默认设备，同一项目即可在多台机器上一致工作，无需改项目文件；
排查输入无信号：先确认Audio Source为External Device，再看Input Device是否为Default Audio Input且机器默认设备（Default Device/ Settings → Audio）指向了一个真实有信号的设备，最后观察Level电平表是否响应。