技術細節與開發 - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

這一頁給想了解內部運作或參與開發的人：請求流程、路徑怎麼比對、已實作的 Emby 端點、管理 API、程式結構、怎麼跑測試，以及參考過的專案。

Mi302 是一個 FastAPI 程式，用 uvicorn 執行，資料存在 SQLite（data/library.db）。

1. 掃描：把媒體庫資料夾裡的 .strm、一般影片檔、nfo、圖片寫進資料庫，見 媒體庫與掃描。
2. 瀏覽：播放器呼叫 Emby API（/Users/{id}/Views、/Items…），Mi302 從資料庫組出 Emby 的 BaseItemDto。
3. 播放資訊：POST /Items/{id}/PlaybackInfo。strm 項目回 Protocol=Http、IsRemote=true，只允許直接播放（關閉轉碼），DirectStreamUrl 指回 /videos/{id}/stream.{格式}。
4. 串流：播放器請求 /Videos/{id}/stream、/Videos/{id}/original.xxx 或 /Items/{id}/Download：
   • strm 項目：讀 strm 內容，套用路徑替換；帶 pickcode 就用播放器的 User-Agent 向 115 取直鏈，否則可以先跟完上游的重導向；最後回 302 Location: <真實網址>。
   • 一般影片檔：直接送檔，支援 Range。
5. 進度：/Sessions/Playing… 記續播位置和已看，也拿來學片頭片尾，見 片頭片尾跳過。

細節見 播放與外網連線。Mi302 回報自己是 Emby Server 4.8.11.0。

進來的每個 HTTP 請求先整理路徑，再比對路由：

• 路徑裡的英文字母轉小寫，其他字元不動（/Persons/Émilie 的 É 保留），所以路徑不分大小寫。
• 開頭的 /emby、/mediabrowser 拿掉，有沒有這個前綴都可以。
• 結尾的 / 拿掉。
• 查詢參數的名稱不分大小寫（ParentId、parentid 都可以）。

其他：

• 錯誤回應是純文字，和 Emby 一樣。
• CORS 全開。
• FastAPI 自動產生的 API 說明在 /api-docs。

token 依序從這些地方找：

1. 標頭 X-Emby-Token、X-MediaBrowser-Token。
2. 標頭 X-Emby-Authorization（或 Authorization）裡的 Token="…"，格式是 MediaBrowser Client="…", Device="…", DeviceId="…", Version="…", Token="…"。
3. 查詢參數 api_key、X-Emby-Token、ApiKey、X-MediaBrowser-Token。

token 由 POST /Users/AuthenticateByName 發給。同一個使用者在同一個裝置（DeviceId）重新登入時，舊的 token 作廢。API 金鑰（設定檔的 api_keys，或在網頁上建立的）以管理員的身分執行（依名稱排序的第一個管理員），給 MoviePilot 這類程式用；它不能呼叫 /web/api/… 和 /p115/…。

路徑裡有使用者（/Users/{id}/…）或帶 UserId 參數時，讀寫的是那個人的觀看紀錄、續播點和收藏。一般使用者只能指定自己，指定別人回 403；管理員和 API 金鑰可以指定別人，找不到那個人回 404。id 不分大小寫，也接受有連字號的 GUID 寫法。沒指定就是登入的人。

路徑照 Emby 的寫法列出，實際上不分大小寫。「不用登入」以外的都要帶 token。

/Items 的查詢參數：ParentId、Recursive、IncludeItemTypes（含 Person 時一併搜尋人物）、ExcludeItemTypes、Ids、PersonIds、Person、IsFolder、SearchTerm、NameStartsWith、Years、Genres、Filters（IsPlayed、IsUnplayed、IsFavorite、IsResumable）、IsPlayed、IsFavorite、SortBy、SortOrder、StartIndex、Limit、Fields（MediaSources、People、Chapters）、UserId。

StartIndex、Limit 是負數或看不懂時當成沒給。/Items 和 /Shows/{id}/Episodes 沒給 Limit 就是全部，和 Emby 一樣；最新、繼續觀看、接著看預設 20 項，人物搜尋預設 50 項，這幾個最多 500 項。Limit=0 只回總數。

SortBy 認得：SortName、Name、DateCreated、DateLastContentAdded、PremiereDate、ProductionYear、CommunityRating、CriticRating、Runtime、Random、DatePlayed、PlayCount、IndexNumber、ParentIndexNumber、AiredEpisodeOrder。

回空結果的端點（讓播放器不報錯）：/Users/{id}/Items/{id}/Intros、/Items/{id}/Similar、/Movies/{id}/Similar、/Shows/{id}/Similar、/Videos/{id}/AdditionalParts、/Items/{id}/CriticReviews、/Users/{id}/Items/{id}/LocalTrailers、/Users/{id}/Items/{id}/SpecialFeatures、/Items/{id}/SpecialFeatures、/Items/{id}/ThemeMedia。

管理網頁 /web 用的 API。115 的檔案、資料夾 id 有 19 位，超過 JavaScript 能精確表示的整數，回傳時一律是字串；送進來時字串、數字都接受。除了 /web/api/setup，都要用管理員帳號登入後的 token（放在 X-Emby-Token 標頭），API 金鑰不行。請求和回應都是 JSON。

GET /web 是管理網頁本身，/web/115 轉到 /web#115。

embyserver/ 底下每個模組：

資料庫 library.db 的資料表：meta（伺服器 id、115 登入狀態、同步進度等）、users、tokens、items、user_data（觀看紀錄、收藏）、p115_index（115 檔案 id 對本機路徑）、media_info、people、person_names、intro_obs、mp_no_image。

需要 Python 3.10 以上。在 venv 裡：

pip install -r requirements.txt pytest ruff
python -m pytest
ruff check embyserver tests

測試也會用 node --check 檢查管理網頁的 JavaScript 語法（沒有 node 就略過），並檢查說明文件：Wiki 的連結和錨點都找得到、每一頁都在側欄、三種語言的設定檔參考都寫到每一個鍵。

改了 install.sh 之後：

shellcheck install.sh

• DDSRem-Dev/MoviePilot-Plugins：302 播放流程參考 embyreverseproxy 外掛，差別是 Mi302 背後不需要真的 Emby，Emby API 自己實作；115 掃碼登入和取直鏈的流程參考 p115strmhelper。
• StrmAssistant（Emby 神醫助手）：X-mediainfo.json 沿用它「媒體資訊持久化」的格式；片頭片尾的學法參考它的「片頭探測 - 播放行為」。
• xiao-vvv/emby-mediainfo（MIT 授權）：ffprobe 到 Emby 欄位的對照、探測的限速和 115 熔斷規則改寫自這個專案，版權聲明保留在 embyserver/mediainfo.py。