54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# 转码档位配置、雪碧图与播放缩略图轴
|
||
|
||
## 目标
|
||
|
||
1. 后台可配置转码档位与雪碧图参数，worker 对之后的新任务在 30 秒内自动生效。
|
||
2. 转码成功后生成雪碧图与 VTT，登记到 `media_thumbnail`。
|
||
3. 播放接口与详情剧集返回 `thumbnailsUrl`，无产物时为 `null`。
|
||
|
||
## 配置模型
|
||
|
||
- `sys_config.config_key = media.transcode.profile`，值为 JSON。
|
||
- 配置包含总开关、分片秒数、码率阶梯与雪碧图参数。
|
||
- 缺省配置等价于现有 360p/480p/720p/1080p 四档。
|
||
- 后台 GET 缺省或历史配置非法时返回 yml 等价默认值；PUT 非法时返回统一 400，且不写库。
|
||
- worker 读取配置缓存 30 秒；缺省、解析失败或校验失败时回退 yml 默认阶梯。
|
||
|
||
## 权限取舍
|
||
|
||
现有权限点没有 `media:transcode`。本次两个接口复用最小可用的
|
||
`episode:upload`，避免新增权限点导致已有角色需要补授权；不新增菜单或权限 SQL。
|
||
|
||
## 数据与产物
|
||
|
||
- 新增 `media_thumbnail`，按 `episode_id` 唯一，记录 VTT、雪碧图前缀、采样参数、
|
||
尺寸、帧数、时长、状态、错误与总大小。
|
||
- 雪碧图目录固定在 `transcoded/{taskId}/thumbnails/`：
|
||
`thumbnails.vtt` + `sprite_001.jpg` 等多张图。
|
||
- VTT cue 链接使用相对路径 `sprite_XXX.jpg#xywh=x,y,w,h`，同一 VTT 目录下可直接解析。
|
||
- 缩略图失败只把 `media_thumbnail.status` 置 `FAILED` 并记录错误；主 HLS 仍成功。
|
||
|
||
## 播放
|
||
|
||
- `PlayRespVO` 和 `AppEpisodeVO` 增加 `thumbnailsUrl`。
|
||
- 查询 `media_thumbnail` 仅读取 `READY` 产物；objectKey 经
|
||
`MediaStorageService.toPublicUrl` 后使用现有 `PlaybackSigner` 签名。
|
||
- 详情剧集列表批量查询缩略图，禁止 N+1。
|
||
- 不改变现有 HLS/原文件回落与 qualities 列表。
|
||
|
||
## 测试
|
||
|
||
- worker：配置解析、非法配置回退 yml、30 秒缓存、VTT 坐标、多雪碧图索引、
|
||
缩略图失败不阻断主转码。
|
||
- admin：GET 默认值、PUT 非法不落库、PUT 成功落库。
|
||
- playback：有 READY 缩略图返回签名 `thumbnailsUrl`，无产物返回 `null`。
|
||
- 门禁：`mvn -pl fruitshorts-transcode-worker,fruitshorts-admin-api,fruitshorts-app-api -am test`。
|
||
|
||
## 风险 / 边界
|
||
|
||
- 本次只对合并后的新转码任务生效，不回跑历史任务。
|
||
- 配置中的顶层 `enabled` 会持久化并返回；本单不改变既有队列消费开关语义，
|
||
worker 仍以 `worker-enabled` 决定是否消费任务。
|
||
- 雪碧图生成依赖 ffmpeg `tile` 滤镜；真实产物由 worker 门禁和 PM 后续环境验收，
|
||
本任务不启动服务、不改客户端。
|