• 音视频

本指南面向已完成 BUILD.md 基础编译安装、希望进一步掌控播放行为的 Shairport Sync 用户。读完本文，你将掌握配置文件/etc/shairport-sync.conf的完整用法：如何把音频输出到指定的硬件 DAC、如何用 DAC 内置混音器实现即时响应的音量与静音控制、如何针对 Raspberry Pi 等平台优化音量范围，以及如何通过延迟偏移、重同步阈值和漂移容差三个核心参数让多设备同步播放更稳定。文章全部内容以仓库中的 ADVANCED TOPICS/InitialConfiguration.md 为主体，并结合 scripts/shairport-sync.conf 样例配置与 shairport.c、audio_alsa.c、player.c 源码进行印证。

配置文件：一切高级设置的入口

按照 BUILD.md 完成安装后，Shairport Sync 已经可以基本工作，但默认行为（例如输出到系统default设备）不一定是最优的。若要获得更多控制力——比如指定某个 DAC，或让 AirPlay 直接操作 DAC 的音量——推荐使用配置文件，也可使用命令行选项（主要用于向后兼容）。

Shairport Sync 从配置文件读取设置，Linux 下默认位置为/etc/shairport-sync.conf，FreeBSD 下为/usr/local/etc/shairport-sync.conf。当你执行sudo make install时，一个名为shairport-sync.conf.sample的样例配置会被安装或更新。该样例（仓库中的 scripts/shairport-sync.conf）包含所有设置分组和全部可用设置项，但每一项都被注释掉（注释以//开头），因此默认值生效。文件内附有每项设置的详细解释、实用提示与建议。

提示：配置文件采用类似 C 语言的块结构语法，//之后的内容为注释。修改配置后必须重启 Shairport Sync 才会生效；如果出现语法错误，Shairport Sync 将无法启动并在日志中留下错误信息（错误消息还会精确到行号，参见 shairport.c 中对config_error_line的使用）。

指定输出设备与混音器控制

为什么应该绕开default设备

默认情况下，Shairport Sync 接收的音频会被送往default设备。但这样做有两个潜在问题：

1. default设备在把音频送往硬件之前可能做了额外的处理（如重采样、混合），损害保真度；
2. 如果让 Shairport Sync 使用真实硬件设备的混音器来控制音量，它能获得完整的音量范围控制权，并让音量/静音命令获得即时响应。

用shairport-sync -h发现硬件设备

要列出系统上的硬件 DAC，可参考shairport-sync -h的输出。以下是文档中给出的 Raspberry Pi 3B 系统示例：

Usage: shairport-sync [options...] or: shairport-sync [options...] -- [audio output-specific options] ... [snip] ... Settings and options for the audio backend "alsa": -d output-device set the output device, default is "default". -c mixer-control set the mixer control name, default is to use no mixer. -m mixer-device set the mixer device, default is the output device. -i mixer-index set the mixer index, default is 0. hardware output devices: "hw:Headphones" "hw:sndrpihifiberry" "hw:vc4hdmi" ... [snip] ...

该系统中存在三个硬件输出设备："hw:Headphones"、"hw:sndrpihifiberry"和"hw:vc4hdmi"。注意hw:前缀正是源码识别"真实硬件设备"的标志——在 audio_alsa.c 中，Shairport Sync 通过检查设备名是否以hw:开头来判断是否可启用更精确的定时（precision timing）。

查找混音器控制名称

借助alsamixer（或aplay）等工具可以检查某个输出设备对应的音量控制混音器名称。例如上述第一个设备的混音器名为"Headphone"。文档还提到了dacquery这类辅助工具，但核心操作都可以用系统自带的 ALSA 工具完成。

在alsa段中写入设置

找到设备名与混音器名后，在配置文件的alsa段写入如下内容：

