渲染词在整理 / 重命名流程中，对最终生成的文件名做额外加工。可在归档相关设置里配置 custom_render_words（自定义渲染词），也可通过 render_word_links 订阅远程词表。

渲染词在本项目中分为两类：

类型	作用对象	典型用途
普通渲染词	标题或已渲染出的文件夹名 / 文件名字符串	把某些属性渲染成自己喜欢的格式、统一写法、正则替换
高级渲染词（@? 格式）	识别完成后的元数据字典（季、集、TMDB ID 等）	按 TMDB / 季集 / 文件名条件修正媒体信息、集数偏移、换绑 TMDB

两类规则写在同一份 custom_render_words 列表中；引擎会在不同阶段分别套用。

---

一、普通渲染词

作用

在字符串上按正则处理，分为两种写法（实现见 MetaAssistant.process_render_words）：

1. 替换规则：匹配正则 => 替换内容
   对匹配片段做替换（支持捕获组等正则替换写法）。
   箭头两侧的分隔符可为 =>（两侧有空格）或 =>（无空格）。

2. 屏蔽规则：仅写一条正则，不含 =>
   将匹配内容替换为空串，即从标题或名称中删除。

处理顺序与特殊写法

• 以 # 开头的整行视为注释，忽略。
• 以 ! 开头的规则为终末规则：先收集并执行其它普通规则，最后再执行带 ! 的规则（执行时去掉前缀 !，再按上两类处理）。适合必须最后才做的清理或替换。
• 规则中可写 (?i) 前缀表示忽略大小写；处理前会去掉该前缀并启用忽略大小写匹配。

注意：以 @? 开头的行在普通渲染词阶段不会当作字符串规则执行（由高级渲染词逻辑单独解析），不要用 @?... 当作普通正则去匹配标题。

使用场景

• 把识别后仍留在名称里的噪声统一成空格或规范分隔符。
• 与命名模板配合：模板先用占位符生成路径，再用渲染词做最后一道字符串修整。

应用时机（效果）

• 整理 / 重命名：在 FileTransfer.get_folder_name、get_file_name 中，命名模板通过 render_str 生成目录名、文件名之后，再对生成结果套用普通渲染词，因此会直接影响目标目录名与文件名。

说明：MetaAssistant.process_title 内部也有「识别词 → 制作组 → 普通渲染词」的顺序，但当前仓库主流程识别路径多走 process_keywords 等接口。若运行环境里没有单独调用 process_title，普通渲染词未必会作用在识别前的原始标题上；以实际部署版本为准。配置时建议优先把普通渲染词理解为命名结果的后处理。

示例

规则	说明	输入示例	效果（示意）
Dovi => DV	把某些属性映射为自己喜欢的格式	阿甘正传.1994.2160p.Dovi.mkv	阿甘正传.1994.2160p.DV.mkv
(?i)web-dl => WEB-DL	忽略大小写，统一写法	xxx.web-dl.xxx	xxx.WEB-DL.xxx
S(\d+)E(\d+) => 第\1季第\2集	正则替换（命名模板若已写出 SxxExx）	...S01E03...	...第1季第3集...

---

二、高级渲染词（@?{[...]} => {[...]}）

作用

在 TMDB 等媒体信息已识别并写入元数据后，根据条件块决定是否执行动作块，从而改写 MetaInfo 中的字段（如 tmdbid、season、episode、year 等）。适用于纠错、分版本映射、集数整体偏移等。

格式（与代码解析一致）：

@?{[条件1=值1;条件2=值2;...]} => {[动作1=值1;动作2=值2;...]}

