Tutorial5 min di lettura

Annotazione video con controlli fotogramma per fotogramma

Come impostare in Potato l'annotazione video, con navigazione fotogramma per fotogramma, marcatori temporali, etichettatura degli eventi nel tempo e classificazione per segmento con schemi radio o span.

Potato Team12 gennaio 2026

L'annotazione video è il modo in cui si costruiscono i dati di addestramento per cose come il riconoscimento di azioni, il tracciamento di oggetti e il rilevamento di eventi nel tempo. Questo tutorial copre la navigazione tra i fotogrammi, la divisione di uno spezzone lungo l'asse del tempo e i modi per tenere veloce l'etichettatura. Per il riferimento completo degli schemi video, vedi la documentazione di riferimento.

Che cosa si può fare con l'annotazione video

Potato gestisce il video sia per l'etichettatura sia per i task di classificazione:

Classificazione video: etichettare interi spezzoni
Etichettatura multipla: applicare più tag allo stesso video
Annotazione temporale: marcare gli eventi dentro il video

Configurazione video di base

yaml

annotation_task_name: "Video Action Recognition"
task_dir: "."
 
data_files:
  - "data/videos.json"
 
item_properties:
  id_key: id
  text_key: video_url
 
output_annotation_dir: "annotation_output/"
export_annotation_format: "jsonl"
 
annotation_schemes:
  - annotation_type: video_annotation
    name: action
    description: "Mark each stretch of video where one action is happening"
    mode: segment
    labels:
      - name: walking
        color: "#4ECDC4"
        key_value: "1"
      - name: running
        color: "#FF6B6B"
        key_value: "2"
      - name: jumping
        color: "#45B7D1"
        key_value: "3"
      - name: sitting
        color: "#FFEAA7"
        key_value: "4"
 
user_config:
  allow_all_users: true

Navigazione fotogramma per fotogramma

yaml

    min_segments: 1
    label_requirement:
      required: true

Annotazione di segmenti temporali

Marca gli eventi con un tempo di inizio e uno di fine:

yaml

annotation_schemes:
  - annotation_type: video_annotation
    name: frame_label
    description: "Classify the current frame"
    mode: frame
    frame_stepping: true
    show_timecode: true
    video_fps: 30
    labels:
      - name: action
        color: "#FF6B6B"
        key_value: "1"
      - name: no_action
        color: "#9CA3AF"
        key_value: "2"

Creare i segmenti

Portati all'inizio di un evento
Premi [ oppure clicca «Mark Start»
Portati alla fine dell'evento
Premi ] oppure clicca «Mark End»
Scegli l'etichetta dell'evento
Ripeti per tutti gli eventi

Marcare i momenti chiave

Puoi segnare singoli momenti dentro uno spezzone:

yaml

annotation_schemes:
  - annotation_type: video_annotation
    name: key_moments
    description: "Mark the moment each action begins, peaks, and ends"
    mode: keyframe
    labels:
      - name: action_start
        color: "#22C55E"
        key_value: "1"
      - name: action_peak
        color: "#EF4444"
        key_value: "2"
      - name: action_end
        color: "#3B82F6"
        key_value: "3"

Classificazione dell'intero video

Per etichettare un video per intero bastano i tipi di annotazione standard:

yaml

annotation_schemes:
  - annotation_type: video_annotation
    name: plays
    description: "Mark each play and describe it"
    mode: segment
    labels:
      - name: attack
        color: "#EF4444"
      - name: defense
        color: "#3B82F6"
    segment_schemes:
      - annotation_type: radio
        name: outcome
        description: "How did this play end?"
        labels: ["scored", "turnover", "out of play"]

Video con etichette di categoria

Annotare i video con etichette di categoria:

yaml

annotation_schemes:
  - annotation_type: multiselect
    name: clip_tags
    description: "Tags that apply to this clip as a whole"
    labels:
      - Highlight worthy
      - Good camera angle
      - Multiple players
      - Close-up
      - Wide shot
      - Slow motion available

Una configurazione completa

yaml

annotation_task_name: "Sports Video Analysis"
task_dir: "."
 
data_files:
  - "data/sports_clips.json"
 
item_properties:
  id_key: id
  text_key: video_url
 
output_annotation_dir: "annotations/"
export_annotation_format: "jsonl"
 
annotation_instructions: |
  ## Event marking
 
  - Mark an event from the frame it **starts**, not from the frame it becomes obvious.
  - Include the full play sequence in the segment.
  - For a goal, run the segment from the shot to the ball crossing the line.
 
  ## Navigation
 
  - `Space` plays and pauses, `,` and `.` step one frame.
  - `[` and `]` set the segment boundaries, `Enter` creates the segment.
 
annotation_schemes:
  - annotation_type: video_annotation
    name: game_events
    description: "Mark every game event and its duration"
    mode: segment
    frame_stepping: true
    show_timecode: true
    playback_rate_control: true
    video_fps: 30
    min_segments: 1
    label_requirement:
      required: true
    labels:
      - name: goal
        color: "#22C55E"
        key_value: "1"
      - name: foul
        color: "#EF4444"
        key_value: "2"
      - name: corner_kick
        color: "#3B82F6"
        key_value: "3"
      - name: free_kick
        color: "#F59E0B"
        key_value: "4"
      - name: penalty
        color: "#EC4899"
        key_value: "5"
      - name: offside
        color: "#8B5CF6"
        key_value: "6"
 
  - annotation_type: multiselect
    name: clip_tags
    description: "Tags that apply to this clip as a whole"
    labels:
      - Highlight worthy
      - Good camera angle
      - Multiple players
      - Close-up
      - Wide shot
      - Slow motion available
 
user_config:
  allow_all_users: true

Formato di output

json

{
    "video_metadata": {
        "duration": 120.5,
        "fps": 30,
        "width": 1920,
        "height": 1080
    },
    "segments": [
        {
            "id": "segment_1",
            "start_time": 0.0,
            "end_time": 10.5,
            "start_frame": 0,
            "end_frame": 315,
            "label": "goal"
        }
    ],
    "frame_annotations": {
        "450": {
            "frame": 450,
            "time": 15.0,
            "label": "scene_change"
        }
    },
    "keyframes": [
        {
            "id": "kf_1",
            "frame": 900,
            "time": 30.0,
            "label": "important_moment",
            "note": "Key dialogue"
        }
    ],
    "tracking": {}
}

Consigli per l'annotazione video

Prima passata d'insieme: guarda tutto a velocità normale
Rallentatore per la precisione: usa 0.25x per i tempi esatti
Scorciatoie da tastiera: molto più rapide del mouse
Fai delle pause: annotare video stanca gli occhi
Criteri coerenti: metti per iscritto i casi limite

Prossimi passi

Scopri il confronto tra immagini per valutare la qualità video
Configura il crowdsourcing per annotare video su larga scala

Documentazione completa su Annotazione di Immagini, sezione video.