影片標註

在 Potato 中用時間片段、幀分類、關鍵幀和物件跟蹤來標註影片，並沿時間軸逐幀導航。

Potato 支援影片標註，涵蓋時間分割、幀分類、關鍵幀標記和物件跟蹤。

標註模式

你選的 mode 決定標註者產出什麼，以及介面上出現哪些控制元件，所以要按研究所需的分析單位來選。

模式	描述	使用場景
`segment`	標記時間範圍	場景檢測、說話人輪次
`frame`	分類單個幀	幀級標註
`keyframe`	標記重要時刻	高亮檢測
`tracking`	跨幀跟蹤物件	物件跟蹤
`combined`	在一個介面中使用所有模式	複雜標註任務

基本配置

最簡方案只給出標籤，其餘顯示選項全部留在預設值，這樣標註者進入的是片段時間軸，縮放、速度控制和逐幀步進都已可用：

yaml

annotation_schemes:
  - name: "video_segments"
    description: "Mark segments where the speaker changes"
    annotation_type: "video_annotation"
    labels:
      - name: "Speaker A"
        color: "#FF6B6B"
      - name: "Speaker B"
        color: "#4ECDC4"

配置選項

欄位	類型	預設值	描述
`name`	string	必填	標註的唯一識別符號
`description`	string	必填	顯示給標註者的說明
`annotation_type`	string	必填	必須為 `"video_annotation"`
`labels`	list	必填	可用的標註標籤
`mode`	string	`"segment"`	標註模式
`min_segments`	integer	0	最少所需標註數
`max_segments`	integer	null	最大允許標註數
`timeline_height`	integer	70	時間軸高度（畫素）
`overview_height`	integer	40	概覽欄高度（畫素）
`zoom_enabled`	boolean	true	啟用時間軸縮放
`playback_rate_control`	boolean	true	顯示播放速度選擇器
`frame_stepping`	boolean	true	啟用逐幀導航
`show_timecode`	boolean	true	顯示幀號和時間
`video_fps`	integer	30	用於計算的影片幀率
`source_field`	string	`""`	條目包含多個影片時，本方案所標註的顯示欄位

標籤配置

標籤可以是簡單字串，也可以是帶顏色和鍵盤快捷鍵的物件。key_value 把標籤繫結到某個按鍵，這在片段標註中最有用，因為標註者的手一直放在播放控制元件上：

yaml

labels:
  - name: "intro"
    color: "#4ECDC4"
    key_value: "1"
  - name: "content"
    color: "#3B82F6"
    key_value: "2"
  - name: "outro"
    color: "#8B5CF6"
    key_value: "3"

按模式的示例

片段模式（預設）

標記帶開始和結束時間的時間範圍。縮放和播放速度這兩個控制元件決定標註者能把邊界放得多準，所以場景類任務會把兩者都保持開啟：

yaml

annotation_schemes:
  - name: "scene_detection"
    description: "Mark each scene in the video"
    annotation_type: "video_annotation"
    mode: "segment"
    labels:
      - name: "indoor"
        color: "#3B82F6"
        key_value: "1"
      - name: "outdoor"
        color: "#22C55E"
        key_value: "2"
      - name: "transition"
        color: "#F59E0B"
        key_value: "3"
    zoom_enabled: true
    playback_rate_control: true

幀模式

對單個幀分類。逐幀步進和時間碼讀數讓標註者能停在某一幀上，並記錄下他們判斷的是哪一幀，標籤因此才可復現：

yaml

annotation_schemes:
  - name: "frame_quality"
    description: "Classify each frame's quality"
    annotation_type: "video_annotation"
    mode: "frame"
    labels:
      - name: "good"
        color: "#22C55E"
      - name: "blurry"
        color: "#F59E0B"
      - name: "occluded"
        color: "#EF4444"
    frame_stepping: true
    show_timecode: true

關鍵幀模式

標記重要時刻。關鍵幀是一個點而不是一段範圍，所以整個任務的準確度都落在逐幀步進上：

yaml

annotation_schemes:
  - name: "highlights"
    description: "Mark key moments in the video"
    annotation_type: "video_annotation"
    mode: "keyframe"
    labels:
      - name: "goal"
        color: "#22C55E"
      - name: "foul"
        color: "#EF4444"
      - name: "highlight"
        color: "#F59E0B"
    frame_stepping: true

跟蹤模式

用邊界框跨幀跟蹤物件。把 video_fps 設成你自己檔案的幀率，因為 Potato 用這個值把時間換算成幀號，數值不符會讓每個框都偏移：

yaml

annotation_schemes:
  - name: "object_tracking"
    description: "Track the ball throughout the video"
    annotation_type: "video_annotation"
    mode: "tracking"
    labels:
      - name: "ball"
        color: "#3B82F6"
      - name: "player"
        color: "#22C55E"
    frame_stepping: true
    video_fps: 30

組合模式

組合模式把片段、幀標籤、關鍵幀和跟蹤放在一個介面裡。它對標註者每段影片的要求最高，所以只在同一遍標註要產出多種結果時才用：

yaml

annotation_schemes:
  - name: "full_pass"
    description: "Full video annotation"
    annotation_type: "video_annotation"
    mode: "combined"
    labels:
      - name: "action"
        color: "#3B82F6"
      - name: "dialogue"
        color: "#22C55E"
      - name: "transition"
        color: "#F59E0B"
    zoom_enabled: true
    playback_rate_control: true
    frame_stepping: true
    show_timecode: true

