主题模式

Symedia 二级分类使用教程 ​

📖 目录 ​

基础概念 ​

什么是二级分类？ ​

二级分类是在媒体库中按照特定规则对影片进行自动分类的功能。例如：

电影/
├── 漫威系列/
│   ├── 钢铁侠系列/
│   │   ├── 钢铁侠 (2008)/
│   │   └── 钢铁侠2 (2010)/
│   └── 复仇者联盟系列/
├── 华语电影/
│   └── 让子弹飞 (2010)/
└── 欧美电影/
    └── 盗梦空间 (2010)/

配置文件位置 ​

配置文件路径：config/category.yaml

配置文件结构 ​

基本格式 ​

yaml
# 电影分类配置
movie:
  分类名称1:
    匹配条件1: "值"
    匹配条件2: "值"
  分类名称2:
    匹配条件: "值"

# 电视剧分类配置
tv:
  分类名称1:
    匹配条件: "值"

重要说明 ​

  1. 分类名称 = 目录名称
  2. 按顺序匹配，匹配成功后停止
  3. 空配置 = 保底分类（匹配所有未分类的）
  4. 默认匹配规则：
    • 没有 ? 前缀的属性 = 必须全部满足（AND）
    • 有 ? 前缀的属性 = 至少满足一个（OR）

匹配规则详解 ​

常用匹配字段 ​

字段说明示例
genre_ids内容类型"28" (动作), "16" (动画)
original_language原始语言"zh,en,ja"
production_countries制作国家（电影）"US,CN,JP"
origin_country制作国家（电视剧）"US,CN,JP"
keywords关键词（从标题匹配）"漫威,复仇者"
include_keywordsTMDB 标签关键词"tokusatsu,superhero"
year年份"2020-2025"
series_keywords系列关键词"钢铁侠,蜘蛛侠"
series_directors系列导演"诺兰,斯皮尔伯格"
series_actors系列演员"汤姆·克鲁斯"
?属性名可选匹配属性"?original_language"

多值匹配 ​

使用逗号分隔多个值：

yaml
华语电影:
  original_language: "zh,cn,bo,za" # 匹配中文、粤语、藏语、壮语

Keywords 和 Include_Keywords 的区别 ​

keywords - 标题关键词匹配 ​

从影片标题中匹配关键词：

yaml
漫威系列:
  keywords: "漫威,复仇者,钢铁侠" # 标题包含这些词

include_keywords - TMDB 标签匹配 ​

从 TMDB 数据库的标签/关键词字段匹配，更精确：

yaml
特摄片:
  include_keywords: "tokusatsu" # TMDB标签包含 tokusatsu

使用场景：

  • keywords：适合根据常见中文/英文标题分类
  • include_keywords：适合根据 TMDB 专业标签精确分类

实例对比：

yaml
# 方式1：通过标题匹配（可能不够精确）
假面骑士系列:
  keywords: "假面骑士,Kamen Rider"

# 方式2：通过TMDB标签（更精确）
特摄片:
  include_keywords: "tokusatsu,super sentai"
  series_keywords: "假面骑士,超级战队,奥特曼"

操作符 ​

+ 号 - 必须包含 ​

yaml
儿童动画:
  genre_ids: "+16,+10751" # 必须同时是动画(16)和家庭(10751)

- 号 - 必须排除 ​

yaml
纪录片:
  genre_ids: "99,-10402" # 是纪录片(99)但不是音乐(10402)

混合使用 ​

yaml
动作冒险:
  genre_ids: "+28,12,14,-27" # 必须有动作(28)，可以有冒险(12)或奇幻(14)，但不能有恐怖(27)

年份范围 ​

yaml
近期电影:
  year: "2020-2025" # 2020年到2025年之间

可选属性匹配（? 前缀） ​

什么是可选属性匹配？ ​

