媒体处理

受众：开发者摘要：Media starter 使用方式、Provider 抽象、转码 / 截图 / 录制回调归一化和 Core File 绑定边界。

Media starter 提供统一的媒体处理抽象，用于 Meeting 云录制文件处理、Video 转码 / 封面截图、Live 回放处理和 Core File 文件绑定。

第一阶段保持轻量：内置 log provider，不连接外部媒体服务，便于业务模块先完成本地 contract 和测试。真实云转码、截图、录制回调和回调验签通过新增 MediaProvider 接入。

何时使用

适合：

提交视频转码、截图、封面生成等异步媒体任务。
把 RTC / 云录制 provider 回调归一化为稳定业务结果。
描述媒体处理产物和 Core File 资源绑定关系。

不适合：

直接替代 Storage / Core File 的权限、生命周期和资源落库。
在业务模块里直接依赖云厂商媒体 SDK。
把 provider 原始回调大 payload、密钥或签名 URL 透传给业务 DTO / VO。

快速开始

按需引入：

xml

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-media</artifactId>
</dependency>

启用：

yaml

spring:
  open:
    media:
      enabled: true
      default-provider: log

提交任务：

java

MediaProcessTask task = Media.submit(new MediaProcessRequest(
        null,
        MediaProcessTypes.TRANSCODE,
        "video",
        "video-1",
        new MediaSource("res-1", "local", "videos/original.mp4", "original.mp4",
                null, "video/mp4", 1024L, Map.of()),
        List.of("mp4", "m3u8"),
        Map.of(),
        Map.of()));

归一化回调：

java

MediaProcessResult result = Media.handleCallback(new MediaProcessCallback(
        "log",
        "task-1",
        MediaProcessTypes.RESOURCE_BINDING,
        MediaProcessStatuses.COMPLETED,
        Instant.now(),
        List.of(),
        null,
        null,
        Map.of("providerEvent", "finished")));

机制说明

Media starter 的核心边界是 Facade + Manager + Provider：

Media 是业务侧入口，不直接依赖云厂商 SDK。
DefaultMediaManager 负责选择启用的 provider、提交任务和归一化回调。
MediaProvider 只负责具体 provider 的任务提交和回调标准化。
MediaProcessRequest 描述 provider、任务类型、业务归属、来源和输出格式。
MediaProcessCallback 描述 provider 回调中已经过验签和解析的稳定字段。
MediaProcessOutput 描述转码文件、截图、封面图、录制文件等产物。
MediaResourceBinding 只描述资源绑定信息，不直接写 Core File 表。

内置任务类型

类型	说明
`transcode`	转码任务，例如 mp4 / hls / dash
`screenshot`	截图或封面生成任务
`recording-callback`	录制文件完成 / 失败回调归一化
`resource-binding`	媒体产物与 Core File 绑定描述

配置

yaml

spring:
  open:
    media:
      enabled: true
      default-provider: log
      providers:
        log:
          provider: log
          enabled: true
          remark: local contract provider

配置	默认值	说明
`spring.open.media.enabled`	`true`	是否启用媒体处理能力；显式设为 `false` 时关闭
`spring.open.media.default-provider`	`log`	默认 provider
`spring.open.media.providers.*.provider`	-	provider 使用的实现名称
`spring.open.media.providers.*.enabled`	`true`	provider 是否启用
`spring.open.media.providers.*.remark`	-	provider 备注

Provider 实现边界

新增 Provider 时只实现 MediaProvider：

providerName() 返回稳定 provider 名称，内置名称放到 MediaProviderNames。
supports(taskType) 只判断任务类型能力，不做业务权限判断。
submit(request) 负责提交 provider 任务并返回统一任务快照。
normalizeCallback(callback) 负责把已验签、已解析的 provider 回调转成标准结果。
Provider metadata 只放轻量诊断信息，不放密钥、原始大 payload 或临时访问凭证。

私有文件读取、Storage 授权、Core File 落库、附件 owner / bizType / scene 校验由调用方或后续适配层完成，不在通用 Provider 中硬编码。

业务适配入口

当前已有三类业务适配：

场景	入口	行为
Core File / 文件生命周期	`FileMediaResourceBindingAdapter`	把 `MediaResourceBinding` 转成文件记录保存 / 绑定命令，调用方负责事务边界和后续资源生命周期
Meeting / 录制回调	`POST /api/v1/meetings/{roomNo}/recordings/{recordingNo}/files`	录制完成 / 失败回调先按 `recording-callback` 归一化，再更新会议录制状态、Core File `resourceId`、`storageDisk`、转存来源 / 状态和文件快照
Video / 创作者媒体处理	`POST /api/v1/video/creator/contents/{contentId}/media-processing`	当前创作者拥有内容后提交 `video-content` 媒体任务，默认用于转码、截图或封面生成，并返回任务快照

与其他模块关系

模块	关系
Core File	保存文件元数据、私有访问和文件生命周期；Media 只描述绑定关系
Core File	已提供文件记录绑定适配；回调补偿和失败重试由 Runtime 或调用方按 contract 编排，异步任务调度由 Core Async Task 承接
Meeting	已把 RTC 录制文件完成 / 失败回调归一化后更新会议录制状态、Core File 绑定和转存来源 / 状态快照
Video	已提供创作者媒体处理提交入口，可提交转码 / 截图任务并绑定处理产物
Live	可复用转码、截图和回放文件处理 contract

验证

bash

./mvnw -pl spring-open-starters/spring-open-starter-media -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
git diff --check

媒体处理 ​

何时使用 ​

快速开始 ​

机制说明 ​

内置任务类型 ​

配置 ​

Provider 实现边界 ​

业务适配入口 ​

与其他模块关系 ​

验证 ​