hg
/
FONGMITV
mirror of https://github.com/FongMi/TV.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update readme

Browse Source
release
FongMi 3 weeks ago
parent 9c9307c28d
commit d9f9b699a0
5 changed files with 2173 additions and 325 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 316
      README.md
  2. 720
      docs/CONFIG.md
  3. 527
      docs/LOCAL.md
  4. 839
      docs/SPIDER.md
  5. 96
      other/sample/config.json

316
README.md
Unescape View File

@ -1,270 +1,128 @@
# 影視
### 基於 CatVod 項目
https://github.com/CatVodTVOfficial/CatVodTVJarLoader
### 點播欄位
| 欄位名稱 | 預設值 | 說明 | 其他 |
|------------|------|------|------------|
| searchable | 1 | 是否搜索 | 0：關閉；1：啟用 |
| changeable | 1 | 是否換源 | 0：關閉；1：啟用 |
| quickserch | 1 | 是否快搜 | 0：關閉；1：啟用 |
| indexs | 0 | 是否聚搜 | 0：關閉；1：啟用 |
| hide | 0 | 是否隱藏 | 0：顯示；1：隱藏 |
| timeout | 15 | 播放超時 | 單位：秒 |
| header | none | 請求標頭 | 格式：json |
| click | none | 點擊js | javascript |
### 直播欄位
| 欄位名稱 | 預設值 | 說明 | 其他 |
|----------|-------|-------|------------|
| ua | none | 用戶代理 | |
| origin | none | 來源 | |
| referer | none | 參照地址 | |
| epg | none | 節目地址 | |
| logo | none | 台標地址 | |
| pass | false | 是否免密碼 | |
| boot | false | 是否自啟動 | |
| timeout | 15 | 播放超時 | 單位：秒 |
| header | none | 請求標頭 | 格式：json |
| click | none | 點擊js | javascript |
| catchup | none | 回看參數 | |
| timeZone | none | 時區 | |
### 樣式
| 欄位名稱 | 值 | 說明 |
|-------|------|-----|
| type | rect | 矩形 |
| | oval | 橢圓 |
| | list | 列表 |
| ratio | 0.75 | 3：4 |
| | 1.33 | 4：3 |
直式
```json
{
"style": {
"type": "rect"
}
}
```
橫式
# 📺 開發者文件
```json
{
"style": {
"type": "rect",
"ratio": 1.33
}
}
```
基於 [CatVod](https://github.com/CatVodTVOfficial/CatVodTVJarLoader) 的開源 Android 影音應用程式，同時支援
**Android TV 大螢幕** 與 **手機** 兩種使用情境。爬蟲引擎支援 Java JAR、JavaScript、Python
三種語言，透過外部配置檔靈活擴展內容來源。
正方
[討論群組](https://t.me/fongmi_official) | [發布頻道](https://t.me/fongmi_release)
```json
{
"style": {
"type": "rect",
"ratio": 1
}
}
```
[![Star History Chart](https://api.star-history.com/svg?repos=FongMi/TV&type=Date)](https://www.star-history.com/#FongMi/TV&Date)
正圓
---
```json
{
"style": {
"type": "oval"
}
}
```
## 目錄
橢圓
- [專案架構](#專案架構)
- [播放器](#播放器)
- [點播功能](#點播功能)
- [直播功能](#直播功能)
- [爬蟲引擎](#爬蟲引擎)
- [網路功能](#網路功能)
- [DLNA 投放](#dlna-投放)
- [遠端控制](#遠端控制)
- [配置說明](#配置說明)
- [延伸閱讀](#延伸閱讀)
```json
{
"style": {
"type": "oval",
"ratio": 1.1
}
}
```
---
### API
## 🏗️ 專案架構
播放控制
| 項目 | 值 |
|--------------------|-------------------------------|
| Package | `com.fongmi.android.tv` |
| minSdk / targetSdk | 24 / 28 |
| ABI | `arm64-v8a`、`armeabi-v7a` |
| Flavor | `leanback`（電視版）、`mobile`（手機版） |
type 包含 stop、prev、next、loop、play、pause、replay
```
http://127.0.0.1:9978/action?do=control&type=next
TV/
├── app/ 主應用程式（含兩套 UI Flavor）
├── catvod/ 爬蟲抽象層（Spider 介面、OkHttp 網路棧）
├── quickjs/ QuickJS JavaScript 引擎
├── chaquo/ Chaquopy Python 引擎
```
刷新詳情
`app/src/main/` 為兩個版本共用的業務邏輯，`app/src/leanback/` 與 `app/src/mobile/` 各自實作對應 UI。
```
http://127.0.0.1:9978/action?do=refresh&type=detail
```
---
刷新播放
## 🎬 播放器
```
http://127.0.0.1:9978/action?do=refresh&type=player
```
- **核心**：ExoPlayer（Media3）+ FFmpeg 軟解，硬解 / 軟解自動降級切換
- **渲染**：SurfaceView / TextureView
- **DRM**：Widevine、PlayReady、ClearKey，支援 `#KODIPROP` 宣告
- **彈幕**：DanmakuFlameMaster，與播放時間軸精確同步，支援遠端推送
- **字幕**：SRT / SSA / ASS 外掛字幕、系統 CaptioningManager、遠端即時注入
- **其他**：倍速、多縮放比例、畫中畫（PiP）、背景音訊、片頭 / 片尾自動跳過
刷新直播
---
```
http://127.0.0.1:9978/action?do=refresh&type=live
```
## 📼 點播功能
推送字幕
- 多站點分類瀏覽，Filter 篩選（年份 / 地區 / 類型等）
- 多站點**並行搜尋**，關鍵字自動繁轉簡提升相容性
- 播放失敗自動換源：解析器 → 線路 → 搜尋其他站 → 下一站點
- 觀看記錄（保留 60 天）、收藏、無痕模式
- 電視版使用遙控器操作；手機版支援手勢（亮度 / 音量 / 進度）、上下滑切集、螢幕旋轉與鎖定
```
http://127.0.0.1:9978/action?do=refresh&type=subtitle&path=http://xxx
```
---
推送彈幕
## 📡 直播功能
```
http://127.0.0.1:9978/action?do=refresh&type=danmaku&path=http://xxx
```
- 支援 M3U/M3U8、TXT（`#genre#` 分組）、JSON 三種直播源格式
- **EPG**：XMLTV 格式（支援 `.gz`），每 6 小時自動刷新
- **追看 / 時移**：`append`、`pltv` 等多種類型
- 頻道收藏、隱藏分組密碼保護
- 特殊引擎：TVBus、ForceTech
新增緩存字串
---
```
http://127.0.0.1:9978/cache?do=set&key=xxx&value=xxx
```
## 🕷️ 爬蟲引擎
取得緩存字串
支援三種語言撰寫爬蟲：Java JAR（DexClassLoader）、JavaScript（QuickJS）、Python（Chaquopy）。透過 `api`
欄位指定爬蟲，`ext` 欄位傳入初始化參數。完整 API 規格見 [SPIDER.md](docs/SPIDER.md)。
```
http://127.0.0.1:9978/cache?do=get&key=xxx
```
---
刪除緩存字串
## 🌐 網路功能
```
http://127.0.0.1:9978/cache?do=del&key=xxx
```
- **DoH**：DNS over HTTPS，支援 Bootstrap IP
- **代理**：HTTP / HTTPS / SOCKS4 / SOCKS5，依 host 正則規則動態選擇
- **hosts**：DNS 解析覆蓋，支援萬用字元 `*`
- **CORS 注入**：依 host 規則在回應中注入自訂標頭
- **廣告攔截**：`ads` 黑名單，符合域名直接攔截
- **WebView 嗅探**：Sniffer 以 regex 攔截媒體 URL；支援 UA 偽裝
### Proxy
---
支持 http, https, socks4, socks5
## 📲 DLNA 投放
```
scheme://username:password@host:port
```
- **DMC（投放端）**：手機版，掃描區域網路 DLNA 設備並投放媒體
- **DMR（被投放端）**：電視版，作為 DLNA Renderer 接收其他設備投放
配置新增 proxy 可指定代理
靠前的 host 匹配到則使用該代理
```json
{
"spider": "",
"proxy": [
{
"name": "自訂",
"hosts": [
"googlevideo.com",
"raw.githubusercontent.com"
],
"urls": [
"http://127.0.0.1:7890"
]
},
{
"name": "全局",
"hosts": [
".*."
],
"urls": [
"socks5://127.0.0.1:7891"
]
}
]
}
```
使用 Cling 2.1.1（UPnP），支援 play / pause / stop / seek 控制。
### Hosts
---
```json
{
"spider": "",
"hosts": [
"cache.ott.*.itv.cmvideo.cn=base-v4-free-mghy.e.cdn.chinamobile.com"
]
}
```
## 🖥️ 遠端控制
### Headers
```json
{
"spider": "",
"headers": [
{
"host": "gslbserv.itv.cmvideo.cn",
"header": {
"User-Agent": "okhttp/3.12.13",
"Referer": "test"
}
}
]
}
```
### 爬蟲本地代理
Java
```
proxy://
```
```
Proxy.getUrl(boolean local)
```
Python
```
proxy://do=py
```
應用啟動後綁定本地 HTTP 伺服器（NanoHTTPD），埠號從 **9978** 起自動偵測至 **9998**
，可用於播放控制、推送字幕 / 彈幕、多裝置同步等。完整端點說明見 [LOCAL.md](docs/LOCAL.md)。
```
getProxyUrl(boolean local)
```
---
JS
## ⚙️ 配置說明
```
proxy://do=js
```
```
getProxy(boolean local)
```
`config.json`（VOD 配置）為應用主要入口，透過頂層欄位定義點播站點（`sites`）、解析規則（`parses`）、直播來源（
`lives`）及網路設定（`doh`、`proxy`、`hosts`、`ads`）。Live
配置可內嵌或獨立存放。完整欄位說明見 [CONFIG.md](docs/CONFIG.md)。
### 配置範例
---
[本地/線上](other/sample/config.json)
## 📚 延伸閱讀
### 飛機群
[討論群組](https://t.me/fongmi_official)
[發布頻道](https://t.me/fongmi_release)
### 贊助
![photo_2024-01-10_11-39-12](https://github.com/FongMi/TV/assets/3471963/fdc12771-386c-4d5d-9a4d-d0bec0276fa7)
### Star
[![Star History Chart](https://api.star-history.com/svg?repos=FongMi/TV&type=Date)](https://www.star-history.com/#FongMi/TV&Date)
| 文件 | 說明 |
|-----------------------------|----------------------|
| [CONFIG.md](docs/CONFIG.md) | VOD / Live 完整配置欄位說明 |
| [SPIDER.md](docs/SPIDER.md) | Spider 所有方法規格與回傳格式 |
| [LOCAL.md](docs/LOCAL.md) | 本地 HTTP API 所有端點完整說明 |

720
docs/CONFIG.md
Unescape View File

@ -0,0 +1,720 @@
# 配置說明
本文件說明 VOD（點播）與 Live（直播）配置檔案的 JSON 結構與各欄位意義。
---
## 目錄
- [VOD 配置（VodConfig）](#vod-配置vodconfig)
- [頂層欄位](#頂層欄位)
- [sites — 點播來源](#sites--點播來源)
- [parses — 解析規則](#parses--解析規則)
- [lives — 直播來源](#lives--直播來源)
- [Live 配置（LiveConfig）](#live-配置liveconfig)
- [頂層欄位](#頂層欄位-1)
- [groups — 頻道分組](#groups--頻道分組)
- [channel — 頻道項目](#channel--頻道項目)
- [共用欄位物件](#共用欄位物件)
- [doh — DNS over HTTPS](#doh--dns-over-https)
- [proxy — 代理伺服器](#proxy--代理伺服器)
- [rules — 網路攔截規則](#rules--網路攔截規則)
- [headers — 注入回應標頭](#headers--注入回應標頭)
- [hosts — DNS 解析覆蓋](#hosts--dns-解析覆蓋)
- [ads — 廣告過濾](#ads--廣告過濾)
- [catchup — 追看/時移](#catchup--追看時移)
- [style — 卡片樣式](#style--卡片樣式)
- [完整範例](#完整範例)
---
## VOD 配置（VodConfig）
VOD 配置為一個 JSON 物件，作為應用程式的主要配置入口。配置可透過 URL、本地路徑或直接貼入字串的方式載入。
### 頂層欄位
| 欄位 | 類型 | 說明 |
|-------------|-----------------|----------------------------------------------------------------|
| `spider` | `string` | 全局 Spider JAR 路徑或 URL，提供給所有 `sites` 作為預設爬蟲。支援相對路徑（`./`、`../`）。 |
| `wallpaper` | `string` | 桌布圖片或影片的路徑/URL。支援靜態圖、GIF、影片格式。 |
| `logo` | `string` | 應用程式 Logo 圖片路徑/URL。 |
| `notice` | `string` | 啟動公告文字，將顯示給使用者。 |
| `sites` | `array<Site>` | 點播來源清單。詳見 [sites](#sites--點播來源)。 |
| `parses` | `array<Parse>` | 影片解析規則清單。詳見 [parses](#parses--解析規則)。 |
| `lives` | `array<Live>` | 直播來源清單。詳見 [lives — 直播來源](#lives--直播來源)。 |
| `doh` | `array<Doh>` | DNS over HTTPS 設定清單。詳見 [doh](#doh--dns-over-https)。 |
| `proxy` | `array<Proxy>` | 代理伺服器設定清單。詳見 [proxy](#proxy--代理伺服器)。 |
| `rules` | `array<Rule>` | 網路攔截規則清單。詳見 [rules](#rules--網路攔截規則)。 |
| `headers` | `array<Header>` | 針對特定主機注入 HTTP 回應標頭。詳見 [headers](#headers--注入回應標頭)。 |
| `hosts` | `array<string>` | DNS 解析覆蓋規則。詳見 [hosts](#hosts--dns-解析覆蓋)。 |
| `flags` | `array<string>` | 平台標示旗標，用於標記特殊平台處理（如 `"qq"`）。 |
| `ads` | `array<string>` | 廣告域名過濾清單，符合的請求將被攔截。詳見 [ads](#ads--廣告過濾)。 |
---
### sites — 點播來源
`sites` 為 `Site` 物件陣列，每個物件代表一個點播來源。
| 欄位 | 類型 | 說明 |
|---------------|-----------------|-------------------------------------------|
| `key` | `string` | 來源唯一識別碼，作為主鍵使用，不可重複。 |
| `name` | `string` | 來源顯示名稱。 |
| `type` | `integer` | 來源類型，決定呼叫方式。詳見下表。 |
| `api` | `string` | API 端點 URL 或爬蟲類別名稱（如 `csp_Push`）。 |
| `ext` | `string` | 額外擴充資料，傳入爬蟲 `init()` 使用。可為字串、JSON 物件或路徑。 |
| `jar` | `string` | 指定此來源使用的 Spider JAR 路徑/URL，覆蓋全局 `spider`。 |
| `click` | `string` | 點擊攔截處理 URL 或規則。 |
| `playUrl` | `string` | 播放 URL 前綴或轉換規則。 |
| `hide` | `integer` | `1` 表示在來源列表中隱藏此項目。 |
| `timeout` | `integer` | 請求逾時秒數，覆蓋預設值。 |
| `searchable` | `integer` | 搜尋開關。`0`=停用，`1`=啟用（預設）。 |
| `changeable` | `integer` | 線路切換開關。`0`=停用，`1`=啟用（預設）。 |
| `quickSearch` | `integer` | 快速搜尋開關。`0`=停用，`1`=啟用。 |
| `categories` | `array<string>` | 顯示的分類名稱白名單，僅顯示清單中的分類。 |
| `header` | `object` | 此來源請求時附加的 HTTP 標頭，格式為鍵值對。 |
| `style` | `Style` | 卡片顯示樣式。詳見 [style](#style--卡片樣式)。 |
**`type` 可選值：**
| `type` | `api` 格式 | 說明 |
|--------|---------------------------------------|------------------------------------------------------------------|
| `0` | HTTP URL | 直接 GET 請求，回傳 XML 格式（`ac=videolist`）。 |
| `1` | HTTP URL | 直接 GET 請求，回傳 JSON 格式，額外支援 Filter 篩選參數（`f=`）。 |
| `3` | `csp_ClassName` / `xxx.js` / `xxx.py` | 爬蟲直接呼叫：JAR（DexClassLoader）、JavaScript（QuickJS）、Python（Chaquopy）。 |
| `4` | HTTP URL | 同 `1`，`ext` 擴充參數以 Base64 編碼傳遞（`ext=`）。 |
**範例：**
```json
{
"key": "my_source",
"name": "我的來源",
"type": 3,
"api": "csp_XYZ",
"ext": "./ext.json",
"searchable": 1,
"changeable": 1,
"timeout": 30,
"header": {
"User-Agent": "Mozilla/5.0"
},
"style": {
"type": "rect",
"ratio": 1.33
}
}
```
---
### parses — 解析規則
`parses` 為 `Parse` 物件陣列，定義影片 URL 的解析處理規則。
| 欄位 | 類型 | 說明 |
|--------------|-----------------|------------------------------------------|
| `name` | `string` | 解析器顯示名稱。 |
| `type` | `integer` | 解析器類型。詳見下表。 |
| `url` | `string` | 解析 API 端點 URL，通常以待解析的影片 URL 作為後綴參數。 |
| `ext` | `Parse.Ext` | 解析器擴充設定物件。 |
| `ext.flag` | `array<string>` | 適用旗標清單，標示此解析器適用的平台（如 `["qq", "iqiyi"]`）。 |
| `ext.header` | `object` | 解析請求時附加的 HTTP 標頭，格式為鍵值對。 |
**`parses.type` 可選值：**
| `type` | 說明 |
|--------|--------------------------------------|
| `0` | 嗅探（WebView 攔截媒體 URL） |
| `1` | JSON API（GET 請求，取回應的 `url` 欄位） |
| `2` | JSON 擴展（將所有 type=1 的解析器合併後送入 JAR 處理） |
| `3` | JSON 聚合（將所有解析器資訊合併後送入 JAR 處理） |
| `4` | 超級解析（自動並行嘗試所有 type=0/1 的解析器） |
**範例：**
```json
{
"name": "通用解析",
"type": 1,
"url": "https://api.example.com/parse?url=",
"ext": {
"flag": [
"qq",
"youku"
],
"header": {
"Referer": "https://www.example.com/"
}
}
}
```
### lives — 直播來源
VOD 配置中的 `lives` 欄位用於指向外部直播配置或內嵌直播資訊。每個物件為一個 `Live`
來源，欄位定義與 [Live 配置頂層欄位](#頂層欄位-1) 相同。
常見用法為指定 `url` 指向外部 `live.json`，或直接內嵌 `groups` 頻道資料。
---
## Live 配置（LiveConfig）
Live 配置可以是獨立的 JSON 檔案，或內嵌於 VOD 配置的 `lives` 陣列中。
獨立的 `live.json` 頂層支援以下欄位：
| 欄位 | 類型 | 說明 |
|-----------|-----------------|-------------------------------------------------|
| `spider` | `string` | 全局 Spider JAR 路徑，提供給所有 `lives` 作為預設爬蟲。 |
| `lives` | `array<Live>` | 直播來源清單，欄位定義見下表。 |
| `proxy` | `array<Proxy>` | 代理設定，同 VOD 配置。詳見 [proxy](#proxy--代理伺服器)。 |
| `rules` | `array<Rule>` | 攔截規則，同 VOD 配置。詳見 [rules](#rules--網路攔截規則)。 |
| `headers` | `array<Header>` | 注入標頭，同 VOD 配置。詳見 [headers](#headers--注入回應標頭)。 |
| `hosts` | `array<string>` | DNS 覆蓋規則，同 VOD 配置。詳見 [hosts](#hosts--dns-解析覆蓋)。 |
| `ads` | `array<string>` | 廣告過濾清單，同 VOD 配置。詳見 [ads](#ads--廣告過濾)。 |
### 頂層欄位
`lives` 陣列中每個 `Live` 物件的欄位：
| 欄位 | 類型 | 說明 |
|------------|----------------|-----------------------------------------------------------------------------------------------------|
| `name` | `string` | 直播來源名稱，作為主鍵使用，不可重複。 |
| `url` | `string` | 外部直播列表 URL（M3U、TXT 或 JSON 格式）。與 `groups` 二擇一。 |
| `api` | `string` | 直播 API 端點或爬蟲類別名稱。 |
| `ext` | `string` | 傳入直播爬蟲的額外擴充資料。 |
| `jar` | `string` | 此直播來源使用的 Spider JAR 路徑/URL。 |
| `click` | `string` | 點擊攔截處理 URL 或規則。 |
| `logo` | `string` | 頻道預設 Logo 圖片 URL，支援 `{id}`、`{name}`、`{logo}` 變數替換。 |
| `epg` | `string` | EPG 節目表 URL，多個以逗號分隔。支援 `{id}`、`{name}`、`{epg}` 變數替換；含 `xml`/`gz` 的條目作為 XMLTV 來源，含 `{` 的條目作為 API 範本。 |
| `ua` | `string` | 預設 User-Agent 字串。 |
| `origin` | `string` | 請求 `Origin` 標頭值。 |
| `referer` | `string` | 請求 `Referer` 標頭值。 |
| `timeZone` | `string` | 時區設定，用於 EPG 時間顯示（如 `"Asia/Taipei"`）。 |
| `timeout` | `integer` | 請求逾時秒數。 |
| `header` | `object` | 此來源請求時附加的 HTTP 標頭，格式為鍵值對。 |
| `catchup` | `Catchup` | 追看/時移設定，作為此來源所有頻道的預設值。詳見 [catchup](#catchup--追看時移)。 |
| `groups` | `array<Group>` | 直播頻道分組清單（內嵌方式）。詳見 [groups](#groups--頻道分組)。 |
| `boot` | `boolean` | 是否在應用啟動時自動選中此直播來源。多個來源設定時，最後一個生效。 |
| `pass` | `boolean` | `true` 表示略過此直播來源的載入。 |
**範例：**
```json
{
"name": "我的直播",
"url": "./live.m3u",
"epg": "https://epg.example.com/api?id={id},https://epg.example.com/xmltv.xml.gz",
"ua": "Mozilla/5.0",
"timeZone": "Asia/Taipei",
"boot": true
}
```
---
### groups — 頻道分組
`groups` 為 `Group` 物件陣列，將頻道組織為分組顯示。
| 欄位 | 類型 | 說明 |
|-----------|------------------|-----------------------------------------|
| `name` | `string` | 分組顯示名稱。 |
| `pass` | `string` | 分組密碼，設定後需輸入密碼才能瀏覽此分組。 |
| `channel` | `array<Channel>` | 此分組下的頻道清單。詳見 [channel](#channel--頻道項目)。 |
**範例：**
```json
{
"name": "新聞台",
"channel": [
{
"name": "TVBS新聞台",
"urls": [
"http://example.com/tvbs.m3u8"
]
},
{
"name": "民視新聞",
"urls": [
"http://example.com/ftv.m3u8"
]
}
]
}
```
---
### channel — 頻道項目
`channel` 為 `Channel` 物件陣列，每個物件代表一個直播頻道。
| 欄位 | 類型 | 說明 |
|-----------|-----------------|---------------------------------------------------------|
| `name` | `string` | 頻道顯示名稱。 |
| `urls` | `array<string>` | 頻道播放 URL 清單，支援多個備用線路，依序嘗試。 |
| `number` | `string` | 頻道號碼（顯示用）。 |
| `logo` | `string` | 頻道 Logo 圖片 URL，覆蓋來源預設值。 |
| `epg` | `string` | 此頻道專屬 EPG URL，覆蓋來源預設 EPG。 |
| `ua` | `string` | 此頻道播放請求的 User-Agent，覆蓋來源預設值。 |
| `click` | `string` | 點擊攔截處理。 |
| `format` | `string` | 指定媒體格式（如 `"m3u8"`、`"flv"`）。 |
| `origin` | `string` | 請求 `Origin` 標頭值，覆蓋來源預設值。 |
| `referer` | `string` | 請求 `Referer` 標頭值，覆蓋來源預設值。 |
| `tvgId` | `string` | TVG 格式 EPG 頻道 ID。 |
| `tvgName` | `string` | TVG 格式 EPG 頻道名稱。 |
| `header` | `object` | 此頻道請求的額外 HTTP 標頭，格式為鍵值對。 |
| `parse` | `integer` | 是否需要解析此頻道 URL。`0`=不解析，`1`=解析。 |
| `catchup` | `Catchup` | 此頻道的追看/時移設定，覆蓋分組及來源預設值。詳見 [catchup](#catchup--追看時移)。 |
| `drm` | `Drm` | DRM 版權保護設定。欄位同 [playerContent 回傳的 `drm` 物件](SPIDER.md)。 |
**範例：**
```json
{
"name": "HBO",
"urls": [
"http://cdn1.example.com/hbo.m3u8",
"http://cdn2.example.com/hbo.m3u8"
],
"number": "601",
"logo": "https://example.com/logo/hbo.png",
"ua": "Mozilla/5.0",
"header": {
"Referer": "https://www.example.com/"
},
"catchup": {
"type": "append",
"days": "7",
"source": "?playseek=${(b)yyyyMMddHHmmss}-${(e)yyyyMMddHHmmss}"
}
}
```
---
## 共用欄位物件
以下物件可在 VOD 配置或 Live 配置的對應陣列欄位中使用。
> `doh` 僅 VOD 配置支援，其餘欄位兩者均可使用。
---
### doh — DNS over HTTPS
設定加密 DNS 解析伺服器，保護 DNS 查詢隱私並防止污染。僅 VOD 配置支援。
| 欄位 | 類型 | 說明 |
|--------|-----------------|-------------------------------------------------------|
| `name` | `string` | 伺服器顯示名稱。 |
| `url` | `string` | DoH 查詢端點 URL（如 `https://dns.google/dns-query`）。 |
| `ips` | `array<string>` | 伺服器本身的 IP 位址清單，用於 Bootstrap 解析，避免 DoH 伺服器本身需要 DNS 查詢。 |
**範例：**
```json
{
"name": "Google DoH",
"url": "https://dns.google/dns-query",
"ips": [
"8.8.4.4",
"8.8.8.8"
]
}
```
---
### proxy — 代理伺服器
設定特定域名流量的代理規則。支援 HTTP、HTTPS、SOCKS4、SOCKS5 代理。
**代理 URL 格式：**
```
scheme://username:password@host:port
```
| 協議 | 範例 |
|--------|-------------------------------------|
| HTTP | `http://127.0.0.1:7890` |
| HTTPS | `https://127.0.0.1:7890` |
| SOCKS4 | `socks4://127.0.0.1:1080` |
| SOCKS5 | `socks5://127.0.0.1:7891` |
| 帶認證 | `socks5://user:pass@127.0.0.1:7891` |
| 欄位 | 類型 | 說明 |
|---------|-----------------|---------------------------------|
| `name` | `string` | 代理規則顯示名稱。 |
| `hosts` | `array<string>` | 適用此代理的主機名稱清單，支援正規表示式。靠前的規則優先匹配。 |
| `urls` | `array<string>` | 代理伺服器 URL 清單（多個時依序嘗試）。 |
**範例：**
```json
[
{
"name": "指定域名代理",
"hosts": [
"googlevideo.com",
"raw.githubusercontent.com"
],
"urls": [
"http://127.0.0.1:7890"
]
},
{
"name": "全域代理",
"hosts": [
".*"
],
"urls": [
"socks5://127.0.0.1:7891"
]
}
]
```
---
### rules — 網路攔截規則
設定 WebView 或播放器的網路請求攔截與處理規則。
| 欄位 | 類型 | 說明 |
|-----------|-----------------|-------------------------------------------------|
| `name` | `string` | 規則顯示名稱。 |
| `hosts` | `array<string>` | 觸發此規則的目標主機名稱清單。 |
| `regex` | `array<string>` | 用於擷取播放 URL 的正規表示式清單，符合者視為有效的媒體 URL。 |
| `script` | `array<string>` | 在 WebView 中執行的 JavaScript 程式碼清單，用於自動點擊、關閉廣告等操作。 |
| `exclude` | `array<string>` | 排除清單，符合此清單的 URL 不觸發 `regex` 擷取。 |
**範例：**
```json
[
{
"hosts": [
"video.example.com"
],
"regex": [
"m3u8?token="
],
"exclude": [
"preview.json"
]
},
{
"hosts": [
"ads.example.com"
],
"script": [
"document.querySelector('.close-btn').click()"
]
}
]
```
---
### headers — 注入回應標頭
針對特定主機，在 HTTP 回應中注入自訂標頭（通常用於解除 CORS 限制）。
| 欄位 | 類型 | 說明 |
|----------|----------|-------------------------------|
| `host` | `string` | 目標主機名稱（不含協議，如 `example.com`）。 |
| `header` | `object` | 要注入的 HTTP 標頭物件，格式為鍵值對。 |
**範例：**
```json
{
"host": "stream.example.com",
"header": {
"Access-Control-Allow-Origin": "*",
"User-Agent": "okhttp/3.12.13"
}
}
```
---
### hosts — DNS 解析覆蓋
覆蓋特定主機名稱的 DNS 解析結果，可用於 CDN 調度或繞過封鎖。支援萬用字元 `*`。
**格式：** `"原始主機名=目標主機名（或 IP）"`
| 欄位 | 類型 | 說明 |
|--------|----------|---------------------------------|
| （陣列元素） | `string` | 格式為 `"原始主機名=目標主機名"`，支援萬用字元 `*`。 |
**範例：**
```json
"hosts": [
"stream.example.com=1.2.3.4",
"old.cdn.example.com=new.cdn.example.com",
"cache.ott.*.itv.cmvideo.cn=base-v4-free-mghy.e.cdn.chinamobile.com"
]
```
---
### ads — 廣告過濾
廣告域名黑名單，符合的 HTTP 請求將被直接攔截拒絕。
| 欄位 | 類型 | 說明 |
|--------|----------|---------|
| （陣列元素） | `string` | 要攔截的域名。 |
**範例：**
```json
"ads": [
"ads.example.com",
"tracker.example.net"
]
```
---
### catchup — 追看/時移
設定頻道的回看/時移功能，可定義在 `Live`（來源層級）或 `Channel`（頻道層級）。
| 欄位 | 類型 | 說明 |
|-----------|----------|---------------------------------------------------------------------------------------------------------------------|
| `type` | `string` | 時移類型，決定 URL 的組合方式（如 `"append"`、`"shift"`、`"flussonic"`、`"xui"`）。 |
| `days` | `string` | 支援回看的天數（如 `"7"`）。 |
| `regex` | `string` | 用於提取時間參數的正規表示式。 |
| `source` | `string` | 時移 URL 範本。支援 `{(b)格式}`（開始時間）、`{(e)格式}`（結束時間）、`{utc:}`（開始 Unix 秒）、`{utcend:}`（結束 Unix 秒）。非 `default` 類型時結果附加至原始 URL。 |
| `replace` | `string` | 用於替換 URL 中部分字串的替換字串。 |
**範例：**
```json
{
"type": "append",
"days": "7",
"source": "?playseek=${(b)yyyyMMddHHmmss}-${(e)yyyyMMddHHmmss}"
}
```
---
### style — 卡片樣式
設定 VOD 來源的內容卡片顯示樣式。
| 欄位 | 類型 | 說明 |
|---------|----------|-----------------------------------------------------|
| `type` | `string` | 卡片類型。可選值：`"rect"`（矩形）、`"oval"`（圓形/橢圓）、`"list"`（列表）。 |
| `ratio` | `float` | 卡片寬高比（寬度 / 高度）。省略時使用預設比例。 |
**`ratio` 常用值：**
| `ratio` | 比例 | 用途 |
|---------|------|----------|
| `0.75` | 3:4 | 直式海報（預設） |
| `1` | 1:1 | 正方形 |
| `1.33` | 4:3 | 橫式縮圖 |
| `1.78` | 16:9 | 寬螢幕縮圖 |
**範例：**
直式（海報，3:4）
```json
{
"style": {
"type": "rect"
}
}
```
橫式（4:3）
```json
{
"style": {
"type": "rect",
"ratio": 1.33
}
}
```
正方（1:1）
```json
{
"style": {
"type": "rect",
"ratio": 1
}
}
```
正圓
```json
{
"style": {
"type": "oval"
}
}
```
---
## 完整範例
### VOD 配置（config.json）
```json
{
"spider": "./custom_spider.jar",
"wallpaper": "./wallpaper.jpg",
"logo": "./logo.jpg",
"notice": "歡迎使用，本配置僅供測試！",
"sites": [
{
"key": "push_agent",
"name": "Push",
"type": 3,
"api": "csp_Push"
},
{
"key": "my_source",
"name": "我的影音",
"type": 3,
"api": "csp_MySource",
"ext": "./myext.json",
"searchable": 1,
"changeable": 1,
"timeout": 15,
"style": {
"type": "rect",
"ratio": 1.33
}
}
],
"lives": [
{
"name": "直播",
"url": "./live.json",
"epg": "https://epg.example.com/?ch={name}"
}
],
"parses": [
{
"name": "官方解析",
"type": 1,
"url": "https://api.example.com/parse?url="
}
],
"doh": [
{
"name": "Google",
"url": "https://dns.google/dns-query",
"ips": [
"8.8.4.4",
"8.8.8.8"
]
}
],
"proxy": [
{
"name": "指定代理",
"hosts": [
"googlevideo.com"
],
"urls": [
"http://127.0.0.1:7890"
]
}
],
"rules": [
{
"hosts": [
"video.example.com"
],
"regex": [
"m3u8?token="
],
"exclude": [
"preview.json"
]
}
],
"headers": [
{
"host": "stream.example.com",
"header": {
"User-Agent": "okhttp/3.12.13"
}
}
],
"hosts": [
"old.cdn.example.com=new.cdn.example.com"
],
"flags": [
"qq"
],
"ads": [
"ads.example.com"
]
}
```
### Live 配置（live.json）
```json
{
"lives": [
{
"name": "台灣頻道",
"epg": "https://epg.example.com/api?id={id},https://epg.example.com/xmltv.xml.gz",
"ua": "Mozilla/5.0",
"timeZone": "Asia/Taipei",
"boot": true,
"groups": [
{
"name": "新聞台",
"channel": [
{
"name": "TVBS新聞台",
"number": "56",
"urls": [
"http://cdn1.example.com/tvbs.m3u8"
],
"logo": "https://example.com/logo/tvbs.png"
},
{
"name": "民視新聞",
"number": "52",
"urls": [
"http://cdn1.example.com/ftv.m3u8",
"http://cdn2.example.com/ftv.m3u8"
],
"catchup": {
"type": "append",
"days": "3",
"source": "?playseek=${(b)yyyyMMddHHmmss}-${(e)yyyyMMddHHmmss}"
}
}
]
}
]
}
]
}
```

527
docs/LOCAL.md
Unescape View File

@ -0,0 +1,527 @@
# 本地 HTTP API
應用程式啟動後會在本地綁定一個 HTTP 伺服器，埠號從 **9978** 開始依序嘗試至 **9998**，取得第一個可用埠。
```
http://127.0.0.1:{port}
```
> 實際埠號依系統可用情況而定，預設起始為 9978。
所有端點支援 GET 與 POST（除特別標注外），參數可放在 Query String 中。回應若無特別說明皆為 `text/plain`
，成功回傳 `OK`，失敗回傳 `500` 與錯誤訊息。
---
## 目錄
- [/action — 動作指令](#action--動作指令)
- [do=control — 播放控制](#docontrol--播放控制)
- [do=refresh — 刷新指令](#dorefresh--刷新指令)
- [do=push — 推送播放](#dopush--推送播放)
- [do=file — 開啟檔案](#dofile--開啟檔案)
- [do=search — 觸發搜尋](#dosearch--觸發搜尋)
- [do=setting — 載入配置](#dosetting--載入配置)
- [do=cast — 投放媒體](#docast--投放媒體)
- [do=sync — 同步資料](#dosync--同步資料)
- [/cache — 快取操作](#cache--快取操作)
- [/media — 播放狀態](#media--播放狀態)
- [/file — 本地檔案系統](#file--本地檔案系統)
- [/upload — 上傳檔案](#upload--上傳檔案)
- [/newFolder — 新增資料夾](#newfolder--新增資料夾)
- [/delFolder — 刪除資料夾](#delfolder--刪除資料夾)
- [/delFile — 刪除檔案](#delfile--刪除檔案)
- [/parse — 解析頁面](#parse--解析頁面)
- [/proxy — 爬蟲代理](#proxy--爬蟲代理)
- [/device — 裝置資訊](#device--裝置資訊)
- [端點總覽](#端點總覽)
---
## /action — 動作指令
透過 `do` 參數分派不同動作。
```
GET/POST http://127.0.0.1:9978/action?do={do}&...
```
---
### do=control — 播放控制
控制目前播放器的播放狀態。
```
http://127.0.0.1:9978/action?do=control&type={type}
```
| 參數 | 說明 |
|--------|-----------|
| `type` | 控制指令，見下表。 |
**`type` 可選值：**
| `type` | 說明 |
|----------|----------|
| `play` | 播放 |
| `pause` | 暫停 |
| `stop` | 停止 |
| `replay` | 重新播放 |
| `prev` | 上一集 |
| `next` | 下一集 |
| `loop` | 切換循環播放模式 |
**範例：**
```
http://127.0.0.1:9978/action?do=control&type=play
http://127.0.0.1:9978/action?do=control&type=pause
http://127.0.0.1:9978/action?do=control&type=next
```
---
### do=refresh — 刷新指令
觸發應用程式重新載入指定頁面資料，或推送內容至播放器。
```
http://127.0.0.1:9978/action?do=refresh&type={type}&...
```
**`type` 可選值：**
| `type` | 額外參數 | 說明 |
|------------|--------|-----------------------------------|
| `live` | — | 重新整理直播頁面。 |
| `detail` | — | 重新整理影片詳情頁。 |
| `player` | — | 重新整理播放頁面。 |
| `subtitle` | `path` | 推送字幕至目前播放器，`path` 為字幕檔 URL。 |
| `danmaku` | `path` | 推送彈幕至目前播放器，`path` 為彈幕檔 URL。 |
| `vod` | `json` | 推送 Vod 物件更新，`json` 為 Vod JSON 字串。 |
**範例：**
```
http://127.0.0.1:9978/action?do=refresh&type=detail
http://127.0.0.1:9978/action?do=refresh&type=subtitle&path=http://example.com/sub.srt
http://127.0.0.1:9978/action?do=refresh&type=danmaku&path=http://example.com/danmaku.xml
```
---
### do=push — 推送播放
推送一個 URL 至應用程式進行播放。
```
http://127.0.0.1:9978/action?do=push&url={url}
```
| 參數 | 說明 |
|-------|-----------------------|
| `url` | 要播放的媒體 URL（需 URL 編碼）。 |
**範例：**
```
http://127.0.0.1:9978/action?do=push&url=http%3A%2F%2Fexample.com%2Fvideo.m3u8
```
---
### do=file — 開啟檔案
指定本地檔案路徑，依副檔名執行對應動作。
```
http://127.0.0.1:9978/action?do=file&path={path}
```
| 參數 | 說明 |
|--------|------------|
| `path` | 本地檔案的絕對路徑。 |
**依副檔名的行為：**
| 副檔名 | 行為 |
|----------------------|---------------|
| `.apk` | 觸發 APK 安裝流程。 |
| `.srt` `.ssa` `.ass` | 注入字幕至目前播放器。 |
| 其他 | 觸發設定頁面開啟對應檔案。 |
---
### do=search — 觸發搜尋
在應用程式介面觸發關鍵字搜尋。
```
http://127.0.0.1:9978/action?do=search&word={word}
```
| 參數 | 說明 |
|--------|--------|
| `word` | 搜尋關鍵字。 |
**範例：**
```
http://127.0.0.1:9978/action?do=search&word=%E9%A3%9F%E7%A5%9E
```
---
### do=setting — 載入配置
載入配置內容或指定名稱的配置。
```
http://127.0.0.1:9978/action?do=setting&text={text}&name={name}
```
| 參數 | 說明 |
|--------|----------------|
| `text` | 配置內容字串或配置 URL。 |
| `name` | 配置顯示名稱（選填）。 |
---
### do=cast — 投放媒體
將指定媒體投放至遠端裝置播放。
```
http://127.0.0.1:9978/action?do=cast&config={config}&device={device}&history={history}
```
| 參數 | 說明 |
|-----------|------------------------------------|
| `config` | Config 物件的 JSON 字串，指定要投放的配置。 |
| `device` | 目標裝置的 Device 物件 JSON 字串（含 IP 等資訊）。 |
| `history` | History 物件的 JSON 字串，包含播放歷史。 |
---
### do=sync — 同步資料
在多個裝置間同步觀看紀錄（`history`）或收藏清單（`keep`）。
```
POST http://127.0.0.1:9978/action?do=sync&type={type}&device={device}&force={force}&mode={mode}
```
**Query 參數：**
| 參數 | 說明 |
|----------|--------------------------------------------|
| `type` | 同步類型：`"history"`（觀看紀錄）或 `"keep"`（收藏）。 |
| `device` | 目標裝置的 Device 物件 JSON 字串。 |
| `force` | `"true"` = 先刪除後合併；其他 = 直接合併。 |
| `mode` | `"0"` = 雙向（發送+接收）；`"1"` = 僅接收；`"2"` = 僅發送。 |
| `config` | （`history` 用）Config 物件 JSON 字串。 |
**POST Body（`application/x-www-form-urlencoded`）：**
| 參數 | 說明 |
|-----------|-----------------------------------|
| `targets` | History 或 Keep 物件陣列的 JSON 字串。 |
| `configs` | （`keep` 用）Config URL 陣列的 JSON 字串。 |
---
## /cache — 快取操作
存取應用程式的鍵值快取（基於 SharedPreferences），可用於爬蟲在不同請求間共享資料。
```
GET/POST http://127.0.0.1:9978/cache?do={do}&...
```
**Key 計算規則：** `"cache_" + (rule 為空 ? "" : rule + "_") + key`
---
### do=get — 讀取快取
```
http://127.0.0.1:9978/cache?do=get&key={key}&rule={rule}
```
| 參數 | 說明 |
|--------|-------------------------|
| `key` | 快取鍵名。 |
| `rule` | 命名空間前綴，用於隔離不同爬蟲的快取（選填）。 |
**回應：** `200 OK`，回傳儲存的字串值（若不存在則為空字串）。
---
### do=set — 寫入快取
```
http://127.0.0.1:9978/cache?do=set&key={key}&value={value}&rule={rule}
```
| 參數 | 說明 |
|---------|-------------|
| `key` | 快取鍵名。 |
| `value` | 要儲存的字串值。 |
| `rule` | 命名空間前綴（選填）。 |
---
### do=del — 刪除快取
```
http://127.0.0.1:9978/cache?do=del&key={key}&rule={rule}
```
| 參數 | 說明 |
|--------|-------------|
| `key` | 要刪除的快取鍵名。 |
| `rule` | 命名空間前綴（選填）。 |
---
## /media — 播放狀態
取得目前播放器的媒體資訊與播放狀態。
```
GET http://127.0.0.1:9978/media
```
**回應格式：** `application/json`
**播放器未啟動時：**
```json
{}
```
**播放器啟動時：**
```json
{
"url": "https://cdn.example.com/video.m3u8",
"state": 3,
"speed": 1.0,
"title": "範例電影",
"artist": "來源名稱",
"artwork": "https://example.com/cover.jpg",
"duration": 7200000,
"position": 1234567
}
```
**欄位說明：**
| 欄位 | 類型 | 說明 |
|------------|-----------|----------------------------------------------------------|
| `url` | `string` | 目前串流 URL，無則為 `""`。 |
| `state` | `integer` | PlaybackStateCompat 狀態碼。`1`=緩衝中，`2`=暫停，`3`=播放中，無則為 `-1`。 |
| `speed` | `float` | 播放速率（`1.0` = 正常速度），無則為 `-1`。 |
| `title` | `string` | 媒體標題，無則為 `""`。 |
| `artist` | `string` | 藝術家或來源名稱，無則為 `""`。 |
| `artwork` | `string` | 封面圖 URI，無則為 `""`。 |
| `duration` | `long` | 媒體總時長（毫秒），無則為 `-1`。 |
| `position` | `long` | 目前播放位置（毫秒），無則為 `-1`。 |
---
## /file — 本地檔案系統
瀏覽或下載應用程式的本地儲存空間。
```
GET http://127.0.0.1:9978/file/{path}
```
| 參數 | 說明 |
|--------|-------------------------|
| `path` | 相對於應用程式根目錄的路徑。省略時列出根目錄。 |
**目錄回應（JSON）：**
```json
{
"parent": "videos",
"files": [
{
"name": "movie.mp4",
"path": "videos/movie.mp4",
"time": "2025/03/05 12:00:00",
"dir": 0
},
{
"name": "subtitles",
"path": "videos/subtitles",
"time": "2025/03/05 10:00:00",
"dir": 1
}
]
}
```
**`files` 陣列欄位說明：**
| 欄位 | 類型 | 說明 |
|--------|-----------|----------------------------------|
| `name` | `string` | 檔案或目錄名稱。 |
| `path` | `string` | 相對於根目錄的路徑。 |
| `time` | `string` | 最後修改時間，格式 `yyyy/MM/dd HH:mm:ss`。 |
| `dir` | `integer` | `1` = 目錄，`0` = 檔案。 |
**`parent` 欄位說明：**
| 值 | 意義 |
|--------------------|----------------|
| `"."` | 目前即為根目錄（無上一層）。 |
| `""` | 上一層為根目錄。 |
| `"path/to/parent"` | 上一層目錄的相對路徑。 |
**檔案回應：** 直接串流檔案內容，支援 Range 請求（`206 Partial Content`）與 ETag 快取（
`304 Not Modified`）。
---
## /upload — 上傳檔案
上傳檔案至指定目錄，`.zip` 檔案會自動解壓縮。
```
POST http://127.0.0.1:9978/upload?path={path}
Content-Type: multipart/form-data
```
| 參數 | 說明 |
|--------|------------------|
| `path` | 目標目錄，相對於應用程式根目錄。 |
| 檔案類型 | 行為 |
|--------|----------------------|
| `.zip` | 解壓縮至 `path` 目錄。 |
| 其他 | 複製至 `path/filename`。 |
---
## /newFolder — 新增資料夾
在指定路徑下建立新目錄。
```
GET http://127.0.0.1:9978/newFolder?path={path}&name={name}
```
| 參數 | 說明 |
|--------|-------------------|
| `path` | 父目錄路徑，相對於應用程式根目錄。 |
| `name` | 要建立的資料夾名稱。 |
---
## /delFolder — 刪除資料夾
刪除指定目錄及其所有內容。
```
GET http://127.0.0.1:9978/delFolder?path={path}
```
| 參數 | 說明 |
|--------|----------------------|
| `path` | 要刪除的目錄路徑，相對於應用程式根目錄。 |
---
## /delFile — 刪除檔案
刪除指定檔案。
```
GET http://127.0.0.1:9978/delFile?path={path}
```
| 參數 | 說明 |
|--------|----------------------|
| `path` | 要刪除的檔案路徑，相對於應用程式根目錄。 |
---
## /parse — 解析頁面
將解析器腳本與目標 URL 嵌入 HTML 範本後回傳，通常供 WebView 內部使用。
```
GET http://127.0.0.1:9978/parse?jxs={jxs}&url={url}
```
| 參數 | 說明 |
|-------|---------------|
| `jxs` | 解析器腳本識別碼或內容。 |
| `url` | 待解析的媒體頁面 URL。 |
**回應格式：** `text/html`，回傳渲染後的 `parse.html` 頁面。
---
## /proxy — 爬蟲代理
將請求轉發至爬蟲的 `proxy()` 方法處理，供爬蟲自訂回應（如轉發串流、修改標頭等）。
```
GET/POST http://127.0.0.1:9978/proxy?...
```
所有 Query String 參數、請求標頭與 POST Body 會合併後傳入 `BaseLoader.get().proxy(params)`。回應由爬蟲
`proxy()` 決定，框架原封不動地轉發爬蟲回傳的串流與標頭。
爬蟲如何實作 `proxy()` 方法及取得代理 URL，見 [SPIDER.md — 爬蟲本地代理 URL](SPIDER.md#爬蟲本地代理-url)。
---
## /device — 裝置資訊
取得本機裝置資訊。
```
GET http://127.0.0.1:9978/device
```
**回應格式：** `text/plain`，內容為裝置資訊的 JSON 字串。
**回應欄位：**
| 欄位 | 類型 | 說明 |
|--------|----------|---------------|
| `name` | `string` | 裝置顯示名稱。 |
| `ip` | `string` | 裝置區域網路 IP 位址。 |
---
## 端點總覽
| 端點 | 方法 | 主要參數 | 說明 |
|----------------------|----------|-----------------------------------|---------------------------------------------|
| `/action?do=control` | GET/POST | `type` | 播放控制（play/pause/stop/prev/next/loop/replay） |
| `/action?do=refresh` | GET/POST | `type`, `path`, `json` | 刷新頁面或推送字幕/彈幕 |
| `/action?do=push` | GET/POST | `url` | 推送 URL 播放 |
| `/action?do=file` | GET/POST | `path` | 開啟本地檔案 |
| `/action?do=search` | GET/POST | `word` | 觸發關鍵字搜尋 |
| `/action?do=setting` | GET/POST | `text`, `name` | 載入配置 |
| `/action?do=cast` | GET/POST | `config`, `device`, `history` | 投放媒體至遠端裝置 |
| `/action?do=sync` | POST | `type`, `device`, `force`, `mode` | 多裝置資料同步 |
| `/cache?do=get` | GET/POST | `key`, `rule` | 讀取快取值 |
| `/cache?do=set` | GET/POST | `key`, `value`, `rule` | 寫入快取值 |
| `/cache?do=del` | GET/POST | `key`, `rule` | 刪除快取值 |
| `/media` | GET | — | 取得播放狀態 JSON |
| `/file/{path}` | GET | — | 瀏覽目錄或下載檔案（支援 Range） |
| `/upload` | POST | `path`（multipart） | 上傳檔案（支援 .zip 解壓） |
| `/newFolder` | GET | `path`, `name` | 建立資料夾 |
| `/delFolder` | GET | `path` | 刪除資料夾 |
| `/delFile` | GET | `path` | 刪除檔案 |
| `/parse` | GET | `jxs`, `url` | 取得渲染後的解析 HTML 頁面 |
| `/proxy` | GET/POST | 自訂（轉發至爬蟲） | 爬蟲代理轉發 |
| `/device` | GET | — | 取得裝置資訊 |

839
docs/SPIDER.md
Unescape View File

@ -0,0 +1,839 @@
# 爬蟲 API 規格說明
本文件說明如何實作一個 Spider 爬蟲，包含所有方法的參數、回傳格式及 JSON 結構定義。
---
## 目錄
- [概覽](#概覽)
- [爬蟲類型與載入方式](#爬蟲類型與載入方式)
- [Spider 抽象類別](#spider-抽象類別)
- [init — 初始化](#init--初始化)
- [homeContent — 首頁分類](#homecontent--首頁分類)
- [homeVideoContent — 首頁推薦影片](#homevideoContent--首頁推薦影片)
- [categoryContent — 分類列表](#categorycontent--分類列表)
- [detailContent — 影片詳情](#detailcontent--影片詳情)
- [searchContent — 搜尋](#searchcontent--搜尋)
- [playerContent — 播放解析](#playercontent--播放解析)
- [liveContent — 直播頻道列表](#livecontent--直播頻道列表)
- [proxy — 本地代理](#proxy--本地代理)
- [action — 自定義動作](#action--自定義動作)
- [manualVideoCheck / isVideoFormat — 影片格式判斷](#manualvideocheck--isvideoformat--影片格式判斷)
- [destroy — 銷毀](#destroy--銷毀)
- [回傳資料結構](#回傳資料結構)
- [Result — 通用回傳物件](#result--通用回傳物件)
- [Vod — 影片卡片物件](#vod--影片卡片物件)
- [Class — 分類物件](#class--分類物件)
- [Filter — 篩選器物件](#filter--篩選器物件)
- [Danmaku — 彈幕物件](#danmaku--彈幕物件)
- [Sub — 字幕物件](#sub--字幕物件)
- [Drm — DRM 設定物件](#drm--drm-設定物件)
- [播放集數格式（vod_play_from / vod_play_url）](#播放集數格式vod_play_from--vod_play_url)
- [完整 JSON 範例](#完整-json-範例)
- [homeContent 回傳範例](#homecontent-回傳範例)
- [homeVideoContent / categoryContent 回傳範例](#homevideoContent--categorycontent-回傳範例)
- [detailContent 回傳範例](#detailcontent-回傳範例)
- [playerContent 回傳範例](#playercontent-回傳範例)
- [searchContent 回傳範例](#searchcontent-回傳範例)
- [liveContent 回傳範例](#livecontent-回傳範例)
- [爬蟲本地代理 URL](#爬蟲本地代理-url)
---
## 概覽
Spider 是應用程式爬蟲的抽象基底類別，位於 `com.github.catvod.crawler.Spider`。每個影片來源（`Site`）對應一個
Spider 實例。
**生命週期：**
```
init(context, ext)
│
├─► homeContent(filter) 首頁分類
├─► homeVideoContent() 首頁推薦
├─► categoryContent(...) 分類瀏覽
├─► detailContent(ids) 影片詳情
├─► searchContent(key, quick) 搜尋
├─► playerContent(flag, id, ...) 播放解析
├─► liveContent(url) 直播解析
└─► destroy() 清理資源
```
**欄位：**
| 欄位 | 類型 | 說明 |
|-----------|----------|--------------------------------|
| `siteKey` | `String` | 由載入器注入，標識此 Spider 服務的來源 `key`。 |
---
## 爬蟲類型與載入方式
在 `sites` 配置中，`type` 欄位決定呼叫方式，`api` 欄位決定載入哪種引擎：
| `type` | `api` 格式 | 引擎 | 說明 |
|--------|-----------------|---------------------|------------------------------------------------------------|
| `0` | HTTP URL | 內建 XML 解析 | 直接 GET 請求，回傳 XML 格式。 |
| `1` | HTTP URL | 內建 JSON+Filter | 直接 GET 請求，回傳 JSON 格式，篩選參數以 `f=` 傳遞。 |
| `3` | `csp_ClassName` | JAR（DexClassLoader） | 從 `jar` 指定的 .jar 檔載入 `com.github.catvod.spider.ClassName`。 |
| `3` | `xxx.js` | JavaScript（QuickJS） | 載入 `.js` 檔作為 Spider。 |
| `3` | `xxx.py` | Python（Chaquopy） | 載入 `.py` 檔作為 Spider。 |
| `4` | HTTP URL | 內建 JSON+Base64 ext | 同 `1`，擴充參數以 Base64 編碼傳遞（`ext=`）。 |
> 本文件主要說明 `type=3`（Spider 直接呼叫）的情境。
---
## Spider 抽象類別
所有方法預設回傳空字串 `""`，子類別僅需覆寫所需功能。
---
### init — 初始化
```java
public void init(Context context, String extend) throws Exception
```
**觸發時機：** Spider 實例建立後呼叫一次，用於初始化連線、載入設定等。
| 參數 | 類型 | 說明 |
|-----------|-----------|-------------------------------------------------------|
| `context` | `Context` | Android Context，可取得應用資源、路徑等。 |
| `extend` | `String` | 對應 `Site.ext` 欄位的額外擴充資料，內容由爬蟲自行定義（可為 URL、JSON 字串或路徑）。 |
**回傳：** 無（`void`）
---
### homeContent — 首頁分類
```java
public String homeContent(boolean filter) throws Exception
```
**觸發時機：** 使用者進入首頁時呼叫，取得分類列表（及可選的篩選器）。
| 參數 | 類型 | 說明 |
|----------|-----------|-----------------------------------|
| `filter` | `boolean` | `true` 表示需要回傳篩選器資料（`filters` 欄位）。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。
`class`（分類列表）為主要回傳欄位，`filters`（各分類的篩選器定義）為選填。
---
### homeVideoContent — 首頁推薦影片
```java
public String homeVideoContent() throws Exception
```
**觸發時機：** 首頁分類載入完成後呼叫，取得首頁推薦影片列表。
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。
主要回傳欄位為 `list`（推薦影片列表）。
---
### categoryContent — 分類列表
```java
public String categoryContent(String tid, String pg, boolean filter, HashMap<String, String> extend) throws Exception
```
**觸發時機：** 使用者點擊分類或切換篩選條件時呼叫。
| 參數 | 類型 | 說明 |
|----------|---------------------------|------------------------------------------------------|
| `tid` | `String` | 分類 ID，對應 `Class.typeId`。 |
| `pg` | `String` | 頁碼，從 `"1"` 開始。 |
| `filter` | `boolean` | 是否啟用篩選器。 |
| `extend` | `HashMap<String, String>` | 使用者選擇的篩選條件，key 為篩選器 ID，value 為選項 key。為空 `{}` 時表示無篩選。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。
主要回傳欄位為 `list`（影片列表），選填 `pagecount`（總頁數，用於分頁控制）。
---
### detailContent — 影片詳情
```java
public String detailContent(List<String> ids) throws Exception
```
**觸發時機：** 使用者點擊影片卡片時呼叫，取得完整詳情與播放集數。
| 參數 | 類型 | 說明 |
|-------|----------------|-----------------------------------|
| `ids` | `List<String>` | 影片 ID 清單，通常只含一個元素，對應 `Vod.vodId`。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)，`list` 陣列中有一個完整的 `Vod` 物件。
主要 Vod 欄位：`vod_id`、`vod_name`、`vod_play_from`、`vod_play_url`。
---
### searchContent — 搜尋
```java
public String searchContent(String key, boolean quick) throws Exception
public String searchContent(String key, boolean quick, String pg) throws Exception
```
**觸發時機：** 使用者輸入關鍵字搜尋時呼叫。
| 參數 | 類型 | 說明 |
|---------|-----------|----------------------------------------|
| `key` | `String` | 搜尋關鍵字。框架會自動進行繁→簡轉換以提升相容性。 |
| `quick` | `boolean` | `true` 表示快速搜尋（只傳回基本資訊），`false` 表示完整搜尋。 |
| `pg` | `String` | 頁碼（僅分頁版本），從 `"1"` 開始。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。
主要回傳欄位為 `list`（搜尋結果影片列表）。
> 若 `Site.quickSearch = 0`，快速搜尋會被跳過，直接回傳空結果。
---
### playerContent — 播放解析
```java
public String playerContent(String flag, String id, List<String> vipFlags) throws Exception
```
**觸發時機：** 使用者選擇集數準備播放時呼叫，需解析出實際的媒體 URL。
| 參數 | 類型 | 說明 |
|------------|----------------|--------------------------------------------------------|
| `flag` | `String` | 播放來源名稱，對應 `vod_play_from` 中的一項（如 `"youku"`、`"iqiyi"`）。 |
| `id` | `String` | 集數 URL 或 ID，對應 `vod_play_url` 中某集數的 value 部分。 |
| `vipFlags` | `List<String>` | 全局 VIP 平台旗標清單，對應配置中的 `flags` 欄位（如 `["qq", "youku"]`）。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)（播放解析結果）。
主要回傳欄位為 `url`（實際可播放的媒體 URL）。
選填欄位：
| 欄位 | 說明 |
|------------|------------------------------------------------------------------------------------|
| `parse` | `0` = 直接播放，`1` = 需進一步解析（預設 `0`）。 |
| `header` | 播放請求所需的 HTTP 標頭（鍵值對）。 |
| `flag` | 覆蓋來源旗標，傳入 VIP 解析器時使用。 |
| `jxFrom` | 強制指定解析器旗標（覆蓋 `flag` 的解析器比對結果）。 |
| `format` | 媒體 MIME type（如 `"application/x-mpegURL"`、`"application/dash+xml"`），指定後播放器跳過格式自動偵測。 |
| `danmaku` | 彈幕資料列表，詳見 [Danmaku](#danmaku--彈幕物件)。 |
| `subs` | 字幕列表，詳見 [Sub](#sub--字幕物件)。 |
| `drm` | DRM 版權保護設定，詳見 [Drm](#drm--drm-設定物件)。 |
| `artwork` | 播放頁面封面圖 URL。 |
| `desc` | 播放頁面描述文字。 |
| `position` | 播放恢復位置（毫秒）。 |
| `lrc` | 歌詞 URL（音樂類來源使用）。 |
---
### liveContent — 直播頻道列表
```java
public String liveContent(String url) throws Exception
```
**觸發時機：** 載入直播來源時呼叫，爬蟲回傳頻道列表的原始文字，框架再依格式解析（支援 TXT、M3U、JSON）。
| 參數 | 類型 | 說明 |
|-------|----------|------------------------|
| `url` | `String` | 來源配置中的 `Live.url` 欄位值。 |
**回傳：** 頻道列表的原始文字字串（非 JSON Result），格式可為：
| 格式 | 說明 |
|------|---------------------------------------|
| TXT | 每行 `頻道名稱,URL#URL2...`，以 `#genre#` 分組。 |
| M3U | 標準 `#EXTM3U`/`#EXTINF` 格式。 |
| JSON | `Group` 物件陣列，結構與配置的 `groups` 欄位相同。 |
---
### proxy — 本地代理
```java
public Object[] proxy(Map<String, String> params) throws Exception
```
**觸發時機：** 應用程式內建本地 HTTP 代理伺服器收到請求時呼叫。
| 參數 | 類型 | 說明 |
|----------|-----------------------|--------------------------------------------------------------|
| `params` | `Map<String, String>` | 代理請求參數，從本地代理 URL 的 query string 解析而來。通常含有 `do`、`url` 等自定義參數。 |
**回傳：** `Object[]`（注意：非 JSON 字串），格式為：
```
Object[] {
Integer statusCode, // HTTP 狀態碼（如 200）
String mimeType, // Content-Type（如 "video/mp2t"）
InputStream / String // 回應內容
}
```
---
### action — 自定義動作
```java
public String action(String action) throws Exception
```
**觸發時機：** UI 層呼叫特定自定義指令時呼叫（如登入、重新整理 Token 等）。`action` 字串格式由爬蟲自行定義，框架不解析其內容。
| 參數 | 類型 | 說明 |
|----------|----------|-------------------|
| `action` | `String` | 動作指令字串，格式由爬蟲自行定義。 |
**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。
---
### manualVideoCheck / isVideoFormat — 影片格式判斷
```java
public boolean manualVideoCheck() throws Exception
public boolean isVideoFormat(String url) throws Exception
```
| 方法 | 說明 |
|----------------------|----------------------------------------------------------------|
| `manualVideoCheck()` | 回傳 `true` 時，框架在 WebView 中攔截 URL 後會呼叫 `isVideoFormat()` 進行人工判斷。 |
| `isVideoFormat(url)` | 判斷指定 URL 是否為有效的直接媒體 URL。回傳 `true` 表示可直接播放。 |
| 參數（`isVideoFormat`） | 類型 | 說明 |
|---------------------|----------|-----------|
| `url` | `String` | 待判斷的 URL。 |
---
### destroy — 銷毀
```java
public void destroy()
```
**觸發時機：** 配置重新載入或應用程式清理快取時呼叫，釋放資源（連線、執行緒等）。
**回傳：** 無（`void`）
---
## 回傳資料結構
所有方法（`proxy` 除外）的回傳值均為 JSON 字串，解析後對應以下物件。
---
### Result — 通用回傳物件
不同方法使用的欄位不同，以下按方法分組說明。
**homeContent：**
| JSON 欄位 | 類型 | 說明 |
|-----------|----------------|------------------------------------------------------------------------|
| `class` | `array<Class>` | 分類列表。詳見 [Class](#class--分類物件)。 |
| `filters` | `object` | 篩選器定義，key 為 `type_id`，value 為 `Filter` 陣列。詳見 [Filter](#filter--篩選器物件)。 |
**homeVideoContent / categoryContent / detailContent / searchContent：**
| JSON 欄位 | 類型 | 說明 |
|-------------|--------------|--------------------------------------------|
| `list` | `array<Vod>` | 影片卡片列表。詳見 [Vod](#vod--影片卡片物件)。 |
| `pagecount` | `integer` | 總頁數（`categoryContent`、`searchContent` 使用）。 |
**playerContent：**
| JSON 欄位 | 類型 | 說明 |
|------------|------------------|------------------------------------------------------------------------------------|
| `url` | `string` | 實際播放媒體 URL。 |
| `parse` | `integer` | `0` = 直接播放，`1` = 需進一步解析（預設 `0`）。 |
| `header` | `object` | 播放請求的額外 HTTP 標頭，鍵值對格式。 |
| `flag` | `string` | 播放來源旗標名稱，覆蓋原始 `flag` 參數。 |
| `jxFrom` | `string` | 強制指定解析器旗標（覆蓋 `flag` 的解析器比對結果）。 |
| `format` | `string` | 媒體 MIME type（如 `"application/x-mpegURL"`、`"application/dash+xml"`），指定後播放器跳過格式自動偵測。 |
| `danmaku` | `array<Danmaku>` | 彈幕資料列表，詳見 [Danmaku](#danmaku--彈幕物件)。 |
| `subs` | `array<Sub>` | 字幕列表，詳見 [Sub](#sub--字幕物件)。 |
| `drm` | `Drm` | DRM 版權保護設定，詳見 [Drm](#drm--drm-設定物件)。 |
| `artwork` | `string` | 播放頁面封面圖 URL。 |
| `desc` | `string` | 播放頁面描述文字。 |
| `position` | `long` | 播放恢復位置（毫秒）。 |
| `lrc` | `string` | 歌詞 URL（音樂類來源使用）。 |
**通用欄位（所有 JSON 回傳方法）：**
| JSON 欄位 | 類型 | 說明 |
|---------|-----------|----------------|
| `msg` | `string` | 錯誤或提示訊息。 |
| `code` | `integer` | 回應狀態碼（非零表示錯誤）。 |
---
### Vod — 影片卡片物件
`list` 陣列中的每個元素。
| JSON 欄位 | 類型 | 說明 |
|-----------------|-----------|----------------------------------------------------------|
| `vod_id` | `string` | **影片唯一 ID**，傳入 `detailContent` 的 `ids` 參數。 |
| `vod_name` | `string` | 影片顯示名稱（支援 HTML 編碼）。 |
| `vod_pic` | `string` | 縮圖 URL。 |
| `vod_remarks` | `string` | 備註標籤，顯示在縮圖上（如 `"更新至12集"`、`"HD"`）。 |
| `type_name` | `string` | 所屬分類名稱（用於分類過濾）。 |
| `vod_year` | `string` | 年份。 |
| `vod_area` | `string` | 地區。 |
| `vod_director` | `string` | 導演。 |
| `vod_actor` | `string` | 演員。 |
| `vod_content` | `string` | 簡介/描述。 |
| `vod_play_from` | `string` | 播放來源名稱，多個來源以 `$$$` 分隔。 |
| `vod_play_url` | `string` | 播放集數 URL，格式詳見[下方說明](#播放集數格式vod_play_from--vod_play_url)。 |
| `vod_tag` | `string` | 特殊標記。`"folder"` 表示此項為資料夾，點擊後以 `action` 欄位的 URL 取得子列表。 |
| `action` | `string` | 資料夾類型的子列表請求 URL，回傳格式同 `categoryContent`。 |
| `style` | `Style` | 此影片卡片的顯示樣式覆蓋，詳見 [CONFIG.md](CONFIG.md)。 |
| `land` | `integer` | 強制橫向顯示旗標。 |
| `circle` | `integer` | 強制圓形顯示旗標。 |
| `ratio` | `float` | 卡片寬高比覆蓋。 |
---
### Class — 分類物件
`class` 陣列中的每個元素。
| JSON 欄位 | 類型 | 說明 |
|-------------|-----------|----------------------------------------------------|
| `type_id` | `string` | 分類唯一 ID，傳入 `categoryContent` 的 `tid` 參數。可縮寫為 `id`。 |
| `type_name` | `string` | 分類顯示名稱。可縮寫為 `name`。 |
| `type_flag` | `string` | `"1"` 表示此分類為資料夾類型。 |
| `land` | `integer` | 此分類下影片的橫向顯示旗標。 |
| `circle` | `integer` | 此分類下影片的圓形顯示旗標。 |
| `ratio` | `float` | 此分類下影片卡片的寬高比。 |
---
### Filter — 篩選器物件
`filters` 為一個物件，key 為 `type_id`，value 為 `Filter` 陣列，每個 `Filter` 定義一個篩選維度。
```json
"filters": {
"1": [
{
"key": "area",
"name": "地區",
"value": [
{"n": "全部", "v": ""},
{"n": "大陸", "v": "大陸"},
{"n": "美國", "v": "美國"}
]
},
{
"key": "year",
"name": "年份",
"value": [
{"n": "全部", "v": ""},
{"n": "2024", "v": "2024"}
]
}
]
}
```
**Filter 欄位：**
| JSON 欄位 | 類型 | 說明 |
|---------|----------|-------------------------------------------------|
| `key` | `string` | 篩選器 ID，作為 `categoryContent` 的 `extend` 參數的 key。 |
| `name` | `string` | 篩選器顯示名稱。 |
| `value` | `array` | 可選項目列表，每項含 `n`（顯示名稱）與 `v`（傳入值）。 |
使用者選擇後，`extend` 傳入格式為：
```json
{
"area": "大陸",
"year": "2024"
}
```
---
### Danmaku — 彈幕物件
`danmaku` 陣列中的每個元素。
| JSON 欄位 | 類型 | 說明 |
|---------|----------|------------------------------|
| `url` | `string` | 彈幕來源 URL（必填），支援本地路徑（`/` 開頭）。 |
| `name` | `string` | 顯示名稱（選填），省略時使用 `url`。 |
---
### Sub — 字幕物件
`subs` 陣列中的每個元素。
| JSON 欄位 | 類型 | 說明 |
|----------|----------|-------------------------------------------------------|
| `url` | `string` | 字幕檔 URL（必填）。 |
| `name` | `string` | 顯示名稱（選填）。 |
| `lang` | `string` | 語言代碼（選填，如 `"zh-tw"`、`"en"`）。 |
| `format` | `string` | MIME 類型（選填，如 `"application/x-subrip"`），省略時框架依副檔名自動偵測。 |
---
### Drm — DRM 設定物件
`drm` 物件欄位。
| JSON 欄位 | 類型 | 說明 |
|------------|-----------|--------------------------------------------------------|
| `type` | `string` | DRM 類型：`"widevine"`、`"playready"`、`"clearkey"`。 |
| `key` | `string` | License Server URL（Widevine/PlayReady）或 ClearKey 金鑰字串。 |
| `header` | `object` | License 請求的額外 HTTP 標頭，鍵值對格式（選填）。 |
| `forceKey` | `boolean` | `true` = 強制使用預設 License URI（選填，預設 `false`）。 |
---
### 播放集數格式（vod_play_from / vod_play_url）
`detailContent` 回傳的 `Vod` 物件中，集數資訊以特定分隔符號編碼在兩個字串欄位中。
| 符號 | 用途 |
|-------|-----------------|
| `$$$` | 分隔多個播放來源（group） |
| `#` | 分隔同一來源下的集數 |
| `$` | 分隔集數名稱與集數 URL |
**範例：**
```
vod_play_from: "線路一$$$線路二"
vod_play_url: "第01集$https://cdn1.example.com/ep1.m3u8#第02集$https://cdn1.example.com/ep2.m3u8$$$第01集$https://cdn2.example.com/ep1.m3u8#第02集$https://cdn2.example.com/ep2.m3u8"
```
對應解析結果：
```
線路一:
- 第01集 → https://cdn1.example.com/ep1.m3u8
- 第02集 → https://cdn1.example.com/ep2.m3u8
線路二:
- 第01集 → https://cdn2.example.com/ep1.m3u8
- 第02集 → https://cdn2.example.com/ep2.m3u8
```
集數 URL 的 value 部分即為 `playerContent` 的 `id` 參數。
---
## 完整 JSON 範例
### homeContent 回傳範例
```json
{
"class": [
{
"type_id": "1",
"type_name": "電影"
},
{
"type_id": "2",
"type_name": "電視劇"
},
{
"type_id": "3",
"type_name": "綜藝"
},
{
"type_id": "4",
"type_name": "動漫"
}
],
"filters": {
"1": [
{
"key": "area",
"name": "地區",
"value": [
{
"n": "全部",
"v": ""
},
{
"n": "大陸",
"v": "大陸"
},
{
"n": "香港",
"v": "香港"
},
{
"n": "台灣",
"v": "台灣"
},
{
"n": "美國",
"v": "美國"
}
]
},
{
"key": "year",
"name": "年份",
"value": [
{
"n": "全部",
"v": ""
},
{
"n": "2025",
"v": "2025"
},
{
"n": "2024",
"v": "2024"
}
]
}
]
}
}
```
---
### homeVideoContent / categoryContent 回傳範例
> `categoryContent` 可額外回傳 `pagecount`；`homeVideoContent` 無此欄位。
```json
{
"list": [
{
"vod_id": "12345",
"vod_name": "範例電影",
"vod_pic": "https://example.com/pic/12345.jpg",
"vod_remarks": "HD",
"type_name": "電影"
},
{
"vod_id": "67890",
"vod_name": "範例電視劇",
"vod_pic": "https://example.com/pic/67890.jpg",
"vod_remarks": "更新至12集",
"type_name": "電視劇"
}
],
"pagecount": 10
}
```
---
### detailContent 回傳範例
```json
{
"list": [
{
"vod_id": "12345",
"vod_name": "範例電影",
"vod_pic": "https://example.com/pic/12345.jpg",
"vod_year": "2024",
"vod_area": "大陸",
"vod_director": "張三",
"vod_actor": "李四, 王五",
"vod_content": "這是一部精彩的電影...",
"vod_remarks": "HD",
"type_name": "電影",
"vod_play_from": "線路一$$$線路二",
"vod_play_url": "正片$https://cdn1.example.com/movie.m3u8$$$正片$https://cdn2.example.com/movie.m3u8"
}
]
}
```
**多集電視劇範例：**
```json
{
"list": [
{
"vod_id": "67890",
"vod_name": "範例電視劇",
"vod_play_from": "主線路$$$備用線路",
"vod_play_url": "第01集$https://cdn1.example.com/ep1.m3u8#第02集$https://cdn1.example.com/ep2.m3u8$$$第01集$https://cdn2.example.com/ep1.m3u8#第02集$https://cdn2.example.com/ep2.m3u8"
}
]
}
```
---
### playerContent 回傳範例
**直接播放（無需解析）：**
```json
{
"parse": 0,
"url": "https://cdn.example.com/video/ep1.m3u8",
"header": {
"User-Agent": "Mozilla/5.0",
"Referer": "https://www.example.com/"
}
}
```
**需要進一步解析（VIP 影片）：**
```json
{
"parse": 1,
"url": "https://www.youku.com/video/id_xxx.html",
"flag": "youku"
}
```
**含字幕與彈幕：**
```json
{
"parse": 0,
"url": "https://cdn.example.com/video/ep1.m3u8",
"header": {
"Referer": "https://www.example.com/"
},
"subs": [
{
"name": "繁體中文",
"url": "https://cdn.example.com/sub/ep1.zh-tw.srt",
"lang": "zh-tw"
},
{
"name": "英文",
"url": "https://cdn.example.com/sub/ep1.en.srt",
"lang": "en"
}
],
"danmaku": [
{
"url": "https://danmaku.example.com/ep1.xml"
}
]
}
```
---
### searchContent 回傳範例
```json
{
"list": [
{
"vod_id": "12345",
"vod_name": "範例電影",
"vod_pic": "https://example.com/pic/12345.jpg",
"vod_remarks": "HD",
"type_name": "電影"
}
]
}
```
---
### liveContent 回傳範例
**TXT 格式：**
```
央視頻道,#genre#
CCTV1,http://example.com/cctv1.m3u8#http://cdn2.example.com/cctv1.m3u8
CCTV2,http://example.com/cctv2.m3u8
台灣頻道,#genre#
TVBS,http://example.com/tvbs.m3u8
```
**M3U 格式：**
```
#EXTM3U
#EXTINF:-1 tvg-name="CCTV1" group-title="央視頻道",CCTV1
http://example.com/cctv1.m3u8
```
**JSON 格式：**
```json
[
{
"name": "央視頻道",
"channel": [
{
"name": "CCTV1",
"urls": [
"http://example.com/cctv1.m3u8"
]
}
]
}
]
```
---
## 爬蟲本地代理 URL
爬蟲可在回傳的媒體 URL 中使用 `proxy://` 協議，將請求導向本地代理伺服器，由對應語言的 `proxy()`
方法處理。這樣可以在播放器無法直接存取來源時，讓爬蟲居中轉發資料。
| 語言 | 回傳 URL 前綴 | 取得代理 URL 的方法 |
|------------|------------------|-------------------------------|
| Java（JAR） | `proxy://` | `Proxy.getUrl(boolean local)` |
| Python | `proxy://?do=py` | `getProxyUrl(boolean local)` |
| JavaScript | `proxy://?do=js` | `getProxy(boolean local)` |
> `local` 參數：`true` 取得本地（`127.0.0.1`）代理位址，`false` 取得可對外存取的 LAN IP 位址。
完整端點說明見 [LOCAL.md — /proxy](LOCAL.md#proxy--爬蟲代理)。
**使用範例（Java）：**
```java
@Override
public String playerContent(String flag, String id, List<String> vipFlags) throws Exception {
String proxyUrl = Proxy.getUrl(true) + "?url=" + URLEncoder.encode(id, "UTF-8") + "&token=xxx";
return "{\"parse\":0,\"url\":\"" + proxyUrl + "\"}";
}
@Override
public Object[] proxy(Map<String, String> params) throws Exception {
String url = params.get("url");
String token = params.get("token");
InputStream stream = fetchWithAuth(url, token);
return new Object[]{200, "video/mp2t", stream};
}
```

96
other/sample/config.json
Unescape View File

@ -1,96 +0,0 @@
{
"spider": "./custom_spider.jar",
"wallpaper": "./wallpaper.jpg",
"logo": "./logo.jpg",
"sites": [
{
"key": "push_agent",
"name": "Push",
"type": 3,
"api": "csp_Push"
}
],
"lives": [
{
"name": "Live",
"url": "./live.json",
"epg": "https://epg.112114.xyz/?ch={name}&date={date}"
}
],
"parses": [
{
"name": "官方",
"type": 1,
"url": "https://google.com/api/?url="
}
],
"doh": [
{
"name": "Google",
"url": "https://dns.google/dns-query",
"ips": [
"8.8.4.4",
"8.8.8.8"
]
}
],
"proxy": [
{
"name": "自訂",
"hosts": [
"googlevideo.com",
"raw.githubusercontent.com"
],
"urls": [
"http://127.0.0.1:7890"
]
},
{
"name": "全局",
"hosts": [
".*."
],
"urls": [
"socks5://127.0.0.1:7891"
]
}
],
"rules": [
{
"hosts": [
"api.52wyb.com"
],
"regex": [
"m3u8?pt=m3u8"
],
"exclude": [
"test.json"
]
},
{
"hosts": [
"www.maolvys.com"
],
"script": [
"document.getElementsByClassName('swal-button swal-button--confirm')[0].click()"
]
}
],
"headers": [
{
"host": "gslbserv.itv.cmvideo.cn",
"header": {
"User-Agent": "okhttp/3.12.13"
}
}
],
"hosts": [
"cache.ott.ystenlive.itv.cmvideo.cn=base-v4-free-mghy.e.cdn.chinamobile.com"
],
"flags": [
"qq"
],
"ads": [
"static-mozai.4gtv.tv"
]
}
Write Preview
Loading…
Cancel
Save