docs: Add JSON output specification

- Define all JSON output file types and naming conventions - Document Probe, ASR, ASRx, OCR, YOLO, Face, Pose structures - Include field descriptions and data types - Add processing pipeline flow - Document database storage schema
2026-03-16 15:48:51 +08:00
parent e66b9501bd
commit 47b9c2f750
1 changed files with 503 additions and 0 deletions
--- a/docs/JSON_OUTPUT_SPEC.md
+++ b/docs/JSON_OUTPUT_SPEC.md
@@ -0,0 +1,503 @@
+# Momentry JSON 輸出檔案規範
+
+本文檔定義 Momentry Core 系統中所有 JSON 輸出檔案的結構、命名規範與儲存位置。
+
+---
+
+## 1. 輸出檔案總覽
+
+### 1.1 檔案類型
+
+| 類型 | 前綴 | 說明 | 狀態 |
+|------|------|------|------|
+| **Probe** | `{uuid}.probe.json` | 影片元數據 | ✅ 已實作 |
+| **ASR** | `{uuid}.asr.json` | 語音識別結果 | ✅ 已實作 |
+| **ASRx** | `{uuid}.asrx.json` | 說話者分離 | 🔜 規劃中 |
+| **OCR** | `{uuid}.ocr.json` | 文字辨識結果 | 🔜 規劃中 |
+| **YOLO** | `{uuid}.yolo.json` | 物件偵測結果 | 🔜 規劃中 |
+| **Face** | `{uuid}.face.json` | 人臉偵測結果 | 🔜 規劃中 |
+| **Pose** | `{uuid}.pose.json` | 姿態估計結果 | 🔜 規劃中 |
+| **Thumbnail** | `{uuid}/thumb_XXX.jpg` | 縮圖檔案 | ✅ 已實作 |
+
+### 1.2 命名規範
+
+```
+{UUID}.{類型}.json
+
+範例:
+1636719dc31f78ac.probe.json  - 影片探測結果
+1636719dc31f78ac.asr.json   - 語音識別結果
+1636719dc31f78ac.ocr.json    - 文字辨識結果
+```
+
+- **UUID**: 16 字元，基於檔案路徑計算
+- **類型**: 小寫 snake_case
+- **副檔名**: `.json`
+
+---
+
+## 2. 輸出目錄結構
+
+### 2.1 預設輸出位置
+
+```
+momentry_core_0.1/
+├── {uuid}.probe.json          # 影片探測
+├── {uuid}.asr.json           # 語音識別
+├── {uuid}.asrx.json         # 說話者分離
+├── {uuid}.ocr.json           # 文字辨識
+├── {uuid}.yolo.json          # 物件偵測
+├── {uuid}.face.json          # 人臉偵測
+├── {uuid}.pose.json          # 姿態估計
+└── thumbnails/
+    └── {uuid}/
+        ├── thumb_000.jpg
+        ├── thumb_001.jpg
+        └── ...
+```
+
+### 2.2 儲存策略
+
+| 資料類型 | 儲存位置 | 說明 |
+|----------|----------|------|
+| JSON 檔案 | 專案根目錄 | 方便快速存取 |
+| 縮圖 | thumbnails/{uuid}/ | 分離儲存 |
+| 資料庫 | PostgreSQL | 長期儲存 |
+
+---
+
+## 3. JSON 結構定義
+
+### 3.1 Probe (影片探測)
+
+**檔案**: `{uuid}.probe.json`
+
+```json
+{
+  "streams": [
+    {
+      "index": 0,
+      "codec_name": "h264",
+      "codec_type": "video",
+      "width": 1920,
+      "height": 1080,
+      "r_frame_rate": "60000/1001",
+      "duration": "6879.329524",
+      "sample_rate": null,
+      "channels": null
+    },
+    {
+      "index": 1,
+      "codec_name": "aac",
+      "codec_type": "audio",
+      "width": null,
+      "height": null,
+      "r_frame_rate": "0/0",
+      "duration": "6879.245333",
+      "sample_rate": "48000",
+      "channels": 2
+    }
+  ],
+  "format": {
+    "filename": "/path/to/video.mov",
+    "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
+    "duration": "6879.329524",
+    "size": "2361629896",
+    "bit_rate": "2748000"
+  }
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `streams` | Array | 媒體串流陣列 |
+| `streams[].index` | Integer | 串流索引 |
+| `streams[].codec_name` | String | 編碼名稱 |
+| `streams[].codec_type` | String | 串流類型 (video/audio) |
+| `streams[].width` | Integer | 寬度 (video) |
+| `streams[].height` | Integer | 高度 (video) |
+| `streams[].r_frame_rate` | String | 幀率 |
+| `streams[].duration` | String | 持續時間 (秒) |
+| `streams[].sample_rate` | String | 採樣率 (audio) |
+| `streams[].channels` | Integer | 聲道數 (audio) |
+| `format` | Object | 檔案格式資訊 |
+| `format.filename` | String | 原始檔案路徑 |
+| `format.format_name` | String | 格式名稱 |
+| `format.duration` | String | 總時長 (秒) |
+| `format.size` | String | 檔案大小 (bytes) |
+| `format.bit_rate` | String | 位元率 |
+
+---
+
+### 3.2 ASR (語音識別)
+
+**檔案**: `{uuid}.asr.json`
+
+```json
+{
+  "language": "en",
+  "language_probability": 0.9945855736732483,
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 19.04,
+      "text": "Hello and welcome to the old-time movie show."
+    },
+    {
+      "start": 19.04,
+      "end": 25.44,
+      "text": "Today we are featuring the 1963 comedy mystery film Charade."
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `language` | String | 偵測語言代碼 (ISO 639-1) |
+| `language_probability` | Float | 語言偵測機率 (0-1) |
+| `segments` | Array | 語音分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].text` | String | 識別文字 |
+
+---
+
+### 3.3 ASRx (說話者分離)
+
+**檔案**: `{uuid}.asrx.json`
+
+```json
+{
+  "language": "en",
+  "language_probability": 0.95,
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 19.04,
+      "text": "Hello and welcome to the old-time movie show.",
+      "speaker_id": "SPEAKER_00",
+      "speaker_embedding": [0.123, -0.456, ...]
+    },
+    {
+      "start": 19.04,
+      "end": 25.44,
+      "text": "Today we are featuring the 1963 comedy mystery film Charade.",
+      "speaker_id": "SPEAKER_01",
+      "speaker_embedding": [0.789, -0.123, ...]
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `language` | String | 偵測語言代碼 |
+| `language_probability` | Float | 語言偵測機率 |
+| `segments` | Array | 語音分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].text` | String | 識別文字 |
+| `segments[].speaker_id` | String | 說話者 ID |
+| `segments[].speaker_embedding` | Array | 說話者嵌入向量 (可選) |
+
+---
+
+### 3.4 OCR (文字辨識)
+
+**檔案**: `{uuid}.ocr.json`
+
+```json
+{
+  "segments": [
+    {
+      "start": 10.5,
+      "end": 12.3,
+      "text": "EXAMPLE TEXT",
+      "boxes": [
+        {
+          "x1": 100,
+          "y1": 50,
+          "x2": 400,
+          "y2": 100
+        }
+      ],
+      "confidence": 0.95
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `segments` | Array | OCR 分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].text` | String | 辨識文字 |
+| `segments[].boxes` | Array | 文字邊界框陣列 |
+| `segments[].boxes[].x1` | Integer | 左上 X 座標 |
+| `segments[].boxes[].y1` | Integer | 左上 Y 座標 |
+| `segments[].boxes[].x2` | Integer | 右下 X 座標 |
+| `segments[].boxes[].y2` | Integer | 右下 Y 座標 |
+| `segments[].confidence` | Float | 辨識信心度 |
+
+---
+
+### 3.5 YOLO (物件偵測)
+
+**檔案**: `{uuid}.yolo.json`
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 1.0,
+      "objects": [
+        {
+          "class": "person",
+          "confidence": 0.92,
+          "box": {
+            "x1": 150,
+            "y1": 200,
+            "x2": 400,
+            "y2": 800
+          }
+        },
+        {
+          "class": "car",
+          "confidence": 0.87,
+          "box": {
+            "x1": 800,
+            "y1": 400,
+            "x2": 1200,
+            "y2": 700
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `segments` | Array | 時間分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].objects` | Array | 偵測物件陣列 |
+| `segments[].objects[].class` | String | 物件類別 |
+| `segments[].objects[].confidence` | Float | 偵測信心度 |
+| `segments[].objects[].box` | Object | 邊界框 |
+
+---
+
+### 3.6 Face (人臉偵測)
+
+**檔案**: `{uuid}.face.json`
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 1.0,
+      "faces": [
+        {
+          "face_id": "face_001",
+          "box": {
+            "x1": 100,
+            "y1": 50,
+            "x2": 300,
+            "y2": 350
+          },
+          "embedding": [0.123, -0.456, ...],
+          "emotion": "happy",
+          "age": 35,
+          "gender": "female"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `segments` | Array | 時間分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].faces` | Array | 人臉陣列 |
+| `segments[].faces[].face_id` | String | 人臉 ID |
+| `segments[].faces[].box` | Object | 邊界框 |
+| `segments[].faces[].embedding` | Array | 人臉嵌入向量 |
+| `segments[].faces[].emotion` | String | 情緒分類 (可選) |
+| `segments[].faces[].age` | Integer | 年齡估計 (可選) |
+| `segments[].faces[].gender` | String | 性別估計 (可選) |
+
+---
+
+### 3.7 Pose (姿態估計)
+
+**檔案**: `{uuid}.pose.json`
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 1.0,
+      "poses": [
+        {
+          "person_id": "person_001",
+          "keypoints": {
+            "nose": {"x": 320, "y": 120, "confidence": 0.98},
+            "left_eye": {"x": 335, "y": 110, "confidence": 0.95},
+            "right_eye": {"x": 305, "y": 110, "confidence": 0.93},
+            "left_shoulder": {"x": 280, "y": 180, "confidence": 0.91},
+            "right_shoulder": {"x": 360, "y": 180, "confidence": 0.89}
+          },
+          "confidence": 0.92
+        }
+      ]
+    }
+  ]
+}
+```
+
+**欄位說明**:
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `segments` | Array | 時間分段陣列 |
+| `segments[].start` | Float | 開始時間 (秒) |
+| `segments[].end` | Float | 結束時間 (秒) |
+| `segments[].poses` | Array | 姿態陣列 |
+| `segments[].poses[].person_id` | String | 人員 ID |
+| `segments[].poses[].keypoints` | Object | 關鍵點 |
+| `segments[].poses[].keypoints.{name}` | Object | 各關鍵點 |
+| `segments[].poses[].keypoints.{name}.x` | Integer | X 座標 |
+| `segments[].poses[].keypoints.{name}.y` | Integer | Y 座標 |
+| `segments[].poses[].keypoints.{name}.confidence` | Float | 信心度 |
+| `segments[].poses[].confidence` | Float | 整體信心度 |
+
+---
+
+## 4. 處理流程
+
+### 4.1 處理管線
+
+```
+影片檔案
+    │
+    ▼
+┌─────────────────┐
+│  1. Register    │  建立 UUID，註冊影片
+└────────┬────────┘
+         │
+    ┌────▼────┐
+    │ 2. Probe │  ffprobe 擷取元數據
+    └────┬────┘
+         │ {uuid}.probe.json
+    ┌────▼─────┐
+    │ 3. ASR   │  faster-whisper 語音識別
+    └────┬─────┘
+         │ {uuid}.asr.json
+    ┌────▼──────┐
+    │ 4. ASRx   │  說話者分離 (pyannote)
+    └────┬──────┘
+         │ {uuid}.asrx.json
+    ┌────▼────┐
+    │ 5. OCR   │  Tesseract 文字辨識
+    └────┬────┘
+         │ {uuid}.ocr.json
+    ┌────▼────┐
+    │ 6. YOLO │  物件偵測
+    └────┬────┘
+         │ {uuid}.yolo.json
+    ┌────▼────┐
+    │ 7. Face │  人臉偵測
+    └────┬────┘
+         │ {uuid}.face.json
+    ┌────▼────┐
+    │ 8. Pose │  姿態估計
+    └────┬────┘
+         │ {uuid}.pose.json
+    ┌────▼──────┐
+    │ 9. Chunk  │  轉換為資料庫 chunks
+    └───────────┘
+```
+
+### 4.2 失敗處理
+
+| 階段 | 失敗時 | 處理 |
+|------|--------|------|
+| Probe | 無法讀取影片 | 終止流程，輸出錯誤 |
+| ASR | 無音軌 | 產生空 segments，繼續流程 |
+| OCR/YOLO/Face/Pose | 處理失敗 | 跳過該階段，記錄日誌 |
+
+---
+
+## 5. 資料庫儲存
+
+### 5.1 Chunk 結構
+
+```sql
+CREATE TABLE chunks (
+    id BIGSERIAL PRIMARY KEY,
+    uuid VARCHAR(16) NOT NULL,
+    chunk_id VARCHAR(64) NOT NULL,
+    chunk_index INTEGER NOT NULL,
+    chunk_type VARCHAR(32) NOT NULL,
+    start_time DOUBLE PRECISION NOT NULL,
+    end_time DOUBLE PRECISION NOT NULL,
+    content JSONB NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW(),
+    UNIQUE(uuid, chunk_id)
+);
+```
+
+### 5.2 轉換範例
+
+```rust
+// ASR → Chunk (Sentence)
+for (i, seg) in asr_result.segments.iter().enumerate() {
+    let chunk = Chunk::new(
+        uuid.clone(),
+        i as u32,
+        ChunkType::Sentence,
+        seg.start,
+        seg.end,
+        serde_json::json!({"text": seg.text}),
+    );
+    db.store_chunk(&chunk).await?;
+}
+```
+
+---
+
+## 6. 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-03-16 | 初始版本 |
+
+---
+
+## 7. 相關文件
+
+- [RUST_DEVELOPMENT.md](./RUST_DEVELOPMENT.md) - Rust 開發規範
+- [AGENTS.md](../AGENTS.md) - 開發規範
+- [monitor_config.yaml](../monitor/config/monitor_config.yaml) - 監控配置