... alsa = { output_device = "hw:Headphones"; // the name of the alsa output device. Use "shairport-sync -h" to discover the names of ALSA hardware devices. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc. mixer_control_name = "PCM"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software. ... }

务必取消需要生效条目的注释（去掉行首的//），修改后重启 Shairport Sync。

这些设置项在源码中的解析位置清晰可见：alsa.output_device、alsa.mixer_device、alsa.mixer_control_name与alsa.mixer_control_index分别通过config_lookup_non_empty_string/config_lookup_int读取（参见 audio_alsa.c）。此外，源码还指出旧的mixer_type设置已被弃用——只要指定mixer_control_name就会自动选择硬件混音器（audio_alsa.c）。

重要限制：如果你的系统运行着 PipeWire 或 PulseAudio 之类的音频服务（大多数桌面 Linux 都有其一），你可能无法直接访问声音硬件，只能使用default输出。此时请改用pipewire或pulseaudio后端，详见下文。

深入了解配置设置：分组与常用标签

配置文件中的设置按分组组织。以下是文档中的核心示例：在general组中用name标签设置服务名称，用password标签设置密码：

general = { name = "Front Room"; password = "secret"; // ... other general settings };

注意两点：

• password只对经典（classic）AirPlay 有效，AirPlay 2 不使用该密码。
• 绝不要用重要密码作为 AirPlay 密码——它以明文形式存放在 Shairport Sync 配置文件中，完全暴露，极易被读取。

如果编译了多个音频后端而未在general组指定，默认使用alsa后端。要改用 PipeWire，在general组设置：

output_backend = "pipewire";

alsa组用于指定输出设备属性，最直观的标签是output_device。文档特别强调以下两个设置对最大化性能非常重要：如果音频设备自带可用于控制音量的混音器，Shairport Sync 就能用它获得对音量与静音命令的即时响应，同时把部分工作从处理器卸载到硬件上：

• mixer_control_name：指定混音器音量控制的名称；
• mixer_device：指定混音器所在的位置。默认混音器就在output_device上，只有当混音器位于别处时才需要设置。典型场景是output_device指定的是设备（device）而非声卡（card）——因为混音器通常关联于声卡而非设备。例如想使用声卡hw:0上的输出设备5、混音器音量控制名为PCM：

alsa = { output_device = "hw:0,5"; mixer_device = "hw:0"; mixer_control_name = "PCM"; // ... other alsa settings };

pipewire组用于设置 PipeWire 后端相关参数，其中可以指定显示在"声音"控制面板中的"应用程序名称"（application_name），以及node_name、sink_target等（详见 scripts/shairport-sync.conf 的pipewire段）。

说明：Shairport Sync 也可以从命令行选项读取配置，这主要是为了向后兼容，但有时仍有用。在可能的情况下，推荐使用配置文件方式——shairport.c 中明确注释：命令行参数优先于配置文件设置，是 UNIX 惯例。

Raspberry Pi：内置音频 DAC 与volume_range_db

在 Raspberry Pi 上使用内置音频 DAC 及其硬件混音器，只需在alsa段设置如下：

alsa = { output_device = "hw:Headphones"; // the name of the alsa output device. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc. mixer_control_name = "PCM"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software. // ... other alsa settings

（记得删除每行开头的//取消注释。）修改后重启 Shairport Sync 或直接重启系统。

树莓派内置 DAC 有一个已知问题：它声明了非常大的混音器音量范围——从 -102.38 dB 一直到 +4 dB，跨度达 106.38 dB，但实际可用区间只有顶部约 60 dB。为了充分利用它，建议在general组使用volume_range_db设置，让 Shairport Sync 只使用 DAC 混音器声明范围的最顶部。例如设为 60，就只使用顶部 60 dB 区间：树莓派上最大音量为 +4 dB、最小音量为 -56 dB，低于 -56 dB 即触发静音。

从用户视角看，该设置的效果是把"最小可用音量"一直延伸到音量条的最底部，而不是让最小可用音量全部挤在接近最大音量的位置。

该参数在源码中有明确的取值范围校验：general.volume_range_db必须介于30 到 150 dB之间，否则 Shairport Sync 直接终止并报错；不设置则使用混音器原生范围（shairport.c）。样例配置注释同样注明：范围 30 到 150 dB，注释掉则使用混音器原生范围（scripts/shairport-sync.conf 的volume_range_db注释）。

完整配置示例

以下是文档提供的多组可直接照抄修改的完整配置示例，覆盖不同硬件组合：

最简示例——服务命名为 "Joe's Stereo"，音频输出到hw:0：

general = { name = "Joe's Stereo"; }; alsa = { output_device = "hw:0"; };

树莓派内置声卡（设备 hw:0）驱动耳机插孔——为获得真正的静音和对音量/暂停命令的即时响应，务必使用硬件音量控制：

general = { name = "Mike's Boombox"; }; alsa = { output_device = "hw:0"; mixer_control_name = "Headphone"; };

Topping TP30 数字功放（内置 USB DAC，作为音频设备hw:1连接）：

general = { name = "Kitchen"; }; alsa = { output_device = "hw:1"; mixer_control_name = "PCM"; };

树莓派上的廉价 "3D Sound" USB 声卡（仅立体声输出与输入）：

general = { name = "Front Room"; }; alsa = { output_device = "hw:1"; mixer_control_name = "Speaker"; };

树莓派上的第一代 Griffin iMic：

general = { name = "Attic"; }; alsa = { output_device = "hw:1"; mixer_control_name = "PCM"; };

NSLU2 上驱动第一代 Griffin iMic（未指定输出设备，只指定混音器控制名）：

general = { name = "Den"; }; alsa = { mixer_control_name = "PCM"; };

NSLU2 上驱动 "3D Sound" USB 声卡：

general = { name = "TV Room"; }; alsa = { mixer_control_name = "Speaker"; };

使用 PulseAudio 后端（output_backend = "pa"）：

general = { name = "Zoe's Computer"; output_backend = "pa"; };

提示：要发现混音器控制名称，可用amixer、alsamixer或类似工具查询（文档同时推荐了dacquery工具）。对alsa后端而言，访问硬件音量控制才能得到真正的静音、对音量调节和暂停命令的即时响应。

Latency：延迟与补偿

**延迟（Latency）**定义为声音信号的原始时间戳到该信号实际出现在音频输出设备（通常是 DAC）输出端的精确时间差，与计算机内部任何延迟、处理时间无关。

Shairport Sync 使用来源端提供的延迟值，通常是 2 秒或略高于 2.25 秒，一般无需改动。从源码看，Shairport Sync 会自动从来源获取正确的延迟（shairport.c 明确注释："Shairport Sync gets the correct latency automatically from the source"），因此旧的固定延迟设置已被弃用。

真正需要调整的场景是：当你要与自带固有延迟的扬声器系统（典型如环绕声家庭影院系统）同步时。此时可以用对应后端（通常为alsa）的audio_backend_latency_offset_in_seconds设置补偿固定延迟——该值以秒为单位，正值表示输出延后，负值表示提前。例如输出设备本身有 100 ms 延迟，则设为 -0.1：

general = { audio_backend_latency_offset_in_seconds = -0.1; };

样例配置中的注释给出了同样的使用建议："E.g. if the output device, e.g. a soundbar, takes 100 ms to process audio, set this to -0.1 to deliver the audio to the output device 100 ms early, allowing it time to process the audio and output it perfectly in sync."（参见 scripts/shairport-sync.conf）。

Resynchronisation：重同步机制

Shairport Sync 会主动维持与来源的同步。如果同步丢失——比如来源繁忙或网络拥塞——Shairport Sync 会静音输出并执行重新同步。

丢失同步的判定阈值非常保守，为0.050 秒（50 ms）：即实际时间与期望时间之差超过 50 ms 才触发重同步；更小的偏差通过插入或删除音频帧来纠正。在 player.c 中可以确认这一机制：当归一化的同步误差时间centered_sync_error_time的绝对值超过config.resync_threshold，且误差样本连续越界时，才计为需要重同步。

• 可通过general组的resync_threshold_in_seconds调整阈值，设为 0 可完全关闭重同步。
• 旧的命令行选项-r/--resync（以帧为单位）已被弃用并忽略，源码会提示改用resync_threshold_in_seconds（shairport.c）。

Tolerance：漂移容差

播放同步允许在纠正前发生小幅"漂移"，默认容差为0.002 秒（2 ms）。容差越小，越容易发生过度纠正（overcorrection）——即做出的插入/删除纠正比保持流同步严格所需的多。

要监控纠正水平，可在diagnostics组开启statistics设置，日志会输出"Net Sync PPM"（净纠正）与"All Sync PPM"（总插入加删除量）等统计项（player.c）。纠正量不应大幅超过净纠正量——若"All Sync PPM"远大于"Net Sync PPM"，说明系统在来回折腾，容差可能过小。

• 可通过general组的drift_tolerance_in_seconds调整容差（默认 0.002）。
• 旧的--tolerance命令行选项同样已弃用，源码会提示改用配置文件设置（shairport.c）。

命令行参数：配置文件不覆盖的选项

Shairport Sync 仍支持命令行参数，但较新的设置只能通过配置文件使用。完整信息可阅读 man 手册页（仓库中的源文件为 man/shairport-sync.1.xml）。除下列选项外，几乎所有命令行选项都能用配置文件设置替代：

• -c：指定配置文件的位置（源码中对应{"configfile", 'c', POPT_ARG_STRING, ...}，见 shairport.c）；
• -V：显示 Shairport Sync 版本信息后退出；
• -d：让 Shairport Sync 正确守护进程化（在后台运行），可能需要 sudo 权限；
• -k：终止现有的 Shairport Sync 守护进程，同样可能需要 sudo 权限（源码中通过 PID 文件发送 SIGTERM 并等待其退出，见 shairport.c）。

System V init 脚本/etc/init.d/shairport-sync只使用最简参数-d——其全部作用就是让程序进入守护模式，其余设置全部从配置文件读取。

小结与下一步

初始配置的核心要点可归纳为四条：第一，所有持久化设置都应写入/etc/shairport-sync.conf（或 FreeBSD 的/usr/local/etc/shairport-sync.conf），语法错误会导致启动失败并在日志中留下带行号的错误信息；第二，通过shairport-sync -h、alsamixer/aplay找出硬件设备与混音器名称，在alsa段配置output_device与mixer_control_name，即可绕过default设备、获得硬件级即时音量响应；第三，对 Raspberry Pi 这类声明超大音量范围的 DAC，用general段的volume_range_db（30–150 dB）限定实际使用区间；第四，用audio_backend_latency_offset_in_seconds补偿音箱固有延迟、用resync_threshold_in_seconds（默认 0.050 s）控制重同步、用drift_tolerance_in_seconds（默认 0.002 s）控制漂移容差，并借助statistics监控纠正水平。完成以上配置后，可继续阅读 ADVANCED TOPICS/AdjustingSync.md 深入了解同步调优，或参考 CONFIGURATIONFILECHANGES5.md 了解版本 5 配置文件的变化，以及 man/shairport-sync.1 获取全部选项说明。

• 音视频