短视频素材收集（画面 + 音乐音效 · 带合规清单）

这个技能解决什么

给一个选题，产出可直接用、且带完整许可信息的素材包。

同类做法的问题，本技能针对性避开：

两条最重要的事实：

1. 图片/视频：免费商用 ≠ 随便用（见「三条禁止用途」）
2. 音乐/音效：许可逐条不同，且 CC 的署名是许可生效条件，不是礼貌（见「音乐许可红线」）

何时触发

• "帮我找短视频素材 / B-roll / 配画面"
• "要免费可商用的图片 / 视频 / 背景音乐 / BGM / 音效"
• "给这个选题配一批素材"
• "批量下载无版权素材"
• 触发词：短视频素材、找素材、B-roll、配画面、背景音乐、BGM、音效、免费商用图片、免费视频素材、免费音乐、无版权素材、素材包、stock footage、royalty free music

何时不触发

依赖

代码零依赖（只用 Python 标准库）。需要的是各素材源的免费凭据：

> ⚠️ Jamendo 要的是 Client ID，不是 Client Secret。 开发者后台同一个应用页面
> 上给你两个值：Client ID（短，如 709fa152）放 URL 里用；Client Secret
> （长，32 位十六进制）只在 OAuth 换 token 时用、绝不能进 URL。
> 实测把 Client Secret 当 client_id 用会返回 code:5 Invalid Client Id。

> ⚠️ Freesound 正好相反：要用的就是名字里带 secret 的那一列 ——
> 官方文档原话是「use the keys in 'Client secret/Api key' column」。
> 两个平台的方向是反的，别把 Jamendo 的经验直接搬过来。

setx PIXABAY_API_KEY "你的key"
setx JAMENDO_CLIENT_ID "你的值"
setx FREESOUND_TOKEN "你的值"

• 只需画面 → 配 Pixabay 一个就够；只要音乐音效 → 配 Jamendo/Freesound
• 缺哪个源的凭据就自动跳过哪个源（打印 [WARN]），全部缺失才报 [MISSING_DEPS] 并退 3
• Pip 不用装任何东西

> ⚠️ Pexels API 目前停止发放（实测 2026-10-01 无法申请）。代码默认双源、缺 key 自动跳过，只配 Pixabay 也能完整工作。将来 Pexels 恢复发放无需改代码。

工作流（按顺序，别跳步）

Step 1 · 生成检索词（由 agent 完成，不是脚本）

python3 scripts/collect_assets.py template --out ./assets-build --topic "选题"

产出 brief.json 骨架，agent 需要填 keywords（20~30 组为宜）：

• 抽象概念用英文视觉词："压力大" → stress deadline overtime、tired person laptop night
• 具体场景双语都试：keyboard typing / 键盘 打字
• 音乐按情绪/风格搜：uplifting cinematic ambient、calm piano background
• 音效按具体声源搜：footsteps gravel、wind forest、ui click
• 必须知道的一件事：中文场景 / 中式元素 / 中文字幕模板 在 Pexels/Pixabay 基本没有 —— 这类题材别浪费时间搜，直接走 ComfyUI 生成或自己录屏

Step 2 · 检索（不下载）

# 画面
python3 scripts/collect_assets.py search --out ./assets-build \
  --keywords "gaming controller neon,person playing game night" \
  --ratio 9:16 --want images,videos

# 画面 + 音乐 + 音效（自动加上 jamendo,freesound 与 music,sfx）
python3 scripts/collect_assets.py search --out ./assets-build --with-audio \
  --keywords "cinematic drone shot mountain,calm piano ambient,wind mountain"

# 第一次用某个源，建议存一份原始响应以便核对字段
python3 scripts/collect_assets.py search --out ./assets-build --debug-raw

这一步只产出 candidates.json，不下载任何东西。

Step 3 · 挑素材

打开 candidates.json，看 candidates[] 里的 cand_id / width / height / duration / author / license / commercial_ok / derivatives_ok / notes。

Step 4 · 下载

python3 scripts/collect_assets.py fetch --out ./assets-build --select 1,3,5-8
python3 scripts/collect_assets.py fetch --out ./assets-build --select all

下载会同时写出 sources.csv、credits.md、manifest.json。重复执行会跳过已存在的文件。

Step 5 · 交付前自检

python3 scripts/collect_assets.py check --out ./assets-build   # exit 0 才能交付

exit 1 的情形：素材缺文件 / 0 字节 / 缺来源或许可信息 /
音频许可为「禁商用」或「禁改编」（这两条是硬红线）。

输出契约（固定，下游可直读）

sources.csv 的 18 列：

file,source,source_id,title,author,author_url,page_url,download_url,
license,license_url,attribution_required,commercial_ok,derivatives_ok,
download_at,risk_person,risk_brand,risk_standalone,notes

> title（作品名）不是可选项 —— CC 署名必须标作品名，用文件名代替既不合格
> 也过不了 check。commercial_ok / derivatives_ok 是音频的关键列
> —— 图片视频恒为 true，音乐音效取决于逐条的 CC 许可。

candidates.json 里几个关键字段：

• fetched_raw / filtered_out —— 丢弃项全部计数（重复/分辨率/时长/方向/许可受限/许可未识别），不静默丢
• errors[] —— 每个失败的查询，含来源、类型、关键词、错误原文
• risk_summary —— 疑似真人 / 疑似品牌条数（仅画面素材）
• brand_prone_keywords —— 命中"品牌 logo 高密度题材"的检索词

⚠️ 三条禁止用途（画面素材，交付前必读）

• Pexels License：免费商用、官方写明不强制署名
• Pixabay Content License：免费商用、不强制署名；CC0 仅适用于 2019-01-09 之前发布的内容；平台 $0 赔偿

⚠️ 音乐许可红线（音频，交付前必读）

