docs: full demo script with narration (10 steps)

docs_v1.0/API_V1.0.0/DEMO_SCRIPT_v1.0.0.md

@@ -0,0 +1,173 @@
+# Momentry Demo Script v1.0.0
+
+Curl for POST/API, browser for video/thumbnail. 約 10 分鐘。
+
+---
+
+## 開場：這是什麼？
+
+> 「Momentry Core — 影片內容分析系統。給它一支影片，它會自動辨識裡面的人臉、追蹤他們的移動、分析誰是誰，還能用文字搜尋影片內容。」
+
+---
+
+## Step 0: 設定
+
+```bash
+KEY="X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
+BASE=https://api.momentry.ddns.net
+```
+
+---
+
+## Step 1: 系統活著
+
+> 「先確認服務正常。」
+
+```bash
+curl $BASE/health
+```
+
+**預期**: `{"status":"ok","version":"1.0.0","uptime_ms":...}`
+
+👉 瀏覽器開 `https://api.momentry.ddns.net/health` 也可。
+
+---
+
+## Step 2: 檔案一覽
+
+> 「目前系統有 37 支已註冊的影片。」
+
+```bash
+curl "$BASE/api/v1/files?page=1&page_size=3" -H "$KEY"
+```
+
+**預期**: Charade (1963) 為主，還有其他測試檔。
+
+---
+
+## Step 3: 臉部追蹤概覽
+
+> 「這是核心功能。系統把影片中每個出現的人臉追蹤成一個『trace』。這部 Charade 總共找到 **6,892 個 trace、108,204 次臉部偵測**。」
+
+```bash
+curl -X POST $BASE/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"sort_by":"face_count","limit":5}'
+```
+
+**解說**:
+- trace #3128: **1,109 次出現**，持續 44.3 秒 — 這是最長的一段
+- trace #3126: 743 次
+- 數字越高代表這個人出現在畫面上的時間越長
+
+---
+
+## Step 4: 單一 Trace 細節
+
+> 「點進去看一個 trace 的每一幀。每個框框就是一次臉部偵測，包含位置、大小、信心度。」
+
+```bash
+curl "$BASE/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/faces?limit=3" -H "$KEY"
+```
+
+**解說**: 回傳的資料包含 `start_frame`（第幾幀）、`start_time`（第幾秒）、bbox 座標、信心度。
+
+---
+
+## Step 5: 補間動畫
+
+> 「因為 face processor 每隔 30 幀才取樣一次，所以原始資料是稀疏的。加上 `interpolate=true` 後，系統會自動線性補間，填滿中間每一幀的 bbox 位置。」
+
+```bash
+curl "$BASE/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/faces?limit=5&interpolate=true" -H "$KEY"
+```
+
+**解說**: `interpolated: false` 是真實偵測，`interpolated: true` 是補間的，confidence = 0。前端的淺色框就是補間框。
+
+---
+
+## Step 6: Trace 影片播放（瀏覽器）
+
+> 「把 trace 渲染成影片，紅框標記人臉位置。」
+
+**瀏覽器開**:
+```
+https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/5/video?padding=1
+```
+
+**解說**: 紅框 = 臉部位置，文字標籤 = trace ID。每個 detection 的框會持續到下一次偵測為止。
+
+---
+
+## Step 7: 關鍵字搜尋 (BM25)
+
+> 「文字搜尋 — 不需要向量，直接用關鍵字比對。這是『friends』的搜尋結果。」
+
+```bash
+curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+```
+
+**預期**: `"You won't find it difficult to make some new friends."` score=0.90
+
+> 「再搜尋『name』看看：」
+
+```bash
+curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"name","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+```
+
+**預期**: `"What's your name?"` score=0.90
+
+---
+
+## Step 8: 身分辨識
+
+> 「系統不只是追蹤臉，它還知道誰是誰。這是 M5 pipeline 自動比對 TMDb 資料庫後的結果 — **2,810 個身分**，包含 Cary Grant、Audrey Hepburn 等。」
+
+```bash
+curl "$BASE/api/v1/identities?page=560&page_size=5" -H "$KEY"
+```
+
+**預期**: Raoul Delfosse, Albert Daumergue, Claudine Berg...
+
+> 「也可以直接看所有身分的列表，按頁次翻找。」
+
+---
+
+## Step 9: 臉部候選人（未辨識）
+
+> 「還沒被指认的身分叫做『candidate』，可以在這裡手動綁定。」
+
+```bash
+curl "$BASE/api/v1/faces/candidates?page=1&page_size=3" -H "$KEY"
+```
+
+---
+
+## Step 10: 嵌入向量搜尋
+
+> 「最後是 AI 搜尋。Query 先經由 EmbeddingGemma 轉成 768 維向量，再到 Qdrant 做相似度比對。」
+
+```bash
+curl -X POST $BASE/api/v1/search/smart -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"Audrey Hepburn","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+```
+
+---
+
+## 收尾
+
+> 「以上就是 Momentry Core v1.0.0 的主要功能展示。總結：**
+>
+> 1. **臉部追蹤** — 6,892 traces, 108,204 detections
+> 2. **補間動畫** — 稀疏取樣 → 連續軌跡
+> 3. **影片渲染** — bbox overlay MP4
+> 4. **關鍵字搜尋** — BM25 全文檢索
+> 5. **身分辨識** — 2,810 identities, TMDb 整合
+> 6. **AI 語意搜尋** — EmbeddingGemma + Qdrant
+>
+> 所有 API 皆可透過 `https://api.momentry.ddns.net` 存取，使用 demo/demo 登入取得 API key。"