warren/momentry_core

Fork 0

Files

Warren ceb33877ff docs: change media_url to file_path in API response

2026-03-25 16:39:48 +08:00

7.7 KiB

Raw Blame History

Momentry Chunk 資料結構說明

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

1. 什麼是 Chunk？

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

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

每個 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（語音轉文字）

{
  "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（場景偵測）

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

3.3 Trace Chunk（軌跡追蹤）

{
  "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（故事線）

{
  "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 欄位：

{
  "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 語音片段

{
  "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 場景片段

{
  "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：

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
  }'

指定影片搜尋：

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 搜尋相關片段

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

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

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：

{
  "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 回應

{
  "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 回應

{
  "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

7.7 KiB Raw Blame History Unescape Escape