FilmaxWeb — FTP 影音庫 × 網頁串流
把一顆放滿影片、相片與 PDF 的硬碟，變成一個在瀏覽器裡就能看的媒體庫 ——
自動刮削片名與海報、遠端連線自動降畫質、字幕即時轉檔，全部跑在自己的機器上。
⚠️ 使用前請先讀使用聲明與授權範圍。
本專案僅供管理你自己合法持有的影音檔案，嚴禁用於任何非法用途。
🚧 本專案持續開發中。 功能與設定項目會隨版本調整，
更新後請一併看過 .env.example（可能有新增設定）與本文件。
這份 README 是怎麼用、怎麼修。
「為什麼這樣設計」在 docs/規格需求書.md（索引）與 docs/規格/ 底下一章一檔 ——
那裡才有量測數據、取捨過程與被推翻過的決定。
目錄
這個東西能做什麼
| |
|---|
| 影片 | 自動辨識片名／年份／季集 → 抓 TMDB 的海報與簡介 → 瀏覽器直接播。吃不下的格式即時轉碼，吃得下的直接送原檔 |
| 字幕 | 內嵌字幕即時轉成 WebVTT；繁簡自動判斷；開播時背景預抽整份，跳到中間也不必等 |
| 相片 | EXIF 側欄、1920px 預覽衍生圖、PhotoSwipe 燈箱。刻意不讀 GPS |
| PDF | 內建閱讀器（PDF.js legacy build），支援大檔的分段讀取 |
| 帳號 | 單一密碼，或 Google 登入 ＋ 管理員審核；可以把某些資料夾標成「只給指定帳號看」 |
| 後台 | 掃描控制、失敗清單、使用者審核、56 項參數線上改、診斷頁 |
現況規模（開發機）：147 個影片檔、1490 張相片、48 個條目，單機 SQLite。
五分鐘跑起來
需要 Python 3.10+ 與 ffmpeg（Windows 建議 BtbN 的 n8.1 build）。
1. 安裝.bat 建立 .venv、裝套件、裝 playwright（測試用）
2. 啟動.bat 起服務並自動開瀏覽器 → 第一次會直接進「設定精靈」
3. 設定精靈 5 步：影片來源 → 資料夾 → 海報資料(TMDB) → 誰能看 → 套用
4. 後台 → 媒體庫 → 開始掃描
**不需要手動編輯 .env。**設定精靈（/setup）每一步都會當場驗證：測試 FTP／SFTP 連線並把錯誤翻成
「下一步該做什麼」、讓你點選資料夾而不是手打路徑、驗證 TMDB 金鑰、依「誰會來看」決定要不要設密碼，
最後才一次寫進 .env（舊檔備份成 .env.bak）並重新啟動。之後想換片源或密碼也從這裡進，或在後台〈系統參數〉頁點連結。
精靈只能在執行服務的那台電腦上開（沒設登入驗證時），或由登入的管理員開；它能寫的鍵是白名單
（FTP／片庫資料夾／TMDB／登入密碼／對外網址），FFMPEG_PATH 這類會被當命令執行的項目不能透過網頁改。
.env.example 仍是完整參考，想微調進階項目時再查。
最少要填的四項：
FTP_HOST=127.0.0.1
FTP_USER=你的帳號
FTP_PASSWORD=你的密碼
TMDB_API_KEY=去 themoviedb.org 免費申請
使用 Windows OpenSSH SFTP
先執行 安裝.bat 或 .venv\Scripts\python.exe -m pip install -r requirements.txt，安裝新增的 Paramiko 相依套件。在 .env 設定：
FTP_PROTOCOL=sftp
FTP_HOST=192.168.1.100
FTP_PORT=22
FTP_USER=Windows帳號
FTP_PASSWORD=Windows帳號密碼
FTP_TLS=false
SFTP_KNOWN_HOSTS=
SFTP_KEY_FILE=
LIBRARY_ROOTS=/D:/Movies|movie;/D:/TVShows|tv
FTP_HOST 填 OpenSSH Server 所在電腦的位址；同一台電腦可填 127.0.0.1。密碼使用 Windows 帳號密碼，不是 Windows Hello PIN。
若用私鑰登入，填入 SFTP_KEY_FILE 的完整路徑；加密私鑰可用 FTP_PASSWORD 提供解密密碼。
SFTP 不使用 FTP_TLS、FTP_PASSIVE 或 FTP_ENCODING；未指定 FTP_PORT 時，SFTP 預設 22，FTP 預設 21。
首次連線前，以執行 FilmaxWeb 的同一個 Windows 帳號執行 sftp -P 22 帳號@主機位址，核對伺服器主機金鑰指紋後再接受。
程式使用該帳號的 ~/.ssh/known_hosts，也可用 SFTP_KNOWN_HOSTS 指定金鑰檔。未知或變更的主機金鑰會被拒絕；不會自動略過驗證。
在 SFTP 提示字元執行 pwd、ls /D:/Movies，確認實際可讀的片庫路徑，再填 LIBRARY_ROOTS。若有設定 chroot，請用 chroot 內的路徑。
OpenSSH 不會沿用其他 FTP 伺服器的虛擬目錄；從 FTP 切換後，應核對根目錄與 LIBRARY_LOCAL_ROOTS 對應，再重啟並重新掃描。
SFTP 支援目錄掃描、中文檔名、影片 Range／指定位置讀取、字幕、相片與 PDF，以及後台連線測試。
不設定 FTP_PROTOCOL 時維持原本 FTP／FTPS 行為。
片庫跟服務在同一台機器的話，加這一行會讓轉碼少繞三層（見 J 章第 −1 層）：
LIBRARY_LOCAL_ROOTS=/=D:\1.FTP # FTP 的根目錄「/」實際上是這個資料夾
系統架構
flowchart TB
subgraph client["瀏覽器"]
UI["首頁 / 播放器 / 相片 / 閱讀器"]
ADMIN["後台<br/>掃描・使用者・參數・診斷"]
end
subgraph app["FastAPI 服務（單一行程）"]
direction TB
R1["routers/api.py<br/>63 個端點"]
R2["routers/stream.py<br/>原始位元組・HLS・字幕"]
R3["routers/auth_google.py"]
AUTH["auth / oauth / acl<br/>簽章 cookie・Google OIDC・目錄權限"]
SCAN["scanner<br/>走訪 → 刮削 → 探測"]
MEDIA["media / hls / keyframes<br/>ffprobe・轉碼・分段"]
DB["db<br/>SQLite ＋ 批次寫入"]
PARAM["params / paramstore<br/>env > DB > 預設"]
end
subgraph ext["外部"]
FTP[("FTP 伺服器")]
DISK[("本機磁碟<br/>D:\1.FTP")]
FF["ffmpeg / ffprobe"]
TMDB["TMDB API"]
MSSQL[("MSSQL<br/>帳號（選配）")]
end
UI --> R1 & R2
ADMIN --> R1
R3 --> AUTH
R1 & R2 --> AUTH
R1 --> SCAN & DB & PARAM
R2 --> MEDIA
SCAN --> MEDIA & DB
SCAN --> TMDB
MEDIA --> FF
MEDIA -->|"認得的路徑"| DISK
MEDIA -.->|"對應不到就走 FTP"| FTP
DB --> MSSQL
幾個刻意的設計：
- 單一行程、單一寫入者。 SQLite 用 WAL，寫入集中在
db.py，不必處理死鎖重試。
- 沒有外鍵。 刪除只有一個進入點
purge(reason=...)，連磁碟上的海報縮圖都在裡面一起刪；孤兒數量露在後台總覽當體溫計。
- 設定有優先序：
.env > 後台資料庫 > 程式預設。被 .env 蓋掉的後台設定會在參數頁標出來，不會自動刪。
- ffmpeg 讀檔優先走本機路徑，對應不到才回到「HTTP → FastAPI → FTP → 磁碟」那條路。
播放是怎麼決定的
一個檔案可能走三條路。決定權在片源本身與你在區網還是遠端：
flowchart LR
A["開始播放"] --> B{"容器與編碼<br/>瀏覽器吃得下嗎？"}
B -->|"mp4 + h264 + aac"| C["direct<br/>整檔直送，零成本"]
B -->|"mkv / hevc / ac3…"| D{"有邊界表嗎？<br/>（h264 ＋ keyframe 間距 < 分段長度）"}
D -->|"沒有"| E["單階 HLS<br/>即時轉碼"]
D -->|"有"| F{"區網還是遠端？"}
F -->|"區網"| G["單階：上階 remux<br/>原檔畫質・零轉碼"]
F -->|"遠端"| H["兩階<br/>上階 remux ＋ 下階轉碼<br/>由播放器自己選"]
上階（remux） 是 -c:v copy —— 視訊位元組原封不動照抄，只換容器、必要時轉音訊。
畫質等於原檔，CPU 幾乎不動。代價是碼率就是原檔的碼率（實測某部 19.9 Mbps），所以遠端多半選不到它。
下階（轉碼） 綁碼率（REMOTE_BITRATE_KBPS，程式預設 2800，.env.example 範例設為 8000），NVENC 硬體編碼，
畫質由 VMAF 量測定案（見 J 章）。
一次遠端播放的完整往返：
sequenceDiagram
autonumber
participant B as 瀏覽器 (hls.js)
participant S as FastAPI
participant K as keyframes
participant F as ffmpeg
participant D as 磁碟
B->>S: GET /api/play/{id}
S-->>B: 片長・字幕・音軌・畫質階梯
B->>S: GET /hls/{id}/master.m3u8
S->>K: 這個檔案有哪幾階？
K-->>S: 上階(remux) ＋ 下階(轉碼)
S-->>B: master：BANDWIDTH=21.9M / 3.5M
Note over B: 遠端頻寬不足 → 選下階
B->>S: GET /hls/{id}/index.m3u8?p=h1080_a1_b8000_c2_m0
S-->>B: 固定 6 秒分段清單
B->>S: GET seg-0.ts
S->>F: ffmpeg -ss 0 -t 6 -c:v h264_nvenc -b:v 8000k
F->>D: 直接讀檔（LIBRARY_LOCAL_ROOTS）
F-->>S: mpegts
S-->>B: seg-0.ts（同時背景預轉下一段）
Note over B: 若在區網 → master 只有上階
B-->>S: GET seg-0.ts?p=..._m1
S->>F: ffmpeg -c:v copy（不編碼）
F-->>S: 原始位元組
This is the beginning of the README. Read the rest at the original. Read the full README ↗
