# media-assets

匠厂（深圳匠厂科技）跨项目共享媒体资产库。

本仓库是 **media-assets 源仓库**，只维护轻量媒体资源与工具下载 manifest，供各技能（skill）的录制脚本使用。

## 用户下载方式

**不要下载 Gitea 源码 ZIP。** 源码 ZIP 中的 Git LFS 文件可能是 pointer，无法直接作为背景音乐或字体使用。

用户端应下载 CI 生成的稳定包：

https://git.jc2009.com/client-commons/media-assets/releases/download/vlatest/media-assets.zip

### 稳定包内容

`media-assets.zip` 包含：

- `music/`
- `fonts/`
- `watermark/`
- `manifest.json`

`media-assets.zip` **不包含** `ffmpeg.exe` / `ffprobe.exe` 等二进制工具。

ffmpeg 由 `jiangchang-platform-kit` 按 `manifest.json` 里的 `tools.ffmpeg` 下载源另行下载、解压并缓存到用户数据目录。

## 仓库内容

| 类型 | 说明 |
|---|---|
| 背景音乐 | `music/` 目录 |
| 字体 | `fonts/` 目录 |
| 水印 | `watermark/` 目录 |
| 工具下载清单 | `manifest.json` |

**本仓库不直接存放 `ffmpeg.exe` / `ffprobe.exe` 等大二进制工具。**

## 目录结构

```text
media-assets/
  manifest.json
  music/
  fonts/
  watermark/
```

### 音乐子目录

| 目录 | 用途 |
|---|---|
| `music/calm/` | 舒缓类背景音乐，适合流程演示视频 |
| `music/upbeat/` | 活力类背景音乐，适合功能展示视频 |
| `music/corporate/` | 商务类背景音乐，适合对外宣传视频 |

## ffmpeg / ffprobe 获取方式

视频处理工具不由本仓库直接提供，而由 **`jiangchang-platform-kit`** 根据 `manifest.json` 按需下载、解压并缓存到用户数据目录：

```text
D:\jiangchang-data\shared\media-assets\bin\win32-x64\
```

说明：

- 用户**不需要**手工安装 ffmpeg，也**不需要**依赖系统 PATH。
- 用户电脑**没有 Git** 也可以工作：kit 会通过 HTTP 下载稳定 `media-assets.zip` 与 ffmpeg essentials 包。
- Windows x64 默认使用 **ffmpeg-release-essentials**（非 full build）。
- `manifest.json` 中配置了国内镜像与 gyan.dev 官方源；kit 会按顺序尝试。

## 背景音乐

背景音乐从稳定包或本仓库的 `music/` 目录读取。各技能可通过 `jiangchang_skill_core.media_assets` 解析路径并选取音频文件。

## 使用方式

各技能录制脚本通过环境变量 `MEDIA_ASSETS_ROOT` 定位本库：

```python
MEDIA_ASSETS_ROOT = os.environ.get("MEDIA_ASSETS_ROOT", r"D:\OpenClaw\client-commons\media-assets")
```

未设置环境变量时，kit 默认使用 `{JIANGCHANG_DATA_ROOT}/shared/media-assets`（例如 `D:\jiangchang-data\shared\media-assets`）。

## 开发者说明

- MP3、字体、图片等媒体文件通过 **Git LFS** 管理，clone 后请执行 `git lfs pull`。
- 更新音乐后，推送 `main` 前请确认本地 mp3 不是 LFS pointer（可用 `python scripts/validate_bundle.py .` 校验）。
- `main` 分支 push 后，CI 会覆盖 `vlatest` release 下的 `media-assets.zip`，永远只保留一个稳定包。

## 注意

- 请勿将版权不明的音乐文件上传至本库。