通过在属性名前添加 ? 或 ？ 前缀，可以灵活控制匹配逻辑：

  • 没有 ? 前缀 = 必须匹配（所有这类属性都要满足）
  • 有 ? 前缀 = 可选匹配（至少满足其中一个）

匹配规则 ​

最终匹配条件 = 必须属性全部满足 AND 可选属性至少满足一个

使用场景 ​

场景 1：只有必须属性（全部都要满足） ​

yaml
美国科幻片:
  genre_ids: "878" # 必须：科幻
  production_countries: "US" # 必须：美国
  year: "2020-2025" # 必须：2020-2025年

匹配结果：必须同时满足所有三个条件。

场景 2：只有可选属性（至少满足一个） ​

yaml
亚洲电影:
  ?original_language: "zh,ja,ko" # 可选：中文、日语或韩语
  ?origin_country: "CN"

匹配结果：语言是中文,或者国家是 CN,满足任意一个即可。

场景 3：必须 + 可选（组合匹配） ​

yaml
欧美科幻:
  genre_ids: "878" # 必须：科幻
  ?original_language: "en,fr,de" # 可选：英/法/德语任意一个
  ?production_countries: "US,GB" # 可选：美国或英国任意一个

匹配结果：

  • ✅ 科幻片 + 英语 → 匹配（必须满足 + 可选满足）
  • ✅ 科幻片 + 法国制作 → 匹配（必须满足 + 可选满足）
  • ❌ 科幻片 + 中文 + 中国制作 → 不匹配（必须满足但可选都不满足）
  • ❌ 剧情片 + 英语 → 不匹配（必须不满足）

实战示例 ​

示例 1：精确分类 ​

yaml
近期欧美科幻:
  genre_ids: "878" # 必须：科幻
  year: "2020-2025" # 必须：近期

示例 2：广泛收集 ​

yaml
热门动作片:
  genre_ids: "28" # 必须：动作片
  ?keywords: "漫威,DC,速度与激情" # 可选：这些关键词之一
  ?year: "2023-2025" # 可选：或者是近期作品

示例 3：复杂组合 ​

yaml
经典港片:
  origin_country: "HK" # 必须：香港
  year: "1980-2000" # 必须：1980-2000年
  ?genre_ids: "28,80,18" # 可选：动作、犯罪或剧情之一
  ?keywords: "成龙,周星驰,刘德华" # 可选：或这些明星之一

使用技巧 ​

技巧 1：多个可选属性形成"或"关系 ​

yaml
假期观影推荐:
  ?genre_ids: "35,10751" # 可选1：喜剧或家庭
  ?keywords: "圣诞,新年" # 可选2：或节日主题
  ?year: "2024-2025" # 可选3：或最近新片

只要满足任意一个可选条件即可。

技巧 2：必须条件缩小范围，可选条件扩展匹配 ​

yaml
漫威英雄片:
  genre_ids: "+28" # 必须：动作片
  production_countries: "US"
  ?keywords: "复仇者,钢铁侠,蜘蛛侠" # 可选：漫威角色
  ?include_keywords: "marvel cinematic universe (mcu)" # 可选：关键词带有漫威宇宙

Series 系列分类 ​

什么是 Series？ ​

Series 属性用于生成子分类，格式为：分类名/系列名

例如：

  • 漫威系列/钢铁侠系列/
  • 漫威系列/复仇者联盟系列/

Series 属性类型 ​

属性说明示例
series_keywords从标题匹配系列关键词"钢铁侠,蜘蛛侠"
series_directors从导演匹配系列"诺兰,昆汀"
series_actors从演员匹配系列"汤姆·克鲁斯"

重要特性 ​

⚠️ Series 属性只用于生成系列名，不参与匹配条件判断！

使用方式 ​

方式 1：只有 Series 属性 ​

yaml
漫威系列:
  series_keywords: "钢铁侠,美国队长,雷神,复仇者联盟"

效果：

  • 标题包含"钢铁侠" → 漫威系列/钢铁侠系列/
  • 标题包含"复仇者联盟" → 漫威系列/复仇者联盟系列/
  • 标题不包含任何关键词 → 不匹配

