配置指南與欄位字典

配置載入由 BaseConfig 統一處理；VodConfig 管理站點與解析器，LiveConfig 管理直播清單與頻道。以下依目前本地程式碼整理，並區分完整配置與物件片段。

先從可直接修改的配置開始

先選擇點播或直播的完整配置，再替換名稱、路徑與需要的欄位。後續各節另有標明層級的物件片段，需放入對應欄位。

範例位置說明主配置中的 ./ 與 ../ 會以該配置檔的位置展開；外部陣列檔或直播列表內的路徑不會再次展開，請使用完整網址。example.com 與保留測試 IP 只用來展示結構，並不是可用來源。

點播配置：Java、JS、Python

JSON / VodConfigvod.json

{
  "spider": "./spider.jar",
  "sites": [
    {
      "key": "java_demo",
      "name": "Java Demo",
      "type": 3,
      "api": "csp_Demo"
    },
    {
      "key": "js_demo",
      "name": "JavaScript Demo",
      "type": 3,
      "api": "./demo.js",
      "ext": { "region": "tw" }
    },
    {
      "key": "py_demo",
      "name": "Python Demo",
      "type": 3,
      "api": "./demo.py"
    }
  ],
  "parses": [
    {
      "name": "JSON 解析範例",
      "type": 1,
      "url": "https://example.com/parse?url=",
      "ext": {
        "flag": ["demo"],
        "header": { "User-Agent": "ExampleClient/1.0" }
      }
    }
  ]
}

Java 使用 csp_ 類別名稱；JS 與 Python 檔案使用 ./ 相對路徑。

直播配置：外部 M3U

JSON / LiveConfiglive-config.json

{
  "lives": [
    {
      "name": "M3U 範例",
      "url": "./live.m3u",
      "epg": "https://example.com/epg.xml",
      "logo": "https://example.com/logo/{id}.png",
      "ua": "ExampleClient/1.0",
      "timeZone": "Asia/Taipei",
      "boot": false
    }
  ]
}

url 也可改成 ./live.txt 或 ./live.json；內容格式會由 LiveParser 判斷。

VodConfig 頂層欄位

主要配置入口。只有 headers、proxy、rules、doh 等經過 fetchArray 的欄位，才支援物件陣列、外部位置或兩者混用。

18 欄位

欄位	類型	用途	預設
`urls`	Depot[]	配置倉庫清單；登記各項配置後載入第一項，清單不可為空。	—
`msg`	string	配置回傳的錯誤訊息；存在時停止載入，普通配置與倉庫都適用。	—
`spider`	string	全域 Spider JAR 路徑或 URL；Site 未指定 jar 時使用。	—
`wallpaper`	string	桌布圖片、GIF 或影片位置。	—
`logo`	string	App Logo 圖片位置。	—
`notice`	string	啟動後顯示的公告文字。	—
`sites`必要	Site[]	點播站點清單。	—
`parses`	Parse[]	需要進一步處理 URL 時使用的解析規則。	—
`lives`	Live[]	內嵌直播配置清單；也可以另外載入獨立 LiveConfig。	—
`doh`	Doh[]	DNS over HTTPS 端點。	—
`proxy`	Proxy[]	依 host 套用的代理伺服器。	—
`rules`	Rule[]	WebView 網路擷取與腳本規則。	—
`headers`	Header[]	依 host 注入或覆寫 HTTP 請求標頭。	—
`hosts`	string[]	原主機=目標主機或 IP 的 DNS 覆蓋。	—
`flags`	string[]	提供給 playerContent 的全域平台旗標。	—
`ads`	string[]	要攔截的主機名稱清單。	—
`danmaku`	string	彈幕搜尋 API；可使用 {name} 與 {episode}。	—
`assrt`	string	字幕搜尋服務使用的存取字串。	—

配置倉庫 Depot

JSON / Depotdepot.json

{
  "urls": [
    { "name": "同目錄配置", "url": "./vod.json" },
    { "name": "遠端配置", "url": "https://example.com/vod.json" }
  ]
}

頂層出現 urls 時，App 登記清單後會載入第一項配置，清單不可為空；每一項包含 name 與 url。

可引用外部陣列的欄位

JSON / arraysVodConfig 頂層欄位片段

