本文主要把早期项目笔记中与媒体库开发直接相关的基础知识收成一篇速记：动态范围与蓝光规格、API 契约概念、实时进度通道，以及像素格式 / 图像处理边界。不追求百科完整度；详细播放与架构见同系列专题。
动态范围：HDR / SDR 与 tone mapping
- SDR：常见 Web 与普通显示器基线（如 BT.709）。
- HDR10 / PQ、HLG、Dolby Vision：更高动态范围与不同传递特性；浏览器与部分设备无法「原样」显示。
- Tone mapping：把高动态范围映射到可显示的 SDR（或另一目标），可能在服务端转码（
tonemapx/ VAAPI / OpenCL）或在原生播放器本地完成。
需要注意的是：
- 「能解码」≠「能正确显示」。
- Web 端对 HDR/DV 的兜底往往依赖服务端 tone map；原生端才有机会走硬解直通。
详见：动态范围与色彩管线、硬转码与 Tone Mapping。
蓝光与 UHD 蓝光（片源语境）
| 项 | 常见差异（片源语境） |
|---|---|
| 分辨率 | 1080p vs 4K 级 |
| 动态范围 | 多 SDR / 部分 HDR vs HDR10 / DV 更常见 |
| 音频 | 高码率无损、多音轨、对象音频更常见于 UHD 片源 |
| 字幕 | PGS 等位图轨更常见 |
对媒体库的含义：扫描与 Planner 必须能描述编码、色彩与字幕形态，而不是只认「扩展名是 mkv」。
像素格式速记：yuv420p10le
- yuv：亮度 + 色度分离。
- 420：色度水平 / 垂直抽样（体积与兼容性常见组合）。
- p10：10-bit 分量。
- le：小端。
HDR / Main10 HEVC 片源里 10-bit 像素格式很常见；转码到 Web SDR 时通常落到 8-bit yuv420p 一类基线。硬解与滤镜链是否支持 10-bit 路径，会影响能否 DirectPlay 或必须转码。
API 契约：DTO、OpenAPI / Swagger、Scalar
| 概念 | 用途 |
|---|---|
| DTO | 跨边界传输的数据形状，不等于领域实体 |
| OpenAPI | 接口契约描述；生成文档、客户端与校验 |
| Swagger UI / Scalar | 人类可读的 API 探索与调试界面 |
工程习惯：
- 对外响应信封（成功 / 错误 / 分页 Meta）保持稳定。
- 领域内部 Result 与对外 ApiResponse 可以分层（见结果契约专题）。
- 文档站点与真实路由版本要同步，避免「UI 能点、实现已改」。
详见：后端结果契约与配置可视化。
SignalR 与实时进度
长任务（扫描、刮削、重命名）适合：
HTTP 只下命令 → 后台执行 → SignalR（或同类）推送进度 / 完成 / 失败
注意：
- 进度事件是观测面，不是第二个命令通道。
- 重连后应能恢复「当前任务状态」查询，不能只依赖瞬时推送。
- 权限：进度可见范围应与用户角色 / 库权限一致。
服务端图像处理边界（ImageSharp 一类）
海报 / 封面 / 缩略图处理常见落在服务端图像库（如 SixLabors.ImageSharp）：
- 解码、缩放、格式转换、有损压缩
- 与「播放像素管线」不是同一条链
图片访问（Signed URL、缓存、鉴权生成期）见：图片访问架构。不要把缩略图处理策略和播放 tone mapping 混为一谈。
使用建议
- 新人先读本速记建立词汇，再进播放 / 扫描专题。
- 概念变更以现行 arch / decision 为准；本篇只做入门锚点。
- 未收录：纯 IDE 技巧、过时对话草稿、与媒体库无关的算法随笔。
相关阅读
来源
本文择优改写自早期 vault 基础知识笔记（HDR/SDR、蓝光规格、DTO、OpenAPI、SignalR、ImageSharp、yuv420p10le 等；原稿已从本仓 drafts 移除），并与 2026 公开系列专题对齐；删除对话腔与不可核验断言。