---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Chunk 資料結構說明"
date: "2026-03-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "chunk"
  - "資料結構說明"
ai_query_hints:
  - "查詢 Momentry Chunk 資料結構說明 的內容"
  - "Momentry Chunk 資料結構說明 的主要目的是什麼？"
  - "如何操作或實施 Momentry Chunk 資料結構說明？"
---

# Momentry Chunk 資料結構說明

> **對象**: marcom 團隊  
> **版本**: V1.0 | **日期**: 2026-03-25

---

## 1. 什麼是 Chunk？

Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統會自動：

1. **分析** - 偵測場景、人臉、姿態
2. **轉換** - 語音轉文字（ASR）
3. **分段** - 將內容切割成可搜尋的片段
4. **向量化** - 產生可搜尋的特徵向量

每個 Chunk 就是一個**可獨立搜尋的內容單位**。

---

## 2. Chunk 資料結構

### 2.1 主要欄位

| 欄位名 | 類型 | 說明 | 範例 |
|--------|------|------|------|
| `uuid` | 字串 (32) | 影片唯一識別碼 | `952f5854b9febad1` |
| `chunk_id` | 字串 (64) | Chunk 唯一識別碼 | `asr_00001` |
| `chunk_index` | 整數 | Chunk 順序號碼 | `1` |
| `chunk_type` | 字串 (32) | Chunk 類型 | `sentence` |
| `start_time` | 浮點數 | 開始時間（秒） | `12.5` |
| `end_time` | 浮點數 | 結束時間（秒） | `18.3` |
| `content` | JSONB | 詳細內容 | 見下方 |
| `vector_id` | 字串 (64) | 向量 ID | `vec_12345` |
| `text_content` | 文字 | 純文字內容 | `這是一段話` |
| `fps` | 浮點數 | 影片幀率 | `24.0` |
| `start_frame` | 整數 | 開始幀數 | `300` |
| `end_frame` | 整數 | 結束幀數 | `439` |
| `frame_count` | 整數 | 總幀數 | `139` |

### 2.2 Chunk 類型說明

| 類型 | ID | 說明 | 來源處理器 |
|------|-----|------|-----------|
| `sentence` | `sentence` | 語音轉文字片段 | ASR 處理 |
| `time` | `time_based` | 固定時間分段 | 系統自動切割 |
| `cut` | `cut` | 場景變化片段 | CUT 處理 |
| `trace` | `trace` | 軌跡追蹤片段 | YOLO 追蹤處理 |
| `story` | `story` | 故事線片段（父子區塊） | Story 分析處理 |

**父子區塊關係**：
- `story` 是**父區塊**，可包含多個 `sentence`、`cut`、`trace` 子區塊
- 透過 `parent_chunk_id` 和 `child_chunk_ids` 建立階層關係

---

## 3. Content JSON 結構

每個 Chunk 的 `content` 欄位包含詳細的處理結果：

### 3.1 ASR Chunk（語音轉文字）

```json
{
  "text": "今天天氣非常好，我們去郊外踏青吧",
  "words": [
    {
      "word": "今天",
      "start": 12.5,
      "end": 12.8,
      "confidence": 0.95
    },
    {
      "word": "天氣",
      "start": 12.8,
      "end": 13.1,
      "confidence": 0.92
    }
  ],
  "language": "zh-TW",
  "speaker": null
}
```

### 3.2 Cut Chunk（場景偵測）

```json
{
  "scenes": [
    {
      "scene_id": "cut_001",
      "start_time": 12.5,
      "end_time": 45.2,
      "transition": "cut",
      "confidence": 0.98
    }
  ]
}
```

### 3.3 Trace Chunk（軌跡追蹤）

```json
{
  "track_id": "track_001",
  "object_class": "person",
  "frames": [
    {
      "frame": 300,
      "bbox": [120, 80, 200, 300],
      "confidence": 0.95
    },
    {
      "frame": 301,
      "bbox": [122, 82, 202, 302],
      "confidence": 0.94
    }
  ],
  "total_frames": 180
}
```

### 3.4 Story Chunk（故事線）

```json
{
  "story_id": "story_001",
  "title": "開場介紹",
  "summary": "主持人介紹節目主題",
  "child_chunk_ids": ["sentence_00001", "sentence_00002", "cut_00001"],
  "tags": ["intro", "host"]
}
```

### 3.5 Metadata（其他偵測資訊）

人臉（Face）、文字辨識（OCR）、姿態（Pose）等偵測結果會附加在 `metadata` 欄位：

```json
{
  "metadata": {
    "faces": [
      {
        "bbox": [120, 80, 200, 180],
        "confidence": 0.87,
        "emotion": "neutral"
      }
    ],
    "ocr": {
      "text": "MOMENTRY",
      "confidence": 0.96
    },
    "pose": {
      "keypoints": [
        {"name": "nose", "x": 192, "y": 85, "confidence": 0.95}
      ]
    }
  }
}
```