{
  "doh": "./doh.json",
  "headers": [
    "./headers.json",
    {
      "host": "media.example.com",
      "header": { "Referer": "https://example.com/" }
    }
  ],
  "proxy": "./proxy.json",
  "rules": [
    "./rules.json",
    {
      "name": "媒體請求範例",
      "hosts": ["player.example.com"],
      "regex": [".*m3u8.*"],
      "exclude": [".*preview.*"]
    }
  ]
}

整個欄位可以是一個位置，也可以在陣列中混用外部 JSON 位置與內嵌物件。外部檔案本身必須回傳 JSON 陣列。

Site 點播站點

0XML HTTP1JSON HTTP3JAR / JS / PY4HTTP 擴充

19 欄位

欄位	類型	用途	預設
`key`必要	string	站點唯一識別碼，不可重複。	—
`name`必要	string	顯示名稱。	—
`type`	integer	0=XML HTTP、1=JSON HTTP、3=Spider；4=擴充 HTTP JSON，分類篩選以 Base64 ext 傳送，站點 ext 另以 extend 傳送。	0
`api`必要	string	HTTP 端點、csp_ 類別，或以 ./、../ 表示的 .js／.py 相對路徑；也可使用完整網址。	—
`ext`	string \| object \| array	type 3 傳給 Spider.init；HTTP 站點以 extend 傳送。物件與陣列先序列化為字串；主配置可填 URL 或相對路徑。	—
`jar`	string	覆蓋全域 spider 的 JAR 位置。	—
`click`	string	在 WebView 執行的 JavaScript 點擊程式。	—
`playUrl`	string	type 0/1 的解析 URL 前綴；支援 json: 端點或 parse: 解析器名稱。type 3/4 由播放 Result.playUrl 提供。	—
`hide`	integer	1 時從站點清單隱藏。	0
`indexs`	integer	1 時作為索引站點。	0
`timeout`	integer	播放逾時秒數，最小 1。	15
`searchable`	integer	0=永久停用、1=啟用；執行期間也可能保存為 2。	1
`changeable`	integer	0=禁止切換、1=可切換；執行期間也可能保存為 2。	1
`lang`	string	搜尋關鍵字轉換語系，支援繁簡中文標籤；非空的其他值保留原文，空值使用既有轉換。	—
`danmaku`	integer	0 停用此站點透過全域彈幕 API 自動搜尋，不影響 Spider 自帶彈幕。	1
`quickSearch`	integer	0 跳過快速搜尋，1 啟用。	1
`categories`	string[]	有匹配名稱時只保留匹配分類並依清單排序；完全無匹配時保留原分類。	—
`header`	object	HTTP API 請求標頭；播放 Result.header 全空時也作為預設。type 3 不會自動套用到 Spider 自行發出的請求。	—
`style`	Style	站點預設卡片樣式。	—

Type 3 站點範例

JSON / Sitesites[] 物件片段

{
  "key": "js_demo",
  "name": "JavaScript Demo",
  "type": 3,
  "api": "./demo.js",
  "ext": { "region": "tw" },
  "searchable": 1,
  "changeable": 1,
  "categories": ["電影", "戲劇"],
  "header": { "User-Agent": "ExampleClient/1.0" },
  "style": { "type": "rect", "ratio": 1.33 }
}

改用 Python 時只需把 api 換成 ./demo.py；Java 類別則填 csp_Demo。相對路徑也適用於 ext 與 jar。

Parse URL 處理規則

5 欄位

欄位	類型	用途	預設
`name`必要	string	解析器顯示名稱，也是具名選取依據。	—
`type`	integer	0=WebView、1=JSON API、2=JAR JSON、3=JAR 混合、4=並行嘗試。	0
`url`	string	解析 API 端點或前綴。	—
`ext.flag`	string[]	type 4 並行解析時，優先選取同類型且匹配旗標的解析器；沒有匹配時回退該類型全部解析器。	—
`ext.header`	object	附加於解析請求；JSON 解析結果未提供標頭時，也作為播放請求的預設標頭。	—

WebView 與 JSON API 範例

JSON / Parseparses 欄位值

