hg
/
FONGMITV
mirror of https://github.com/FongMi/TV.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
6501 Commits
3 Branches
0 Tags
3.7 GiB
 
 
 
 
 
Tag: Branch: Tree: release
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'release'
${ noResults }
FONGMITV/docs/LOCAL.md

524 lines
16 KiB
Raw Permalink Blame History

# 本地 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 | — | 取得裝置資訊 |