音源给的不是一份总许可，而是每条各自的 Creative Commons 许可。给视频配乐天然是
「改编 + 可能商用」，所以：

• --allow-restricted 可取回 NC/ND（只在确认纯个人非商业用途时使用），取回后 --check 仍会拦
• ⚠️ ShareAlike 是最容易漏的一条：CC BY-SA / CC BY-NC-SA 标着「可商用 · 可改编」，
  但附带义务是 —— 你的视频（衍生物）必须以同一 CC 许可发布。
  带货 / 品牌 / 需要独家版权的视频不要用 SA 素材，它会把许可"传染"到整个作品。
  credits.md 会为 SA 组单独打出警告，notes 列也会写明
• CC 的署名是许可生效条件，不是礼貌。credits.md 会为需署名的曲目生成可直接粘贴的署名行（含真实作品名）
• ⚠️ 期望管理（实测数据）：两个音源差别极大 ——
  采样 Jamendo 500 条，可商用且可改编的只占 4%（by-nc-nd 一项占 81.2%，
  它靠卖商用授权赚钱）；采样 Freesound 600 条，可用率 86.3%（以 CC0 / CC BY 为主）。
  两者相差 21 倍，所以超采样倍数也按源不同（Jamendo 抓 10 倍、Freesound 抓 2 倍），
  否则前者过滤后几乎必然是 0 条。
• 音效要限时长：实测搜 footsteps 头部返回的是 1481 秒（25 分钟）环境录音，
  短视频用不上还拖慢下载 → 默认 --sfx-max-duration 60（0 = 不限）

> 本工具只做记录、过滤和提示，不构成法律意见，也不替使用者承担法律责任。

硬约束

• 不联网上报：只调用素材站 API，不向任何第三方发送使用记录
• 不要账号：除素材站免费凭据外无任何登录
• 不静默失败：丢弃有计数、失败进 errors、缺凭据退 3
• 不猜许可：音频许可解析不出来就丢弃并计数，绝不默认放行
• 不改原文件：所有产物写在 --out
• 批量安全：单条下载失败不影响整批，失败项进 manifest.json

已知边界（诚实列出）

• Pixabay 没有音频 API（实测 403），音乐只能用 Jamendo
• Jamendo 可用曲目极少：实测 500 条采样里只有 4% 可商用且可改编
  （by-nc-nd 占 81%）。工具已自动超采样，但仍要预期"抓 240 条得 7 条"
• Freesound 已用真实 token 端到端验证（检索/下载/自检全通过）；唯一保留项是
  CDN 在部分网络下偏慢且没有断点续传 —— 用 --sfx-max-duration 避开长音频
• 许可判定不靠模糊解析：Jamendo 用结构化布尔位（licenses.ccnc/ccnd，
  比解析 URL 权威）；Freesound 实测返回许可 URL（文档写的三个词组是写入 API 的
  取值，会误导）—— 两个源都认不出就丢弃，绝不放行
• 中文/中式场景基本搜不到：Pexels/Pixabay 以欧美视角为主 → 走 ComfyUI 或自录
• 竖屏视频极少：实测搜 video game controller neon 返回的视频全是横屏，被 --ratio 9:16 全过滤（0 条视频素材）
• 品牌 logo 会漏检：关键词启发式只看标题/标签。实证：搜 game controller 返回的图里带 Xbox / TCL logo，而标题只有 game, controller —— 这类必须人工逐张看画面
• 真人也会漏检：只出现在画面里、标题没提的真人抓不到
• Freesound 用的是 previews 直链（原始文件需 OAuth2 授权流程），音质为预览档
• 不做剪辑：本技能到"素材包"为止

反模式（不要这样做）

FAQ

Q：画面素材能商用吗？要署名吗？
A：Pexels/Pixabay 都允许免费商用、都不强制署名。但三条禁令要遵守。credits.md 已按来源写好了署名文本。

Q：音乐能商用吗？要署名吗？
A：逐条看。默认只保留 CC0 / CC BY / CC BY-SA（都可商用、可改编），其中 BY 系列必须署名。CC BY-NC（禁商用）和 CC BY-ND（禁改编）默认被丢弃。

Q：为什么 --with-audio 什么都没搜到？
A：可能是凭据没配，或许可过滤把结果都丢了（CC 曲库里 NC/ND 占比不低）。看 candidates.json 的 filtered_out.license_restricted 计数；若确实要用受限曲目，加 --allow-restricted（并确认非商业用途）。

Q：为什么搜不到我要的中文画面？
A：Pexels/Pixabay 是欧美素材库，中文场景/中式元素/中文字幕模板基本没有。这类题材建议用 ComfyUI 生成或自己录屏。

Q：为什么竖屏（9:16）搜不到视频？
A：Pixabay 视频库以横屏为主，且视频接口会忽略 orientation 参数（本工具已改为客户端按宽高比过滤）。可行做法：--ratio 16:9 取横屏再裁剪、--any-orientation 自己挑、或改用图片。

Q："疑似品牌风险"标记准确吗？
A：只是关键词启发式的初筛，会漏。 实测搜 game controller 返回的画面里有 Xbox/TCL logo，但标题没有品牌词。游戏、电子产品、汽车、运动鞋这类题材 logo 密度极高，必须逐张看画面。

Q：可以只用 Pixabay 吗？
A：可以。只设 PIXABAY_API_KEY 即可，脚本会自动跳过没有凭据的源（并打印 WARN）。

Q：重复运行会重复下载吗？
A：不会。已存在且非空的文件会跳过。

Q：有失败怎么办？
A：查 candidates.json 的 errors（检索失败）和 manifest.json 的 failed（下载失败）。网络抖动已内置退避重试 3 次，4xx 不重试（重试无意义）。

复用资源