From d9f9b699a0a97d6377417f0c21782d00450b322c Mon Sep 17 00:00:00 2001 From: FongMi Date: Fri, 6 Mar 2026 00:13:04 +0800 Subject: [PATCH] Update readme --- README.md | 316 ++++----------- docs/CONFIG.md | 720 +++++++++++++++++++++++++++++++++ docs/LOCAL.md | 527 ++++++++++++++++++++++++ docs/SPIDER.md | 839 +++++++++++++++++++++++++++++++++++++++ other/sample/config.json | 96 ----- 5 files changed, 2173 insertions(+), 325 deletions(-) create mode 100644 docs/CONFIG.md create mode 100644 docs/LOCAL.md create mode 100644 docs/SPIDER.md delete mode 100644 other/sample/config.json diff --git a/README.md b/README.md index 4645bb62d..7186ae350 100644 --- a/README.md +++ b/README.md @@ -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 所有端點完整說明 | diff --git a/docs/CONFIG.md b/docs/CONFIG.md new file mode 100644 index 000000000..10dfd171c --- /dev/null +++ b/docs/CONFIG.md @@ -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` | 點播來源清單。詳見 [sites](#sites--點播來源)。 | +| `parses` | `array` | 影片解析規則清單。詳見 [parses](#parses--解析規則)。 | +| `lives` | `array` | 直播來源清單。詳見 [lives — 直播來源](#lives--直播來源)。 | +| `doh` | `array` | DNS over HTTPS 設定清單。詳見 [doh](#doh--dns-over-https)。 | +| `proxy` | `array` | 代理伺服器設定清單。詳見 [proxy](#proxy--代理伺服器)。 | +| `rules` | `array` | 網路攔截規則清單。詳見 [rules](#rules--網路攔截規則)。 | +| `headers` | `array
` | 針對特定主機注入 HTTP 回應標頭。詳見 [headers](#headers--注入回應標頭)。 | +| `hosts` | `array` | DNS 解析覆蓋規則。詳見 [hosts](#hosts--dns-解析覆蓋)。 | +| `flags` | `array` | 平台標示旗標，用於標記特殊平台處理（如 `"qq"`）。 | +| `ads` | `array` | 廣告域名過濾清單，符合的請求將被攔截。詳見 [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` | 顯示的分類名稱白名單，僅顯示清單中的分類。 | +| `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` | 適用旗標清單，標示此解析器適用的平台（如 `["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` | 直播來源清單，欄位定義見下表。 | +| `proxy` | `array` | 代理設定，同 VOD 配置。詳見 [proxy](#proxy--代理伺服器)。 | +| `rules` | `array` | 攔截規則，同 VOD 配置。詳見 [rules](#rules--網路攔截規則)。 | +| `headers` | `array
` | 注入標頭，同 VOD 配置。詳見 [headers](#headers--注入回應標頭)。 | +| `hosts` | `array` | DNS 覆蓋規則，同 VOD 配置。詳見 [hosts](#hosts--dns-解析覆蓋)。 | +| `ads` | `array` | 廣告過濾清單，同 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` | 直播頻道分組清單（內嵌方式）。詳見 [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--頻道項目)。 | + +**範例：** + +```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` | 頻道播放 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` | 伺服器本身的 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` | 適用此代理的主機名稱清單，支援正規表示式。靠前的規則優先匹配。 | +| `urls` | `array` | 代理伺服器 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` | 觸發此規則的目標主機名稱清單。 | +| `regex` | `array` | 用於擷取播放 URL 的正規表示式清單，符合者視為有效的媒體 URL。 | +| `script` | `array` | 在 WebView 中執行的 JavaScript 程式碼清單，用於自動點擊、關閉廣告等操作。 | +| `exclude` | `array` | 排除清單，符合此清單的 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}" + } + } + ] + } + ] + } + ] +} +``` diff --git a/docs/LOCAL.md b/docs/LOCAL.md new file mode 100644 index 000000000..bb4c8071d --- /dev/null +++ b/docs/LOCAL.md @@ -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 | — | 取得裝置資訊 | diff --git a/docs/SPIDER.md b/docs/SPIDER.md new file mode 100644 index 000000000..b9cdebf18 --- /dev/null +++ b/docs/SPIDER.md @@ -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 extend) throws Exception +``` + +**觸發時機：** 使用者點擊分類或切換篩選條件時呼叫。 + +| 參數 | 類型 | 說明 | +|----------|---------------------------|------------------------------------------------------| +| `tid` | `String` | 分類 ID，對應 `Class.typeId`。 | +| `pg` | `String` | 頁碼，從 `"1"` 開始。 | +| `filter` | `boolean` | 是否啟用篩選器。 | +| `extend` | `HashMap` | 使用者選擇的篩選條件，key 為篩選器 ID，value 為選項 key。為空 `{}` 時表示無篩選。 | + +**回傳：** JSON 字串，結構為 [Result](#result--通用回傳物件)。 + +主要回傳欄位為 `list`（影片列表），選填 `pagecount`（總頁數，用於分頁控制）。 + +--- + +### detailContent — 影片詳情 + +```java +public String detailContent(List ids) throws Exception +``` + +**觸發時機：** 使用者點擊影片卡片時呼叫，取得完整詳情與播放集數。 + +| 參數 | 類型 | 說明 | +|-------|----------------|-----------------------------------| +| `ids` | `List` | 影片 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 vipFlags) throws Exception +``` + +**觸發時機：** 使用者選擇集數準備播放時呼叫，需解析出實際的媒體 URL。 + +| 參數 | 類型 | 說明 | +|------------|----------------|--------------------------------------------------------| +| `flag` | `String` | 播放來源名稱，對應 `vod_play_from` 中的一項（如 `"youku"`、`"iqiyi"`）。 | +| `id` | `String` | 集數 URL 或 ID，對應 `vod_play_url` 中某集數的 value 部分。 | +| `vipFlags` | `List` | 全局 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 params) throws Exception +``` + +**觸發時機：** 應用程式內建本地 HTTP 代理伺服器收到請求時呼叫。 + +| 參數 | 類型 | 說明 | +|----------|-----------------------|--------------------------------------------------------------| +| `params` | `Map` | 代理請求參數，從本地代理 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--分類物件)。 | +| `filters` | `object` | 篩選器定義，key 為 `type_id`，value 為 `Filter` 陣列。詳見 [Filter](#filter--篩選器物件)。 | + +**homeVideoContent / categoryContent / detailContent / searchContent：** + +| JSON 欄位 | 類型 | 說明 | +|-------------|--------------|--------------------------------------------| +| `list` | `array` | 影片卡片列表。詳見 [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--彈幕物件)。 | +| `subs` | `array` | 字幕列表，詳見 [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 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 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}; +} +``` diff --git a/other/sample/config.json b/other/sample/config.json deleted file mode 100644 index 5e574c3b5..000000000 --- a/other/sample/config.json +++ /dev/null @@ -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" - ] -} \ No newline at end of file