---
updatedAt: 2026-04-11T17:53:17.000Z
agentTools:
  projectIndex: https://vi.developers.datature.com/llms.txt
---

# Freeform Text

Select frame sequences with the video scrubber and write freeform text annotations to train a VLM on temporal reasoning tasks.

<WorkflowStages current="prepare-your-data" />

<ViCallout type="info" title="Before You Start">
  * A [freeform text dataset](https://vi.developers.datature.com/docs/create-a-dataset) with [uploaded videos](https://vi.developers.datature.com/docs/upload-videos)
  * A plan for the text structure or schema you want to use across your dataset
</ViCallout>

Freeform text annotations for videos let you describe what happens across a sequence of frames. You use the timeline scrubber to select a frame range, then write text in any format (JSON, plain text, or custom schemas) that describes the action, event, or scene within that range. This guide walks through creating video freeform text annotations in Datature Vi.

***

## Open the annotator

Go to your dataset, then click the **Annotate** tab. Click any video thumbnail in the bottom strip to load it into the Video Annotator.

<StepCarousel
  steps={[
    {
      title: "Open the Annotator tab",
      image: "https://files.readme.io/782539b2e0aa09ee2670c1e5c7acac34c992241202141473df1ba4240911317e-Annotator-04-11-2026_02_35_AM.png",
      description: "Go to the Dataset Overview page and click the Annotator tab to open the labeling interface."
    },
    {
      title: "Select a video",
      image: "https://files.readme.io/148d30bd4578e56dde7abd34a92ba0139b1a7a2d79a93c367b1e3b10e0bc337b-Annotator-04-11-2026_02_36_AM.png",
      description: "Click a video thumbnail in the bottom strip to load it into the Video Annotator. The video player shows the current frame, and the timeline scrubber appears below."
    },
    {
      title: "Select a frame sequence",
      image: "https://files.readme.io/f0b5811c9e9d10c2c927a02c2ddbb9b9d5c2b2128dc1c6187d61507baaf15a31-Annotator-04-11-2026_02_36_AM_1.png",
      description: "Use the timeline scrubber to select the frame range you want to annotate. Drag the start and end handles to define the sequence boundaries. The colored segments on the timeline represent different annotation regions."
    },
    {
      title: "Choose the text format",
      image: "https://files.readme.io/512fe44f4a37eeaf27a184dcf3d21db7170b2335209e42cd076709b0221ed281-Annotator-04-11-2026_02_36_AM_2.png",
      description: "In the Freeform panel on the right, use the format dropdown to select your text format: JSON, Plain Text, YAML, or Markdown. The editor adapts its syntax highlighting to match."
    },
    {
      title: "Write your annotation",
      image: "https://files.readme.io/fb492b2216c189c2ef76928de780b43cd59e55c76d1dc09db2d813e28768df7a-Annotator-04-11-2026_02_36_AM_3.png",
      description: "Type your annotation text in the Freeform panel. Describe what happens in the selected frame sequence: actions, events, physics behaviors, or any details relevant to your training task."
    },
    {
      title: "Add more frame sequences",
      image: "https://files.readme.io/da47a6b14d9b624a99337cea721b6d5c58f108b16e8e234a4f503dd6d4641ca5-Annotator-04-11-2026_02_36_AM_4.png",
      description: "Drag the scrubber to select a new frame range for your next annotation. Each sequence gets its own freeform text entry. Aim for non-overlapping sequences that cover the key events in the video."
    },
    {
      title: "Move to the next video",
      image: "https://files.readme.io/cb84d1cd656378d2c8c3b785df00effddb79d980543fa5865c3641dcb114feda-Annotator-04-11-2026_02_36_AM_5.png",
      description: "Press E to advance to the next video or Q to go back. Annotations save automatically when you move between videos or make changes."
    }
  ]}
/>

<UIResultPreview variant="verify" screenshot="https://files.readme.io/2b24fe26fa2ae2bd8cd5900a826910b1fed59090a9186df5c1249c0f80efe039-Annotator-04-11-2026_02_34_AM.png" screenshotAlt="Dataset Overview showing video and annotation count" caption="Your annotations are ready when you see annotation count matching the video count in the Dataset Overview." />

***

## The timeline scrubber

The timeline scrubber is the core tool for video annotation. It displays the video's frames as a horizontal timeline below the video player.

**Frame selection:** Drag the start and end handles on the timeline to define a frame sequence. The selected range highlights in color, and the video player shows the current frame within that range.

**Playback controls:** Use the play/pause button to preview the selected sequence. The frame counter shows your position (e.g., "13 / 49") and the timestamp shows the current time within the video.

**Multiple sequences:** Each annotation occupies a distinct segment on the timeline, shown as colored blocks. You can create multiple non-overlapping sequences per video, each with its own freeform text annotation.

**Navigation:** Click anywhere on the timeline to jump to that frame. Use the previous/next frame buttons to step through frames one at a time.

***

## Keyboard shortcuts

<InfoTable title="Keyboard shortcuts" headers={['Key', 'Action']}>
  <InfoRow cells={['E', 'Next video']} />

  <InfoRow cells={['Q', 'Previous video']} />

  <InfoRow cells={['Space', 'Play/pause video']} />

  <InfoRow cells={['Esc', 'Exit current tool mode']} />

  <InfoRow cells={['?', 'Show all shortcuts']} />
</InfoTable>

***

## Annotation guidelines

These guidelines produce annotations that train well for temporal reasoning tasks.

<GuidelineGrid columns={2}>
  <GuidelineCard icon="fa-solid fa-list-check" title="Define your schema first">
    * Pick a consistent structure (JSON or plain text) before you start
    * Use the same fields and format across every video in the dataset
  </GuidelineCard>

  <GuidelineCard icon="fa-solid fa-clock" title="Describe temporal events, not static scenes">
    * Focus on actions: "The rider maintains balance" over "A person on a Segway"
    * Capture changes: "The vehicle accelerates from stationary"
    * Note cause and effect: "The speed bump causes posture adjustment"
  </GuidelineCard>

  <GuidelineCard icon="fa-solid fa-scissors" title="Choose meaningful frame boundaries">
    * Capture complete actions from start to finish
    * Avoid cutting mid-action or mixing unrelated events
    * Keep sequences focused on a single scene or activity
  </GuidelineCard>

  <GuidelineCard icon="fa-solid fa-film" title="Cover the full video">
    * Annotate all significant events; leave gaps only for static segments
    * Aim for 3-5 sequences covering the key events (2-3 minimum)
    * Dense annotation: every significant action or scene change
  </GuidelineCard>
</GuidelineGrid>

**JSON example for action recognition:**

<CodeGroup>
  ```json
  {
    "caption": "A Segway bumps over a series of small speed bumps, the rider maintaining balance with slight adjustments.",
    "action": "using segway",
    "physics_rules_followed": [
      "The Segway wheels rotate.",
      "The rider and Segway move forward.",
      "The rider's shadow length changes as the sun's angle changes."
    ],
    "physics_rules_unfollowed": [],
    "physics_rules_cannot_be_determined": [],
    "human_violated_rules": [
      "The Segway should experience a change in speed when going over speed bumps"
    ]
  }
  ```
</CodeGroup>

**Plain text example:**

<CodeGroup>
  ```text
  Caption: A Segway bumps over a series of small speed bumps
  Action: Using segway
  Physics followed: Wheels rotate, forward movement, shadow changes with sun angle
  Physics violated: None
  Human violated: No speed change over speed bumps
  ```
</CodeGroup>

***

## Edit or delete annotations

**To edit an annotation:** Click the corresponding segment on the timeline to select it, then modify the text in the Freeform panel. Changes save automatically.

**To adjust frame boundaries:** Click a segment on the timeline, then drag the start or end handle to resize it.

**To delete an annotation:** Click the segment on the timeline, then clear the text in the Freeform panel or use the delete option.

<ViCallout type="danger" title="Deletions Cannot Be Undone">
  Deleted annotations and frame sequences cannot be recovered. Export your dataset regularly as a backup.
</ViCallout>

***

## Chain-of-thought reasoning

<ViAccordion title="How to enable chain-of-thought in video freeform text annotations">
  You can include step-by-step reasoning in video freeform text annotations by prepending `<datature_think>` tags. During training, Datature Vi converts these to the model's native `<think>` tags.

  See [Chain-of-Thought Reasoning](https://vi.developers.datature.com/docs/chain-of-thought-reasoning) and [Annotation Guide](https://vi.developers.datature.com/docs/annotation-guide) for details.
</ViAccordion>

***

## Next steps

<BentoGrid className="grid grid-cols-1 md:grid-cols-2 gap-6 my-10">
  <BentoCard title="Train A Model" description="Use your video annotations to fine-tune a vision-language model." href="doc:train-a-model" faIcon="fa-solid fa-brain" />

  <BentoCard title="Dataset Overview" description="Check annotation coverage and quality across your video dataset." href="doc:dataset-overview" faIcon="fa-solid fa-chart-bar" />
</BentoGrid>