影片顯示

如果只需要播放影片而不做標註（例如配合其他標註類型使用），用 video 類型。它渲染一個播放器，不收集任何資料，標註者看完片段後回答任務中其他方案提出的問題：

yaml

annotation_schemes:
  - name: "video_player"
    description: "Watch the video clip"
    annotation_type: "video"
    video_path: "{{video_url}}"
    controls: true
    autoplay: false
    loop: false
    muted: false

字幕與說明文字

如果影片帶字幕，可以標註字幕，替代影片時間軸，或者與它並用。Potato 能讀取 WebVTT、SubRip、TTML/DFXP、SubStation Alpha，以及 YouTube 的 json3 和 srv1/srv2/srv3 格式，並且是根據檔案內容而不是副檔名來識別的。

bash

yt-dlp --write-auto-subs --sub-langs en --sub-format vtt --skip-download <URL>

json

{"id": "talk_01", "conversation": {"audio": "media/talk_01.mp3",
                                   "transcript": "captions/talk_01.vtt"}}

注意： 自動生成的字幕沒有標點，也沒有說話人標籤，它的字幕塊邊界落在字幕視窗寫滿的地方，而不是句子結束的地方。不要在這種字幕上建立句子級的方案。替代做法見標註 YouTube 字幕。

完整的格式列表見文字稿格式。

鍵盤快捷鍵

Potato 根據方案生成快捷鍵列表，所以幀、片段、關鍵幀和分類相關的按鍵只會出現在用到它們的模式中。

按鍵	操作
`Space`	播放/暫停
`←` / `→`	前後跳轉 5 秒
`,` / `.`	上一幀/下一幀（`frame_stepping` 開啟時）
`[`	設定片段起點（片段模式和組合模式）
`]`	設定片段終點（片段模式和組合模式）
`Enter`	建立片段（片段模式和組合模式）
`K`	標記關鍵幀（關鍵幀模式和組合模式）
`C`	對當前幀分類（幀模式和組合模式）
`Del`	刪除選中項
`+` / `-`	放大/縮小
`0`	適應檢視

每個帶 key_value 的標籤會再加上自己的按鍵，所以在上面的示例中 1、2、3 用來選擇標籤。

資料格式

輸入資料

資料檔案中應包含影片路徑或 URL：

json

[
  {
    "id": "video_1",
    "video_url": "https://example.com/videos/sample1.mp4",
    "description": "Meeting recording - identify speakers"
  },
  {
    "id": "video_2",
    "video_url": "/data/videos/sample2.mp4",
    "description": "Activity video - label actions"
  }
]

輸出格式

輸出因模式而異：

片段模式：

json

{
  "id": "video_1",
  "annotations": {
    "scene_detection": [
      {
        "start": 0.0,
        "end": 5.2,
        "start_frame": 0,
        "end_frame": 156,
        "label": "indoor"
      }
    ]
  }
}

幀模式：

json

{
  "id": "video_1",
  "annotations": {
    "frame_quality": [
      {
        "frame": 120,
        "time": 4.0,
        "label": "good"
      }
    ]
  }
}

關鍵幀模式：

json

{
  "id": "video_1",
  "annotations": {
    "highlights": [
      {
        "frame": 450,
        "time": 15.0,
        "label": "goal",
        "note": "First goal of the match"
      }
    ]
  }
}

跟蹤模式：

json

{
  "id": "video_1",
  "annotations": {
    "object_tracking": [
      {
        "id": "track_1",
        "label": "ball",
        "frames": [
          {"frame": 0, "bbox": {"x": 100, "y": 200, "w": 30, "h": 30}},
          {"frame": 1, "bbox": {"x": 105, "y": 198, "w": 30, "h": 30}}
        ]
      }
    ]
  }
}

支援的影片格式

MP4（推薦）
WebM
MOV
OGG

影片物件跟蹤與關鍵幀插值

v2.2.0 新增

跟蹤模式會在關鍵幀之間做插值。標註者只在少數幾幀上標出物件的位置，Potato 補上中間的幀，所以跟蹤一個物件只需要幾個框，而不是每幀一個框。把 video_fps 設成原始檔的幀率，因為插值是按幀號計算的：

yaml

annotation_schemes:
  - name: "tracking"
    description: "Track objects with keyframe interpolation"
    annotation_type: "video_annotation"
    mode: "tracking"
    labels:
      - name: "person"
        color: "#3B82F6"
      - name: "vehicle"
        color: "#22C55E"
    frame_stepping: true
    video_fps: 30

工作流程

導航到某個關鍵幀，在物件周圍畫出邊界框
向前跳過若干幀，重新放置邊界框
系統自動為中間幀插值出位置
按需要檢查並調整插值出來的位置

有效標註模式的完整集合為：segment、frame、keyframe、tracking 和 combined。

技術說明

使用 Peaks.js 做時間軸視覺化
標準 HTML5 影片元素（無需額外的伺服器依賴）
時間軸支援拖動選擇來建立片段

最佳實踐

使用壓縮過的影片 - 大檔案載入慢
設定合適的幀率 - 讓 video_fps 與影片實際幀率一致
保持逐幀步進開啟 - 幀級標註依賴它
使用播放速度控制 - 慢放有助於精細的工作
給出清晰的片段定義 - 明確什麼算片段邊界
使用區分度高的顏色 - 讓標籤在視覺上容易分辨
考慮時間軸高度 - 複雜的分割任務可以調高