方式 2：必须条件 + Series ​

yaml
科幻系列:
  genre_ids: "878" # 必须：科幻片
  production_countries: "US" # 必须：美国
  series_keywords: "星球大战,星际迷航" # 系列名

效果：

  • 美国科幻片 + 标题含"星球大战" → 科幻系列/星球大战系列/
  • 美国科幻片 + 标题不含关键词 → 科幻系列/
  • 中国科幻片 → 不匹配（必须条件不满足）

方式 3：可选条件 + Series ​

yaml
动作系列:
  genre_ids: "28" # 必须：动作片
  ?keywords: "汽车,赛车" # 可选：关键词
  series_keywords: "速度与激情,变形金刚" # 系列名

效果：

  • 动作片 + 标题含"速度与激情" → 动作系列/速度与激情系列/
  • 动作片 + 标题含"汽车" → 动作系列/
  • 动作片（无特殊关键词）→ 动作系列/
  • 剧情片 + 标题含"速度与激情" → 不匹配（必须条件不满足）

⚠️ 注意：series_keywords 匹配只影响系列名，不影响是否匹配该分类！

高级用法 ​

1. 排除特定类型 ​

yaml
剧情片:
  genre_ids: "18,-27,-16" # 剧情片，但不要恐怖片和动画

2. 多条件组合 ​

yaml
亚洲动作片:
  genre_ids: "28" # 必须：动作片
  origin_country: "CN,HK,TW,JP,KR,TH" # 必须：亚洲国家
  year: "2020-2025" # 必须：近期

3. 保底分类 ​

放在最后，不配置任何条件：

yaml
其他电影:
  # 不配置条件，匹配所有前面未匹配的

或配置为空：

yaml
其他电影:

4. 导演/演员系列 ​

yaml
诺兰作品:
  series_directors: "克里斯托弗·诺兰"

汤姆·克鲁斯电影:
  series_actors: "汤姆·克鲁斯"

5. 复杂的可选逻辑 ​

yaml
假期观影推荐:
  ?genre_ids: "35,10751" # 可选1：喜剧或家庭
  ?keywords: "圣诞,新年,假期" # 可选2：节日关键词
  ?year: "2023-2025" # 可选3：最近新片

6. 使用 TMDB 标签精确分类 ​

利用 include_keywords 进行专业分类：

yaml
# 特摄片分类（假面骑士、奥特曼等）
特摄片:
  include_keywords: "tokusatsu,super sentai,kaiju"
  series_keywords: "假面骑士,奥特曼,超级战队,哥斯拉"

# 超级英雄电影（通过标签更精确）
超级英雄:
  include_keywords: "superhero,marvel cinematic universe,dc extended universe"

# 赛博朋克题材
赛博朋克:
  genre_ids: "878" # 必须：科幻类型
  include_keywords: "cyberpunk,dystopia" # 必须：赛博朋克标签

# 音乐传记片
音乐传记:
  include_keywords: "biography,music" # 必须：传记+音乐标签
  genre_ids: "10402,36" # 必须：音乐+历史类型

提示：在 TMDB 网站上查看影片的 Keywords 标签，可以找到更多可用的标签词。

实战示例 ​

示例 1：电影完整配置 ​

