帮助
MusicBee UPnP Plugin 的用途
MusicBee 的一个开源插件，可将您的音乐库连接到家庭网络上的 UPnP/DLNA 设备——手机、智能电视、高保真流媒体播放器、网络扬声器——无需云服务，也无需登录。它是 Steven Mayall 原版 UPnP 插件的一个分支，旨在让浏览一个庞大、多样化的音乐库从其他设备上变得愉快。
此分支与普通 UPnP 服务器有两点不同，这也是选择它的原因：
- 它发布 MusicBee 的全部内容——而不仅仅是“音乐”。 您的 Filters、Podcasts、Audiobooks、Radio 电台、Inbox 和您的 Playlists 都作为它们自己的可浏览容器出现在其他设备上，与音乐并列。大多数服务器只显示一个扁平的音乐库，别无其他。
- 每个节点都可以单独显示、隐藏和塑形。 您决定设备看到哪些节点，并为每个节点指定自己的发现路径——您深入浏览它的路线（Album Artist → Album → Tracks、扁平的曲目列表、按 Genre、按 Year…）。一个包含 300,000 首曲目的音乐库最终会像一个组织良好的库一样浏览，而不是一个扁平的数据转储。
在这两个主要思想之下，该插件围绕一个结构性事实进行组织：MusicBee 可以扮演三种不同的网络角色，并且设置对话框中的每个屏幕都属于其中之一。弄清这三个角色，对话框的其余部分就会不言自明：
- Server — 其他设备浏览 MusicBee 库并从中拉取曲目。这是上述两个主要功能所在。
- Renderer — MusicBee 成为其他应用程序可以播放到的目标，就像网络扬声器一样。
- Control point — MusicBee 将自己的音频输出到远程扬声器或流媒体播放器。
您可以使用一个角色或全部三个角色。只开启您需要的功能。在本指南中，每个设置都在其所属功能的旁边进行解释——没有单独的“设置”列表供交叉引用。
安装
- 从发布页面下载
mb_UPnP_yaiol.dll。 - 将其复制到您的 MusicBee 插件文件夹中，通常是
C:\Users\<您>\AppData\Roaming\MusicBee\Plugins\。 - 重启 MusicBee。
- 打开 编辑 → 首选项 → 插件，找到 MusicBee UPnP Plugin，然后点击 配置。
yaiol DLL 具有独特的文件名，因此它可以与原始插件一起在磁盘上运行而不会发生冲突。
服务器 — 其他设备浏览您的媒体库
UPnP 是一种音频设备在本地网络上相互发现和驱动的协议，其中每个参与者都扮演一个明确的角色。启用服务器角色（UPnP 服务器开关）后，MusicBee 扮演媒体服务器角色：它响应局域网上的发现请求，并将其媒体库提供给任何请求的设备。从其他设备上，您会看到一个媒体树并点击播放；音频直接从 MusicBee 的内置 HTTP 服务器流式传输到设备。MusicBee 只是源 — 其他设备负责控制。
为什么使用它。 它将存储您整个收藏的 PC 变成其他所有设备都可以访问的网络源，而无需复制文件或登录任何内容。这是插件中投入最大的部分，也是两个主要功能所在 — 您发布什么（下文）以及每个节点如何形成。
何时关闭它。 仅当您从不从其他设备浏览 MusicBee 时。该角色独立于其他两个角色；您可以提供媒体库，同时仍关闭渲染器和控制点角色。
一些服务器范围的设置与开关并存：其他设备在其列表中显示的服务器名称，MusicBee 绑定的网络接口和端口（请参阅在网络上相互发现），以及服务器一次将服务的最大同时流数量的最大连接数限制。
设置
| 控件 | 功能 |
|---|---|
| UPnP 服务器：允许 UPnP 设备浏览和播放 MusicBee 媒体库中的内容 | 服务器角色的主开关 — 允许 UPnP 设备浏览 MusicBee 媒体库并从中播放。 |
| 服务器名称 | 其他设备发现 MusicBee 时显示的名称。 |
| 最大连接数 | 服务器将同时提供的最大文件流数（默认 16，范围 1–256）。如果设备发出许多并行请求导致**⚠ 最大连接数**徽章亮起，请提高此值。重启后生效。 |
| 更新 MusicBee 中的播放统计 | 将通过 UPnP 播放的曲目计入 MusicBee 的播放次数和上次播放时间戳。 |
发布 MusicBee 的所有内容，而不仅仅是音乐
这是此分支的两个主要功能中的第一个。普通的 UPnP 服务器向网络提供一个单一的扁平“音乐”库。而此服务器则将 MusicBee 组织的所有内容区域 显示为浏览设备上的独立顶级容器。
MusicBee 可以发布七种内容
当设备浏览 MusicBee 时，它所到达的根目录可以并排提供所有这些内容：
- 音乐 — 您的主音乐库，可按您喜欢的方式组织（请参阅下面的 发现路径）。
- 筛选器 — 您已在 MusicBee 主视图顶部使用的筛选器选项卡（
Music、ALL、FAV、爵士乐筛选器、古典乐筛选器，无论您设置了什么）会显示为入口点，反映您对音乐库的现有思考方式。筛选器从 MusicBee 本身使用的相同文件中实时读取，因此无需配置即可保持同步。 - 播客 — 您的播客订阅，每个订阅都会打开其剧集，并带有订阅封面图。
- 有声读物 — MusicBee 的有声读物类别。
- 广播 — 您保存的互联网广播电台。
- 收件箱 — MusicBee 的收件箱，包含新添加但尚未归档的曲目。
- 播放列表 — 您的 MusicBee 播放列表。
由于这些内容直接来自 MusicBee，因此无需单独设置 — 在 MusicBee 中订阅播客或添加电台后，下次设备浏览时即可从网络访问。每个内容是否实际出现以及其呈现形式，是下一个功能的工作。
默认情况下，筛选器和播放列表位于各自整洁的包装文件夹中。每个源是否实际显示、它的位置 — 包括将您最常使用的那些固定在浏览根目录的顶部，并与同类项分组 — 以及它所呈现的形状，都由下一个功能按节点决定。
此帮助的早期版本将“无播客根容器”列为限制。这已不再是事实 — 播客像所有其他来源一样发布。
显示、隐藏和调整每个节点
这是第二个主要功能，也是该分支得名的原因。如果您无法控制七个来源，那么发布它们将是噪音——因此每个暴露的节点都可以独立切换、固定到根目录，并拥有自己的发现路径。
您可以在设置对话框的视图选项卡上管理所有这些，该选项卡将整个暴露的树显示为清单。模式始终相同：勾选您要操作的节点，然后使用树旁边的控件一次性设置它们——使它们可见或隐藏，将它们固定到树的顶部，或应用路径模板。因此，您可以暴露音乐、过滤器和播放列表，隐藏收件箱和广播，将您的爵士过滤器固定到根目录，并为播客提供按订阅的形状——每个都独立进行。
显示、隐藏和置顶每个节点
两个开关决定节点是否出现以及出现在何处，这与节点的形状无关。这两个开关都位于“视图”选项卡上，作为三态复选框，作用于您在树中勾选的每个节点：
- 可见 — 设备是否能看到该节点。取消勾选可隐藏节点；它仍保留在您的库中，只是不再被宣传。(因为它作用于已勾选的集合，当您的选择部分可见、部分隐藏时，复选框会显示一个阴影的“混合”状态。) 隐藏的节点在树中会显示为灰色 — 当文件夹内的所有节点都隐藏时，该文件夹也会变灰 — 因此一目了然地知道哪些内容仍然可见。
- 顶层 — 该节点是否也固定在浏览根目录的顶部。固定是累加的：该节点仍会出现在其常规的包装文件夹中，并在根目录顶部获得一个副本，与其同类分组 — 固定的筛选器直接位于筛选器文件夹下方，固定的播放列表直接位于播放列表文件夹下方 — 因此您的快捷方式会与其所属内容保持在一起。固定的节点在对话框中会标有**★**，以便您一目了然地看到哪些节点已被提升。
当过滤器或播放列表置顶到根目录时，可能很难与普通的顶层源区分开来，因此您可以在其显示名称前添加一个简短的前缀（在“库选项”选项卡上设置）。前缀是字面意义的——您输入的任何内容都会原样放在名称前面，因此如果您需要，请包含自己的尾随空格。
操作示例。 您主要通过您的 Jazz 过滤器和您的 Friday Night 播放列表进行导航，两者目前都隐藏在 Filters 和 Playlists 包装文件夹中。
您在视图树中勾选这两个节点，然后点击 Top level。现在，对话框中每个都显示一个 ★。在浏览设备上，它们仍然像以前一样显示在其包装文件夹中，但也在根目录中获得一个副本，每个副本都位于其同类旁边：固定的 Jazz 过滤器直接位于 Filters 文件夹下方，固定的 Friday Night 播放列表直接位于 Playlists 文件夹下方。当过滤器前缀设置为 Filter: 且播放列表前缀设置为 Playlist: 时，这两个固定的副本显示为 Filter: Jazz 和 Playlist: Friday Night —— 与其在包装文件夹中的副本不同，并且每个都位于其同类文件夹旁边。取消勾选其中任何一个的 Top level，其固定的副本就会消失，而包装文件夹中的副本保持不变。
这取代了旧的全局“在根目录公开过滤器”/“在根目录公开播放列表”开关：现在置顶是您对任何源逐个节点做出的选择，而不是过滤器和播放列表的全部或全无切换。
设置
| Control | What it does |
|---|---|
| 可见 | 显示或隐藏每个已勾选的节点。隐藏的节点会保留在您的库中，但不会向设备宣传。当选择部分可见时，显示为阴影的“混合”状态。 |
| 顶层 | 还会将每个已勾选的节点固定在浏览根目录的顶部，并按其类型分组 — 筛选器固定在“筛选器”文件夹下方，播放列表固定在“播放列表”文件夹下方（累加 — 节点也会保留其正常位置）。已固定的节点在对话框中显示 ★。 |
| 筛选器前缀（在根目录时） | 当筛选器固定到根目录时，放置在其名称前面的文字前缀（有助于将固定的副本分组）。 |
| 播放列表前缀（在根目录时） | 当播放列表固定到根目录时，放置在其名称前面的文字前缀。 |
发现路径 — 每个节点的向下钻取路线
发现路径是浏览器在节点内部行走的路线。同一个节点可以呈现为专辑艺术家 → 专辑 → 曲目，或者作为单个扁平曲目列表，或者按流派然后按艺术家分组，或者按年份分组。路径由一个或多个级别（每个级别分组的字段）组成，以一个叶子（最深级别显示的内容 — 专辑及其曲目，或扁平曲目列表）结束。一个节点甚至可以同时携带多条路径，因此它提供了不止一种进入方式。
不同的内容需要不同的形状，错误的形状会使节点无法使用。音乐需要专辑艺术家分组；播放列表需要扁平有序列表；播客需要其订阅。每个节点都能得到正确的答案，因为每个节点都拥有自己的路径。
**示例。**您有一个包含 5,000 首曲目的爵士乐过滤器和一个包含 30 首曲目的“周五之夜”播放列表，两者都已公开。
- 对于爵士乐过滤器，您应用了一个路径为专辑艺术家 → 专辑 → 曲目的模板。在设备上，您向下钻取：艺术家，然后是该艺术家的专辑，然后是专辑的曲目，按唱片和曲目顺序排列。
- 对于播放列表，您改为应用扁平曲目模板。打开它会显示按播放列表顺序排列的 30 首曲目，中间没有艺术家或专辑层 — 这正是播放列表应有的样子。
相同的插件，相同的对话框，两个节点，两种完全不同的形状 — 因为路径是节点的属性，而不是全局设置。您无法在不知道节点携带哪个模板的情况下预测其在设备上的布局；这就是为什么需要详细说明这一点。
节点不仅仅是接收模板的副本 — 它是遵循它。视图树显示每个节点遵循哪个模板，就在节点名称之后，并且在路径选项卡上编辑模板会立即重塑所有遵循它的节点 — 无需逐个节点重新应用。将模板应用于隐藏节点也会使其再次可见：应用是“向我显示这个，以这种形状”的手势，而隐藏则保留在可见复选框中。每个模板行都显示一个实时**（n）*计数，表示遵循它的节点数量，并且只有当该计数为零时才能删除模板 — 当有任何内容遵循模板时，删除按钮将保持禁用状态，因此节点永远不会因删除而成为孤立节点。要确切查看哪些*节点遵循模板，视图树旁边的漏斗按钮会将树过滤到仅显示这些节点；选择另一个模板会重新过滤，关闭漏斗会恢复完整的树。删除未使用的模板现在也有效 — 随附的默认值不再在插件下次加载时悄悄重新创建。
当路径以专辑 → 曲目叶子结束时，您还可以决定什么算作一张专辑。您不是严格按专辑标题分组，而是选择一个或多个字段 — 专辑、排序专辑、年份、专辑艺术家 — 它们共同决定哪些曲目合并成一张专辑，其标题如何读取，以及专辑出现的顺序，每个字段都可以按升序或降序排序。添加专辑艺术家可以将不同艺术家的两张同名专辑分开；添加年份降序排列艺术家的专辑，最新专辑在前。当您按年份分组时，MusicBee 提供两个与其自身镜像的字段 — 年份，完整的日期标签（可以包含 2024-03-15 这样的完整日期），以及年份 (yyyy)，仅四位年份 — 因此选择年份 (yyyy) 会将一年的所有发行版聚集在一起，而不是按确切日期拆分。
默认值是合理的 — 新过滤器按专辑艺术家分组，播放列表和收件箱获得合理的默认值 — 因此对于常见情况，您无需更改任何内容。当您希望特定节点以不同方式呈现时，请使用“视图”选项卡。
设置
您在路径选项卡上构建命名、可重用的路径模板，然后将它们应用于视图选项卡上的节点。
| 控件 | 作用 |
|---|---|
| 应用到已勾选的端点 | 使您在树中勾选的每个节点都遵循当前选定的模板（如果它被隐藏，则重新公开它）。 |
| 全部展开 / 全部折叠 | 展开或折叠整个端点树。 |
| 仅显示符合所选模板的节点 | 漏斗开关：将端点树过滤到仅显示遵循所选模板的节点。选择另一个模板以重新过滤；关闭以恢复完整的树。 |
| 模板 | 正在编辑的命名路径模板。 |
| ↑ / ↓ | 在列表中向上或向下移动选定的模板，以调整模板的呈现顺序。 |
| 分组依据 | 级别分组的字段（例如专辑艺术家）。 |
| 叶节点 | 最深级别显示的内容。 |
| 专辑 → 曲目 (AT) | 叶子模式：专辑 → 曲目 — 钻取专辑以查看其曲目。 |
| 扁平曲目 (T) | 叶子模式：扁平曲目 — 单个扁平曲目列表。 |
| 在每个级别包含[所有曲目] | 在每个级别添加一个**[所有曲目]快捷方式。仅在专辑 → 曲目**模式下显示。 |
| 专辑分组方式： | 定义什么算作一张专辑，其标题如何读取，以及专辑出现的顺序 — 选择一个或多个字段（专辑、排序专辑、年份、专辑艺术家…），每个字段都有自己的升序/降序开关。仅在专辑 → 曲目模式下显示。 |
| 添加 / 移除 | 在模板中添加或删除路径。 |
路径被类型化到它们适合的节点
并非每个字段都对每种节点类型都有意义。广播电台没有专辑或年份；播客剧集有订阅、文件夹和发布日期，但没有专辑艺术家。因此，每个路径属于三个类别之一——标准（您的音乐、过滤器、有声读物、收件箱和播放列表，它们都带有完整的标签）、广播或播客——该类别同时决定两件事：您可以按哪些字段分组，以及该路径可以应用于哪些节点。
在“路径”选项卡上，模板列表分为两部分绘制：“标准”——您的模板所在的位置，以及创建每个新模板的位置——以及一个“保留”部分，其中包含广播和播客模板。当您编辑标准模板时，字段菜单提供所有内容；广播模板只提供电台实际拥有的字段；播客模板只提供剧集拥有的内容——其文件夹、其订阅和其发布年份。在“视图”选项卡上，应用模板只会点亮它适合的节点——其余的会变灰且无法勾选——因此标准路径永远不能落在广播或播客节点上。
事实上，您根本不会对广播或播客应用任何东西：每个都永久与其类别的模板配对。在“路径”选项卡上重塑广播或播客模板，节点会自行跟随；选择保留模板后，“应用”按钮会简单地禁用，因为没有什么可应用的。这可以防止您通过对节点无法填充的字段进行分组而悄悄地生成空内容的路径——而且由于已跟随的模板永远无法删除（参见上面的发现路径），广播和播客模板始终存在以供重塑。
按排序名称归档的艺术家
在任何音乐形状的节点中，艺术家都按排序专辑艺术家标签进行分组和字母排序，而不是按显示名称。这就是让人感到惊讶的地方，下面是具体发生的情况。
示例。 假设一个音轨被标记为：
- 艺术家 =
Bob Dylan- 排序专辑艺术家 =
Dylan, Bob在浏览树中，Dylan 被归档在字母 D 下（来自
Dylan, Bob），而不是在 B 下（来自Bob Dylan）。排序标签同时决定了分组和字母位置，就像高保真浏览器或唱片店会归档它一样。
它是自动的，完全由您现有的 MusicBee 标签驱动 — 无需配置。
多值标签扇出
当一个音轨的专辑艺术家（或流派）包含多个值时，该音轨会分别显示在每个值下，而不是创建一个合并的条目。
示例。 一个音轨的专辑艺术家包含两个值：
yaiol; Ars Ricercata。该音轨会显示在yaiol和Ars Ricercata两者之下——在每个艺术家的分支中各出现一次——而不是在一个虚假的“yaiol; Ars Ricercata”艺术家下。多值艺术家标签的扇出方式与多流派标签相同。
类似于排序名称分组，这是自动且由标签驱动的。
按首字母对长列表进行分组
如果某个层级在手机上滚动起来太长，不方便浏览，它可以按首字母分组 — 在条目上方插入一个 A、B、C……层，这样您就可以先选择一个字母。它是根据模板中的每个字段设置的，从字段的上下文菜单中选择：按首字母拆分 [字段]。对于短列表，请将其关闭；对于列表庞大的层级（通常是艺术家），请将其打开。
将标签作为嵌套树浏览
有些标签使用分隔符将层次结构打包成单个值——例如 Jazz/Cool Jazz 的分组标签，或 Electronic/Ambient/Drone 的自定义流派。默认情况下，整个字符串是一个扁平的条目，因此您在标签中编码的结构被浪费了。将字段标记为分层，插件会根据您选择的分隔符拆分每个值，并将其转换为一个可深入的树——您选择爵士，然后选择冷爵士，与标签的写法完全一致。
您可以在库选项选项卡上进行设置：选择一个字段，输入分隔其级别的一个字符（例如 /），然后将其添加到列表中。然后，无论该字段在任何发现路径中用作分组级别，它都将适用。在分支而不是叶子处标记的曲目——仅标记为 Jazz，没有子流派——会出现在更深分支旁边的带括号的**[爵士]**条目下，因此没有任何内容被隐藏。只包含一个子项的分支会自动折叠（与所有其他地方的单选规则相同），并且 ; 不能用作分隔符——那是 MusicBee 自己的多值分隔符，因此像 Rock; Jazz/Cool Jazz 这样的值会首先拆分为两个标签，然后每个标签都会被深入。
示例。您的曲目带有
Jazz/Cool Jazz、Jazz/Hard Bop和Classical/Baroque等分组标签，以及按分组分组的发现路径。扁平化后，节点列出三个长条目。将分组标记为分层，分隔符为/，相同的节点现在打开为爵士和古典；打开爵士会显示冷爵士和硬波普。仅标记为Jazz的曲目会出现在它们旁边的**[爵士]**条目下。您无法仅凭标签预测此布局——它完全取决于您标记了哪个字段以及使用哪个分隔符——因此值得刻意设置。
设置
| 控件 | 功能 |
|---|---|
| 层级字段 | 渲染为可深入树的字段列表，每个字段都与其一个字符的分隔符配对。选择一个字段，输入分隔符（不是 ;），然后添加它；然后，无论发现路径按该字段分组，该字段都会逐级深入。 |
单选层级自动折叠
当您浏览的某个分组层级只包含一个条目时，插件会跳过它，而不是让您打开一个只包含单个文件夹的文件夹 — 您会直接进入下一个真正的选择。无需配置；它会在所有路径上自动发生。
示例。 您的路径按唱片类型 → 专辑 → 曲目分组。一个只发行过LP唱片的艺术家，否则会要求您打开一个单独的唱片类型 → LP文件夹才能到达专辑。相反，打开该艺术家会直接将您带到专辑 — 该冗余层级会为该艺术家消失，而一个拥有LP唱片和EP唱片的艺术家仍然会显示唱片类型选择。连续的几个单条目层级会一起折叠，而只有一个字母的首字母层级也会以同样的方式消失。
专辑缩略图在浏览树中
专辑将其封面艺术带入浏览响应，因此，在其列表中显示缩略图的设备会实际显示它们。（原始插件仅将艺术作品附加到单个曲目，因此专辑列表显示为纯文本。）无需配置——它会随专辑一起传输。
从设备搜索和随机播放
大多数控制应用都会在浏览树旁边放置一个搜索框和一个“随机”或“随机播放”文件夹。两者都以相同类型的 UPnP 请求到达 MusicBee，并且两者都从您的库中实时响应，而不是从预构建的索引中响应——因此您一分钟前重新标记的曲目会立即被找到。
搜索匹配标题或艺术家。当您的应用搜索曲目时，标题搜索会查看曲目标题；当它搜索专辑时，会查看专辑标题。艺术家搜索匹配曲目的艺术家或专辑的专辑艺术家，因此无论您输入表演者的姓名还是专辑的归档名称，都会出现合辑。结果会随着您滚动而逐页返回，因此匹配数千首曲目的术语会保持响应，而不是停滞或循环回到第一个结果。
示例。 您从控制应用的专辑视图中搜索
Blue。您会得到名为 Blue 的专辑——Kind of Blue、Blue Train——而不是碰巧包含名为“Blue”的曲目的所有专辑。将应用切换到其曲目视图并搜索相同的词，您会得到曲目。匹配哪个字段取决于您的应用请求了什么，而不是您输入了什么。
随机播放文件夹——某些应用显示的随机曲目和随机专辑条目——是请求所有内容的一部分，不带搜索词。默认情况下，“所有内容”是您的整个音乐库，如果其中一半是口语或您从不随机播放的材料，这通常不是您想要的。随机播放来源：，在库选项选项卡上，允许您将其指向您的 MusicBee 过滤器之一，因此每个随机请求都只从该过滤器的内容中提取。此处也提供隐藏过滤器——随机播放的范围与您是否希望该过滤器出现在浏览树中无关。从设备上过滤器内部打开随机播放文件夹仍然会随机播放该过滤器：浏览时做出的明确选择始终优先于设置。
设置
| 控件 | 功能 |
|---|---|
| 随机播放来源： | 设备随机播放请求的来源——所有音乐（您的整个库，默认）或命名的 MusicBee 过滤器。如果所选过滤器后来在 MusicBee 中被删除或重命名，该设置会悄悄地恢复为整个库。 |
调整流以适应每个设备
浏览只是工作的一半；音频仍然需要在接受能力差异很大的硬件上播放。此功能是 MusicBee 如何定制每个流的方式——它是共享的：它既适用于 Server 角色向浏览设备提供音轨时，也适用于 Control point 角色向远程渲染器播放时。驱动它的有两个概念：设备配置文件（设备可以处理什么）和转码优先级链（音轨是否被重新编码）。
设备配置文件 — 适应每台设备
真实的 UPnP 硬件在接受内容方面表现不一：一台流媒体播放器需要 24 位 FLAC，另一台只播放 16 位 PCM，第三台则谎报其支持的编解码器。设备配置文件是您教导插件了解特定设备的限制和怪癖的方式。
如何选择配置文件。 每台设备在连接时都会用一个 User-Agent 字符串来标识自己。配置文件会说“当用户代理包含此片段时应用我”。当设备连接时，插件会找到匹配的配置文件；如果没有匹配项，则会回退到内置的通用设备配置文件。您可以列出几个用 | 分隔的片段（例如 Linn|ChorusDS|BubbleDS），这样一份配置文件就可以覆盖一系列相关设备。
配置文件控制什么。 设备不能超过的限制——专辑封面的最大图片尺寸、允许的采样率范围、最大位深、仅立体声下混——此外，当音轨确实需要转换时，要转换成的输出格式和采样率。一组单独的“问题设备”开关用于解决特定的硬件错误（原始 PCM 处理、字节顺序、HTTP 内容长度标头）。这些开关之所以存在，是因为 UPnP 在实际应用中合规性参差不齐；大多数人从不触碰它们。
何时触碰配置文件。 仅当特定设备出现异常行为时。开箱即用时，通用配置文件以及针对常见硬件提供的每设备默认设置涵盖了大多数情况。要查找设备的 user-agent 以便对其进行定位，请打开调试日志（参见诊断），从设备播放一些内容，然后读取日志中的 useragent= 行。
配置文件中最重要的开关——强制原生流——实际上与限制无关；它决定了上述任何一项是否适用。这是下一个概念。
设置
| 控件 | 作用 |
|---|---|
| 名称 | 配置文件的显示名称。 |
| 当用户代理包含以下内容时适用 | 设备必须包含的用户代理片段才能匹配此配置文件；用 | 分隔替代项。不匹配的设备将回退到通用配置文件。 |
| 最大图片尺寸 | 发送到此设备的最大专辑封面像素尺寸（160 像素是 DLNA 标准；更大的尺寸并非普遍支持）。 |
| 输出采样率 / 到 | 设备接受的采样率范围；超出此范围的源将被转换（强制转码）。 |
| 声道 / 仅立体声 | 对于只支持两声道的设备，将多声道下混为立体声。 |
| 最大位深 | 设备接受的最高位深；位深更深的源将被转换。 |
| 输出格式 | 当需要转码时，要转换成的格式（PCM、FLAC、MP3、AAC、Ogg）。 |
| 输出采样率 | 转码时使用的采样率；“与源相同”保留原始采样率。 |
| 不使用 RAW PCM | 将 PCM 封装在 WAV 容器中，而不是发送原始 L16/L24。适用于会损坏原始 PCM 的设备（某些 Marantz）。 |
| 强制 PCM 流使用小端序 | 发送小端序 PCM，而不是规范的大端序。解决期望小端序的设备上播放白噪声的问题。 |
| 内容长度 | 如何填充 HTTP Content-Length 标头：默认（正确值）、无（省略）、仅 PCM 或固定（一个哨兵“巨大”值）。适用于错误处理此标头的设备。 |
转码与否 — 优先级链
“转码”是指即时重新编码音轨 — 转换为设备可以播放的格式，或者以便应用 MusicBee 的 EQ 和音量均衡。插件宁愿不转码（发送原始文件更快且无损），因此它遵循固定的规则链来决定。**优先级较高的规则获胜并静默覆盖优先级较低的规则。*这是插件中最容易被误解的部分，因为有几个设置看起来*应该协同工作，但实际上并非如此。
| 优先级 | 规则 | 效果 |
|---|---|---|
| 1 (最高) | 强制转码（按设备配置文件） | 始终转码。覆盖以下所有规则。与强制原生互斥 — 勾选一个会取消勾选另一个。 |
| 2 | 强制原生流（按设备配置文件，默认开启） | 从不为此设备转码。完全抑制规则 3-5 — 无论格式、效果或限制如何，都发送原始字节。 |
| 3 | EQ/DSP 和 ReplayGain（媒体库） | 强制转码以便处理音频。如果规则 2 获胜则静默忽略。 |
| 4 | 采样率 / 位深度 / 仅立体声（设备配置文件） | 源超出范围 → 转码以适应。如果规则 2 获胜则静默忽略。 |
| 5 (最低) | 编解码器支持（设备配置文件） | 设备无法播放的源编解码器 → 转码为配置文件的输出格式。如果规则 2 获胜则静默忽略。 |
由于强制原生流默认对每个配置文件都开启，因此开箱即用的行为是：将原始文件交给设备，不进行任何其他操作。这对于连接良好网络的现代设备来说是完全正确的 — 但这意味着媒体库效果和配置文件的音频限制在您更改规则 2 之前似乎“不起作用”。
示例。您希望 MusicBee 的 ReplayGain 音量均衡应用于您的流媒体播放器。您在媒体库下勾选使用 MusicBee 中激活的 ReplayGain 模式均衡播放音量。您播放一首曲目 — 但音量根本没有均衡。
为什么：流媒体播放器的配置文件仍然开启强制原生流（规则 2）。规则 2 优先于 ReplayGain 规则（规则 3），因此插件发送未触动的文件，您的 ReplayGain 设置被静默跳过。
解决方法：打开该设备的配置文件并取消勾选强制原生流。由于强制原生是按配置文件设置的，您可以为您的位完美高保真 DAC 保持开启，而为需要 ReplayGain 的便携式扬声器关闭 — 每个设备都能得到正确的答案。
经验法则：
- 希望将 EQ/DSP 或 ReplayGain 应用于设备？在该设备的配置文件上关闭强制原生流。
- 希望保证进行新的转码（用于测试，或用于无法处理原生文件的设备）？在其配置文件上勾选强制转码 — 它优先于所有其他设置。
- 否则，保持强制原生流开启。它是插件中影响最大的设置，默认值适用于大多数现代设备。
设置
| 控件 | 作用 |
|---|---|
| 强制使用原生流（绕过转码器） | 发送原始文件字节，绕过转码器、效果、ReplayGain 和配置文件的音频限制。**默认开启。**影响最大的播放设置；上述链中的规则 2。 |
| 强制转码（与强制原生流互斥） | 强制通过转码器将每个流传输到此设备。优先于强制原生；两者互斥（勾选一个会取消勾选另一个）。规则 1。 |
| 使用 MusicBee 中激活的均衡器和DSP效果 [强制转码] | 将 MusicBee 的均衡器和 DSP 效果应用于输出音频。强制转码（规则 3），并在其配置文件开启强制原生的任何设备上被抑制。 |
| 使用 MusicBee 中激活的重放增益模式调整播放音量 [强制转码] | 应用 MusicBee 的 ReplayGain 音量均衡。强制转码（规则 3），并在其配置文件开启强制原生的任何设备上被抑制。 |
| 强制广播使用原生流（绕过电台转码器） | 发送未触动的广播/流媒体源，专门绕过电台的转码器。 |
渲染器 — 将 MusicBee 作为播放目标
启用渲染器角色（UPnP 渲染器开关）后，MusicBee 会告诉网络“我是一个可以播放到的设备”。然后，一个单独的控制点应用程序——手机遥控器、另一个媒体控制器——可以选择 MusicBee 并推送音频，让它在这台电脑上播放。您为目标设备指定一个友好的渲染器名称，以便它在其他应用程序的列表中易于识别。
它可以播放什么。 控制应用程序可能发送的两种类型的曲目。如果曲目来自 MusicBee 自己的库——您在手机上浏览了这台电脑的库并点击了一首歌曲——MusicBee 会直接从自己的磁盘播放文件，未经修改，不会引入网络往返可能造成的任何音质损失。如果曲目位于其他任何地方——存储在手机本身、NAS、另一个媒体服务器上的文件——MusicBee 会获取它并在此处播放。
从其他地方发送的曲目会先复制，以及这为什么很重要。 对于不在您库中的曲目，MusicBee 会悄悄地下载一份副本到临时文件夹并播放它，而不是在网络上实时收听。它必须这样做：MusicBee 视为实时网络流的任何内容都可以启动和停止，但不能在其中移动，因此跳到歌曲的不同点将是不可能的，并且曲目将显示为裸露的网址而不是其标题。播放自己磁盘上的真实文件可以避免这两个问题。在家庭网络上，复制大约需要一秒钟。会并排保留几份——正在播放的、接下来排队的以及一份在后面以便即时跳回——当新曲目到达时，旧的会被删除；下次 MusicBee 启动时，任何剩余的都会被清除。曲目长度不是障碍：长的高分辨率或 DSD 文件像其他任何文件一样被获取。
互联网广播被识别并保持不变。 实时广播永远不会被复制，因为它没有可下载的结尾，而且无论如何也没有什么可跳过的——MusicBee 只是将其作为流播放。控制应用程序会说明它正在发送的是哪一种，因此这不需要您进行任何设置和猜测。如果由于任何其他原因无法获取副本，也适用同样的情况：播放通过网络继续，只有那时标题和位置滑块才会变得不可靠。
专辑无间隙播放。 当控制应用程序告诉 MusicBee 接下来播放什么时——大多数都会这样做——该曲目会在当前曲目仍在播放时被获取，并且 MusicBee 自己的播放器会跨越边界。因此，从手机发送的现场录音、DJ 设置或连续古典作品会按预期播放，而不会在每首曲目处暂停。
为什么您会使用它。 它允许手机或平板电脑将这台电脑用作 UPnP 扬声器——当电脑连接到好的扬声器并且您想在沙发上控制它时很方便，无论音乐是存储在电脑上还是您手中的手机上。
何时关闭它。 除非您特别想从另一个应用程序将音频发送到这台电脑，否则请将其关闭。关闭后，MusicBee 不会出现在任何地方作为目标，这通常是您想要的。
一次使用一个控制应用程序。 UPnP 没有应用程序“拥有”渲染器的概念：网络上的任何应用程序都可以向 MusicBee 发送曲目，任何正在观看的应用程序都可以对其看到的内容做出反应。因此，如果两个播放器同时指向 MusicBee，您将得到看起来像错误但不是错误的行为。第二个仍然选择 MusicBee 的应用程序会继续观看，看到它发送的曲目停止，得出结论它的歌曲已完成，并“乐于助人”地从它的队列中发送下一首——因此音乐突然跳到不同的专辑，或者在一个应用程序中按下下一首会在另一个应用程序中开始一首歌曲。在第二个应用程序中停止播放不足以解决问题，因为它仍然被选中并继续观看。将其指回手机自己的扬声器、另一个设备，或正确关闭它。
关于成熟度的说明。 渲染器比服务器角色新，并且在实际硬件上的测试较少。如果某个特定的控制器应用程序驱动它异常，报告它会很有用。
设置
| 控件 | 功能 |
|---|---|
| UPnP 渲染器：允许其他应用程序播放到 MusicBee | 渲染器角色的主开关——允许其他应用程序播放到 MusicBee。在 MusicBee 重启后生效。 |
| 渲染器名称 | 这台电脑作为渲染器宣传的名称，显示在其他应用程序的设备列表中。 |
控制点 — 播放到远程扬声器
启用控制点角色（UPnP 控制点开关）后，网络 UPnP/DLNA 渲染器会显示为MusicBee 内部的输出设备 — 与您选择声卡的位置相同。选择一个，按下播放，MusicBee 就会将音频流式传输到该远程扬声器或流媒体设备，同时您继续使用 MusicBee 自己的界面作为遥控器。
**使用场景。**它使高保真流媒体设备或网络扬声器表现得像另一个 MusicBee 输出设备，无需额外的中间软件。
**何时关闭。**如果您只通过此电脑自己的扬声器播放，请将其关闭。
有两件事决定了此角色的行为方式。第一个是无缝播放（见下文）。第二个是根据每个设备调整流 — 管理服务器的相同设备配置文件和转码优先级也适用于此处，因为插件再次将音频馈送到远程设备。控制点还重用 MusicBee 的 HTTP 服务器来输出音频，因此，即使您从不开启服务器角色，服务器的端口和防火墙规则在这里也很重要。
设置
| 控制项 | 功能 |
|---|---|
| UPnP 控制点：将网络 UPnP/DLNA 渲染器添加为 MusicBee 输出设备 | 控制点角色的主开关 — 将网络 UPnP/DLNA 渲染器添加为 MusicBee 输出设备。 |
无缝播放 — 两种不同的机制
有些音乐注定要不间断地播放——现场专辑、古典乐章、DJ 混音、概念唱片。音轨之间半秒的静默会毁掉它们。该插件提供了两种消除间隙的方法，它们的工作方式截然不同。
真正的无缝播放 (NextURI)。 当渲染器表示支持时，插件会在当前音轨结束前将下一音轨预加载到设备上，因此设备会在内部无静默地跨越边界——就像 CD 播放器一样。这是首选机制：每个音轨都保留自己的元数据，搜索和跳过仍然有效，并且无需开启——插件会在支持的设备上自动使用它。对于每个设备，您可以将其关闭（对于实现有错误的硬件）或告诉插件在列表清空时不要清除排队的音轨（这是针对将空队列视为“停止”的设备的解决方法）。
连续流。 较旧的备用方案将所有内容连接成一个无休止的流。它保证在任何设备上都没有间隙——但代价是：渲染器会显示整个会话的第一首音轨信息，“下一首/上一首”控件停止工作，并且由于所有内容都融合到一个流中，因此必须全部进行转码（强制原生无法应用）。屏幕上的标签会说明这种权衡。
如何选择。 首选真正的无缝播放——它是自动且无损的。仅当设备无法执行 NextURI 且间隙确实困扰您时，才回退到连续流，并接受您会丢失每音轨元数据和传输控件。两者是互斥的：开启连续流会禁用 NextURI，因此您不会意外地同时运行两者。
设置
| 控件 | 作用 |
|---|---|
| 为此设备启用无缝播放 (NextURI) | 为此设备启用真正的无缝播放 (NextURI)。对于支持的设备，此项为开启；如果设备的实现有错误，请将其关闭。 |
| 队列清空时不发送空白 NextURI | 阻止插件在队列清空时发送空白 NextURI——这是针对将此视为“停止”的设备（例如 Denon）的解决方法。 |
| 输出为连续流 | 发送一个连续连接的流而不是离散的音轨。消除任何设备上的间隙，但渲染器仅显示第一首音轨的信息，传输控件停止工作，并且所有内容都经过转码。开启时禁用 NextURI。 |
在网络上相互发现
在任何角色开始工作之前，设备必须相互发现。MusicBee 的服务器绑定到一个网络地址和一个 TCP 端口，然后通过 SSDP 向局域网广播自身，以便设备可以发现它。默认端口是 9779；如果该端口已被占用，插件会自动选择一个附近的空闲端口，设备仍然可以发现它（只有当您的设置需要固定端口时才需要设置）。
在网络配置不寻常的机器上，有两个设置很重要：
- IP 地址 / 网络接口。 “自动”表示在所有接口上提供服务，这适用于大多数电脑。在同时连接多个网络（Wi-Fi 和 以太网 和 VPN）的机器上，请选择您的音频设备实际所在的接口，以便 MusicBee 广播一个它们可以访问的地址。
- 端口。 仅当其他程序已使用默认端口，或者您的防火墙坚持使用特定端口号时才更改它。
设备“看不到 MusicBee”的首要原因是防火墙，而不是 UPnP。 Windows 防火墙必须允许 MusicBee 的端口在专用和公共网络配置文件上都通过，并且在更改防火墙规则后，您通常需要重新启动 MusicBee。在更改插件内的任何设置之前，请先检查这一点。
设置
| 控件 | 功能 |
|---|---|
| IP 地址 | 服务器绑定的网络接口；“自动”使用所有接口。MusicBee 重启后生效。 |
| 端口 | HTTP 服务器监听的 TCP 端口（默认 9779）。如果端口被占用，插件会自动选择一个空闲端口。重启后生效。 |
诊断
当特定设备出现异常行为时，插件的行为是不可见的，除非您将其记录下来。这些工具服务于每个角色，因此它们位于自己的调试选项卡上，而不是某个功能之下。
- 记录调试信息会将每个请求、设备的user-agent以及每个编解码器/转码决策记录到一个日志文件中，您可以使用查看打开该文件。在故障排除时（以及发现设备user-agent以用于配置文件时）将其打开，然后再次关闭——日志增长很快。您也可以在每次启动时清除它。
- 网络带宽受限（播放）告诉插件，每当它进行转码时，它应该使用设备配置文件的有损输出（MP3/AAC/Ogg），而不是大的无损输出。对于慢速Wi-Fi连接，请将其打开。
- 调试选项卡还包含用于开发的低级查询工具；在正常使用中您可以忽略它们（请参阅其他设置）。
日常诊断的模式是：启用日志记录 → 重现问题 → 读取日志 → 调整相关设备配置文件 → 禁用日志记录。
设置
| 控件 | 作用 |
|---|---|
| 记录调试信息 | 将每个请求、user-agent和编解码器决策记录到一个文件中。故障排除时打开，否则关闭。 |
| 插件启动时清除日志 | 每次插件启动时清空日志。 |
| 查看 | 打开当前日志文件。 |
| 清除日志 | 立即清除日志。 |
| 网络带宽受限 - 将输出转码为上述设备配置文件中设置的有损格式 | 当发生转码时，使用设备配置文件的有损输出格式。适用于慢速连接。要求在配置文件的转码部分选择有损格式。 |
快速故障排除
| 症状 | 首先尝试 |
|---|---|
| 设备完全看不到 MusicBee | 检查 Windows 防火墙的专用和公共网络；插件的端口（默认为 9779）必须可达。防火墙更改后重启 MusicBee。 |
| 某个来源（播客、广播、收件箱……）在树中缺失 | 它可能被隐藏了。在视图选项卡上，勾选该节点并确保其可见复选框已选中。 |
| 某个节点以错误的形状浏览 | 在视图选项卡上应用不同的发现路径——例如，播放列表选择平铺曲目，音乐筛选器选择专辑艺术家 → 专辑 → 曲目。 |
| 设备看到了 MusicBee 但无法播放任何曲目 | 设备的配置文件可能不正确，或者强制原生流已关闭且转码失败。勾选该设备配置文件上的强制原生流并重试。 |
| 音频播放为静电声/白噪声 | 尝试在该设备的配置文件上勾选强制小端序用于 PCM 流。如果这没有帮助，请尝试不使用 RAW PCM。 |
| 曲目之间有间隙 | 真正的无缝播放会在支持 NextURI 的设备上自动运行。如果您仍然听到间隙，则设备要么不支持它，要么其实现有错误——回退到输出为连续流（无缝播放有保证，但曲目信息和下一首/上一首控制停止工作）。 |
| EQ / DSP / Re增益“不起作用” | 该设备已开启强制原生流——它优先于这些设置。取消勾选该设备配置文件上的强制原生流。请参阅转码或不转码。 |
| 现代（2020+）设备忽略 MusicBee 的控制 | 针对宣传为 MediaRenderer:2/3 的设备的修复在此分支中；它应该有效。如果无效，请捕获调试日志并提交问题。 |
| 插件加载但配置无法打开 | 检查 MusicBee 的 ErrorLog.dat——插件可能在加载时崩溃了。删除插件的设置文件并重新配置通常可以解决问题。 |
| 英语以外的语言 | 插件支持 22 种语言，并遵循 MusicBee 自身的语言，并且此帮助提供所有这些语言版本。要使用不同的语言，请在常规选项卡上设置语言。 |
测试范围
为了避免您感到意外，以下是此插件在实际使用中经过的测试情况。
所有测试均针对 BubbleUPnP 进行，并以 foobar2000 作为第二个参考。所有三种角色都在那里工作——但 BubbleUPnP 是唯一经过验证的插件对应方，因此除了这两个之外的其他控制应用程序、其他播放器和浏览设备都未经测试，将受益于社区测试。
这在实践中最重要的地方是播放到物理流媒体设备（控制点角色）。在 BubbleUPnP 上确认了真正的无缝曲目过渡，但实际的流媒体设备——WiiM、Sonos、Cambridge、Eversolo、Marantz、Denon——每个设备处理曲目之间的切换方式略有不同，并且都没有在实际硬件上进行测试。如果其中一个设备上无缝播放出现问题，请为该设备关闭 NextURI，以便它回退到一次播放一首曲目。
其他设置
少数控件不属于任何一个功能：
| 控件 | 功能 |
|---|---|
| 帮助 | 在您的网络浏览器中打开此帮助页面，使用 MusicBee 的语言（如果翻译尚未准备好，则回退到英语）。 |
| 读取上次查询、运行查询、获取前5个标签 | 调试 选项卡上的低级查询工具，用于开发；在正常使用中请忽略它们。 |
| 保存 | 保存更改。在启动时绑定的设置（端口、IP、最大连接数、渲染器）会显示 ⚠ 需要重启 徽章，直到您重启 MusicBee。 |
| 取消 | 不保存而关闭对话框。 |
鸣谢
- 原始插件由 Steven Mayall 开发。此分支重写了库浏览和设置对话框并添加了渲染器，但其所依赖的 UPnP、HTTP 和 SSDP 核心仍主要由他编写。
- BoringName 的闭源 UPnP 2025 分支，其公共论坛帖子提供了错误目录。