[
  {
    "name": "WebView 解析範例",
    "type": 0,
    "url": "https://example.com/web?url="
  },
  {
    "name": "JSON API 解析範例",
    "type": 1,
    "url": "https://example.com/api?url=",
    "ext": {
      "flag": ["demo"],
      "header": { "Referer": "https://example.com/" }
    }
  }
]

parses 的值是陣列；ext.flag 是 type 4 並行解析的優先比對條件，不是全域白名單。ext.header 也可能作為解析結果的預設播放標頭，詳見上表。

LiveConfig 與直播來源

獨立 LiveConfig 的 JSON 頂層使用 lives，並支援 spider、headers、proxy、rules、hosts、ads、urls 與 msg；不讀取獨立的 doh。下表說明 lives[] 中的 Live 來源物件。

url 與 groups 通常擇一；groups 為空且提供 api 時，會先呼叫 Spider 的 liveContent(url) 取得文字，再交由 LiveParser 判斷格式。

同名配置已保存的 boot、pass 與 keep 可能覆蓋配置值；請同時檢查 App 內的已保存設定。

20 欄位

欄位	類型	用途	預設
`name`必要	string	直播配置唯一名稱。	—
`url`	string	外部 TXT、M3U 或 JSON 列表位置；與 groups 擇一。	—
`api`	string	groups 為空時，用此 Spider 的 liveContent(url) 取得外部列表文字。	—
`ext`	string \| object \| array	傳給直播 Spider 的初始化資料；物件與陣列會先序列化為字串。	—
`jar`	string	此直播配置專用 JAR。	—
`click`	string	預設在 WebView 執行的 JavaScript 點擊程式。	—
`logo`	string	預設 Logo 範本，可用 {id}、{name}、{logo}。	—
`epg`	string	節目表位置，逗號分隔；支援 XMLTV 與 API 範本。	—
`ua`	string	預設 User-Agent。	—
`origin`	string	預設 Origin 標頭。	—
`referer`	string	預設 Referer 標頭。	—
`timeZone`	string	節目表時區，例如 Asia/Taipei。	系統時區
`keep`	string	已保存頻道定位資訊；通常由 App 自行維護。	—
`timeout`	integer	播放逾時秒數，最小 1。	15
`header`	object	直播請求附加 HTTP 標頭。	—
`catchup`	Catchup	外部列表頻道的預設追看／時移設定；內嵌 groups 需在頻道自行提供。	—
`core`	Core	特殊播放核心的進階初始化設定。	—
`groups`	Group[]	內嵌頻道分組。	—
`boot`	boolean	目前選中的直播配置為 true 時，載入完成後觸發自動進入直播。	false
`pass`	boolean	true 時不把 TXT／M3U 分組名稱中的 _後綴解析成密碼；JSON 內明確設定的 Group.pass 不受影響。	false

載入外部列表

JSON / LiveConfiglive-config.json

{
  "lives": [
    {
      "name": "M3U 範例",
      "url": "./live.m3u",
      "epg": "https://example.com/epg.xml",
      "logo": "https://example.com/logo/{id}.png",
      "ua": "ExampleClient/1.0",
      "timeZone": "Asia/Taipei",
      "boot": false
    }
  ]
}

這是含 lives 陣列的完整 LiveConfig；url 指向可獨立維護的 M3U、TXT 或 JSON 檔案。

直接內嵌 Group / Channel

JSON / LiveConfiglive-config.json

{
  "lives": [
    {
      "name": "內嵌 JSON 範例",
      "groups": [
        {
          "name": "新聞",
          "channel": [
            {
              "name": "範例一台",
              "number": "1",
              "tvgId": "demo-1",
              "urls": [
                "https://example.com/live/main.m3u8$主線",
                "https://example.com/live/backup.m3u8$備線"
              ],
              "header": { "Referer": "https://example.com/" }
            }
          ]
        }
      ]
    }
  ]
}

$主線、$備線 是線路標籤；同一頻道可以提供多個位置。直接內嵌 groups 不經外部列表的自動編號與預設值繼承，請在 Channel 明確設定需要的欄位。

分組與頻道欄位

19 欄位

