planet/docs/technical/zh/earth-news-live-streams-collector-format.md

新闻直播采集格式

news_live_streams 采集器面向“频道目录 JSON”输入，而不是直接抓网页。

这样做的目标是：

• 让后台能够稳定接入世界各地新闻直播源
• 让 Earth 页面电视模块始终消费统一结构
• 便于后续接入类似 worldmonitor 那种 YouTube / HLS / iframe 混合频道目录

推荐 JSON 结构

{
  "sources": [
    {
      "id": "bbc-world-news",
      "name": "BBC World News",
      "provider": "BBC",
      "region": "UK",
      "language": "en",
      "source_type": "youtube",
      "youtube_video_id": "dQw4w9WgXcQ",
      "youtube_channel": "https://www.youtube.com/@BBCNews",
      "embed_url": "",
      "stream_url": "",
      "homepage_url": "https://www.youtube.com/@BBCNews/live",
      "poster_url": "",
      "sort_order": 220,
      "is_enabled": true,
      "notes": "Primary English global news channel"
    },
    {
      "id": "france24-en",
      "name": "France 24 English",
      "provider": "France 24",
      "region": "France",
      "language": "en",
      "source_type": "hls",
      "stream_url": "https://example.com/live.m3u8",
      "homepage_url": "https://www.france24.com/en/live",
      "sort_order": 230,
      "is_enabled": true
    },
    {
      "id": "cctv4-page",
      "name": "CCTV-4 中文国际",
      "provider": "CCTV",
      "region": "China",
      "language": "zh-CN",
      "source_type": "iframe",
      "embed_url": "https://tv.cctv.com/live/cctv4/",
      "homepage_url": "https://tv.cctv.com/live/cctv4/",
      "sort_order": 10,
      "is_enabled": true
    }
  ]
}

字段约定

• id: 唯一标识，建议稳定不变
• name: 频道显示名
• provider: 提供方
• region: 国家或地区
• language: 语言代码
• source_type: iframe / hls / video / external / youtube
• embed_url: 适合 iframe 内嵌的页面
• stream_url: 直接视频流地址
• homepage_url: 官网或频道页
• youtube_video_id: YouTube 直播视频 ID
• youtube_channel: YouTube 频道 handle 或频道 URL
• poster_url: 封面图，可选
• sort_order: 排序值，越小越靠前
• is_enabled: 是否启用
• notes: 简短备注

面板行为约定

• youtube
  • 优先使用 youtube_video_id
  • 无法内嵌时至少保留 youtube_channel 或 homepage_url 供外部打开
• hls / video
  • 优先走 stream_url
• iframe
  • 优先走 embed_url
• external
  • 不尝试内嵌，只保留外部打开

当前实现状态

• 后台设置页可以手工维护频道目录
• Earth 电视模块会合并：
  • 手工配置源
  • news_live_streams 采集器采集源
• 当前默认兜底源为 CCTV-4 中文国际
• news_live_streams 在未配置 override 时，默认使用 iptv-org：
  • channels.json
  • streams.json
  • logos.json 并自动筛出新闻类频道目录

采集器配置方式

news_live_streams 不需要单独新页面，直接复用控制台 /settings 的“采集器设置”：

• endpoint
  • 频道目录 JSON API 地址
• auth_type
  • none / bearer / api_key / basic
• headers
  • 额外请求头
• config
  • 采集器请求与解析行为

支持的 config 字段

{
  "timeout": 30,
  "method": "GET",
  "params": {
    "region": "global"
  },
  "body_type": "json",
  "body": {
    "include_disabled": false
  },
  "response_path": "payload.channels"
}

• timeout
  • 请求超时秒数
• method
  • GET 或 POST
• params
  • 查询参数对象
• body_type
  • json 或 form
• body
  • 配合 POST 使用的请求体
• json_body
  • 显式 JSON 请求体，优先级高于 body
• form_body
  • 显式表单请求体，优先级高于 body
• response_path
  • 返回 JSON 中频道数组所在路径，支持点路径，例如：
    • payload.channels
    • data.items
    • result.streams

认证补充

• bearer
  • 使用 Authorization: Bearer <token>
• api_key
  • 默认作为请求头发送
  • 如果 auth_config.in = "query"，则作为 query param 发送
• basic
  • 使用 HTTP Basic Authorization

兼容的响应结构

采集器会优先读取：

• 顶层数组
• 或这些常见字段下的数组：
  • sources
  • streams
  • channels
  • items
  • results
  • data

同时会兼容这些字段别名：

• id / source_id / slug / channel_id / code
• name / title / channel / display_name
• provider / publisher / network
• stream_url / stream / playback_url / hls_url / m3u8_url
• embed_url / embed / page_url
• homepage_url / source_url / website
• language / lang / locale
• youtube_video_id / video_id
• youtube_channel / channel_handle