---

## 4. 時間格式說明

### 4.1 秒數格式（常用）

```
格式: 秒.幀數
範例: 1234.60 = 第 1234 秒 + 第 60 幀
```

### 4.2 時間軸格式

```
格式: HH:MM:SS.FF
範例: 00:20:34.12 = 20分34秒12幀
```

### 4.3 幀數計算

```
幀數 = 秒數 × fps
例如: 12.5秒 × 24fps = 300幀
```

---

## 5. 實際資料範例

假設有一個影片，包含以下處理結果：

### 5.1 語音片段

```json
{
  "uuid": "952f5854b9febad1",
  "chunk_id": "asr_00001",
  "chunk_type": "sentence",
  "start_time": 12.5,
  "end_time": 18.3,
  "content": {
    "text": "今天天氣非常好，我們去郊外踏青吧",
    "language": "zh-TW"
  },
  "text_content": "今天天氣非常好，我們去郊外踏青吧",
  "start_frame": 300,
  "end_frame": 439,
  "fps": 24.0
}
```

### 5.2 場景片段

```json
{
  "uuid": "952f5854b9febad1",
  "chunk_id": "cut_00001",
  "chunk_type": "cut",
  "start_time": 45.0,
  "end_time": 120.5,
  "content": {
    "scenes": [{
      "scene_id": "cut_001",
      "transition": "cut",
      "confidence": 0.98
    }]
  },
  "start_frame": 1080,
  "end_frame": 2892,
  "fps": 24.0
}
```

---

## 6. 如何使用 Chunk

### 6.1 API 取得 Chunk

使用搜尋 API 取得 Chunk：

```bash
curl -X POST "https://api.momentry.ddns.net/api/v1/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "關鍵字",
    "limit": 10
  }'
```

**指定影片搜尋**：
```bash
curl -X POST "https://api.momentry.ddns.net/api/v1/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "關鍵字",
    "uuid": "39567a0eb16f39fd",
    "limit": 5
  }'
```

### 6.2 搜尋相關片段

當使用者搜尋「天氣」時，系統會：

1. 將「天氣」轉換為向量
2. 在向量資料庫中搜尋相似向量
3. 找到相關的 Chunk
4. 返回時間軸和內容

### 6.3 播放指定片段

取得 Chunk 後可播放：

```
開始時間: 12.5 秒
結束時間: 18.3 秒
影片 UUID: 39567a0eb16f39fd
```

**播放器連結格式**：
```
/player?uuid={uuid}&start={start_time}&end={end_time}
```

### 6.4 組合多個 Chunk

多個相關 Chunk 可以組合成一個章節或故事線。

### 6.5 Story Chunk（父子關係）

Story Chunk 可包含多個子 Chunk：

```json
{
  "chunk_id": "story_001",
  "chunk_type": "story",
  "content": {
    "story_id": "story_001",
    "title": "開場介紹",
    "child_chunk_ids": ["sentence_00001", "sentence_00002", "cut_00001"]
  }
}
```

---

## 7. API 回應格式

### /search 回應

```json
{
  "results": [
    {
      "uuid": "39567a0eb16f39fd",
      "chunk_id": "sentence_1471",
      "chunk_type": "sentence",
      "start_time": 5309.08,
      "end_time": 5311.08,
      "text": "influenced by a vital way,",
      "score": 0.68
    }
  ],
  "query": "關鍵字"
}
```

### /n8n/search 回應

```json
{
  "query": "關鍵字",
  "count": 1,
  "hits": [
    {
      "id": "sentence_1471",
      "vid": "39567a0eb16f39fd",
      "start": 5309.08,
      "end": 5311.08,
      "title": "Chunk sentence_1471",
      "text": "influenced by a vital way,",
      "score": 0.68,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}
```

> **注意**: `file_path` 是影片的實際路徑，可用於本地播放。

---

## 8. 快速參考

| 項目 | 說明 |
|------|------|
| UUID | 影片唯一識別碼（16位 hex） |
| Chunk ID | 片段識別碼（如 `sentence_00001`） |
| chunk_type | 片段類型（sentence/time/cut/trace/story） |
| start_time | 開始時間（秒） |
| end_time | 結束時間（秒） |
| text_content | 純文字內容 |
| content | 詳細 JSON 結構 |
| metadata | 人臉、OCR、姿態等偵測結果 |
| parent_chunk_id | 父區塊 ID（用於 story 區塊） |
| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） | |

---

## 附錄：版本歷史

| 版本 | 日期 | 內容 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-25 | 初版建立 | OpenCode |
| V1.1 | 2026-03-25 | 新增 API 取得 Chunk 方式、播放連結格式 | OpenCode |