欄位	類型	用途	預設
`Group.name`必要	string	分組顯示名稱。	—
`Group.pass`	string	分組密碼；未通過前視為隱藏。	—
`Group.channel`必要	Channel[]	分組內頻道清單。	—
`Channel.name`必要	string	頻道顯示名稱。	—
`Channel.urls`必要	string[]	播放位置清單；未設定 drm 時可用 $線路名稱指定標籤。設定 drm 時 URL 原樣使用，請勿附加標籤。	—
`Channel.number`	string	顯示用頻道號碼。	—
`Channel.logo`	string	覆蓋配置預設 Logo。	—
`Channel.epg`	string	覆蓋配置預設 EPG。	—
`Channel.ua`	string	覆蓋配置預設 User-Agent。	—
`Channel.click`	string	覆蓋配置的 JavaScript 點擊程式。	—
`Channel.format`	string	直接指定媒體 MIME type。	—
`Channel.origin`	string	覆蓋 Origin。	—
`Channel.referer`	string	覆蓋 Referer。	—
`Channel.tvgId`	string	EPG 頻道 ID。	—
`Channel.tvgName`	string	EPG 頻道名稱。	—
`Channel.header`	object	頻道 HTTP 標頭；外部列表僅在整份 header 為空時繼承 Live.header，不逐鍵合併。	—
`Channel.drm`	Drm	媒體 DRM 參數，子欄位見共用物件。	—
`Channel.parse`	integer	0=不解析、1=解析。	0
`Channel.catchup`	Catchup	覆蓋配置的追看／時移設定。	—

若 JSON 是由 Live.url 載入，檔案最外層直接放 Group 陣列，如下一節的 JSON 範例；若寫在主配置內，則放進 lives[].groups。

直播列表的三種完整輸入

JSON

JSON / Group[]live.json

[
  {
    "name": "新聞",
    "channel": [
      {
        "name": "範例一台",
        "number": "1",
        "tvgId": "demo-1",
        "urls": [
          "https://example.com/live/main.m3u8$主線",
          "https://example.com/live/backup.m3u8$備線"
        ]
      }
    ]
  }
]

最外層是 Group 陣列，適合完整保存頻道欄位與多線路。

M3U

M3Ulive.m3u

#EXTM3U url-tvg="https://example.com/epg.xml"
#EXTINF:-1 tvg-id="demo-1" tvg-name="範例一台" tvg-chno="1" tvg-logo="https://example.com/logo/demo-1.png" group-title="新聞",範例一台
#EXTVLCOPT:http-user-agent=ExampleClient/1.0
#EXTVLCOPT:http-referrer=https://example.com/
https://example.com/live/demo.m3u8

支援節目表、分組、頻道 ID、號碼、Logo、User-Agent 與 Referer。

TXT

TXTlive.txt

新聞,#genre#
ua=ExampleClient/1.0
referer=https://example.com/
format=hls
範例一台,https://example.com/live/main.m3u8$主線#https://example.com/live/backup.m3u8$備線

#genre# 建立分組；同一頻道的多個位置使用 # 分隔。

TXT / M3U 設定行ua= · parse= · click= · header= · format= · origin= · referer= · forceKey=

特殊播放核心欄位

Live.core 只在對應播放核心初始化時使用；一般直播配置不需要填寫。以下示範它在 Live 物件中的位置；option 的名稱與值由該核心實作定義，不是通用配置參數。

13 欄位

欄位	類型	用途	預設
`auth`	string	核心授權端點；resp 取得非空內容時，App 會改用本機 /tvbus 端點。	—
`name`	string	傳給播放核心的名稱；值也可以是回傳文字的網址。	—
`pass`	string	傳給播放核心的密碼；值也可以是回傳文字的網址。	—
`broker`	string	傳給播放核心的 broker 位置。	—
`domain`	string	傳給播放核心的 domain；值也可以是回傳文字的網址。	—
`resp`	string	本機 /tvbus 端點要回傳的內容，也可填回傳文字的網址；取得非空內容時取代 auth 的對外位置。	—
`sign`	string	與 pkg 一起建立執行期 Hook；值也可以由網址取得。	—
`pkg`	string	與 sign 一起建立執行期 Hook；值也可以由網址取得。	—
`so`	string	核心原生函式庫位置；App 會下載到本機後載入。	—
`key`	string	目前保留於 Core 配置中的識別值；現行 Core 流程沒有公開讀取方法。	—
`option`	Core.Option[]	初始化核心前逐筆套用的額外選項。	—
`option[].key`	string	選項名稱。	—
`option[].values`	string[]	傳給該選項的值清單。	—

