# Cut 結構說明

**Date**: 2026-05-16

---

## 定義

Cut = **視覺 chunk**。  
同鏡頭連續拍攝的一組 frame（one continuous camera take）。  
由 `cut_processor.py`（PySceneDetect）偵測場景轉換點自動切割。

與 **聽覺 chunk（sentence）** 的對照：

```
chunk 類型      | 模態  | 產出者              | 內容
----------------|-------|---------------------|----------------------
cut (視覺)      | video | cut_processor.py    | scene boundary
sentence (聽覺) | audio | asr_processor.py    | speech text
```

兩者各自獨立：cut 不含聽覺資訊，sentence 不含視覺資訊。  
但在時間軸上可以對齊：某個 cut 時間區間內包含哪些 sentence。

特性：
- 同一個 cut 內：光線、構圖、背景一致
- 換鏡頭 → 新 cut → 物體動態軌跡中斷
- trace 必定落在一個 cut 內（不跨 cut）

儲存在 `chunk` 表中，`chunk_type = 'cut'`。

## 儲存方式

獨立的 `cuts` 表：

```sql
cuts 表
├── id            SERIAL PK
├── file_uuid     VARCHAR(32)  所屬檔案
├── cut_number    INTEGER      同一檔案內序號 (1, 2, 3...)
├── start_frame   BIGINT       開始影格
├── end_frame     BIGINT       結束影格
├── start_time    FLOAT8       開始時間（秒）
├── end_time      FLOAT8       結束時間（秒）
├── fps           FLOAT8       影格率
├── metadata      JSONB       附加資訊
├── created_at    TIMESTAMPTZ  建立時間
└── UNIQUE(file_uuid, cut_number)
```

## 資料範例

```json
{
  "id": 989849,
  "chunk_id": "989849",
  "chunk_type": "cut",
  "start_frame": 0,
  "end_frame": 867,
  "fps": 25.0,
  "content": {"type": "scene", "scene_number": 1}
}
```

## 與 Trace 的關係

每個 cut 涵蓋一定範圍的影格，trace 則落在 cut 的影格範圍內：

```
cut 1:  frame 0-867      → trace_id 0-31    (32 traces)
cut 2:  frame 868-973    → trace_id 35-45   (11 traces)
cut 3:  frame 974-1073   → trace_id 46      (1 trace)
```

`trace_id` 是 **per-file global sequential**，不因 cut 重設。  
同一個人的不同 cut 會得到不同的 trace_id（因為物體軌跡不連續），但 trace_id 是持續給號的。

```
cut 1 (camera A): frame 0-867     → trace_1 0~31
cut 2 (camera B): frame 868-973   → trace_1 32~45  ← 繼續給號，不歸零
cut 3 (camera C): frame 974-1073  → trace_1 46     ← 繼續給號
```

**唯一約束仍然是 `(file_uuid, trace_id)`**，`cut_id` 只是輔助查詢用的 scope 欄位。

## 查詢

```sql
-- 列出所有 cuts
SELECT id, cut_number, start_frame, end_frame, 
       (end_frame - start_frame) as frames
FROM cuts
WHERE file_uuid = ?
ORDER BY cut_number;

-- 某個 cut 內的 traces
SELECT DISTINCT fd.trace_id, count(*) as faces
FROM face_detections fd
WHERE fd.file_uuid = ? AND fd.cut_id = ?
GROUP BY fd.trace_id
ORDER BY fd.trace_id;
```

## 數量

| File | Cuts | Faces per Cut (avg) |
|------|:----:|:-------------------:|
| `3abeee81...` | 70 | ~1,546 |