MovieApp 开发文档

Appearance

播放与弹幕 ​

播放相关接口负责提供影片详情、真实播放地址、弹幕以及去广告的 M3U8 文件。

获取视频详情 ​

  • Method：GET
  • Path：/api/mobile/v1/vod/detail
  • Query：
参数必填类型说明
vodId是number视频 ID。

响应字段 ​

json
{
  "vodId": 216862,
  "vodName": "三更雪",
  "vodPic": "https://cdn.example/poster.jpg",
  "vodBlurb": "简介",
  "vodDirector": "导演",
  "vodActor": "主演A, 主演B",
  "vodArea": "中国大陆",
  "vodYear": "2025",
  "vodLang": "普通话",
  "typeName": "国产剧",
  "sources": [
    {
      "sourceFrom": "youku",
      "sourceName": "优酷超清",
      "sourceType": "OFFICIAL",
      "episodes": [
        {
          "episodeIndex": 1,
          "episodeTitle": "第1集",
          "playUrl": "https://v.youku.com/xxx"
        }
      ],
      "sort": 100
    }
  ],
  "recommended": [
    {
      "vodId": 213847,
      "vodName": "照镜辞",
      "vodPic": "https://cdn.example/recommend.jpg",
      "vodRemarks": "更新至第10集",
      "typeName": "国产剧"
    }
  ]
}

说明：

  • sources：由 vodPlayFrom、vodPlayUrl 与远程 playerConfig 决定，后端会根据配置过滤不可用的播放源，并按照 sort 值降序排列。
  • recommended：同类型最新 10 条视频，用于推荐区域。
  • Redis 缓存键：{redisKey}_vodDetail_{vodId}。如需强制更新，可在后台关闭缓存或手动清除。
  • 数据来源：
    • mac_vod：主表，提供影片基础信息、播放源原始字符串、同分类推荐。
    • mac_type：拼接 typeName。
    • app_config（type=AppConfig）：决定缓存开关、解析地址、播放源配置 URL、弹幕接口等。其中播放源的 sourceType：
      • mobile.service 会把来自 bilibili、qiyi、mgtv、youku、qq、pptv、letv、sohu 等源自动标记为 OFFICIAL；
      • 其余源可通过 playerConfigUrl 对应 JSON 内设置 "type": "OFFICIAL" 明确指定，便于客户端触发官解。

获取官解真实地址 ​

  • Method：GET
  • Path：/api/mobile/v1/vod/OfficialPlayUrl
  • Query：
参数必填类型说明
url是string原始播放页地址（例如腾讯、优酷链接）。

响应 ​

返回一个字符串，为解析后的真实播放地址。该功能依赖后台 AppConfig.data.officialUrl（第三方解析接口）及 officialUrlField（结果字段名）。如未配置，会返回错误。

解析接口由第三方提供，超时时间 5 秒。建议客户端在调用失败时回退到 WebView 播放。

触发条件 ​

  • 播放源来自 playerConfig，当某个源的配置项 type（或 from）被标记为 OFFICIAL 时，客户端应在播放时调用本接口获取真实地址。
  • 后台路径：APP 管理 → 基础配置（type=AppConfig）中维护 officialUrl、officialUrlField；在 playerConfigUrl 指向的 JSON 中，为需要官解的源设置 "type": "OFFICIAL"。
  • 若源未被标记为 OFFICIAL，OfficialPlayUrl 接口不会被调用，播放器直接使用 vodPlayUrl 中的链接。

获取弹幕 ​

  • Method：GET
  • Path：/api/mobile/v1/vod/dplayerDanmu
  • Query：
参数必填类型说明
url是string播放地址或影片标识。具体由第三方弹幕服务决定。

响应示例 ​

json
{
  "code": 0,
  "danmuku": [
    [1.5, 1, 16777215, "第一条弹幕"],
    [2.8, 1, 16777215, "不错哦"]
  ],
  "player": "dplayer"
}

后端会：

  • 调用 AppConfig.data.danmuApiUrl 指定的第三方接口（自动拼接 ?url= 参数）。
  • 清理空字段并按时间排序弹幕。
  • 移除第三方响应中的 code 字段，保留 danmuku 等关键信息。

去广告 M3U8 ​

  • Method：GET
  • Path：/api/mobile/v1/vod/m3u8
  • Query：
参数必填类型说明
url是string原始 M3U8 地址（可以是主播放列表或子播放列表）。
quality否string指定分辨率（如 720）。若未提供则默认选择最高带宽。

行为说明 ​

  • 接口会解析 M3U8：
    • 若为主播放列表，自动选择最高带宽或匹配 quality 的子流。
    • 若为媒体播放列表，移除包含广告关键词（adjump、/ads/ 等）的分段，并补全绝对路径。
  • 返回内容类型：application/vnd.apple.mpegurl，内容为纯文本。
  • 缓存键：{redisKey}_m3u8Url_{encodeURIComponent(url)}。

错误处理 ​

  • 未配置 AppConfig 中的 danmuApiUrl、officialUrl、playerConfigUrl 时，接口会返回 500 错误。
  • 第三方接口超时时会抛出 ECONNABORTED，客户端应提示用户稍后重试。

推荐在播放器中为 m3u8 接口添加超时和错误重试机制，确保用户体验。

配置与调优 ​

  • 后台管理 → APP 管理 / 基础配置（type=AppConfig）字段说明：
    字段作用
    redisStatus是否启用 Redis 缓存。关闭后所有接口走实时查询。
    redisKey缓存键前缀，实际键名会追加 _homeData_、_vodDetail_ 等后缀。
    redisTime缓存时长（秒），默认 1800。
    playerConfigUrl指向远程 JSON，定义播放源展示名、排序、status、type。当 type 或 key 被识别为官方源时，移动端需调用官解接口。
    officialUrl / officialUrlField第三方官解接口地址与返回中真实播放地址字段名。
    danmuApiUrl第三方弹幕服务地址，移动端以 ?url= 拼接参数调用。
  • 建议统一维护 playerConfig JSON 的格式，至少包含：show（展示名称）、sort（越大越靠前）、status（"1" 启用）、type（可为空或 "OFFICIAL"）。
  • 若新增播放源，需要在 playerConfigUrl 指向的配置文件中增加对应项，并保证 mac_vod.vod_play_from 中包含相同的 key。
  • 弹幕或官解接口替换后，务必同步更新本仓库文档，提醒客户端刷新缓存。