Momentry Studio
5951aca086
Core Changes: - Fix SearchView to use start_frame/end_frame directly (no time*fps conversion) - Add hard_delete support to delete_trace API - VideoPlayer: Main timeline + Mark system foundation - Proxy: Add local routes for auth, media, identity-matches, cluster-results - Add .gitignore to exclude build artifacts and dependencies Design Documents: - Multi-track Mark system design (.opencode/plans/) - Video editing positioning standards research Files Modified: - src/views/SearchView.vue: Frame positioning, ensureMinDuration (240 frames) - src/views/PeopleView.vue: batchDeleteGroups with hard_delete - src/api/index.ts: delete_trace with hard_delete body - src/components/VideoPlayer.vue: Timeline + Mark UI - src-tauri/src/proxy.rs: New local routes - AGENTS.md: Update documentation
69 lines
2.3 KiB
Markdown
69 lines
2.3 KiB
Markdown
# Face Clustering Agent Endpoint Request
|
||
|
||
## 需求
|
||
新增一個 on-demand face clustering endpoint，讓前端可以手動觸發 face trace 分組。
|
||
|
||
## 背景
|
||
Momentry Studio 的 People 頁面有「Face Deduplication」按鈕，目的是讓使用者可以對已處理 face 的影片執行 face 分組（clustering）。目前這個功能無法使用，因為對應的 API endpoint 不存在。
|
||
|
||
## 需要的 Endpoint
|
||
|
||
### `POST /api/v1/file/:file_uuid/cluster-agent`
|
||
|
||
**用途**：對指定檔案觸發 face clustering，將相似的 face traces 分組。
|
||
|
||
#### Request
|
||
```
|
||
POST /api/v1/file/{file_uuid}/cluster-agent
|
||
Content-Type: application/json
|
||
X-API-Key: {key}
|
||
|
||
{}
|
||
```
|
||
|
||
| 參數 | 類型 | 必填 | 說明 |
|
||
|------|------|------|------|
|
||
| `file_uuid` | string | ✅ (URL path) | 檔案 UUID |
|
||
|
||
#### Response (200)
|
||
```json
|
||
{
|
||
"success": true,
|
||
"file_uuid": "477b24d3...",
|
||
"message": "Clustering started for file",
|
||
"clusters": 0,
|
||
"total_traces": 2
|
||
}
|
||
```
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `success` | boolean | 是否成功觸發 |
|
||
| `file_uuid` | string | 檔案 UUID |
|
||
| `message` | string | 狀態訊息 |
|
||
| `clusters` | integer | 已分組數量（剛觸發時為 0） |
|
||
| `total_traces` | integer | 該檔案總 face trace 數 |
|
||
|
||
#### 實作邏輯（建議）
|
||
1. 檢查檔案是否存在且 face 已處理完成
|
||
2. 讀取 face detections / face embeddings
|
||
3. 執行 face clustering（可參考 pipeline 中的 clustering 邏輯）
|
||
4. 將分組結果寫入 TKG（更新 `face_trace` node 的 `label`）
|
||
5. 回傳觸發結果（clustering 可非同步執行）
|
||
|
||
### 前端消費流程
|
||
```
|
||
1. POST /api/v1/file/{uuid}/cluster-agent → 觸發 clustering
|
||
2. GET /api/v1/file/{uuid}/face-groups → 輪詢直到 face_groups 有資料
|
||
3. 顯示 face groups 在 People 頁面
|
||
```
|
||
|
||
## 相關檔案
|
||
- **前端按鈕**: `src/views/PeopleView.vue` line 14-18 (`runClusterAgent()`)
|
||
- **API 映射**: `src/api/index.ts` line 369-371 (`run_cluster_agent`)
|
||
- **現有 face-groups**: `GET /api/v1/file/:file_uuid/face-groups` (已存在，用於讀取結果)
|
||
- **Pipeline 處理**: `docs_v1.0/doc_wasm/modules/05_process.md` (face 處理流程)
|
||
|
||
## 優先級
|
||
中優先級 — 目前有 2 個 unassigned traces 但無法分組，使用者無法有效的進行 face deduplication。
|