JSON / Live.corelives[] 物件片段

{
  "name": "特殊核心示意",
  "url": "./live.m3u",
  "core": {
    "auth": "https://example.com/core/auth",
    "name": "demo",
    "pass": "demo-pass",
    "broker": "https://example.com/core/broker",
    "domain": "example.com",
    "so": "https://example.com/core/libcore.so",
    "option": []
  }
}

網路、時移與顯示物件

25 欄位

欄位	類型	用途	預設
`Doh.name`	string	DoH 顯示名稱。	—
`Doh.url`	string	DoH 查詢端點。	—
`Doh.ips`	string[]	Bootstrap IP。	—
`Proxy.name`	string	代理規則名稱。	—
`Proxy.hosts`	string[]	適用 host，支援規則比對。	—
`Proxy.urls`	string[]	含主機與埠號的代理位置，例如 http://127.0.0.1:8080、socks5://127.0.0.1:1080；依 http 或 socks 前綴選擇 Java 代理類型。	—
`Rule.name`	string	規則顯示名稱。	—
`Rule.hosts`	string[]	觸發目標 host。	—
`Rule.regex`	string[]	有效媒體位置的擷取條件。	—
`Rule.click`	string[]	WebView 中要點擊的 CSS 選擇器清單；與 JavaScript script 分開設定。	—
`Rule.script`	string[]	WebView 中執行的腳本。	—
`Rule.exclude`	string[]	不應被擷取的排除條件。	—
`Header.host`	string	要處理的 host。	—
`Header.header`	object	要注入或覆寫的 HTTP 請求標頭。	—
`Catchup.type`	string	default 完全替換；其他值附加於原位置。	空字串；行為為附加
`Catchup.days`	string	保留欄位；目前不限制可追看的天數。	—
`Catchup.regex`	string	判斷設定是否套用的字串或規則。	—
`Catchup.source`	string	追看／時移 URL 範本，請提供非空值；可含開始與結束時間 token。	—
`Catchup.replace`	string	附加模式使用正規表示式,替換內容；default 模式不套用。	—
`Drm.type`	string	媒體 DRM 類型，例如 widevine、playready、clearkey。	—
`Drm.key`	string	DRM 請求位置或該類型接受的金鑰資料。	—
`Drm.header`	object	DRM 請求標頭。	—
`Drm.forceKey`	boolean	強制使用指定的 DRM 請求位置，不使用媒體內的預設位置；對應 forceDefaultLicenseUri。	false
`Style.type`	string	rect、oval 或 list。	rect
`Style.ratio`	float	寬／高；正值最大 4。未設或小於等於 0 時，oval 為 1，其餘為 0.75。	依 type

DoH、Proxy、Hosts 與 Ads

JSON / sharedVodConfig 頂層欄位片段

{
  "doh": [
    {
      "name": "Example DoH",
      "url": "https://dns.example.com/dns-query",
      "ips": ["203.0.113.53"]
    }
  ],
  "proxy": [
    {
      "name": "本機代理範例",
      "hosts": ["media.example.com"],
      "urls": ["http://127.0.0.1:8080", "socks5://127.0.0.1:1080"]
    }
  ],
  "hosts": ["media.example.com=203.0.113.10"],
  "ads": ["ads.example.com"]
}

代理位置必須包含 scheme、host 與 port；hosts 使用 原主機=目標主機或 IP。

追看 / 時移 Catchup

JSON / Live.catchuplives[] 物件片段

{
  "name": "時移示意",
  "url": "./live.m3u",
  "catchup": {
    "type": "append",
    "days": "7",
    "regex": "example.com/live/",
    "source": "?playseek=${(b)yyyyMMddHHmmss}-${(e)yyyyMMddHHmmss}",
    "replace": "live/,archive/"
  }
}

${(b)yyyyMMddHHmmss} 與 ${(e)yyyyMMddHHmmss} 會分別替換為節目開始與結束時間，格式化使用裝置系統時區，不使用 Live.timeZone。