yaml
movie:
  # 1. 特定系列（优先匹配）
  漫威系列:
    series_keywords: "钢铁侠,美国队长,雷神,复仇者联盟,银河护卫队,蜘蛛侠"

  DC系列:
    series_keywords: "蝙蝠侠,超人,神奇女侠,正义联盟"

  # 2. 特定类型
  纪录片:
    genre_ids: "99,-10402" # 纪录片但不包括音乐类

  演唱会:
    genre_ids: "10402" # 必须：音乐类型
    ?keywords: "演唱会,巡演,live" # 可选：相关关键词

  # 3. 动画电影
  国产动画:
    genre_ids: "16" # 必须：动画
    production_countries: "CN" # 必须：中国

  日本动画:
    genre_ids: "16" # 必须：动画
    production_countries: "JP" # 必须：日本
    series_keywords: "哆啦A梦,柯南,火影忍者"

  # 3.5. 特殊类型（通过TMDB标签）
  特摄片:
    include_keywords: "tokusatsu,super sentai,kaiju"
    series_keywords: "假面骑士,奥特曼,超级战队"

  # 4. 地区分类
  华语电影:
    original_language: "zh,cn"

  日韩电影:
    original_language: "ja,ko"

  # 5. 保底分类
  欧美电影:

示例 2：电视剧完整配置 ​

yaml
tv:
  # 1. 动漫分类（优先）
  国漫:
    genre_ids: "16" # 必须：动画
    origin_country: "CN,TW,HK" # 必须：中国地区

  日漫:
    genre_ids: "16" # 必须：动画
    origin_country: "JP" # 必须：日本

  欧美动漫:
    genre_ids: "16" # 必须：动画
    origin_country: "US,GB,FR" # 必须：欧美

  # 2. 特定类型
  纪录片:
    genre_ids: "99"

  综艺:
    genre_ids: "10764,10767"

  儿童节目:
    genre_ids: "10762"

  # 3. 地区剧集
  国产剧:
    origin_country: "CN,TW,HK,SG"
    series_keywords: "长相思,庆余年,三体"

  日剧:
    origin_country: "JP"

  韩剧:
    origin_country: "KR"
    series_keywords: "爱的迫降,鱿鱼游戏"

  泰剧:
    origin_country: "TH"

  # 4. 欧美剧
  欧美剧:
    origin_country: "US,GB,CA,DE,FR"

  # 5. 保底
  其他剧集:

常见问题 ​

Q1: 分类顺序重要吗？ ​

非常重要！ 程序会按配置顺序匹配，匹配成功后停止。

❌ 错误示例（宽泛的在前）：

yaml
movie:
  欧美电影: # 这个太宽泛，几乎匹配所有
  漫威系列: # 永远不会匹配到这里
    series_keywords: "复仇者联盟"

✅ 正确示例（具体的在前）：

yaml
movie:
  漫威系列: # 先匹配具体的
    series_keywords: "复仇者联盟"
  欧美电影: # 再匹配宽泛的

Q2: 怎么调试分类不生效？ ​

  1. 检查配置语法是否正确（YAML 格式）
  2. 检查分类顺序（是否被前面的分类拦截）
  3. 查看日志输出
  4. 确认 TMDB 数据是否包含该字段

Q3: 什么时候用必须属性，什么时候用可选属性？ ​

  • 必须属性（无 ? 前缀）：需要精确分类时使用
    • 例如："2020 年后的美国科幻片"
    • 所有条件都必须满足
  • 可选属性（有 ? 前缀）：需要广泛收集时使用
    • 例如："漫威电影 或 DC 电影 或 2024 年新片"
    • 至少满足其中一个即可

Q4: Series 属性如何工作？ ​

Series 属性不参与匹配条件判断，只用于生成系列名。

yaml
动作系列:
  genre_ids: "28" # 必须：动作片
  ?keywords: "爆炸" # 可选：关键词
  series_keywords: "速度与激情" # 只生成系列名
  • 动作片 → 匹配 ✓
  • 动作片 + 标题含"爆炸" → 匹配 ✓
  • 标题含"速度与激情"但不是动作片 → 不匹配 ✗

Q5: 能否让 Series 也参与匹配判断？ ​

不能。这是设计决策。如果需要关键词参与判断，请使用 keywords 或 ?keywords：

yaml
动作系列:
  genre_ids: "28" # 必须：动作片
  ?keywords: "速度与激情" # 可选：关键词匹配

Q6: 怎么处理多语言标题？ ​

keywords 和 series_keywords 从 TMDB 标题 匹配，使用本地化标题：

