如果你在搭建个人媒体服务器时曾经为如何优雅地管理和播放3D视频而头疼那么这篇文章或许能给你提供一个全新的思路。我们讨论的不是简单的文件堆叠而是一个专门为3D视频设计的“智能仓库”——Halcyon Video。这个名字听起来可能有些陌生但它的定位非常清晰一个为你的媒体服务器量身打造的3D视频存储与管理方案。很多人对3D视频的印象还停留在电影院里的特效大片或者需要特殊眼镜才能观看的复杂格式。但在个人媒体库的语境下3D视频的管理远比2D电影要棘手。它不仅仅是多了一个视频文件那么简单还涉及到左右眼视频流的同步、多种3D格式如SBS、OU、MVC的识别、元数据的匹配以及如何在客户端正确渲染。普通的媒体服务器软件如Plex、Jellyfin或Emby虽然功能强大但在原生3D视频支持上往往力不从心要么识别混乱要么播放时需要复杂的设置。Halcyon Video的出现正是为了解决这个“最后一公里”的问题。它不是一个独立的流媒体服务器而更像是一个插件或补充层专门负责将你散落在硬盘各处的3D视频整理成一个结构清晰、元数据丰富、能被主流媒体服务器正确识别和播放的“3D视频商店”。这背后的核心价值不是简单地增加一个功能而是将一次性的、混乱的3D视频整理工作沉淀为一套自动化、可复用的管理流程。接下来我们将从为什么需要它、如何理解它的工作方式、如何落地部署以及长期使用的注意事项一步步拆解这个方案。1. 为什么你的媒体服务器需要一个“3D专用仓库”在深入Halcyon Video之前我们必须先理解普通媒体服务器在处理3D视频时的根本困境。这不是功能缺失的问题而是设计目标不同导致的“水土不服”。1.1 普通媒体服务器的“盲区”格式识别与元数据混乱当你把一个3D电影文件比如一个My.Movie.3D.HSBS.1080p.mkv丢进Plex或Jellyfin的媒体库时会发生什么服务器会扫描它尝试从文件名或文件内嵌信息中提取元数据片名、年份、海报等。问题就出在这里格式识别困难服务器可能无法从“HSBS”Half Side-by-Side这样的文件名标记中准确判断这是一个3D视频。即使识别了它也不知道该如何告诉客户端如Plex App、Kodi以正确的3D模式播放。元数据匹配错误刮削器如TheMovieDB通常只为2D电影版本提供元数据。当服务器试图为My.Movie.3D.xxx匹配信息时很可能匹配到错误的电影或者干脆匹配失败导致你的媒体库出现大量“未知电影”。播放体验割裂即使文件被正确识别为3D播放时也可能需要用户在客户端手动切换视频输出模式如从2D切换到SBS 3D这个过程既不直观也容易出错。其结果就是你的3D视频库看起来杂乱无章播放体验全凭运气和手动调试。这完全违背了搭建媒体服务器追求“一站式”、“傻瓜式”体验的初衷。1.2 Halcyon Video的核心思路建立专用索引层Halcyon Video采取了一种更聪明的策略。它不试图去改造Plex或Jellyfin的核心而是在它们之外建立一个专属于3D视频的“预处理与索引层”。你可以这样理解Halcyon Video是一个高度专业化的“3D视频管理员”。它的工作流程是扫描你指定的文件夹里面存放着原始的3D视频文件。利用更精准的规则可能是文件名解析、内部流检测来识别视频的3D格式、分辨率、编码等信息。为这些3D视频生成一套独立、整洁的元数据可能是通过匹配2D版本的ID然后打上3D标签。最后它以一种你的主媒体服务器Plex/Jellyfin能够完美理解的方式将整理好的3D视频“呈现”出去。这通常是通过生成符号链接Symbolic Link、硬链接或者在特定目录下创建标准化的媒体文件结构来实现。这样一来你的Plex媒体库看到的就不再是原始的、命名混乱的My.Movie.3D.HSBS.1080p.mkv而是一个像My Movie (2010) [3D SBS].mkv这样规范、且带有明确3D标识的文件。Plex的刮削器可以轻松地为My Movie (2010)匹配到正确的2D电影元数据而[3D SBS]这个标签则能被支持3D的客户端如Plex for Android TV, Kodi with Plex add-on识别并自动触发3D播放模式。这个方案的真正价值在于它把“人适应工具”变成了“工具适应流程”。你不再需要为每一个3D视频手动修改信息、调试播放而是建立一套规则让后续所有的3D视频都能自动归位。2. 拆解Halcyon Video它到底做了什么没做什么在决定使用任何工具前清晰地界定其能力边界至关重要。Halcyon Video不是一个“全能选手”它的设计有非常明确的聚焦点。2.1 它的核心职责元数据标准化与接口适配根据其“3D视频商店”的定位我们可以推断Halcyon Video的核心功能模块可能包括3D格式探测器自动分析视频文件判断其属于SBS左右、OU上下、MVC帧封装等中的哪一种3D格式。智能重命名与标签化根据识别结果和刮削到的元数据对文件进行标准化重命名并嵌入或关联3D标签。媒体服务器桥接器将处理好的视频以你的主媒体服务器Plex/Jellyfin/Emby期望的目录结构和命名规范进行“投放”。这通常不是直接移动原文件而是创建链接或在新位置组织文件。刮削代理可能内置或调用TheMovieDB、TVDb等刮削器的API但会采用更聪明的策略例如先剥离文件名中的3D标识再去匹配2D元数据。2.2 它不负责什么澄清常见误解理解一个工具“不做什么”有时比知道它“做什么”更重要。Halcyon Video很可能不是一个完整的流媒体服务器它不提供直接的流媒体播放、用户管理、转码等功能。这些依然是Plex、Jellyfin的工作。一个视频转码工具它不会改变视频的编码格式如把H.264转成H.265也不会改变3D格式如把SBS转成OU。它的工作是“识别”和“组织”而非“转换”。一个万能播放器播放环节依赖于终端客户端如电视上的Plex App、Kodi对3D格式的支持。Halcyon Video只是确保客户端能拿到一个它看得懂的、带正确标签的3D视频文件。一个自动下载工具它不会帮你从网络获取3D视频资源。你需要自己准备好原始的3D视频文件。注意由于缺乏官方详细文档以上功能推断基于其项目标题和解决同类问题的常见工程思路。实际部署时需要以项目的README或Wiki为准。2.3 技术实现猜想符号链接与元数据注入从工程角度这类工具通常有两种实现路径路径一符号链接/硬链接标准刮削。Halcyon Video在后台目录处理文件生成标准命名的符号链接到Plex的媒体库目录。Plex扫描这些链接文件因为命名规范能顺利刮削到2D电影元数据。3D信息则通过文件名中的标签如[3D]或自定义视频标签传递给客户端。路径二直接元数据写入。更高级的做法是Halcyon Video直接向视频文件容器如MKV中写入特定的元数据字段例如在MKV的“标题”或“标签”字段写入3D-SBS这些字段可以被某些媒体服务器或客户端直接读取。对于大多数用户路径一更为常见和可靠。它的好处是非侵入式不修改原始视频文件所有操作可逆。3. 从零开始部署与配置Halcyon Video的实践路径假设我们已经理解了Halcyon Video的价值和边界接下来就是如何让它跑起来。这里我们将基于同类工具的最佳实践规划一个从准备到验证的完整流程。3.1 环境准备与前置思考在安装任何软件之前先规划好你的媒体库结构。一个清晰的目录结构能避免后续无数麻烦。推荐的结构如下/media/ ├── raw_movies/ # 原始电影文件2D/3D混杂未经整理 ├── raw_tvshows/ # 原始剧集文件 ├── plex_library/ # Plex/Jellyfin的媒体库目录 │ ├── movies/ # Plex的电影库指向整理后的2D/3D电影 │ └── tvshows/ # Plex的剧集库 └── halcyon_workspace/ # Halcyon Video的工作目录 ├── input/ # 放置待处理的原始3D视频 ├── processing/ # 可选处理中的临时文件 └── output/ # 处理完成、标准化的3D视频符号链接或文件关键决策点输入源halcyon_workspace/input/是你的3D视频“入海口”。你可以手动拷贝也可以用其他工具如Sonarr/Radarr的定制脚本自动送入。输出目标halcyon_workspace/output/里的内容需要被你的Plex媒体库plex_library/movies/扫描。如何关联通常是直接将output目录挂载为Plex电影库的一个源或者在output和movies之间建立符号链接。原始文件raw_movies/作为原始文件的备份和归档位置不要被Plex直接扫描。3.2 安装与初步配置Halcyon Video的具体安装方式取决于其发布形式Docker镜像、Python脚本、可执行文件。我们以最常见的Docker方式为例勾勒出步骤。# 1. 拉取镜像假设镜像存在 docker pull yourusername/halcyon-video:latest # 2. 创建必要的目录 mkdir -p /path/to/halcyon_workspace/{input,output,config} # 3. 运行容器进行初始配置 docker run -it --rm \ -v /path/to/halcyon_workspace/config:/config \ -v /path/to/halcyon_workspace/input:/input \ -v /path/to/halcyon_workspace/output:/output \ yourusername/halcyon-video:latest setup运行setup或首次启动后通常需要在/config目录下生成一个配置文件如config.yaml。你需要编辑它核心配置项可能包括# 示例配置结构非真实配置 halcyon: # 输入输出路径已在容器挂载中映射 input_dir: /input output_dir: /output # 3D识别规则 naming_patterns: - pattern: *.3d*.mkv # 匹配含3d字样的mkv文件 format: auto_detect # 自动检测格式 - pattern: *.sbs*.mp4 format: half_sbs # 指定为半宽左右格式 # 元数据刮削 metadata: agent: tmdb # 使用TheMovieDB language: zh-CN # 中文元数据 prefer_original_title: false # 媒体服务器集成 plex: enabled: true # 输出目录的结构如何匹配Plex期望的“电影/电影名 (年份)/电影名 (年份).mkv” movie_naming: {title} ({year})/{title} ({year}){3d_tag}.{ext} # 3D标签如何添加 tag_3d_format: [3D {format}] # 例如生成“阿凡达 (2009) [3D HSBS].mkv” # 处理选项 processing: create_symlinks: true # 创建符号链接而非复制节省空间 clean_input: false # 处理完成后是否删除输入文件慎用3.3 首次运行与验证配置完成后进行最小可行性测试。# 1. 放置一个测试用的3D视频文件到输入目录 cp /path/to/your/test.3d.sbs.mkv /path/to/halcyon_workspace/input/ # 2. 启动Halcyon Video处理进程 docker run -d --name halcyon \ --restart unless-stopped \ -v /path/to/halcyon_workspace/config:/config \ -v /path/to/halcyon_workspace/input:/input \ -v /path/to/halcyon_workspace/output:/output \ yourusername/halcyon-video:latest run # 3. 查看日志确认处理过程 docker logs -f halcyon验证关键点日志输出查看是否有“识别成功”、“刮削元数据成功”、“创建链接成功”等关键日志。输出目录检查/output目录下是否生成了符合电影名 (年份)/电影名 (年份) [3D SBS].mkv格式的文件或符号链接。Plex扫描将/output目录或其上级目录添加到Plex的电影库中触发扫描。检查该电影是否被正确识别为《阿凡达》2009并且海报、简介等信息齐全。客户端播放在支持3D的客户端如搭载Android TV的电视上的Plex App中播放该电影。观察是否能自动或手动切换至3D模式并正常呈现3D效果。重要提醒第一次测试务必使用单个文件。确保整个流程——从Halcyon识别处理到Plex刮削展示再到客户端播放——全部跑通后再考虑批量处理。4. 从“能用”到“好用”进阶配置与长期维护策略单次跑通只是开始。要让Halcyon Video稳定、自动化地融入你的媒体管理流水线还需要考虑以下几个工程化问题。4.1 自动化流水线集成理想状态下3D视频的管理应该完全自动化。这通常需要与自动化下载工具如Radarr配合。一个常见的自动化流程设计Radarr监控并下载3D电影资源到/media/raw_movies/。Radarr下载完成后触发一个自定义脚本Post-processing Script。该脚本判断下载的电影是否为3D版本通过文件名关键词如3D、SBS、HSBS等。如果是3D电影则将其移动到Halcyon Video的输入目录/media/halcyon_workspace/input/。Halcyon Video监控/input目录或由脚本触发自动处理新文件。处理完成后标准化后的文件符号链接出现在/output目录。Plex监控/output目录自动更新媒体库。这个流程的关键在于第3步的“判断”和第4步的“移动”。你需要编写一个简单的Shell或Python脚本来完成这个调度工作。4.2 关键配置项深度解析要让Halcyon Video发挥最大效用需要理解几个核心配置命名模式 (naming_patterns)这是识别3D视频的“眼睛”。你需要根据自己资源文件的命名习惯来调整。例如如果你的3D文件都像Movie.Title.2010.3D.HSBS.1080p.mkv那么模式可以设为*3D*.mkv。更精细的可以区分*HSBS*和*HOU*上下。3D标签格式 (tag_3d_format)这个标签会体现在最终的文件名里。它需要满足两个条件一是能让Plex正确刮削通常标签放在文件名最后用括号或方括号包裹二是能让你的客户端识别。例如[3D HSBS]或(3D-SBS)。你可能需要测试哪种格式对你的播放设备最友好。符号链接 vs 硬链接 vs 复制 (create_symlinks)符号链接节省空间但如果源文件被移动或删除链接会失效。适合源文件位置稳定不变的场景。硬链接同样节省空间且删除一个链接不会影响另一个。但要求源文件和目标文件必须在同一文件系统分区内。复制最稳定但占用双倍空间。除非空间极其充裕否则不推荐。建议优先使用硬链接它兼具节省空间和稳定的优点。确保Halcyon的工作目录和你的原始媒体库在同一个硬盘分区上。4.3 故障排查与日常维护即使配置正确运行中也可能遇到问题。建立一个清晰的排查路径至关重要。当Plex无法识别或播放3D电影时请按此顺序检查排查步骤检查点可能原因与解决方案1. 源文件检查原始3D视频文件本身是否能被本地播放器如VLC以3D模式正常播放文件已损坏或编码异常。重新获取源文件。2. Halcyon处理日志Halcyon的日志中该文件是否显示“处理成功”是否有刮削失败、识别错误的警告文件名不符合识别规则网络问题导致元数据刮削失败。调整命名模式或检查网络。3. 输出结果检查/output目录下生成的最终文件命名是否符合预期是否包含了3D标签Halcyon配置中的命名模板或标签格式有误。4. Plex扫描与匹配在Plex网页端该电影条目是否显示正确的海报、简介还是“未知电影”即使命名规范Plex也可能匹配错误。尝试在Plex中“修复匹配”手动指定TMDB ID。5. 客户端能力换一个客户端如Kodi Plex插件尝试播放是否能触发3D你使用的Plex客户端可能不支持自动3D切换。查阅客户端文档或尝试在播放时手动选择视频输出模式。6. 流媒体设置Plex服务端是否对该视频进行了转码转码可能会剥离3D信息。在客户端设置中将视频质量设置为“原始质量”或“最大”强制直接播放Direct Play。长期维护建议定期查看日志不是等出了问题再看。每周花几分钟浏览一下Halcyon和Plex的日志可以发现潜在的模式识别错误或刮削API变化。备份配置文件将调试好的config.yaml进行备份。在升级Halcyon Video版本或迁移服务器时它能节省大量时间。社区与更新关注Halcyon Video的项目页面如GitHub留意Issue和Release。这类工具可能会随着TMDB API或媒体服务器客户端的更新而需要调整。5. 超越工具构建个人3D媒体库的完整心法Halcyon Video是一个优秀的工具但它只是解决方案的一部分。要真正享受一个整洁、自动化的3D视频库你需要建立起一套系统性的思维。5.1 资源获取与命名规范工具再好也依赖于规范的输入。对于3D视频资源建议从一开始就建立自己的命名规则这能极大减轻后期整理的压力。推荐的原始文件命名格式电影名.年份.分辨率.3D格式.编码.来源.mkv示例Avatar.2009.1080p.3D.HSBS.DTS.x264.mkv优点结构清晰每个部分都有明确含义极易被Halcyon这类工具通过正则表达式解析。如果你使用Radarr/Sonarr等工具自动下载可以在其配置中设置这样的命名规则从源头保证一致性。5.2 播放链路的最终拼图客户端选择媒体服务器整理得再好最终体验取决于播放客户端。对于3D播放客户端的支持度差异很大。电视/盒子原生Plex App许多智能电视如Android TV的Plex App支持自动识别并切换3D SBS/OU格式。这是最便捷的体验。Kodi Plex插件Kodi本身对3D的支持非常强大和灵活。使用Plex for Kodi插件既能享受Plex的媒体管理又能利用Kodi顶级的播放和渲染能力是高端用户的常见选择。Plex Media Player (PC/Mac)功能齐全但3D播放可能需要手动设置或依赖第三方渲染器。Plex Web通常不支持3D播放。因此你的3D媒体库体验上限很大程度上由你客厅里的播放设备决定。在投入大量时间整理库之前先用一两个测试文件确认你的目标播放链路是通的。5.3 理性看待3D内容的价值最后也是一个务实的建议评估你对3D内容的需求强度。3D电影的热潮已过新片产量很少片源质量参差不齐播放设备也有要求。投入大量精力搭建一个完美的3D库是否值得一个更平衡的策略是将3D作为媒体库的一个“特色分区”来管理而非核心。用Halcyon Video这样的工具以较小的维护成本让已有的3D资源变得规整、可播放。而对于未来除非是《阿凡达2》这种级别的原生3D大作否则不必强求。你的媒体服务器核心体验依然应该建立在海量的2D高清内容之上。Halcyon Video的价值在于它用一个相对轻量的方式解决了一个特定但棘手的问题。它没有重新发明轮子而是给现有的轮子Plex/Jellyfin做了一个好用的“3D专用适配器”。通过理解它的工作原理精心配置自动化流程并管理好预期你就能在个人媒体服务器的世界里为自己保留一个随时可以沉浸其中的3D角落。这一切的起点就是从用一个测试文件走通那看似繁琐、实则一步都不能少的验证流程开始。
如果你在搭建个人媒体服务器时曾经为如何优雅地管理和播放3D视频而头疼那么这篇文章或许能给你提供一个全新的思路。我们讨论的不是简单的文件堆叠而是一个专门为3D视频设计的“智能仓库”——Halcyon Video。这个名字听起来可能有些陌生但它的定位非常清晰一个为你的媒体服务器量身打造的3D视频存储与管理方案。很多人对3D视频的印象还停留在电影院里的特效大片或者需要特殊眼镜才能观看的复杂格式。但在个人媒体库的语境下3D视频的管理远比2D电影要棘手。它不仅仅是多了一个视频文件那么简单还涉及到左右眼视频流的同步、多种3D格式如SBS、OU、MVC的识别、元数据的匹配以及如何在客户端正确渲染。普通的媒体服务器软件如Plex、Jellyfin或Emby虽然功能强大但在原生3D视频支持上往往力不从心要么识别混乱要么播放时需要复杂的设置。Halcyon Video的出现正是为了解决这个“最后一公里”的问题。它不是一个独立的流媒体服务器而更像是一个插件或补充层专门负责将你散落在硬盘各处的3D视频整理成一个结构清晰、元数据丰富、能被主流媒体服务器正确识别和播放的“3D视频商店”。这背后的核心价值不是简单地增加一个功能而是将一次性的、混乱的3D视频整理工作沉淀为一套自动化、可复用的管理流程。接下来我们将从为什么需要它、如何理解它的工作方式、如何落地部署以及长期使用的注意事项一步步拆解这个方案。1. 为什么你的媒体服务器需要一个“3D专用仓库”在深入Halcyon Video之前我们必须先理解普通媒体服务器在处理3D视频时的根本困境。这不是功能缺失的问题而是设计目标不同导致的“水土不服”。1.1 普通媒体服务器的“盲区”格式识别与元数据混乱当你把一个3D电影文件比如一个My.Movie.3D.HSBS.1080p.mkv丢进Plex或Jellyfin的媒体库时会发生什么服务器会扫描它尝试从文件名或文件内嵌信息中提取元数据片名、年份、海报等。问题就出在这里格式识别困难服务器可能无法从“HSBS”Half Side-by-Side这样的文件名标记中准确判断这是一个3D视频。即使识别了它也不知道该如何告诉客户端如Plex App、Kodi以正确的3D模式播放。元数据匹配错误刮削器如TheMovieDB通常只为2D电影版本提供元数据。当服务器试图为My.Movie.3D.xxx匹配信息时很可能匹配到错误的电影或者干脆匹配失败导致你的媒体库出现大量“未知电影”。播放体验割裂即使文件被正确识别为3D播放时也可能需要用户在客户端手动切换视频输出模式如从2D切换到SBS 3D这个过程既不直观也容易出错。其结果就是你的3D视频库看起来杂乱无章播放体验全凭运气和手动调试。这完全违背了搭建媒体服务器追求“一站式”、“傻瓜式”体验的初衷。1.2 Halcyon Video的核心思路建立专用索引层Halcyon Video采取了一种更聪明的策略。它不试图去改造Plex或Jellyfin的核心而是在它们之外建立一个专属于3D视频的“预处理与索引层”。你可以这样理解Halcyon Video是一个高度专业化的“3D视频管理员”。它的工作流程是扫描你指定的文件夹里面存放着原始的3D视频文件。利用更精准的规则可能是文件名解析、内部流检测来识别视频的3D格式、分辨率、编码等信息。为这些3D视频生成一套独立、整洁的元数据可能是通过匹配2D版本的ID然后打上3D标签。最后它以一种你的主媒体服务器Plex/Jellyfin能够完美理解的方式将整理好的3D视频“呈现”出去。这通常是通过生成符号链接Symbolic Link、硬链接或者在特定目录下创建标准化的媒体文件结构来实现。这样一来你的Plex媒体库看到的就不再是原始的、命名混乱的My.Movie.3D.HSBS.1080p.mkv而是一个像My Movie (2010) [3D SBS].mkv这样规范、且带有明确3D标识的文件。Plex的刮削器可以轻松地为My Movie (2010)匹配到正确的2D电影元数据而[3D SBS]这个标签则能被支持3D的客户端如Plex for Android TV, Kodi with Plex add-on识别并自动触发3D播放模式。这个方案的真正价值在于它把“人适应工具”变成了“工具适应流程”。你不再需要为每一个3D视频手动修改信息、调试播放而是建立一套规则让后续所有的3D视频都能自动归位。2. 拆解Halcyon Video它到底做了什么没做什么在决定使用任何工具前清晰地界定其能力边界至关重要。Halcyon Video不是一个“全能选手”它的设计有非常明确的聚焦点。2.1 它的核心职责元数据标准化与接口适配根据其“3D视频商店”的定位我们可以推断Halcyon Video的核心功能模块可能包括3D格式探测器自动分析视频文件判断其属于SBS左右、OU上下、MVC帧封装等中的哪一种3D格式。智能重命名与标签化根据识别结果和刮削到的元数据对文件进行标准化重命名并嵌入或关联3D标签。媒体服务器桥接器将处理好的视频以你的主媒体服务器Plex/Jellyfin/Emby期望的目录结构和命名规范进行“投放”。这通常不是直接移动原文件而是创建链接或在新位置组织文件。刮削代理可能内置或调用TheMovieDB、TVDb等刮削器的API但会采用更聪明的策略例如先剥离文件名中的3D标识再去匹配2D元数据。2.2 它不负责什么澄清常见误解理解一个工具“不做什么”有时比知道它“做什么”更重要。Halcyon Video很可能不是一个完整的流媒体服务器它不提供直接的流媒体播放、用户管理、转码等功能。这些依然是Plex、Jellyfin的工作。一个视频转码工具它不会改变视频的编码格式如把H.264转成H.265也不会改变3D格式如把SBS转成OU。它的工作是“识别”和“组织”而非“转换”。一个万能播放器播放环节依赖于终端客户端如电视上的Plex App、Kodi对3D格式的支持。Halcyon Video只是确保客户端能拿到一个它看得懂的、带正确标签的3D视频文件。一个自动下载工具它不会帮你从网络获取3D视频资源。你需要自己准备好原始的3D视频文件。注意由于缺乏官方详细文档以上功能推断基于其项目标题和解决同类问题的常见工程思路。实际部署时需要以项目的README或Wiki为准。2.3 技术实现猜想符号链接与元数据注入从工程角度这类工具通常有两种实现路径路径一符号链接/硬链接标准刮削。Halcyon Video在后台目录处理文件生成标准命名的符号链接到Plex的媒体库目录。Plex扫描这些链接文件因为命名规范能顺利刮削到2D电影元数据。3D信息则通过文件名中的标签如[3D]或自定义视频标签传递给客户端。路径二直接元数据写入。更高级的做法是Halcyon Video直接向视频文件容器如MKV中写入特定的元数据字段例如在MKV的“标题”或“标签”字段写入3D-SBS这些字段可以被某些媒体服务器或客户端直接读取。对于大多数用户路径一更为常见和可靠。它的好处是非侵入式不修改原始视频文件所有操作可逆。3. 从零开始部署与配置Halcyon Video的实践路径假设我们已经理解了Halcyon Video的价值和边界接下来就是如何让它跑起来。这里我们将基于同类工具的最佳实践规划一个从准备到验证的完整流程。3.1 环境准备与前置思考在安装任何软件之前先规划好你的媒体库结构。一个清晰的目录结构能避免后续无数麻烦。推荐的结构如下/media/ ├── raw_movies/ # 原始电影文件2D/3D混杂未经整理 ├── raw_tvshows/ # 原始剧集文件 ├── plex_library/ # Plex/Jellyfin的媒体库目录 │ ├── movies/ # Plex的电影库指向整理后的2D/3D电影 │ └── tvshows/ # Plex的剧集库 └── halcyon_workspace/ # Halcyon Video的工作目录 ├── input/ # 放置待处理的原始3D视频 ├── processing/ # 可选处理中的临时文件 └── output/ # 处理完成、标准化的3D视频符号链接或文件关键决策点输入源halcyon_workspace/input/是你的3D视频“入海口”。你可以手动拷贝也可以用其他工具如Sonarr/Radarr的定制脚本自动送入。输出目标halcyon_workspace/output/里的内容需要被你的Plex媒体库plex_library/movies/扫描。如何关联通常是直接将output目录挂载为Plex电影库的一个源或者在output和movies之间建立符号链接。原始文件raw_movies/作为原始文件的备份和归档位置不要被Plex直接扫描。3.2 安装与初步配置Halcyon Video的具体安装方式取决于其发布形式Docker镜像、Python脚本、可执行文件。我们以最常见的Docker方式为例勾勒出步骤。# 1. 拉取镜像假设镜像存在 docker pull yourusername/halcyon-video:latest # 2. 创建必要的目录 mkdir -p /path/to/halcyon_workspace/{input,output,config} # 3. 运行容器进行初始配置 docker run -it --rm \ -v /path/to/halcyon_workspace/config:/config \ -v /path/to/halcyon_workspace/input:/input \ -v /path/to/halcyon_workspace/output:/output \ yourusername/halcyon-video:latest setup运行setup或首次启动后通常需要在/config目录下生成一个配置文件如config.yaml。你需要编辑它核心配置项可能包括# 示例配置结构非真实配置 halcyon: # 输入输出路径已在容器挂载中映射 input_dir: /input output_dir: /output # 3D识别规则 naming_patterns: - pattern: *.3d*.mkv # 匹配含3d字样的mkv文件 format: auto_detect # 自动检测格式 - pattern: *.sbs*.mp4 format: half_sbs # 指定为半宽左右格式 # 元数据刮削 metadata: agent: tmdb # 使用TheMovieDB language: zh-CN # 中文元数据 prefer_original_title: false # 媒体服务器集成 plex: enabled: true # 输出目录的结构如何匹配Plex期望的“电影/电影名 (年份)/电影名 (年份).mkv” movie_naming: {title} ({year})/{title} ({year}){3d_tag}.{ext} # 3D标签如何添加 tag_3d_format: [3D {format}] # 例如生成“阿凡达 (2009) [3D HSBS].mkv” # 处理选项 processing: create_symlinks: true # 创建符号链接而非复制节省空间 clean_input: false # 处理完成后是否删除输入文件慎用3.3 首次运行与验证配置完成后进行最小可行性测试。# 1. 放置一个测试用的3D视频文件到输入目录 cp /path/to/your/test.3d.sbs.mkv /path/to/halcyon_workspace/input/ # 2. 启动Halcyon Video处理进程 docker run -d --name halcyon \ --restart unless-stopped \ -v /path/to/halcyon_workspace/config:/config \ -v /path/to/halcyon_workspace/input:/input \ -v /path/to/halcyon_workspace/output:/output \ yourusername/halcyon-video:latest run # 3. 查看日志确认处理过程 docker logs -f halcyon验证关键点日志输出查看是否有“识别成功”、“刮削元数据成功”、“创建链接成功”等关键日志。输出目录检查/output目录下是否生成了符合电影名 (年份)/电影名 (年份) [3D SBS].mkv格式的文件或符号链接。Plex扫描将/output目录或其上级目录添加到Plex的电影库中触发扫描。检查该电影是否被正确识别为《阿凡达》2009并且海报、简介等信息齐全。客户端播放在支持3D的客户端如搭载Android TV的电视上的Plex App中播放该电影。观察是否能自动或手动切换至3D模式并正常呈现3D效果。重要提醒第一次测试务必使用单个文件。确保整个流程——从Halcyon识别处理到Plex刮削展示再到客户端播放——全部跑通后再考虑批量处理。4. 从“能用”到“好用”进阶配置与长期维护策略单次跑通只是开始。要让Halcyon Video稳定、自动化地融入你的媒体管理流水线还需要考虑以下几个工程化问题。4.1 自动化流水线集成理想状态下3D视频的管理应该完全自动化。这通常需要与自动化下载工具如Radarr配合。一个常见的自动化流程设计Radarr监控并下载3D电影资源到/media/raw_movies/。Radarr下载完成后触发一个自定义脚本Post-processing Script。该脚本判断下载的电影是否为3D版本通过文件名关键词如3D、SBS、HSBS等。如果是3D电影则将其移动到Halcyon Video的输入目录/media/halcyon_workspace/input/。Halcyon Video监控/input目录或由脚本触发自动处理新文件。处理完成后标准化后的文件符号链接出现在/output目录。Plex监控/output目录自动更新媒体库。这个流程的关键在于第3步的“判断”和第4步的“移动”。你需要编写一个简单的Shell或Python脚本来完成这个调度工作。4.2 关键配置项深度解析要让Halcyon Video发挥最大效用需要理解几个核心配置命名模式 (naming_patterns)这是识别3D视频的“眼睛”。你需要根据自己资源文件的命名习惯来调整。例如如果你的3D文件都像Movie.Title.2010.3D.HSBS.1080p.mkv那么模式可以设为*3D*.mkv。更精细的可以区分*HSBS*和*HOU*上下。3D标签格式 (tag_3d_format)这个标签会体现在最终的文件名里。它需要满足两个条件一是能让Plex正确刮削通常标签放在文件名最后用括号或方括号包裹二是能让你的客户端识别。例如[3D HSBS]或(3D-SBS)。你可能需要测试哪种格式对你的播放设备最友好。符号链接 vs 硬链接 vs 复制 (create_symlinks)符号链接节省空间但如果源文件被移动或删除链接会失效。适合源文件位置稳定不变的场景。硬链接同样节省空间且删除一个链接不会影响另一个。但要求源文件和目标文件必须在同一文件系统分区内。复制最稳定但占用双倍空间。除非空间极其充裕否则不推荐。建议优先使用硬链接它兼具节省空间和稳定的优点。确保Halcyon的工作目录和你的原始媒体库在同一个硬盘分区上。4.3 故障排查与日常维护即使配置正确运行中也可能遇到问题。建立一个清晰的排查路径至关重要。当Plex无法识别或播放3D电影时请按此顺序检查排查步骤检查点可能原因与解决方案1. 源文件检查原始3D视频文件本身是否能被本地播放器如VLC以3D模式正常播放文件已损坏或编码异常。重新获取源文件。2. Halcyon处理日志Halcyon的日志中该文件是否显示“处理成功”是否有刮削失败、识别错误的警告文件名不符合识别规则网络问题导致元数据刮削失败。调整命名模式或检查网络。3. 输出结果检查/output目录下生成的最终文件命名是否符合预期是否包含了3D标签Halcyon配置中的命名模板或标签格式有误。4. Plex扫描与匹配在Plex网页端该电影条目是否显示正确的海报、简介还是“未知电影”即使命名规范Plex也可能匹配错误。尝试在Plex中“修复匹配”手动指定TMDB ID。5. 客户端能力换一个客户端如Kodi Plex插件尝试播放是否能触发3D你使用的Plex客户端可能不支持自动3D切换。查阅客户端文档或尝试在播放时手动选择视频输出模式。6. 流媒体设置Plex服务端是否对该视频进行了转码转码可能会剥离3D信息。在客户端设置中将视频质量设置为“原始质量”或“最大”强制直接播放Direct Play。长期维护建议定期查看日志不是等出了问题再看。每周花几分钟浏览一下Halcyon和Plex的日志可以发现潜在的模式识别错误或刮削API变化。备份配置文件将调试好的config.yaml进行备份。在升级Halcyon Video版本或迁移服务器时它能节省大量时间。社区与更新关注Halcyon Video的项目页面如GitHub留意Issue和Release。这类工具可能会随着TMDB API或媒体服务器客户端的更新而需要调整。5. 超越工具构建个人3D媒体库的完整心法Halcyon Video是一个优秀的工具但它只是解决方案的一部分。要真正享受一个整洁、自动化的3D视频库你需要建立起一套系统性的思维。5.1 资源获取与命名规范工具再好也依赖于规范的输入。对于3D视频资源建议从一开始就建立自己的命名规则这能极大减轻后期整理的压力。推荐的原始文件命名格式电影名.年份.分辨率.3D格式.编码.来源.mkv示例Avatar.2009.1080p.3D.HSBS.DTS.x264.mkv优点结构清晰每个部分都有明确含义极易被Halcyon这类工具通过正则表达式解析。如果你使用Radarr/Sonarr等工具自动下载可以在其配置中设置这样的命名规则从源头保证一致性。5.2 播放链路的最终拼图客户端选择媒体服务器整理得再好最终体验取决于播放客户端。对于3D播放客户端的支持度差异很大。电视/盒子原生Plex App许多智能电视如Android TV的Plex App支持自动识别并切换3D SBS/OU格式。这是最便捷的体验。Kodi Plex插件Kodi本身对3D的支持非常强大和灵活。使用Plex for Kodi插件既能享受Plex的媒体管理又能利用Kodi顶级的播放和渲染能力是高端用户的常见选择。Plex Media Player (PC/Mac)功能齐全但3D播放可能需要手动设置或依赖第三方渲染器。Plex Web通常不支持3D播放。因此你的3D媒体库体验上限很大程度上由你客厅里的播放设备决定。在投入大量时间整理库之前先用一两个测试文件确认你的目标播放链路是通的。5.3 理性看待3D内容的价值最后也是一个务实的建议评估你对3D内容的需求强度。3D电影的热潮已过新片产量很少片源质量参差不齐播放设备也有要求。投入大量精力搭建一个完美的3D库是否值得一个更平衡的策略是将3D作为媒体库的一个“特色分区”来管理而非核心。用Halcyon Video这样的工具以较小的维护成本让已有的3D资源变得规整、可播放。而对于未来除非是《阿凡达2》这种级别的原生3D大作否则不必强求。你的媒体服务器核心体验依然应该建立在海量的2D高清内容之上。Halcyon Video的价值在于它用一个相对轻量的方式解决了一个特定但棘手的问题。它没有重新发明轮子而是给现有的轮子Plex/Jellyfin做了一个好用的“3D专用适配器”。通过理解它的工作原理精心配置自动化流程并管理好预期你就能在个人媒体服务器的世界里为自己保留一个随时可以沉浸其中的3D角落。这一切的起点就是从用一个测试文件走通那看似繁琐、实则一步都不能少的验证流程开始。
![【Bug已解决】[modular] ensure branch-specific input defaults 解决方案](http://pic.xiahunao.cn/yaotu/【Bug已解决】[modular] ensure branch-specific input defaults 解决方案)
