---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)"
date: "2026-04-21"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "處理器產出規範"
ai_query_hints:
  - "查詢 Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0) 的內容"
  - "Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0) 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)？"
---

# Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-21 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-21 | 定義處理器產出 JSON 之 Pre-chunk 與 Frame 結構標準 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## 0. 設計原則

為確保所有處理器（ASR, OCR, Face, YOLO, Cut）產出的時間軸精確且一致，本規範定義以下核心原則：

1. **幀為本位 (Frame-Based)**：
    * 所有時間計算的**唯一權威來源**是幀編號 (`frame_number`)。
    * 開始時間、結束時間、長度皆以幀為單位 (`start_frame`, `end_frame`, `length_frames`)。

2. **秒數為參考 (Timestamp is Derived)**：
    * 秒數 (`timestamp_sec`, `start_time_sec`) 僅供人類閱讀與外部 API 參考。
    * 計算公式：`time = frame / fps`。
    * FPS 資訊必須與 `ffprobe` 探針結果嚴格一致。

3. **結構統一**：
    * 產出分為兩大層級：**Frame (單幀檢測)** 與 **Pre-Chunk (時間區間聚合)**。

---

## 1. 核心資料結構

### 1.1 Frame (幀級資料)

適用於需要逐幀記錄空間座標或逐幀屬性的任務 (如 OCR, Face, YOLO)。

```json
{
  "frame_number": 12345,
  "timestamp_sec": 411.91,
  "fps": 29.97,
  "processor": "face_detection",
  "data": {
    "faces": [
      {
        "box": { "x": 100, "y": 50, "w": 60, "h": 60 },
        "identity": null,
        "confidence": 0.98
      }
    ]
  }
}
```

| 欄位 | 類型 | 說明 | 計算方式 |
|:---|:---|:---|:---|
| `frame_number` | `int` | **主鍵**，物理幀編號 | 從 0 開始計數 |
| `timestamp_sec` | `float` | 時間戳記 (秒) | `frame_number / fps` |
| `fps` | `float` | 幀率 | 來自 `ffprobe` 探針結果 |
| `data` | `object` | 偵測結果負載 | 依處理器類型定義 |

### 1.2 Pre-Chunk (預切片資料)

適用於具有持續時間的語意片段 (如 ASR 語句、鏡頭切換、OCR 持續文字)。

```json
{
  "pre_chunk_id": "pc_001",
  "type": "asr_segment",
  "start_frame": 1200,
  "end_frame": 1500,
  "duration_frames": 300,
  "start_time_sec": 40.04,
  "end_time_sec": 50.05,
  "fps": 29.97,
  "data": {
    "text": "這是一個非常長的句子...",
    "speaker": "SPEAKER_00"
  }
}
```

| 欄位 | 類型 | 說明 | 計算方式 |
|:---|:---|:---|:---|
| `start_frame` | `int` | **起始幀** | - |
| `end_frame` | `int` | **結束幀** | - |
| `duration_frames` | `int` | 持續幀數 | `end_frame - start_frame + 1` |
| `start_time_sec` | `float` | 起始秒數 | `start_frame / fps` |
| `end_time_sec` | `float` | 結束秒數 | `end_frame / fps` |
| `data` | `object` | 內容負載 | 依處理器類型定義 |

---

## 2. 處理器產出規範 (JSON Spec)

### 2.1 ASR (語音識別) -> Pre-Chunk
ASR 產出主要是文字片段，因此歸類為 `Pre-Chunk`。

* **輸出檔名**: `{uuid}_asr.json`
* **結構**: Array of Pre-Chunk

```json
[
  {
    "start_frame": 0,
    "end_frame": 149,
    "start_time_sec": 0.0,
    "end_time_sec": 5.0,
    "data": {
      "text": "Hello world, this is a test.",
      "speaker": "SPEAKER_00",
      "language": "en"
    }
  },
  ...
]
```

### 2.2 Face (人臉偵測) -> Frame
人臉位置可能每幀微動，因此以 `Frame` 記錄最精確。

* **輸出檔名**: `{uuid}_faces.json`
* **結構**: Object containing Array of Frames

```json
{
  "info": {
    "fps": 29.97,
    "total_frames": 5000
  },
  "frames": [
    {
      "frame_number": 10,
      "timestamp_sec": 0.33,
      "data": {
        "faces": [
          { "box": { "x": 10, "y": 10, "w": 50, "h": 50 }, "confidence": 0.99 }
        ]
      }
    }
  ]
}
```

### 2.3 OCR (文字辨識) -> Frame
通常以抽樣 (Sample) 方式進行 (如每 30 幀抽 1 幀)。

* **輸出檔名**: `{uuid}_ocr.json`
* **結構**: Array of Frames

```json
[
  {
    "frame_number": 1200,
    "timestamp_sec": 40.04,
    "data": {
      "texts": [
        { "text": "CAST", "bbox": [100, 100, 200, 50] },
        { "text": "Cary Grant", "bbox": [100, 150, 200, 30] }
      ]
    }
  }
]
```

### 2.4 Cut (鏡頭切割) -> Pre-Chunk
鏡頭切割定義了場景的邊界，是典型的 Pre-Chunk。

* **輸出檔名**: `{uuid}_cuts.json`
* **結構**: Array of Pre-Chunk

```json
[
  {
    "start_frame": 0,
    "end_frame": 299,
    "start_time_sec": 0.0,
    "end_time_sec": 10.0,
    "data": {
      "scene_type": "indoor",
      "cut_score": 0.95
    }
  }
]
```

---

## 3. 數據一致性檢查

為確保產出符合規範，寫入資料庫前需執行以下檢查：

1. **FPS 校驗**: JSON 中的 `fps` 必須等於 `assets` 表中 `media_info->fps` 的值。誤差允許範圍 `±0.01`。
2. **幀邊界**: `start_frame` 必須 `>= 0`，`end_frame` 必須 `<= total_frames`。
3. **時間換算驗證**:
    * `abs(timestamp_sec - (frame_number / fps)) < 0.001`

---

## 4. 與 Chunk 系統的關聯

Processor 產出的是 **Raw Data (Pre-chunk / Frames)**。
後續的 **Chunk Strategy (Rule 1/2/3)** 會讀取這些 Raw Data 並進行聚合，生成最終的 `chunks` 表記錄。

* **Input**: 多個 Pre-chunks / Frames
* **Process**: 合併 (Merge)、摘要 (Summarize)、嵌入 (Embedding)
* **Output**: `chunks` 表 (具備語意向量)

```mermaid
graph LR
    A[ASR Pre-Chunk] --> C(Chunk Aggregator)
    B[OCR Frame] --> C
    D[Cut Pre-Chunk] --> C
    C --> E[Final Chunk with Vector]
```

此設計確保了**原始物理資訊 (幀)** 的完整保留，同時允許上層邏輯進行靈活的語意組裝。
