TiXL 默认音频输入设备指南让实时动效项目跨机器可移植的 WASAPI 输入选择机制【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3导读TiXLtooll3是一款用于创建实时动态图形的开源软件它的一大特色是让项目直接响应现场音频——麦克风、线路输入line-in或 What You Hear 回环loopback设备。本指南围绕audio-input-device-default手动测试场景系统讲解默认音频输入设备这一关键机制如何在项目中保持输入设备为默认跟随每台机器当前选中的麦克风或线路输入又如何在需要时把项目钉死到某一个具体设备默认选择只记忆在本机、不写入项目文件从而保证你分享出去的项目在其他人的机器上依然开箱即用。读完本文你将掌握该功能在项目播放设置与全局设置之间的联动关系、其底层 WASAPI 设备解析逻辑以及一套可复现的验证流程。功能背景项目如何响应现场音频在 TiXL 中项目可以通过外部音频输入实时驱动动态图形例如节奏同步、音频反应特效。项目的音频输入由两类设置共同决定项目级设置保存在项目文件CompositionSettings中跟随项目走机器级设置保存在本机CoreSettings中不随项目迁移。文档audio-input-device-default所验证的正是这两种设置的边界默认情况下项目引用这台机器当前的默认输入使共享项目具备可移植性当你需要固定使用某个设备时项目级设置又能显式覆盖默认值。这一设计在源码中有明确注释印证——Core/IO/CoreSettings.csMachine-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 DeviceInput 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.csResync Threshold0.001–0.1s默认范围建议 0.02–0.05s音频播放与动画漂移超过该阈值时触发重新同步Main Volume0–10项目整体输出音量同时同步到 soundtrack 与 operator 音量字段Gain0.01–100默认 1调整输入信号增益适用于现场输入电平波动的场景Decay0.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电平表是否响应。这套项目级空设备名 机器级真实设备名的两级设计是 TiXL 在现场演出可移植性与设备确定性之间做出的取舍理解它之后无论是要分享项目给他人还是为固定演出环境锁定设备都能做到心中有数。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考