影視TV本地 HTTP API
透過 App 的區域網路服務，控制播放、管理檔案與同步資料。
先確認連線位址
啟動 App，使用畫面顯示的服務位址。埠號從 9978 到 9998， 取第一個可用的埠。
127.0.0.1 指目前裝置。從電腦或另一台手機操作時， 請換成 App 裝置的區域網路 IP 與埠號。範例網址與 IP 僅供示意。連線測試curl "http://127.0.0.1:9978/device"一般參數放在 Query String 或 application/x-www-form-urlencoded 表單， 不使用整包 JSON body。中文、URL 與 JSON 字串以 --data-urlencode 編碼。
/media、/device 與目錄列表以 text/plain 回傳 JSON。 其他回應請依實際 Content-Type 處理。
/action 回傳 OK 只表示已收到請求；未知指令、缺少參數或沒有播放服務時， 可能不執行。端點沒有通用 token 驗證，僅限可信任的區域網路使用。/action：動作指令
使用 GET 或表單 POST，以 do 選擇操作。
| do | 參數 | 用途 |
|---|---|---|
control | type | 控制目前播放器；可用指令見下表。 |
danmaku | text | 送出一條即時彈幕；需要有效的播放服務與非空文字。 |
refresh | type；字幕、彈幕另加 path | 重新整理頁面，或推送字幕及彈幕。 |
push | url | 把非空 URL 交給 App 推送播放流程。 |
file | path | 開啟裝置上的檔案；不是上傳檔案。 |
search | word | 把非空關鍵字交給 App 搜尋介面。 |
setting | text、name（選填） | 把配置位置或設定文字交給設定流程；text 不可為空。 |
cast | config、device、history | 三者均為 JSON 物件字串，交給 App 投放事件處理。 |
sync | type、mode、force 等 | 交換觀看紀錄或收藏；參數與資料格式見下節。 |
播放控制與即時彈幕
| type | 用途 |
|---|---|
play | 播放 |
pause | 暫停 |
stop | 停止 |
prev | 上一項 |
next | 下一項 |
repeat | 切換循環模式 |
replay | 重新播放 |
播放控制curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=control" --data-urlencode "type=pause"
curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=danmaku" --data-urlencode "text=範例彈幕"重新整理與推送資料
| type | 額外參數 | 用途 |
|---|---|---|
live | — | 直播 |
detail | — | 詳情 |
player | — | 播放器 |
category | — | 分類 |
subtitle | path | 字幕檔位置 |
danmaku | path | 彈幕檔位置 |
刷新範例curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=refresh" --data-urlencode "type=category"
curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=refresh" --data-urlencode "type=subtitle" --data-urlencode "path=https://example.com/subtitle.srt"播放詳情更新
播放詳情使用 playerContent／play 回傳結果的 list[0]。 格式與套用時機見 爬蟲詳情更新。
播放、搜尋、配置與檔案
推送與設定curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=push" --data-urlencode "url=https://example.com/video.m3u8"
curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=search" --data-urlencode "word=範例"
curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=setting" --data-urlencode "text=https://example.com/vod.json" --data-urlencode "name=示意配置"
curl -G "http://127.0.0.1:9978/action" --data-urlencode "do=file" --data-urlencode "path=/TV/subtitle.srt"do=file 依小寫副檔名分派：.apk 交給安裝流程；.srt、.ssa、.ass 交給字幕流程；其他交給設定流程。它使用裝置檔案位置，不會把電腦上的檔案上傳。
投放既有觀看紀錄
config 使用 App 儲存的 Config 記錄，device 取自目標裝置的/device，history 沿用既有 History 記錄。 請將範例替換為實際資料，config 不可改填整份站點配置。
投放表單curl "http://127.0.0.1:9978/action?do=cast" --data-urlencode 'config={"type":0,"url":"https://example.com/vod.json","name":"示意配置"}' --data-urlencode 'device={"uuid":"demo-android-id","name":"示意電視","ip":"http://192.0.2.10:9978","type":0}' --data-urlencode 'history={"key":"demo@@@demo-1@@@7","vodName":"範例項目","vodFlag":"Demo","vodRemarks":"第 1 集","episodeUrl":"demo://episode/1","position":120000}'/action?do=sync：裝置同步
以表單 POST 傳送 JSON 字串。mode 的方向以收到請求的 App 為準； HTTP OK 不代表資料已合併完成。
| 參數 | 用途 |
|---|---|
type | history＝觀看紀錄；keep＝收藏。 |
mode | 0＝傳送並接收（預設）；1＝只接收；2＝只傳送。 |
device | mode 0 / 2 傳送時使用的目標 Device 物件字串；沒有 device 就不主動傳送。 |
force | 字串 true 才啟用先刪後合併；未填或其他值不先刪除。 |
config | history 使用的 Config 物件字串；接收時需要有效 url，可能先載入該配置。 |
targets | History[] 或 Keep[] 的 JSON 字串；型別依 type 決定。 |
configs | keep 使用的 Config[] 物件陣列字串，不是 URL 字串陣列；以來源 id 對應 Keep.cid。 |
收藏同步的資料關係
兩個表單欄位的解碼內容{
"configs": [
{
"id": 7,
"type": 0,
"url": "https://example.com/vod.json",
"name": "示意配置"
}
],
"targets": [
{
"key": "demo@@@demo-1@@@7",
"cid": 7,
"type": 0,
"siteName": "Demo",
"vodName": "範例項目",
"vodPic": "https://example.com/poster.jpg",
"createTime": 1788825600000
}
]
}將 configs 與 targets 分別轉為 JSON 表單字串。 每筆 Keep.cid 須對應所屬的 Config.id，合併時會轉為本機配置 ID。
只接收收藏，不先刪除curl "http://127.0.0.1:9978/action?do=sync&type=keep&mode=1&force=false" --data-urlencode 'configs=[{"id":7,"type":0,"url":"https://example.com/vod.json","name":"示意配置"}]' --data-urlencode 'targets=[{"key":"demo@@@demo-1@@@7","cid":7,"type":0,"siteName":"Demo","vodName":"範例項目","vodPic":"https://example.com/poster.jpg","createTime":1788825600000}]'觀看紀錄使用 type=history、單一 config 與 History 陣列；合併會比較同名項目的 createTime，不是盲目覆寫全部紀錄。同步可能載入另一份配置，請先備份個人資料。
網頁播放與遙控器
在瀏覽器開啟 App 的服務網址。「播放」頁顯示封面、標題與進度， 可控制播放、切換集數或頻道、單集循環、跳轉與倍速。 預設開啟「搜尋」頁，搜尋與網址推送各自保留輸入內容及瀏覽器紀錄。
拖曳進度滑桿預覽時間，放手後跳轉；方向鍵每次調整五秒。 直播隱藏進度、循環與倍速控制，不能跳轉的影片停用滑桿。 網頁提供 0.5×、1.0×、2.0×、3.0× 四個倍速按鈕。
分頁網址
使用語意分頁參數；舊數字分頁不再對應原頁面，未知值會回到搜尋頁。 檔案頁可另帶 path，例如 /?tab=files&path=/TV。
| 網址 | 用途 |
|---|---|
/?tab=search | 搜尋；未指定 tab 時的預設頁。 |
/?tab=push | 網址推送。 |
/?tab=play | 播放控制。 |
/?tab=subtitles | 字幕上傳與套用。 |
/?tab=danmaku | 即時彈幕與彈幕來源。 |
/?tab=settings | 配置、裝置操作、日誌與爬蟲測試入口。 |
/?tab=files | 裝置檔案與傳輸。 |
/remote：查詢與控制
GET 查詢狀態，POST 以表單欄位 type 送出指令。 成功回傳 JSON（application/json），禁止快取；沒有本機播放時回傳{"active":false}。 回應不包含播放網址；完整網址由日誌資訊 API 提供。 網頁僅在播放頁位於前景時約每秒查詢，返回播放頁立即更新。
查詢、設定循環與跳轉curl "http://127.0.0.1:9978/remote"
curl --data-urlencode "type=repeat_on" "http://127.0.0.1:9978/remote"
curl --data-urlencode "type=repeat_off" "http://127.0.0.1:9978/remote"
curl --data-urlencode "type=seek" --data-urlencode "position=120000" "http://127.0.0.1:9978/remote"
curl --data-urlencode "type=speed" --data-urlencode "speed=1.5" "http://127.0.0.1:9978/remote"| type | 用途 |
|---|---|
play | 播放；已播完時從頭播放。 |
pause | 暫停目前影片。 |
stop | 停止播放。 |
prev | 上一集／上一台；須支援切換項目。 |
next | 下一集／下一台；須支援切換項目。 |
repeat_on | 開啟目前影片的單集循環；重複請求仍為開啟。 |
repeat_off | 關閉單集循環；重複請求仍為關閉。 |
seek | 跳到 position 指定的毫秒位置；須支援跳轉，不改變播放／暫停狀態。 |
speed | 以 speed 設定 0.1–5.0 倍速；須支援倍速，直播不可用。 |
| 欄位 | 類型 | 用途 | 預設 |
|---|---|---|---|
active | boolean | 是否有可遙控的本機播放；false 時不回傳其餘欄位。 | — |
title | string | 目前影片的顯示標題。 | — |
mediaKey | string | 目前播放來源的識別鍵；套用字幕或彈幕時以 key 傳回，換片後須重新取得。 | — |
artwork | string | 目前影片的本機封面端點；沒有封面時為空字串，載入失敗時網頁顯示佔位圖。僅 /remote 回傳此欄位。 | — |
position | integer | 目前播放位置，單位毫秒，最小為 0。 | — |
duration | integer | 總長，單位毫秒；未知長度為 0。 | — |
state | integer | 1＝播放結束；2＝就緒但未播放；3＝正在播放；6＝緩衝中。 | — |
playWhenReady | boolean | 播放器是否設定為播放；影片已播完時為 false。 | — |
repeatOne | boolean | 目前是否開啟單集循環，播完會重新播放同一部影片。 | — |
live | boolean | 是否為直播；網頁隱藏循環開關，API 拒絕循環指令。 | — |
canNavigate | boolean | 是否支援上一項／下一項。 | — |
canSeek | boolean | 是否支援網頁跳轉；支援 timeshift 的直播也可使用，未知長度或不可跳轉時為 false。 | — |
canSetSpeed | boolean | 是否支援倍速；直播或播放器不支援時為 false。 | — |
speed | number | 目前播放倍速，例如 1 或 1.5。 | — |
engine | string | 目前播放引擎，ExoPlayer 或 mpv。 | — |
video | string | 播放器回報的視訊尺寸文字。 | — |
artwork 指向同一服務的 /remote/artwork?key=…， 成功回傳 PNG；瀏覽器不需傳送來源網址、Referer 或 Cookie。 key 須對應目前封面；更換封面或停止播放後，舊 key 回傳 404。 缺少或格式不正確的 key 為 400；載入逾時為 503，載入或編碼失敗為 500。
既有 /action?do=control&type=repeat 仍為切換循環。 上一項、下一項及停止可能先派送至播放介面，應以後續 GET 確認結果。
seek 的 position 是非負整數毫秒，超過總長時跳到結尾； 缺少、格式錯誤或超過 64 位元整數範圍時回傳 400。canSeek 為 false 時回傳 409。 支援 直播回看 的來源也可跳轉，位置以目前回看範圍的起點計算。speed 必須是 0.1–5.0 範圍內的有限數值，否則回傳 400；canSetSpeed 為 false 時回傳 409。
缺少或未知指令回傳 400，跨來源的瀏覽器控制請求回傳 403； 無可控制的播放、直播循環或不支援上一項／下一項回傳 409。 不支援的 HTTP 方法回傳 405，主執行緒忙碌或請求中斷回傳 503。
/remote/key：獨立遙控器
從 App 網頁右上角開啟 /remote.html，即可操作遙控器。 返回時會保留原分頁與檔案目錄。
送出遙控器按鍵curl --data-urlencode "key=ok" "http://127.0.0.1:9978/remote/key"| POST 表單參數 | 說明 |
|---|---|
key | up／down／left／right（方向）、ok（確認）、back（返回）、menu（選單）或 0–9。 |
action | press＝單按（預設）。長按依序送 down（按住）、repeat（持續）、up（放開）；取消用 cancel。 |
id | 非 press 必填，限 1–64 個英數字或 -。同次長按沿用相同的 key 與 id。 |
單按或開始長按需有前景頁面或取得焦點的對話框，否則回傳 409。 成功回傳 {"accepted":true,"holding":false}；holding 為 true 表示仍按住。
長按 5 秒未續送 repeat 會自動放開；正常結束仍請送 up 或 cancel。
字幕上傳與彈幕套用
先以 GET /remote 取得目前 mediaKey， 再以 POST 表單的 key 與 path 套用來源。 字幕須先上傳到裝置共用儲存區，支援 SRT／SSA／ASS； 彈幕可使用同範圍內的既有檔案，或 HTTP(S) 網址。
將 MEDIA_KEY 替換成剛查到的 mediaKeycurl --data-urlencode "key=MEDIA_KEY" --data-urlencode "path=/TV/subtitle.srt" "http://127.0.0.1:9978/remote/subtitle"
curl --data-urlencode "key=MEDIA_KEY" --data-urlencode "path=https://example.com/danmaku.xml" "http://127.0.0.1:9978/remote/danmaku"沒有可控制的本機播放、直播或已換成另一個播放來源時回傳 409； key 格式不正確、檔案無效或超出允許路徑時回傳 400。 這些 POST 與播放控制、按鍵 API 均檢查瀏覽器 Origin，跨來源請求回傳 403。
/remote/info：連線狀態與裝置資訊
點主頁連線狀態可查看 App 版本、variant、buildType、裝置名稱、Android 版本、SDK 與 ABI。 資料由 GET /remote/info 提供，回傳 JSON 並禁止快取； 與提供裝置探索及同步資料的 /device 分開。 網頁離線時保留最後一次成功讀取的資訊。
日誌下載與分享
開啟 /logs.html 查看日誌，自動擷取最長 60 分鐘。 「停止擷取」停止來源裝置的收集；「暫停顯示」只暫停畫面更新。
「下載日誌」與「分享日誌」匯出同一份日誌檔案， 包含版本、裝置、播放摘要、診斷資料與原始日誌。 瀏覽器不支援檔案分享時改為下載，可從下載項目再分享；讀取資訊失敗可按「重新讀取資訊」，保留日誌。
匯出不受搜尋與等級篩選影響，上限 512 KiB；超限保留較新日誌並標示缺漏。 檔案包含匯出時間、狀態取樣時間與日誌筆數。
手機版的裝置清單提供「操作」與「日誌」按鈕，長按裝置名稱可命名。 別名只存於目前手機，依有效裝置識別碼保留，不受 IP 改變影響；清空即恢復原名。
日誌資訊 API
取得日誌資訊curl "http://127.0.0.1:9978/log/info"| 欄位 | 用途 |
|---|---|
version / versionCode / variant / buildType | 應用版本與建置資訊。 |
device / android / sdk / abis | 裝置與 Android 資訊。 |
playback | 播放狀態，不含 artwork。 |
playback.url | 解析後的完整網址，保留 query；無來源為空字串。 |
collection | 日誌收集狀態，含 READ_LOGS 權限、目前 UID／PID 等診斷資訊。 |
playbackLog | 目前播放的診斷取樣；無播放器時仍依實際狀態回傳。 |
lastPlaybackError | 最近一次保存的播放錯誤，沒有錯誤時可為 null。 |
GET 回傳 JSON；停止或失敗後仍保留來源時，網址也會保留。 不含封面 URL、UUID、序號或 MAC。
/media：播放狀態
查詢播放狀態curl "http://127.0.0.1:9978/media"沒有播放服務、播放器已釋放，或讀取失敗時回傳 {}。有資料時回傳以下結構；Content-Type 是 text/plain，客戶端需自行解析 JSON。
/media 回應{
"state": 3,
"speed": 1,
"duration": 7200000,
"position": 120000,
"url": "https://example.com/video.m3u8",
"title": "範例項目",
"artist": "Demo",
"artwork": "https://example.com/poster.jpg"
}| 欄位 | 類型 | 用途 | 預設 |
|---|---|---|---|
state | integer | 3＝正在播放；6＝緩衝中；2＝就緒但未播放；其餘狀態回傳 1。 | — |
speed | number | 目前播放速率，1 表示正常速度。 | — |
duration | integer | 播放器回報的總長，單位毫秒；未知長度可能是負值，不保證為 -1。 | — |
position | integer | 目前播放位置，單位毫秒。 | — |
url | string | 目前播放 URL；沒有值時為空字串。 | — |
title | string | 媒體標題；沒有值時為空字串。 | — |
artist | string | 媒體的 artist 中繼資料；沒有值時為空字串。 | — |
artwork | string | 封面 URI；沒有值時為空字串。 | — |
/device：裝置資訊
/device 回應{
"uuid": "demo-android-id",
"name": "影視TV 示意裝置",
"ip": "http://192.0.2.10:9978",
"type": 0,
"serial": "",
"eth": "",
"wlan": "",
"time": 1788825600000
}內容為 JSON 字串，Content-Type 是 text/plain。不要把裝置識別碼或 MAC 位址填入公開範例；下方只列欄位用途。
| 欄位 | 類型 | 用途 | 預設 |
|---|---|---|---|
uuid | string | 此 App 裝置使用的 Android ID。 | — |
name | string | 裝置顯示名稱。 | — |
ip | string | 完整服務位址，包含 http://、區域網路 IP 與實際埠號。 | — |
type | integer | 0＝電視版；1＝手機版。Device 物件另以 2 表示 DLNA 裝置，但本機 /device 不使用此值。 | — |
serial | string | 系統可取得的裝置序號；可用性受裝置與權限限制。 | — |
eth | string | eth0 的 MAC 位址；不保證每個裝置都能取得。 | — |
wlan | string | wlan0 的 MAC 位址；不保證每個裝置都能取得。 | — |
time | integer | App 實例建立時的 Unix 時間，單位毫秒；不是這次 HTTP 回應的時間。 | — |
id | integer | 資料庫識別碼；/device 建立的是未儲存的 Device，因此通常不輸出此欄位。 | — |
檔案與目錄管理
一般相對路徑以 Android 共用外部儲存根目錄 Path.root() 為基準，不是 App 的私有 data 目錄；實際存取仍受系統儲存權限限制。
| 端點 | 使用方式 | 參數與行為 |
|---|---|---|
/file/{path} | GET | 瀏覽目錄或下載檔案；/file 為共用儲存根目錄。 |
/upload | POST multipart/form-data | path 必填且目錄須已存在；檔案使用 multipart 欄位上傳。 |
/newFolder | GET / POST | path 為既有父目錄，name 為新資料夾名稱。 |
/rename | POST 表單 | path 為既有檔案或目錄，name 為新名稱；目標不可已存在。 |
/move | POST 表單 | path 為來源，target 為既有目標目錄；保留名稱，不覆蓋同名項目，也不可搬進自身目錄。 |
/delFolder | GET / POST | path 必填；遞迴刪除指定項目，不可刪除儲存根目錄。 |
/delFile | GET / POST | 與 /delFolder 共用刪除邏輯，並非只允許刪除一般檔案。 |
列目錄與建立資料夾curl "http://127.0.0.1:9978/file/TV"
curl -G "http://127.0.0.1:9978/newFolder" --data-urlencode "path=TV" --data-urlencode "name=demo-empty"瀏覽 /file/TV 的示意回應{
"parent": "",
"files": [
{
"name": "demo.mp4",
"path": "/TV/demo.mp4",
"time": "2026/09/08 12:00:00",
"dir": 0
},
{
"name": "subtitles",
"path": "/TV/subtitles",
"time": "2026/09/08 12:00:00",
"dir": 1
}
]
}| 欄位 | 用途 |
|---|---|
parent | 位於根目錄時為 .；上一層是根目錄時為空字串；其他回傳上一層相對路徑。 |
files[].name | 檔案或目錄名稱。 |
files[].path | 根目錄內的路徑通常帶前導 /，例如 /TV/demo.mp4。 |
files[].time | 最後修改時間，以裝置時區格式化為 yyyy/MM/dd HH:mm:ss。 |
files[].dir | 1＝目錄；0＝一般檔案。 |
下載、Range 與快取
一般下載回傳 200；單一有效 Range 回傳 206，支援起迄、開放結尾及尾端位元組範圍。多段或無效範圍回傳 416；If-None-Match 命中 ETag 時回傳 304，If-Range 不符時改回完整檔案。
讀取前 1 KiBcurl "http://127.0.0.1:9978/file/TV/demo.mp4" -H "Range: bytes=0-1023" --output demo-part.bin重新命名與搬移
重新命名後搬到另一個既有目錄curl --data-urlencode "path=/TV/subtitle.srt" --data-urlencode "name=demo.srt" "http://127.0.0.1:9978/rename"
curl --data-urlencode "path=/TV/demo.srt" --data-urlencode "target=/TV/subtitles" "http://127.0.0.1:9978/move"檔案與目錄均可操作；新名稱只是一個名稱，不能包含路徑分隔符。 目標已存在時不覆蓋，搬移也不能把目錄放進自己裡面。 網頁提供批次搬移與刪除，逐項操作並回報結果。
一般上傳與刪除
上傳至已存在的 TV 目錄curl "http://127.0.0.1:9978/upload?path=TV" -F "file=@./subtitle.srt"multipart 欄位名稱可自訂，上例使用 file；檔名由上傳欄位提供，不能是空字串、.、.. 或包含路徑分隔符。ZIP 會解壓到指定目錄，其他檔案使用原子複製；缺少檔案、目錄不存在或操作失敗會回傳 500 與文字訊息。
刪除示意目錄curl -G "http://127.0.0.1:9978/delFolder" --data-urlencode "path=TV/demo-empty"上傳、新建、重新命名、搬移與刪除都限制在共用儲存根目錄內，禁止刪除或搬移根目錄本身。/file 的區網請求也限制於此範圍；本機 loopback 請求可由 Path.local 解析其他可存取路徑。
可續傳上傳與裝置下載
上傳中斷後，重新選取相同檔案即可續傳。「裝置下載」會將網址內容存入 App 裝置。
以下均使用 POST；/upload/chunk 用 multipart，其餘用表單。 JSON 回應使用 text/plain，禁止快取。
| 端點 | 參數 | 行為 |
|---|---|---|
/upload/start | id、path、name、size、sha256；parallel（選填） | 建立或查詢續傳。id 是 32 位小寫十六進位；size 是檔案位元組數，sha256 是 64 位小寫十六進位。 |
/upload/chunk | id、offset、size；multipart chunk，並行模式另帶 revision | 上傳分塊；依 start 回傳的 chunkSize 切分，offset 與 size 以位元組計算。 |
/upload/finish | id；並行模式另帶 revision | 檢查完整大小與 SHA-256，再落檔或解壓 ZIP；只有 complete=true 才完成。 |
/download/start | url、path；name（選填） | 由 App 裝置下載 HTTP(S) 檔案到既有目錄；省略 name 時取網址最後一段，無名稱時用 download。 |
/download/status | id（選填） | 查詢目前任務；省略 id 可重新取得目前任務。 |
/download/pause | id | 暫停進行中的任務；依回傳狀態確認，已結束的任務不改變狀態。 |
/download/resume | id | 恢復 paused 或 failed 任務；能否接續取決於來源支援及已保存資料。 |
/download/cancel | id | 取消任務；停止後為 cancelled，不等同刪除目的檔案。 |
分塊上傳
先計算整個檔案的 SHA-256，以固定 id 呼叫 start；同一 id 續傳時， path、name、size 與 sha256 必須保持一致。 回應包含 offset、complete 及 chunkSize（目前 4 MiB）。 依 offset 傳送下一塊，全部上傳後呼叫 finish；伺服器檢查 SHA-256 後才完成落檔。
start 指定 parallel=true 時，另外回傳 revision、chunks 及 threads（目前 4）。 chunks 是已收到的分塊索引；chunk 與 finish 均須帶回 revision。 不要只依 offset 判斷並行分塊是否全部完成；若版本改變，重新 start 取得狀態。 過期上傳回傳 404，重新選取原檔案建立或恢復傳輸。
裝置下載任務
由 App 裝置下載到既有 TV 目錄curl --data-urlencode "url=https://example.com/video.mp4" --data-urlencode "path=/TV" --data-urlencode "name=demo.mp4" "http://127.0.0.1:9978/download/start"
curl -X POST "http://127.0.0.1:9978/download/status"每次回應包含任務 id、name、path、state、total、downloaded、speed 與 error。 大小以位元組、speed 以位元組／秒表示；未知 total 為 -1。 pause、resume、cancel 必須帶回同一 id，舊 id 回傳 409；尚無任務時回傳 404。 每個 App 服務同時只執行一個裝置下載，進行中再次 start 回傳 409。
暫停或取消可能先回報 pausing／cancelling，請繼續查詢並以最終狀態為準； 只有 completed 才代表完成，failed 時查看 error。 可用 status 重新取得遺失的任務回應，但任務狀態不保證跨 App 重啟保留。 下載暫存由 App 管理，檔案列表隱藏 .tv-downloads 目錄。
/cache：鍵值快取
使用 GET 或表單 POST。實際儲存鍵為 "cache_" + (rule 為空 ? "" : rule + "_") + key；rule 可用來隔離不同爬蟲的名稱空間。
| do | 參數 | 回應 |
|---|---|---|
get | key、rule（選填） | 回傳儲存的字串；不存在時為空字串。 |
set | key、value、rule（選填） | 寫入字串，回傳 OK。 |
del | key、rule（選填） | 移除鍵，回傳 OK。 |
寫入、讀取與移除curl -G "http://127.0.0.1:9978/cache" --data-urlencode "do=set" --data-urlencode "rule=demo" --data-urlencode "key=greeting" --data-urlencode "value=Hello"
curl "http://127.0.0.1:9978/cache?do=get&rule=demo&key=greeting"
curl "http://127.0.0.1:9978/cache?do=del&rule=demo&key=greeting"代理與 App 內部端點
| 端點 | 參數與行為 |
|---|---|
/proxy | 把 Query / 表單參數、請求標頭、parseBody 產生的 files 依序合併後交給 BaseLoader.proxy；後加入的同名鍵會覆蓋前者。 |
/parse | jxs 為以分號分隔的解析前綴；url 為目標網址。parse.html 會以每個前綴 + url 建立 iframe，回傳 text/html。 |
/image/{key} | 讀取 ImgUtil 已快取的圖片資料，使用圖片本身的 MIME；找不到 key 時回傳 404。不是任意網址的圖片下載 API。 |
/tvbus | 回傳目前直播配置 Core 的 RESP 字串，不是頻道列表。 |
/ | 回傳 App 內建的 index.html 控制頁；其他未匹配路徑會嘗試讀取內建資源，不存在則回傳 404。 |
/proxy 的 POST body 不是一律直接攤平成參數：一般表單進入 parms，multipart 會提供暫存檔資訊，原始 body 依 NanoHTTPD 的 parseBody 結果傳遞。爬蟲回應決定狀態、Content-Type、串流與標頭；無效回應或例外會回傳 500。
解析頁範例curl -G "http://127.0.0.1:9978/parse" --data-urlencode "jxs=https://example.com/parse?url=" --data-urlencode "url=https://example.com/watch/demo-1"代理回傳格式與各語言差異請見 Spider Proxy 回傳；RESP 欄位請見 Core 配置。