yaml
日本动画:
  genre_ids: "16"
  origin_country: "JP"
  series_keywords: "ワンピース,海贼王,航海王" # 多个译名

Q7: 年份范围的边界是包含还是排除？ ​

包含边界。"2020-2025" 包括 2020 和 2025 年。

Q8: keywords 和 include_keywords 有什么区别？ ​

keywords：从影片的标题中匹配关键词

  • 适用场景：通过常见的中文/英文标题进行分类
  • 例如：keywords: "漫威,复仇者" 会匹配标题包含这些词的影片

include_keywords：从 TMDB 数据库的Keywords 标签字段匹配

  • 适用场景：需要更专业、精确的分类
  • 例如：include_keywords: "tokusatsu" 匹配特摄类型的影片
  • 优势：TMDB 的标签更标准化，不受标题翻译影响

建议：

  • 对于常规分类，用 keywords 就够了
  • 对于专业领域（特摄、赛博朋克等），用 include_keywords 更精确
  • 可以同时使用两者进行组合匹配

Q9: 如何查找可用的 TMDB Keywords？ ​

  1. 访问 TMDB 网站（themoviedb.org）
  2. 搜索你想分类的影片
  3. 在影片页面找到 "Keywords" 部分
  4. 复制相关的英文关键词到 include_keywords 配置中

示例：

  • 搜索《假面骑士》→ 找到 Keywords: tokusatsu
  • 搜索《银翼杀手》→ 找到 Keywords: cyberpunk, dystopia

参考字典 ​

Genre IDs（内容类型） ​

电影类型 ​

ID中文English
28动作Action
12冒险Adventure
16动画Animation
35喜剧Comedy
80犯罪Crime
99纪录Documentary
18剧情Drama
10751家庭Family
14奇幻Fantasy
36历史History
27恐怖Horror
10402音乐Music
9648悬疑Mystery
10749爱情Romance
878科幻Science Fiction
10770电视电影TV Movie
53惊悚Thriller
10752战争War
37西部Western

电视剧类型 ​

ID说明
10759动作冒险
16动画
35喜剧
80犯罪
99纪录片
18剧情
10751家庭
10762儿童
9648悬疑
10763新闻
10764真人秀
10765科幻奇幻
10766肥皂剧
10767脱口秀
10768战争政治
37西部

Language Codes（语言代码） ​

代码语言代码语言
zh中文en英语
ja日语ko韩语
fr法语de德语
es西班牙语it意大利语
pt葡萄牙语ru俄语
ar阿拉伯语hi印地语
th泰语vi越南语
id印尼语tr土耳其语

Country Codes（国家代码） ​

代码国家/地区代码国家/地区
CN中国大陆HK中国香港
TW中国台湾MO中国澳门
US美国GB英国
JP日本KR韩国
FR法国DE德国
IT意大利ES西班牙
CA加拿大AU澳大利亚
IN印度TH泰国
SG新加坡MY马来西亚
RU俄罗斯BR巴西
MX墨西哥AR阿根廷

快速上手 ​

第一步：复制模板 ​

复制示例配置到 config/category.yaml

第二步：测试简单配置 ​

yaml
movie:
  华语电影:
    original_language: "zh,cn"

  其他电影:

第三步：逐步完善 ​

根据实际需求，添加更多分类。

第四步：观察效果 ​

查看媒体库目录结构是否符合预期。

总结 ​

  • ✅ 分类按顺序匹配，具体的放前面
  • ✅ 没有 ? 前缀 = 必须全部满足（AND）
  • ✅ 有 ? 前缀 = 至少满足一个（OR）
  • ✅ Series 属性只生成系列名，不参与匹配判断
  • ✅ 使用操作符 + - 精确控制匹配
  • ✅ 保底分类放最后，配置为空即可
  • ✅ 多测试，查看日志确认效果

祝你使用愉快！如有问题，欢迎查看日志或提 issue。 🎉