• 条件与动作均为 key=value；多条之间用英文分号 ; 分隔。
• => 与后面的花括号之间需要恰好一个空格，应写成 => {[；写成 =>{[ 紧挨着可能被解析失败。

条件侧常用键

键	含义	说明
tmdbid	TMDB 作品 ID	值里可用竖线分隔多个候选 ID（与元数据中任一相同即满足）
type	类型	如 tv、movie（与内部元数据字符串一致）
s	季	支持范围：s=1-3 表示第 1～3 季
e	集	支持范围：e=10-20；单集写 e=12
includes	与原文件名的关系	对 original_name 匹配；见下文

includes 表达式（简化说明）：

• 若表达式中没有 & 与 ||，整段按正则在 original_name 上搜索；可用 (?i) 前缀表示忽略大小写。
• 若含逻辑运算符：& 为与，|| 为或，并支持 (...) 分组。单段子表达式优先按正则匹配；匹配失败时可退化为子串包含（见 _evaluate_includes_expression）。

动作侧常用键

键	含义	说明
s	设置季	会同步更新内部 begin_season
e	设置集	先把值里的 EP 换成当前集号，再 eval 求值。例如 e=EP+1 表示「当前集 +1」。若写成 e=+1（不含 EP），表达式仅为 +1，结果为 1，会把集号固定成 1，而不是「加一」。若存在 end_episode，会对结束集用同一表达式再算一次
tmdbid	改写绑定的 TMDB	若与当前识别结果不同，整理逻辑会按新 tmdbid 重新拉取媒体信息
year	年份	值为数字时转为整数
其它键	写入元数据	值为数字时尝试 int，否则按字符串处理

终末与短路

• 与普通规则相同：整条规则前加 ! 表示终末高级规则，在其它高级规则之后执行。
• 若规则字符串任意位置包含 break=true，则在该规则成功改写元数据后，不再处理后续高级渲染词（适合「命中一条即足够」的场景）。

使用场景

• 多版本 / 多季映射错误：在同一 TMDB 条目下，按文件名里的版本标识（includes）把季集改到正确季度。
• 特别篇、OVA 与 TMDB 集号不一致：对某一季某一集区间用 e=EP+n 做统一偏移。
• 误识别到邻近 TMDB 条目：用 tmdbid 条件命中后，把 tmdbid 改为目标条目并触发重新识别。

应用时机（效果）

高级渲染词在 FileTransfer._update_meta_with_media_info 中执行：在已取得 MediaInfo 并回填基础字段后，用当前元数据的字典形态做条件判断；若改写了 tmdbid，会再次走 TMDB 识别以刷新标题、年份等。之后的命名、季集展示、路径中的季集信息都基于修正后的元数据。

示例（摘自代码注释，便于对照）

以下均为示意；请按自己库里的实际 tmdbid、季集与文件名关键字改写。

说明：源码注释里部分示例写作 e=+1，按当前实现会得到集号 1（因为 eval("+1") == 1）。若要在当前集基础上加 1，应写成 e=EP+1。

# 当 TMDB=16 的电视剧、第 0 季、第 12 集时，改为第 1 季第 13 集（须用 EP 表示「当前集」）
@?{[tmdbid=16;type=tv;s=0;e=12]} => {[s=1;e=EP+1]}

# 集号落在 26～50 时做同样映射
@?{[tmdbid=16;type=tv;s=0;e=26-50]} => {[s=1;e=EP+1]}

# 原文件名中出现 MWeb 或 Audiences（具体匹配逻辑见 includes 一节）
@?{[tmdbid=16;type=tv;includes=MWeb|Audiences]} => {[s=1;e=EP+1]}

# 更复杂的 includes：（MWeb 与 Audiences 同时出现）或出现 HHWeb
@?{[tmdbid=16;type=tv;includes=(MWeb&Audiences)|HHWeb]} => {[s=1;e=EP+1]}

# tmdbid 为 16 或 17 时均可命中
@?{[tmdbid=16|17;type=tv;s=1;e=1]} => {[s=2;e=1]}

效果归纳：

• 条件不满足：元数据不变。
• 条件满足：按动作改写季、集、TMDB 等；若改了 tmdbid，会重新识别并刷新媒体详情；若规则含 break=true，则不再处理列表中排在后面的高级规则。

---

三、与普通「识别词」的区分

项目	普通渲染词	高级渲染词 @?	识别词（keywords）
主要目的	清洗或替换纯字符串	按条件改结构化元数据	改标题字符串以利于识别与匹配
典型写法	正则，或 匹配 => 替换	@?{[...]} => {[...]}	模式 => 替换 等（见识别词文档）

---

四、调试建议

• 普通渲染词：在日志中查找「应用渲染词替换规则 / 屏蔽规则」等 debug 输出（需对应日志级别）。
• 高级渲染词：关注「应用条件判断规则」「tmdbid 发生变化」等；集数表达式异常时会记录「集数计算失败」，并尽量回退到原集号。

若某条高级规则始终不生效，请先确认 => { 中间是否有空格，以及条件里的 type、季集等是否与元数据中的取值完全一致。

版权所有

版权归属：Symedia

许可证：署名 4.0 国际 (CC-BY-4.0)