ContextQMD
Back to Tv

本地 HTTP API

docs/LOCAL.md

latest16.4 KB
Original Source

本地 HTTP API

應用程式啟動後會在本地綁定一個 HTTP 伺服器，埠號從 9978 開始依序嘗試至 9998，取得第一個可用埠。

http://127.0.0.1:{port}

實際埠號依系統可用情況而定，預設起始為 9978。

所有端點支援 GET 與 POST（除特別標注外），參數可放在 Query String 中。回應若無特別說明皆為 text/plain，成功回傳 OK，失敗回傳 500 與錯誤訊息。

目錄

/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—重新整理播放頁面。
subtitlepath推送字幕至目前播放器，path 為字幕檔 URL。
danmakupath推送彈幕至目前播放器，path 為彈幕檔 URL。
vodjson推送 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}
參數說明
configConfig 物件的 JSON 字串，指定要投放的配置。
device目標裝置的 Device 物件 JSON 字串（含 IP 等資訊）。
historyHistory 物件的 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）：

參數說明
targetsHistory 或 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
}

欄位說明：

欄位類型說明
urlstring目前串流 URL，無則為 ""。
stateintegerPlaybackStateCompat 狀態碼。1=緩衝中，2=暫停，3=播放中，無則為 -1。
speedfloat播放速率（1.0 = 正常速度），無則為 -1。
titlestring媒體標題，無則為 ""。
artiststring藝術家或來源名稱，無則為 ""。
artworkstring封面圖 URI，無則為 ""。
durationlong媒體總時長（毫秒），無則為 -1。
positionlong目前播放位置（毫秒），無則為 -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 陣列欄位說明：

欄位類型說明
namestring檔案或目錄名稱。
pathstring相對於根目錄的路徑。
timestring最後修改時間，格式 yyyy/MM/dd HH:mm:ss。
dirinteger1 = 目錄，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。

/device — 裝置資訊

取得本機裝置資訊。

GET http://127.0.0.1:9978/device

回應格式： text/plain，內容為裝置資訊的 JSON 字串。

回應欄位：

欄位類型說明
namestring裝置顯示名稱。
ipstring裝置區域網路 IP 位址。

端點總覽

端點方法主要參數說明
/action?do=controlGET/POSTtype播放控制（play/pause/stop/prev/next/loop/replay）
/action?do=refreshGET/POSTtype, path, json刷新頁面或推送字幕/彈幕
/action?do=pushGET/POSTurl推送 URL 播放
/action?do=fileGET/POSTpath開啟本地檔案
/action?do=searchGET/POSTword觸發關鍵字搜尋
/action?do=settingGET/POSTtext, name載入配置
/action?do=castGET/POSTconfig, device, history投放媒體至遠端裝置
/action?do=syncPOSTtype, device, force, mode多裝置資料同步
/cache?do=getGET/POSTkey, rule讀取快取值
/cache?do=setGET/POSTkey, value, rule寫入快取值
/cache?do=delGET/POSTkey, rule刪除快取值
/mediaGET—取得播放狀態 JSON
/file/{path}GET—瀏覽目錄或下載檔案（支援 Range）
/uploadPOSTpath（multipart）上傳檔案（支援 .zip 解壓）
/newFolderGETpath, name建立資料夾
/delFolderGETpath刪除資料夾
/delFileGETpath刪除檔案
/parseGETjxs, url取得渲染後的解析 HTML 頁面
/proxyGET/POST自訂（轉發至爬蟲）爬蟲代理轉發
/deviceGET—取得裝置資訊