Configuration

Configuration defines the labeling schema and the experience each role gets — what users can see, do, and capture. A well-designed configuration is the single most impactful step before annotation begins.

Access Control

Access Control is a set of per-feature allow-lists. Each control gates a separate capability:

• Upload Files (Roles) — which roles can use the in-editor upload button to add new audio / video files.
• Download Annotations (Roles) — which roles see the Download button.
• Annotation Isolation — Off or By User. When set to By User, each user only sees their own annotations. Bypass Isolation (Roles) and Bypass Isolation (Statuses) independently let reviewers see everyone's work. See Annotation Isolation.

Role and status pickers share the same behaviour: Select all stores All Roles or All Statuses, including roles or statuses added later; a partial selection stores only the checked IDs; No Roles or No Statuses grants no bypass. Upload and download default to admin-only. Isolation bypass defaults to no roles and no statuses when isolation is enabled.

Feature Control

Feature Control toggles editor capabilities. Turning a feature off hides every affordance for it across the editor.

• Object Comments (Off / On) — enables comments on annotations. When on, two sub-controls appear: which roles can resolve and which can delete comments.
• Instance Relationships (Off / On) — enables relationships between annotations. When on, a Relationship Types editor appears so admins can curate the relationship taxonomy. Relationship type names must be unique (case-insensitive); duplicate or empty names are silently reverted on blur.
• Annotation Panel — controls which views of the annotation panel are available: Instance + Table, Instance only, Table only, or None. The adjacent Configure Annotation Panel button becomes active whenever the panel is enabled (any mode other than None); the Table Column Settings button further activates when the table view is specifically reachable (Instance + Table or Table only).
• Default Split View (Off / Split View 2 / 3) — for items with more than one media file, opens the editor directly in catalog split view instead of the single viewport. If the item has fewer media files than the configured column count, the largest fitting split is used. Single-file items always open normally. Best suited to comparison workflows where every item has the same small media-file count.
• Fullscreen on First Interaction (Off / On) — the first pointer interaction inside the editor requests fullscreen (browsers cannot enter fullscreen without a user gesture). Applies once per editor mount; annotators can exit with Esc or the toolbar button and are not forced again until the next item load. A brief informational notice confirms when fullscreen was triggered by this setting.

Annotation Sub-Settings

The following editor toggles are always available:

• Recording — when on, the Record Audio button appears in the player controls so users can capture fresh audio in-browser.
• Overlapping Segments — when on, segments may overlap on the same waveform. When off, draws/resizes that would create an overlap are blocked.
• Segment Loops — when on, currently selected segments will replay during playback. In the editor, press R to toggle selected-segment looping for the current session. Useful for tight in-/out-point review.
• Restrict Segment Length — when on, exposes Min and Max length fields (seconds). New / resized segments outside the range are clamped or rejected.
• Transcript — when on, the transcript panel can be opened. The first time a user opens it on an item with no transcript yet, auto-transcription runs (when an AI proxy is configured).
• Editable Transcript — when on, segment text can be edited inline in the transcript panel and the table view; off makes the transcript read-only.

Media Loading

Sets how each media file starts when an item opens:

• Download First (default) — the whole file downloads (with a progress bar) before playback. Seeking is reliable and the waveform is ready up front.
• Stream First — playback starts as soon as the file streams from its source; the waveform renders once its peaks are ready.

Each file adapts to its host automatically. A Download First file whose host blocks cross-origin downloads (CORS) falls back to streaming; a Stream First file whose host doesn't support range requests falls back to a full download (needed for reliable seeking). When a file's actual behavior differs from the configured mode, a toast appears — stacking if several files fall back, and shown no matter which file or view you're on — and a persistent yellow warning icon marks that file: to the left of its card title in Split View, and to the left of the mute button in single view. Hover the icon for a tooltip explaining why the file fell back.

Annotation Panel Settings

Click Configure Annotation Panel… to set the project-wide defaults that apply when an editor is first opened. Each control commits live — Done simply closes the modal and Restore to Default clears every setting in this modal back to the built-in baseline. Editors can still resize, regroup, or reorder per-session from the panel header; this modal only controls what they start with.

• Default panel width. Optional percentage (between 20% and 75% of the editor's container width) used as the starting width of the annotation panel. Out-of-range values snap to the closest valid percentage; leave the field blank to fall back to the built-in default of 480 px. Once an annotator drags the resize handle in the editor, their per-session width takes over until they reload.
• Default Group By. Initial grouping mode for the panel (Media Name, Class Name, Tool Type, or any project property). Property options are gathered from every regular and tag class. If the chosen property has 100 or more distinct values across the open item, the editor falls back to Media Name grouping for that session — the configured selection re-engages automatically once the dataset shrinks below 100.
• Default Order By. Initial ordering of instances (JSON Export, Class Name, Tool Type, Start Time, Created By, Creator Role, Created At, or any project property). Drag-to-reorder in the panel only writes to the JSON-export order, so it is only available when Group By is set to Media Name and Order By is set to JSON Export — either as project default or at the per-session level.

Reset chevron in the editor. Each Group By / Order By dropdown in the editor has a small reset arrow next to its title to revert to config-selected defaults.

Table Column Settings

Click Configure columns & groups… to open a two-panel modal that controls the Table View columns for the whole project.

Left panel — Columns. Lists every column currently available (excluding role-hidden ones). Drag rows to reorder; uncheck Show to hide a column by default. Click the pin icon to keep a column glued to the leading edge while editors scroll the table horizontally. Changes are saved immediately — Done simply closes the modal. Restore to Default clears all column and group overrides.

Pinned columns. A pinned column sticks to the leading edge of the Table View when editors scroll horizontally; pinned columns always render before unpinned ones in both the editor's Columns dropdown and the table itself, preserving their relative order within each cluster. Drag-reordering inside the modal is also restricted to within a cluster — drop a row across the pinned/unpinned boundary and it snaps back. Pinning is independent of Show: a pinned-but-hidden column is dormant (its pin icon dims at 55% opacity) and reactivates the next time the column is shown. Pinning two or more columns can leave little room for unpinned columns on narrow annotation panels — a heads-up note appears when this happens.

Right panel — Column Groups. Groups let you bundle related columns so editors can show or hide them all at once with a single toggle chip in the Table View. Click + Add Group to create a group, give it a short label, and pick columns from the dropdown. Group labels must be unique (case-insensitive); duplicate or empty labels are silently reverted. Each column can belong to at most one group. Columns assigned to a group have their individual Show checkbox controlled by the group's visibility toggle. Empty groups (no columns selected) are automatically removed when the modal closes.

• Per-session user adjustments. Annotators keep their existing per-session control via the Columns dropdown and the column group chips — their adjustments don't persist across reloads; the project default does.
• New columns appear at the end, visible. Adding a new property or relationship type after configuring defaults appends it visible. Reopen the modal to reposition or hide it.
• Stale entries keep their position. Removing a column source (e.g. toggling Comments off) doesn't drop its stored position — it returns to the same spot if re-enabled later.

Classes & Tags

Classes and tags together form the structured vocabulary of your project. Classes describe what individual annotations are; tags describe what the media file or whole item is about.

Classes

A class is what a user assigns to a new annotation. Each class has:

• Name — the label shown in the class picker and the annotation panel.
• Color — the highlight / fill colour used for that class's regions, boxes, or transcript spans.
• Tool Type — one of Segment, Box, or Entity. Picking a class auto-selects the matching tool in the editor toolbar.
• Properties — the structured fields captured on each annotation of this class (see Properties below).

The three tool types and what they produce:

Class names must be unique (case-insensitive); duplicate or empty names are silently reverted on blur. The first nine classes (in the order they appear in the configuration list) become number-key shortcuts (1–9) in the editor — arrange your most-used classes first.

Classes also accept per-role visibility:

• Hide From Roles — listed roles see no annotations or controls for this class.
• View Only Roles — listed roles see existing annotations of this class but cannot create new ones; the class shows a small lock icon in the dropdown.

Tags

Tags capture structured attributes that describe something broader than a single annotation. There are two scopes per tag class:

• Item-level tags — apply to the whole item regardless of how many media files it contains. Think topic, language, dataset partition, or any coarse attribute about the entire item. Shown at the top of the annotation panel independently of the active file.
• Media-level tags — apply to a specific media file within the item. In multi-file items, each file can have its own media-level tags (e.g. per-file quality, language, domain, speaker). Shown under Media tags sub-headers in the annotation panel.

Tag scope is configured per tag class in the admin settings. Tags are ideal for:

• Routing items through triage (e.g. "English", "Needs-Review", "Music-only").
• Capturing ground-truth for whole-clip classification training.
• Filtering and grouping in dashboards downstream.
• Per-file quality or metadata signals (media-level scope).

Tag names must be unique (case-insensitive); duplicate or empty names are silently reverted on blur.

Properties

Raw segments and boxes only tell a model where something is. Properties attach structured metadata — text, options, numbers, AI-generated content — to each annotation, turning bare regions into rich training samples. Property names must be unique within their class or tag (case-insensitive); duplicate or empty names are silently reverted on blur. There are seven property types:

Common property options:

• Required — flags the annotation as incomplete until filled.
• Text Display (Free Text and AI Text) — a three-way toggle that sets how the field is presented; the three modes are mutually exclusive:
  • Inline (default) — a compact resizable textarea shown directly in the popover / table cell. Best for short values.
  • Modal — opens a roomy plain-text modal that stores the value exactly as typed (no formatting, no conversion). Best for long or structured plain text — e.g. raw HTML, JSON, or multi-line snippets you need preserved verbatim.
  • Rich Text — opens a rich-text modal with inline formatting, useful for longer values like detailed descriptions or multi-paragraph captions.
• Enable Editing (AI Text and AI Select) — controls whether the AI output is editable at extraction time. For AI Text, when off, the model auto-extracts using the predefined prompt as-is; when on, annotators can tweak the prompt before triggering extraction. For AI Select, when off, the model's chosen option is applied directly; when on, annotators can review and override the AI's selection.
• AI Text / AI Select: Default Prompt — the system prompt the model receives when extraction runs. Annotators with prompt editing enabled can also override it per-run from the Edit prompt flow.
• AI Text / AI Select: Proxy / Model override — optional per-property routing. By default each AI property inherits the project-wide AI Property Proxy and model. In the property card, use the Proxy/Model override row to send this property only through a different proxy and/or model tier. Overrides are included when you copy a property to other classes. See Per-property proxy & model routing.
• Default value (Select only) — a starting option auto-populated on each new annotation.
• Hide From Roles / View-Only Roles — restrict who sees and edits this property.
• Info — optional helper text shown next to the field for annotator guidance.

Per-property proxy & model routing

Every AI Text and AI Select property can optionally override the project defaults set under AI Proxy. In the property modal, below the Default System Prompt, the Proxy/Model override row exposes two dropdowns:

• Proxy — starts at Default (project AI proxy / model). Pick any team proxy whose domain routes to OpenAI, Gemini, or Anthropic to override the project selection for this property only.
• Model — enabled once a non-default proxy is chosen. Lists the same three tiers as the project-level model picker for that provider (cheapest → most capable). Changing the override proxy resets the model to that provider's default middle tier.

At extraction time the editor routes each property through its resolved proxy + model. Properties sharing the same route are batched into one API call; properties with different overrides (or a mix of overrides and project defaults) run as separate batches in sequence. A property with an override can still extract when the project default is unset — but any property without an override still requires the project AI Property Proxy to be configured. The Ask AI documentation assistant always uses the project AI Property Proxy / model; it does not read per-property overrides.

Property Visibility Rules

A property visibility rule controls whether an entire property is visible and editable on a given annotation or tag, based on the value of one or more sibling Select / AI Select properties. Use this when a whole field only makes sense in a specific context — e.g. only show "Background Noise Type" when "Has Background Noise" is "Yes", or only show "Music Genre" when "Sound Category" is "Music". This is the property-scope equivalent of option visibility rules: option rules hide individual options inside a Select; property rules hide the whole property.

Property visibility rules can be set on any property type (not just Select / AI Select). A Free Text, Numeric, Rating, AI Text, AI Select, Select, or Approval property can all be gated by a rule. The controller must still be a sibling Select-like property in the same class or tag class.

Setting Up a Rule

1. Open the property modal for a class or tag class.
2. In the property card's right-hand header, click the chain icon next to the copy / delete buttons. The icon is only enabled when the class has at least one sibling Select-like property to use as a controller.
3. An inline rule editor expands below the property card — same shape as the option-rule editor: choose All conditions match (AND) or Any condition matches (OR), then add one or more conditions picking a controller property and which value(s) it must hold.
4. Click the chain icon again (or the editor's × / Remove rule button) to collapse / clear the rule.

The chain icon switches to a bolder blue tint when a rule is active, so you can spot rule-bearing properties at a glance in the property list. Hovering the icon shows a tooltip naming the controlling property and required value(s).

Behavior in the Editor

• Greyed-out field — when the rule is unsatisfied, the property still appears in the popover and table column (so annotators can see the field exists), but it's rendered dimmed with a not-allowed cursor. Hovering anywhere over the disabled field shows a tooltip explaining what controls it (e.g. "Controlled by: Sound Category = Music").
• Stored value cleared — the moment a rule becomes unsatisfied (e.g. the user changes a controller value), any value stored on that property is automatically cleared. The clear cascades: if A controls B, and B itself controls C, changing A clears both B and C in one step.
• Required validation suppressed — an inaccessible property is not counted as "missing required" even when marked Required. The red required indicator on the annotation / tag row only reactivates when the rule becomes satisfied and the field becomes editable again.
• AI extraction skipped — for AI Text / AI Select properties, the row-level Extract / Edit prompt controls, the per-property icons in the property popover, and the per-cell extract icons in the table skip any AI property whose rule is unsatisfied. The buttons appear / disappear immediately as the controller value changes, no popover reopen needed.
• Modal / Rich Text properties — a property gated by an unsatisfied rule renders as a plain "—" placeholder; its modal (plain-text or rich-text) cannot be opened.
• Default values disabled — when a Select property has a property visibility rule, the per-option "Default" checkboxes in the configuration screen are disabled. Defaults wouldn't make sense for a property that may not even be visible on instance creation; the configuration UI prevents the contradiction up-front.

For details on how property visibility rules interact with option visibility rules on the same property, see Property & Option Visibility Rules in the editor section.

Copying properties between classes

Most projects end up with the same property defined on several classes — a Confidence Numeric on a handful, a Speaker Free Text shared between two or three, a Quality Single Select on every class. Recreating each one by hand is tedious and error-prone. Every property row in the Properties modal has a small copy icon next to the remove (×) button that opens a picker for replicating that property across other classes and tags in one step.

The picker lists every class and tag in the project. Each row carries a state badge that tells you what will happen if you select it:

The footer shows a running summary ("3 to add · 1 to overwrite · 2 already identical") and the Copy button only enables once at least one row is in the to-add / to-overwrite / to-duplicate set.

A few details worth knowing:

• Copies are independent. Each paste mints a fresh property ID — there's no hidden link back to the source. Editing the original later does not propagate to the copies, and vice versa. Think of this as a faster "create the same property again" rather than a shared definition. The editor's table view and panel still aggregate properties across classes by name, so a Confidence column will show every class's annotation regardless of which class the property was originally created on.
• Visibility rules are remapped where possible. If the source property carries any option visibility rules or a property visibility rule, the copy tool tries to remap each rule's controller references against the target class's properties: it looks for a sibling property with the same name (case-insensitive) and whose option list contains every value the rule references. When all of a rule's conditions can be remapped this way, the rule carries through fully into the target. When even one condition cannot be remapped (controller absent, or its option list is missing required values), the entire rule is dropped on that target — partial remapping is refused because keeping a "best-effort" subset of an "all conditions match" rule would silently weaken it.
• Quiet on success — warns on drops. The copy modal stays silent when every rule carries through cleanly and only surfaces a per-target warning when one or more rules will actually be dropped, so you can spot the targets where shape divergence matters before confirming.
• Role visibility — the Copy role visibility (Hide From / View Only) checkbox at the top of the modal controls whether the source property's role rules travel with the copy. Turn it off when target classes have their own role-restriction conventions you don't want to overwrite. On the Overwrite property path, the target's existing role visibility is preserved when this option is off.
• AI Text / AI Select on tag classes — AI Text and AI Select properties are not supported on tag classes (item or media scope). When copying an AI Text property into a tag class, it is automatically downgraded to Free Text; when copying an AI Select property, it is downgraded to plain Select. In both cases the default prompt and "Enable Editing" setting are dropped, and the picker row flags this with a small note.
• Overwrite is destructive on the target's definition. Annotators' stored values for the property remain wired to the same row (the property's ID is preserved), but the type, options, and other settings switch to the source's. If a stored value no longer matches the new shape (e.g. an option that was removed from a Single Select), the destructive-warnings banner in the Properties modal will flag it at publish time.

Option Visibility Rules

When a class or tag has multiple Select properties, you can create dependencies between them. An option visibility rule makes one property's options conditionally visible based on what is selected in another property of the same class/tag. This lets you build hierarchical relationships — for example only showing relevant subcategory options when a particular category is selected.

Option visibility rules apply to Select and AI Select properties alike. An AI Select property can be a controller or a dependent in a rule chain — the AI pre-selection respects the same filtering, and cascade clearing applies to AI-chosen values exactly as it does to manual ones.

When to Use

• Category → Subcategory — A "Sound Category" property has 5 options (Speech, Music, SFX, Ambient, Silence); a "Subcategory" property has 20 options. Instead of showing all 20 regardless, you configure each subcategory option to only appear when its parent category is selected.
• Conditional attributes — A "Speaker Gender" dropdown controls which "Voice Type" options are relevant.
• Multi-level filtering — Rules can reference multiple controller properties and combine with AND/OR logic for complex taxonomies.

Key Concepts

Setting Up a Rule (Configuration Screen)

1. Open the property modal for a class or tag class.
2. On any Select property that has at least one sibling Select property, each option row shows a chain icon (⛓).
3. Click the chain icon on the option you want to make conditional. The inline Visibility Rule Editor expands below that option.
4. Click + Add condition. Choose the controller property from the dropdown, then select which of the controller's option values must be active for this option to be visible.
5. For multi-condition rules, choose All (AND) or Any (OR) at the top to control how conditions combine.
6. When done, click the collapse arrow or click the chain icon again to close the editor.

Rule Logic

• Single-select controller — The condition passes if the controller's stored value is any one of the listed values (implicit OR across the selected values in the rule picker).
• Multi-select controller — You choose any (at least one of the listed values is selected) or all (every listed value must be selected).
• Multiple conditions — Combined with a top-level All (every condition must pass) or Any (at least one must pass).
• Empty controller — An empty/blank controller value always counts as "unsatisfied" — the dependent option stays hidden.

Behavior in the Editor

Once rules are published, annotators see them enforced immediately in both the property popover and the table view:

• Option filtering — The dependent property's dropdown only shows options whose rule is currently satisfied by the controller's value on that same row (annotation or tag).
• Cascade clearing — If the annotator changes the controller value and a previously-selected dependent option is no longer valid, it is automatically cleared. This cascades: if A controls B and B controls C, changing A can clear both B and C in one step.
• Controller indicator — Dependent properties show a small chain icon on their label with a tooltip listing which properties control their options (e.g. "Options here are filtered by: Category, Speaker Gender").
• Config-triggered cleanup — If an admin changes rules after annotations already exist, the next time an annotator opens an item, any stored values that violate the new rules are cleaned in memory. The cleanup persists on the annotator's next save.

Interaction with Default Values

Default values and visibility rules are mutually exclusive on the same option. An option marked as Default cannot have a visibility rule, and vice versa. The configuration UI enforces this:

• If "Default" is checked on an option, the chain icon is disabled (tooltip explains why).
• If a visibility rule exists on an option, the Default checkbox is disabled.

This prevents the scenario where a default value would be immediately cascade-cleared on instance creation because its rule isn't satisfied.

Cross-Property Copy

When copying a property that has visibility rules to another class, the copy tool attempts to remap each rule's controller references against the target class's properties. For a rule to carry through, every controller referenced by its conditions must exist in the target by name (case-insensitive) and the target controller's option list must contain every value the rule references. If even one condition can't be remapped, the entire rule is dropped on that target — partial remapping is refused because silently dropping conditions from an "all conditions match" rule would weaken its logic (e.g. A AND B collapsing to just A).

The copy modal stays quiet when every rule carries through cleanly, and surfaces a per-target warning only on targets where one or more rules will be dropped. The same name + shape check applies whether the rule is a per-option rule on this property or a property-level visibility rule. See Copying properties between classes for the full copy flow.

Broken References

If a controller property is deleted or its type is changed away from Select while a dependent still references it, the condition is shown with a red border and alert icon in the configuration screen. The broken condition is preserved during the config session so admins can see what happened. On publish, broken conditions are automatically stripped.

AI Proxy

AI features communicate with external providers through SuperAnnotate Proxies. Proxies act as secure intermediaries: your team's API keys live in SuperAnnotate, never in the browser. The tool separates proxy configuration into two routes:

• Transcription Proxy — powers automatic segment transcription and full-media transcription for media-level tag AI extraction. Supports OpenAI and Gemini proxies.
• AI Property Proxy — powers AI Text / AI Select extraction on annotations and media-level tags, plus the documentation Ask AI assistant. Supports OpenAI, Gemini, and Anthropic proxies.

Why proxies?

• Security — API keys stay server-side. Annotators never see or handle raw keys.
• Central management — Team admins create and rotate proxies in one place; all projects inherit the change.
• Audit & control — Proxy usage is logged per team, making cost tracking and rate limiting easy.

Provider & model

The provider is auto-detected from each proxy's allowed domain. Each route has its own model dropdown and saved selection:

Changing a proxy to a different provider resets that route's model to the provider's default middle tier. Anthropic is available for AI property extraction and Ask AI, but not for transcription because Claude has no first-party speech-to-text endpoint.

Step 1 — Create a proxy in SuperAnnotate

1. Open SuperAnnotate → Team Settings → Security → Proxies.
2. Click Create Proxy. Give it a descriptive name (e.g. "OpenAI Transcription Proxy" or "Anthropic AI Property Proxy").
3. Set Allowed domain to a supported provider domain — this is what determines where the proxy can be used in this tool.
4. Under Secrets, add a header:

   Provider	Allowed domain	Header key	Header value
   OpenAI	https://api.openai.com	authorization	Bearer sk-proj-…
   Gemini	https://generativelanguage.googleapis.com	x-goog-api-key	AIza…
   Anthropic	https://api.anthropic.com	x-api-key	sk-ant-…

5. Save each proxy and note its name — you'll select the transcription and AI-property routes separately in the next step.

Step 2 — Select the proxy in configuration

In the configuration screen's AI Proxy Settings card, configure the two proxy rows independently:

• Transcription Proxy — choose an OpenAI or Gemini proxy, then select the transcription model. OpenAI exposes whisper-1; Gemini offers the Gemini transcription tiers.
• AI Property Proxy — choose an OpenAI, Gemini, or Anthropic proxy, then select the chat model used for AI properties and Ask AI.

Each dropdown is populated from compatible team proxies only, based on the allowed domain. A provider badge appears once a proxy is selected. The currently available models are:

The two routes can use different providers and models. For example, a project can transcribe with OpenAI Whisper and extract AI properties with Anthropic or Gemini. Annotators in the editor are not affected by the route split and do not see which model is active, except when a property has its own proxy/model override.

Bulk annotation panel extraction toggle

Below the AI Property Proxy card, the checkbox Allow Bulk Extraction of all AI Properties controls whether annotators see the panel-header bulk extract control in the editor (see Bulk annotation panel extraction). It is off by default — enable it when you want annotators to run AI extraction across every visible row in the annotation panel in one action. The toggle does not change single-property, row-level, or table-cell extract controls; it only exposes the all-rows shortcut. Works in both Instance View and Table View. Requires an AI Property Proxy to be configured (or at least one AI property with a per-property override and runnable empty values).

Troubleshooting

• "No team available" — the component could not detect your team. Make sure it's loaded inside the SuperAnnotate platform.
• "Failed to load proxies" — network error fetching the proxy list. Refresh and retry.
• "No AI proxy configured" at runtime — return to configuration and pick a proxy.
• "Media is too large for Gemini transcription" — Gemini's inline-data path has a ~12 MB ceiling per request. Use shorter clips or switch to an OpenAI proxy.
• Errors from the model itself — verify the API key on your provider's side (OpenAI, Gemini, or Anthropic dashboard) — valid, not revoked, with remaining quota / billing in good standing.

See API & Media Limits for guidance when running auto-transcription or autofill across large datasets.

Tool Availability by Media Type

The active media type determines which tool types are available in the editor:

Box (bbox) classes only surface on video items. If a project defines box classes, a note appears under the class list in configuration reminding admins that those classes are only available on video items. In the editor, the Box tool is hidden from the tool selector for audio items, and pressing its keyboard shortcut shows an informational toast ("The Box tool is only available on video items."). In Split View the Box tool is also unavailable, since there is no single active video frame to draw on.

Project Instructions

Project Instructions are PDF guidance documents attached per role. Each role can have its own PDF, so annotators and QAs see the instructions relevant to their job. Admins can see and manage all instruction files.

• Upload one PDF per role — annotation conventions, edge cases, audio-quality examples, video-frame guidance, etc.
• Change any time — users pick up the new file on next load.
• The PDF is opened from the editor toolbar's Instructions button (when configured for the user's role).

Item Context

Item Context adds an optional strip of rich-text slots above the editor canvas. Use it for per-item system prompts, task-specific notes, or short instructions that arrive with the item or are written by annotators in the editor. Slot content supports the same rich text formatting as rich-text properties (bold, italic, headings, lists, blockquotes, code, links, and tables). Off by default; toggle it on from the Item Context card and click Configure slots… to manage the slot list.

• 1–10 slots per project — each one becomes a tab in the editor's Item Context section. Add slots with the + Add slot button; drag the handle to reorder; click the × to delete.
• Stable internal id — every slot gets an opaque id (e.g. ctx-abc123) at creation. Renaming or reordering a slot in config never moves stored item data; values stay attached to the same id forever. The id is also exposed in name2id.json so JSONL authors can address slots by name on upload.
• Unique slot names — names must be unique per project (case-insensitive), same rule as classes and tags.
• Per-role visibility — each slot has independent Hide From and View Only role pickers (same widget as class and tag visibility). Defaults for new slots are Hide From: No Roles and View Only: All Roles — i.e. visible read-only to everyone until admin opts a role into editing. If a role is on both lists, Hide From wins.
• Default section height — admin sets the initial height of the strip in the editor (100–500 px, default 200 px). Annotators can drag-resize it for their session, but resized values are not persisted — every reload starts at the admin default.
• Disabling is non-destructive — toggling Item Context off keeps the configured slots and any per-item values on disk; turning it back on later restores everything as it was.
• Deleting a slot leaves prior values on disk as orphans — they no longer appear in the editor but ride through subsequent saves and downloads. Adding a new slot later generates a fresh id; orphan values do not reattach automatically.
• Minimum one slot when enabled — the last slot can't be deleted while the feature is on. Disable Item Context to clear the strip entirely.

Import / Export

The whole configuration — classes (with tool types), tags, properties, access control, feature toggles, audio sub-settings, AI proxy selection, relationships — can be exported as a single JSON file and re-imported into another project.

• Export config — downloads a JSON file with the full schema. Version-control it alongside your project code for reproducibility.
• Import config — reads a previously exported config JSON and replaces the current configuration. A confirmation prompt is shown first.
• Use this to clone a proven configuration across projects, back up before a risky change, or share a template with another team.

The header also includes a Download name2id.json button that exports the name-to-ID mapping file directly from the config screen. This is the same name2id.json included in annotation ZIP downloads, but available here so admins can obtain it without creating items or entering the editor — useful when preparing JSONL imports or integrating with external pipelines.

Editor

The editor is where the actual work happens — uploading media, drawing segments and boxes, transcribing, filling properties, reviewing. The layout puts the media front-and-centre and surfaces the right controls for the task at hand.

Editor Layout

Three regions, each with a purpose:

• Top toolbar — tool / class selectors, upload, download, instructions, split-view toggle, shortcuts, documentation, theme, video adjustments, fullscreen, undo / redo.
• Center media area — the audio waveform and / or the video player. Below them sits a row of playback controls; above them, a tab strip on multi-file items. An optional transcript panel docks at the bottom.
• Right annotation panel — the list of segments, boxes, entities, and tags, with grouping, ordering, filtering, and quick access to properties, comments, and relationships. Can be collapsed.

Layout Conveniences

The top toolbar exposes three layout helpers:

• Fullscreen (F) — maximises the tool area within its host page to reduce visual clutter.
• Fit video to view (Shift+F) — when the video viewport is zoomed, reset it back to the fitted view.
• Dark mode toggle — flips the UI to a dark palette. The same preference is applied to this documentation popup.

Media Sources

Media reaches the editor through one of two paths:

• Uploaded — the user drops audio / video files onto the upload zone, into the Upload modal, or records audio in-browser. The bytes live in SuperAnnotate storage; the editor references them via a uniqueName.
• URL-linked — the JSONL payload contains a url with a urlKind (public, presigned, or integration). The editor signs / fetches the URL on load. See URL-linked media.

Both kinds are equally annotatable. The difference is only where the bytes come from — the editor doesn't gate any feature on the source.

The player shows a live progress indicator while a file loads, and reuses in-flight loads and session-cached media / URLs / peaks — so switching tabs or entering Split View never restarts the same download. Whether a file downloads fully before playing or streams first (and how it falls back per host) is governed by the Media Loading setting.

In-Editor Upload

When the user's role is on the Upload Files allow-list, the Upload button on the top toolbar opens the upload modal. The modal lets you drag or browse for files and shows an "X of 10 files used" indicator (the per-item cap is 10 media files).

Accepted MIME types:

• Audio — MP3, WAV, OGG, FLAC, AAC, WebM, MP4 audio.
• Video — MP4, WebM, OGG, MOV (QuickTime).

The empty drop zone shown when an item has no media yet supports drag-and-drop directly onto the canvas in addition to the modal. Uploads that exceed the 10-file cap are rejected with a banner.

Recording

When Recording is on in configuration and the user can upload, the Record Audio button in the playback controls captures fresh audio in the browser:

• Press to start recording — a small red overlay appears on the waveform with REC, a pause / resume control, and a Finish button.
• The recorded blob is uploaded as a new media file in the item (subject to the 10-file cap).
• The newly-added file becomes the active tab automatically.

Multi-File Items

A single item can contain up to 10 audio / video files. Each file has its own annotations, transcript, and media-scoped tags.

Tab Navigation

When an item has more than one media file, a tab strip appears above the player. Click any tab to switch the active file. The active file's media fills the player, its annotations populate the panel, and its transcript loads into the transcript panel.

• Adding files — use the Upload button or drop new files into the item.
• Per-file state — annotations, transcript, and media-scoped tags are stored per file. Item-scoped tags apply to the whole item regardless of which tab is active.
• Background loading — other file tabs can continue resolving URLs, downloading media, and preparing waveform peaks in the background. Once cached, returning to that tab is much faster.

Panel & Annotations

The annotation panel aggregates annotations across all files in the item. Annotations from every file are shown regardless of which tab is active. Clicking an annotation from another file switches the active tab to that file and scrolls / seeks to it. The panel groups media-scoped tags under file sub-headers (Media tags), while item-level tags appear at the top independently.

Item Context

When Item Context is enabled in the project configuration, the editor renders a dedicated section at the very top of the canvas — above the multi-file tab strip and the player area — for the configured slots.

• Tab strip — one tab per visible slot, in the order set in config. The active tab uses a neutral grey accent stripe so it's clearly distinguishable from the blue file-tab strip directly below.
• Collapse / expand — a chevron button at the leading edge of the tab strip collapses the section down to just the tab row (hiding toolbar, content, and resize handle). The chevron is sticky-left and stays visible when the tab strip overflows and you scroll horizontally. When collapsed, clicking the chevron or the empty area of the strip expands the section; clicking a non-active tab expands and switches to that tab in a single action; clicking the active tab simply expands. Always starts expanded on load.
• Rich text editing — editable slots show a formatting toolbar between the tabs and content area. Available formatting: bold, italic, headings (H1/H2), bullet lists, numbered lists, blockquotes, inline code, code blocks, hyperlinks, and tables. The toolbar sits within the section's height and does not consume additional space.
• Read-only slots — slots set to View Only for the user's role render with a light grey background and no toolbar. Rich text content still renders fully formatted (headings, lists, tables, etc.) — only editing is disabled.
• Hidden slots — slots with the user's role on the Hide From list are not shown in the strip at all. If every slot is hidden for the user, the entire Item Context section disappears.
• Resize handle — drag the thin grey grip at the bottom of the section to resize it (clamped between roughly 80 px and 50 % of the editor height). The resized height is session-only; reloading the item resets to the admin's default height.
• Autosave — edits feed the same debounced auto-save pipeline as the rest of the editor; the unsaved-changes indicator picks them up like any other change.
• Source of values — slot content is either typed directly by the annotator or pre-populated when the item arrives via JSONL upload (see the payload schema).

Split View

For items with multiple media files, the Split toggle in the top toolbar lays out every file side-by-side as a grid of live, fully playable cards. Split View is built for cross-file work — comparing, tagging, and reviewing several files in parallel — without leaving the editor.

• Split 0 (default) — standard single-file editable view with tabs.
• Split 1 / 2 / 3 — renders all of the item's files as a grid that wide. Each cell is an independent mini-player with its own waveform, video frame, and controls.

The toggle only appears when the item has more than one media file. The single-pane tab strip, playback controls, and transcript panel are hidden while Split View is active — each card owns its own loading state and chrome, so slow files show progress on their own cards while ready files remain usable.

Card Anatomy

Every card in the grid contains:

• Header — file name, plus a hover-revealed "Open" pill that disambiguates exit-split affordances from the in-card playback affordances.
• Main waveform — full-width rendering from the file's cached peaks. Display only — no segment editing in Split View. Existing segments are still drawn on the waveform (read-only) so you can spot them while comparing files.
• Video frame (video files) — a live <video> element that plays inline. Box annotation overlays render on top of the frame at the card's current time.
• Control strip at the bottom — mute toggle, play / pause button, current-time / duration readout, and an interactive minimap. Click or drag on the minimap to seek; the main waveform's playhead follows.

Card sizing adapts to the media mix:

• Audio-only items use compact rows so more files fit on screen.
• Items containing any video file use taller rows for all cards so video frames stay legible (audio cards in mixed items get the same chunky row).

Click Targets & Exit Behaviour

Card surfaces are split into two zones with different effects:

• Card playback zone — the bottom control strip (play / pause, mute, time readout) and the minimap. Clicks here drive playback for that card only and stay in Split View. The hover pill is suppressed here so the interactive area is unambiguous.
• "Open in single view" zone — the header, main waveform, and video frame. Clicking here collapses to Split 0 and switches the active file to that card's file. The hover pill fades in to signal this behaviour.

When you exit by clicking a card: any other cards still playing are paused, and the file you opened resumes from wherever it was in Split View (auto-resumes if it was playing in the card).

Parallel Playback & Keyboard Focus

Multiple cards can play simultaneously — useful for A/B comparing similar takes or aligning content across files. Audio mixing is the user's responsibility (mute the cards you don't want to hear).

The global transport strip above the card grid provides controls that apply to every card at once: play / pause all, mute / unmute all, seek all by seconds, and a shared playback speed.

Keyboard shortcuts in Split View follow one of two modes:

• Focused mode (default) — shortcuts target whichever card you most recently interacted with directly (play, seek, mute, or selecting one of its annotations from the panel).
• Broadcast mode — when you interact with the global transport strip (e.g. play all, mute all), shortcuts automatically shift to apply to every card at once. Clicking any individual card returns to focused mode.

Available shortcuts in both modes:

• Space — play / pause.
• Shift+Space — play / pause even while typing in transcript or property fields.
• , / . — seek 3 s back / forward.
• < / > — seek 10 s back / forward.
• M — mute / unmute.

Tool shortcuts (S, G, B, E) and class shortcuts (1–9) are ignored in Split View — Split View is for playback and tagging only; annotation editing happens in Split 0.

Position Persistence

The current playback position of every file is preserved as you move between Split 0 and the higher split modes:

• Play a file in Split 0 to 0:30, switch to Split 2, drag two other cards' minimaps to 0:10 and 0:45, then click into either of those — it opens at 0:45 (or 0:10) in single view.
• Return to Split View afterwards: every card is mounted at its last-known position, including files you only adjusted by dragging the minimap (without ever pressing play).
• Positions are session-only — closing the item or refreshing the page resets every file to 0.

Panel Interaction in Split View

Selecting an annotation, tag, or instance from the annotation panel while in Split View does not collapse the view. The corresponding file's card is scrolled into view, briefly highlighted, and becomes the keyboard-focused card so you can drive playback from the keyboard immediately.

Top Toolbar

Left to right, the top toolbar exposes:

• Tool selector — Select / Segment / Box / Entity. Picking a class auto-switches to its matching tool, but the dropdown lets you switch tools manually.
• Class selector — pick the active class for new annotations. Searchable; first nine classes carry 1–9 shortcuts.
• Upload — opens the upload modal (when allowed).
• Download — exports the current item as a ZIP (when allowed). See Download / Export.
• Instructions — opens the Project Instructions PDF for the user's role (when uploaded).
• Split (multi-file items only) — toggles between Split 0/1/2/3. See Split View.
• Keyboard shortcuts — opens an in-app cheat sheet on hover.
• Documentation — opens this popup.
• Dark mode — toggles the UI palette (preference is saved per browser).
• Video adjustments (when video is visible) — slider dropdown for Brightness, Contrast, Saturation, and Shape Opacity. See Video Adjustments.
• Fullscreen (F) — expands the tool within its host.
• Undo / Redo — see Undo / Redo.

Tool Selector

Four tools, plus a class-driven auto-pair behaviour:

The tool selector only lists tools that have at least one matching class configured and that are available for the current media type (the Box tool is hidden on audio items and in Split View). Shortcuts for hidden tools are disabled — pressing the Box shortcut on an audio item shows an informational toast.

Class Selector

The class dropdown lists every class visible to the user's role whose tool type is available for the current media type, with a colour swatch, the class name, and a shortcut badge for the first nine. Type to filter by name. Selecting a class:

• Sets it as the active class for new annotations.
• Auto-selects the matching tool (Segment / Box / Entity) so the next gesture draws the right kind of annotation.
• Classes flagged as view-only for the user's role show a small lock icon and cannot be selected for new annotations.

Waveform & Video

The center area renders one or both surfaces depending on the media and the project configuration.

Audio Waveform

Always shown — for audio files as the primary surface, and for video files alongside the video frame. Powered by WaveSurfer with its Timeline, Minimap, and Regions plugins:

• Timeline — runs above the waveform with seconds / minutes ticks. Click anywhere to seek.
• Minimap — a compressed overview rendered below the waveform. Drag to scrub at large scale; useful for navigating long files at high zoom.
• Multi-channel toggle — for stereo / multi-channel sources, the Toggle Multi-channel button stacks one waveform per channel. Off, channels are mixed into a single track.
• Zoom in / out — buttons in the playback controls; useful for tightening in/out points on short events.
• Peaks file — on first decode, the editor uploads a small JSON peaks file alongside the media, including video files with a decodable audio track. Subsequent loads use it to render the waveform without re-decoding the full audio. See Peaks Files.

Video Player

Shown automatically for video files (audio files show only the waveform). The video plays in lock-step with the waveform — WaveSurfer is bound to the <video> element so a single decode powers both.

• Box overlay — when the active tool is Box, drag on the video frame to draw an axis-aligned rectangle. Existing boxes are rendered on top of the frame at their current time and respect the Shape Opacity setting.
• Zoom and pan — mouse wheel zooms around the cursor; drag pans while zoomed. Overlay geometry stays aligned with the video under the transform.
• Hide / Show Video — the Toggle Video button in the playback controls hides the video frame to reclaim vertical space when you're focused on waveform-only work; the audio keeps playing.
• Overlay labels — toggled with O or the labels button: when on, hovering an annotation shows a small label chip with its class and primary text/value.
• Shape class names — toggled with Shift+O from the canvas label button: video boxes switch between number-only labels and class-name-plus-number labels.

This tool is audio-first: it offers a single video canvas with axis-aligned box tracking. For frame-level video work — a frame panel, cuboids, rotated boxes, or per-instance visible ranges — use the dedicated Video Annotation Tool.

Keyframes

Box annotations can hold multiple keyframes to track changes over time. Each keyframe stores a (time, rect) pair. Between keyframes, position and size are interpolated linearly so the box tracks moving objects without creating a separate instance per frame. Move or resize a selected box at a new playhead time to add a keyframe there.

Video Adjustments

When video is visible, the Video adjustments button in the top toolbar opens a slider dropdown:

• Brightness / Contrast / Saturation — applied as a CSS filter on the video frame so the original bytes are never mutated.
• Shape Opacity — controls the fill opacity of bounding boxes rendered on top of the video. Useful for keeping the underlying frame readable when many overlapping annotations are present.
• Reset — restores all four sliders to their defaults.

Playback Controls

A row of controls under the player exposes everything needed to drive playback and switch view modes:

• Play / Pause (Space, or Shift+Space while typing), Mute (M).
• Time display — current / total in seconds.
• Zoom Out / In on the waveform.
• Toggle Multi-channel — stack channels or mix to mono.
• Show / Hide Video.
• Overlay labels (O).
• Shape class names (Shift+O, video canvas only).
• Transcript — opens / closes the transcript panel.
• Playback speed — dropdown with values from 0.25x to 3x.
• Record Audio — when Recording is enabled.

Use , / . to seek 3 s back / forward and < / > for 10 s jumps. Press M to toggle mute. Press O to toggle overlay labels on hover, and press Shift+O on video items to toggle class names on shape labels. Press F to toggle fullscreen, and on video items press Shift+F to fit the zoomed video back to view. Press Shift+Space to play / pause even while typing in transcript or property fields. All shortcuts also work in Split View, where they target the focused card (or all cards in broadcast mode).

Creating Annotations

The exact gesture depends on the class's tool type:

Segment

1. Pick a class of type Segment from the dropdown — or press 1–9. The Segment tool selects automatically.
2. Drag horizontally on the waveform to set start and end. Releasing the mouse creates the segment.
3. The new segment appears as a coloured region on the waveform and as a row in the annotation panel.
4. Drag the segment's edges to resize, or grab its body to move. Overlapping Segments and Restrict Segment Length rules are enforced live during drag.

With Segment Loops on, leaving the bounds of the currently selected segment during playback automatically loops back to its start — handy for tight in / out point review.

Box

1. Pick a class of type Box (video items only). The Box tool selects automatically and the video frame becomes the drawing surface.
2. Pause at the desired frame, then drag an axis-aligned rectangle on the video. The box receives a start / end time around the current playhead by default.
3. To track movement, scrub to a later frame, select the box, and move or resize it — a new keyframe is added at that time and the box position interpolates between keyframes.

Entity

1. Open the transcript panel (transcribe first if needed).
2. Pick a class of type Entity. The Entity tool selects automatically.
3. Drag-select a span of transcript text. On mouse-up, the span becomes an entity annotation that ties back to its containing transcript segment.

To remove any annotation, select it (panel row, region body, box, or transcript span) and press Delete or Backspace.

Annotation Panel

The annotation panel is the command-centre for structured data. It lists every annotation in the item and offers two complementary views.

Instance View

The default layout: one row per annotation. Each row shows:

• An eye icon for per-annotation visibility, copy-id button, the class chip (click to change class), the annotation's start / end times (or transcript span text for entities).
• Quick-action icons — comments, relationships, property popover icon (opens property popover).

Click a row to seek the playhead to the annotation's start (segment / box) or scroll the transcript to its span (entity). The panel supports:

• Media filter — (multi-file items only) a dropdown at the top of the panel filtering annotations and tags to a specific media file.
• Group By — Media Name (default for multi-file), Class Name, or Tool Type.
• Order By — JSON Export (default), Class Name, Tool Type, Start Time, Created By, Creator Role, Created At.
• Filter — by class, by property, by comments (when comments are enabled).
• Reordering — when using the Group By Text Name and Order By JSON Export, drag handles appear on instance rows. Drag to reorder instances within the same text file. Reordering is reflected in the data and export.

Table View

Toggle to Table View for a spreadsheet-style grid: one row per annotation, one column per property. This is the fastest way to scan and edit properties across many annotations at once, and ideal for bulk AI autofill review (both AI Text and AI Select).

• Fixed columns: Media (multi-file only), Class, Tool Type, Start, End, optional Comments column when comments are enabled, one column per relationship type, plus the three Created-By / Role / At meta columns (hidden by default).
• Property columns adapt to the class of each row — properties not defined on a class show as empty cells.
• Sort by any column; filter via column headers. Rating columns use the same numeric min/max filter as Numeric. Approval columns offer a fixed three-state picker — Approved, Disapproved, (Blank) — regardless of which states currently appear in the data, so you can always pre-filter for "no verdict yet" before any rows have been approved.
• Inline edit each cell; changes auto-save immediately.
• AI extraction column (Table View) — when a class has AI Text / AI Select properties, the table adds a leading AI column with row-level actions: Extract (all empty, runnable AI properties on that row) and, when Enable Editing is on, Edit prompt. These mirror the action bar at the top of the property popover.
• Per-property extract icons (Table View) — individual AI Text and AI Select cells also show compact extract (and optional edit-prompt) icons beside the field, matching the per-property icons beside each AI field label in the property popover.
• Use the Columns dropdown to reorder, hide, or pin columns for the current session. Your starting order and pin defaults come from the project-wide Table Column Settings.
• Pin columns — clicking the pin icon next to a column glues it to the leading edge of the table. Pinned columns always render before unpinned ones (preserving relative order within each cluster); the leading utility cells (eye icons, drag handle, copy-id) and group subheaders also stick to the leading edge once any column is pinned, so per-row controls and group labels stay visible during horizontal scroll. Drag-reordering inside the dropdown is restricted to within a cluster (pinned↔pinned or unpinned↔unpinned). Pin state is per-session.

Column Group Chips

When an admin has configured column groups, a row of toggle chips appears above the table. Each chip represents one group and shows its label. Click a chip to show or hide all columns in that group at once. Chips display three visual states: active (all group columns visible), partial (some columns individually hidden), and inactive (all group columns hidden). Hovering a chip shows a tooltip listing the columns it contains. Editors can still show or hide individual columns from the Columns dropdown regardless of group state.

Grouping & Bulk Edit

Both Instance View and Table View can group annotations by Media Name, Class Name, Tool Type, or any individual Property. In Table View, groups display visual subheader rows that break the grid into collapsible sections — one per group value. Group headers include collapse / expand controls.

Editable groups expose an Edit action next to the group label. Clicking it opens a bulk-edit popover where you can apply changes to every annotation in the group at once:

• Change the class of all grouped annotations. See Class Changes for class eligibility, property retention, and confirmation details.
• Edit shared property values across the group.

Changes from the bulk-edit popover are applied immediately and feed the standard undo stack.

Property Editing

Click the property popover icon on a row in the Instance View to open the property popover. The popover anchors next to the row so the source annotation and the structured fields stay visible together. For AI Text and AI Select fields, compact extract icons sit beside each property label (single-property scope); a separate action bar at the top of the popover runs extraction for the whole row. In Table View, fields are inline-editable in their cells.

• Free Text — inline editable by default. Its Text Display mode controls presentation: Inline (default), Modal (a roomy verbatim plain-text modal), or Rich Text (a formatted rich-text modal).
• AI Text — auto-fill at three scopes: a single property (extract icon beside the field in the property popover or table cell), a whole row (popover action bar or table AI column), or all visible panel rows when bulk extraction is enabled. Manual edit if Enable Editing is on. Supports the same Text Display modes (Inline / Modal / Rich Text).
• Select — always a dropdown; the Allow multi-select property option controls whether one or multiple options can be picked at the same time.
• AI Select — dropdown with predefined options, pre-selected by AI autofill through the same single-property, row-level, or bulk panel entry points. The model picks from the configured option list based on the segment's transcript or audio content. Manual override is always possible; when Enable Editing is on, annotators can also tweak the prompt before extraction.
• Numeric — number input with optional bounds and unit.
• Rating — orange/gold star picker rendered in the popover, Table View cell, and bulk edit dialog. Click a star to store that number; click the currently selected star again to clear the value. Hover previews fill from the first star through the hovered star. Required-and-empty editable ratings get the same thin red wrapper outline as Approval. View-only access keeps the palette but dims the stars and disables clicks. Table search matches the displayed number.
• Approval — a compact two-button picker (thumbs-up / thumbs-down) for capturing a three-state verdict. Click the up icon to mark the row approved (stores "true"), the down icon to mark it disapproved ("false"); clicking the active icon again clears the verdict, and clicking the opposite icon swaps the verdict in place. Both surfaces — the property popover and the Table View cell — render the same picker, and changes flip on click without needing to dismiss the popover or refresh the panel. In view-only contexts (role lacks edit access, class is view-only) the icons keep their green / red palette but read as dimmed so the verdict is still legible at a glance; the buttons are not interactive. Approval columns are excluded from the table's free-text search — filter by verdict via the column dropdown's three-state picker instead.
• Required indicator — required properties are visually flagged when empty so incomplete annotations are easy to spot.

AI Property Autofill

The AI Text and AI Select property types send segment transcript text (or raw audio when no transcript exists) and each property's configured prompt to your AI proxy. By default the model and proxy come from project configuration; individual properties can override that routing.

Where to trigger extraction

AI extraction is available at three scopes. Single-property and row-level controls exist in both the property popover and Table View; bulk extraction runs from the annotation panel header regardless of which panel mode you are in.

• Single property — run one AI Text or AI Select field at a time.
  • Property popover — each AI property shows compact Extract (and, when Enable Editing is on, Edit prompt) icons beside its label.
  • Table view — the same per-property icons appear inside that property's table cell. See Table View.
• Whole row — run every empty, runnable AI property on one annotation row at once.
  • Property popover — the AI action bar at the top of the popover offers Extract and Edit prompt (when editing is enabled for any AI property on the row).
  • Table view — the leading AI column mirrors those same row-level actions.
• Full annotation panel — when bulk extraction is enabled, the panel-header extract button runs AI extraction across every visible instance row in the panel, in Instance View or Table View. See Bulk annotation panel extraction.
• Edit prompt modal — opened from any Edit prompt entry point above; shows editable per-property prompts before running.

Prompts and routing

The tool sends one chat request per proxy/model batch containing:

• A built-in system prompt assembled from the per-property prompt(s) defined in configuration.
• A user payload with text describing the annotation, built using one of two paths:
  • Linked-segment path — when the annotation is a Segment linked to a transcript segment with non-empty text, the linked transcript text is sent. This is the common case after auto-transcription.
  • Audio-segment path — when there is no linked transcript text, the editor extracts a WAV snippet, sends it through Whisper / Gemini transcription first, then feeds the resulting text into the chat call.
• For Box and Entity annotations, the payload is built from the annotation's surrounding text (entity span text and any linked transcript context for entities).
• Per-property proxy / model — properties with a configuration override route independently. A single row or popover extract may issue multiple API batches when its empty AI properties resolve to different proxy/model pairs.
• For AI Select, the model returns one (or more, if multi-select is enabled) option labels from the property's predefined list; unrecognised values are silently dropped.
• Requires a configured route for each property being extracted — either the project AI Property Proxy or a per-property override.
• The same models also power the Ask AI assistant in this in-app documentation popup — that path always uses the project proxy, not per-property overrides.
• When Enable Editing is on, annotators can tweak a property's prompt before pressing Extract; when off, the configured prompt is used as-is. Errors (rate limits, provider failures, missing proxy) surface as toasts.

Bulk annotation panel extraction

When an admin enables Allow Bulk Extraction of all AI Properties, a compact extract button appears in the annotation panel header (alongside the view / group-by controls). Click it to run AI extraction across every visible instance row in the panel — whether you are in Instance View or Table View.

• Scope — respects the current panel filters, table search (when in Table View), column filters, media/class filters, and collapsed group sections. Collapsed sections are skipped; only expanded groups contribute rows.
• What runs — for each qualifying row, the bulk job extracts the same set of properties the row-level Extract button would — empty AI Text / AI Select fields that pass visibility and accessibility checks. Already-filled values and view-only AI properties are skipped.
• Confirmation & progress — a confirm dialog shows the row count. During the run a non-dismissible progress banner counts completed rows; row-level and per-property extract icons show a spinner while that row is queued. Outcome toasts stack beneath the banner.
• Summary — when finished, a dismissible banner reports how many rows were fully filled, partially filled, failed, or skipped.
• Concurrency — rows are processed in parallel (up to 15 at a time); each row still batches its own properties by proxy/model route.
• The button is hidden entirely when the configuration toggle is off, and disabled when no visible rows have anything left to extract.

Text Display Modals (Modal & Rich Text)

Free Text and AI Text properties whose Text Display mode is set to Modal or Rich Text render as a compact pill in the popover / table cell; clicking it opens a full-page editor instead of editing inline. The same modals are reused for tag-level properties.

• Modal (plain text) — opens the same kind of full-page popup as the Rich Text modal, but with a plain editing area and no formatting toolbar. What you type is stored exactly as-is — whitespace, line breaks, and literal markup (raw HTML, JSON, code) are preserved verbatim, with no formatting or conversion applied. Use it for comfortable reading and editing of long or structured plain text.
• Rich Text — a formatting editor supporting bold, italics, headings, bulleted and numbered lists, blockquotes, inline code, code blocks, links, and tables. Sized for multi-paragraph content like detailed descriptions or transcriptions of long passages. Content round-trips through a formatted representation, so it is not intended for preserving arbitrary literal markup — use Modal for that.

Both modals offer a View only state for read-only roles and close on Save & Close, Cancel, or Esc.

Property & Option Visibility Rules

Configurations defined as property visibility rules and option visibility rules are evaluated and enforced live as the annotator works — there's no separate "validate" step, and the same logic applies in both the floating property popover and the table view.

Property Visibility Rules — apply to any property type

A property visibility rule can be set on any property type (Free Text, AI Text, Select, AI Select, Numeric, Rating, Approval — all of them). When the rule is unsatisfied for the current row, the whole field is treated as inaccessible:

• The field still renders in the popover and as a table column so annotators can see the field exists, but it's dimmed and read-only, with a not-allowed cursor and a hover tooltip explaining what controls it (e.g. "Controlled by: Sound Category = Music").
• Any stored value on that property is automatically cleared the moment the rule flips to unsatisfied — and the clear cascades, so if A controls B and B controls C, changing A can clear both B and C in a single step.
• Required validation is suppressed while the property is inaccessible — the red required indicator on the annotation / tag row only reactivates when the rule becomes satisfied again.
• AI extraction is skipped on AI Text / AI Select properties whose rule is unsatisfied. The row-level Extract / Edit prompt controls, the per-property icons in the property popover, and the per-cell extract icons in the table all hide or grey out for these fields, and re-appear the instant the controller flips back — no popover reopen needed.
• Modal / Rich Text properties gated by an unsatisfied rule render as a plain "—" placeholder; the plain-text or rich-text modal cannot be opened. Approval columns behave the same way in the table — the cell collapses to "—" rather than rendering a dimmed picker, matching the convention used by every other column type. The property popover keeps the dimmed-disabled picker so users still see what the field would look like.

Option Visibility Rules — apply only to Select / AI Select

Select and AI Select properties additionally support per-option visibility rules. These don't hide the whole field — they filter the contents of the dropdown:

• Each option appears in the dropdown only when its own rule is satisfied by the current controller values on that same annotation / tag row. Options with no rule are always shown.
• If the annotator changes a controller value and a previously-selected option is no longer valid, the dropdown's stored value is cascade-cleared the same way property-level rules cascade — so the row never holds an option that can't be re-picked from the visible list.
• For AI Select, the model's pre-selection respects the same filtering — values the model returns that fail the active rules are silently dropped before being written to the row.

How the two layers combine on a Select / AI Select property

A Select / AI Select property can carry both kinds of rules at once: a property visibility rule on the field itself, and option visibility rules on one or more of its individual options. The editor evaluates them in a fixed order — property first, then options — so they can't contradict each other:

1. The property rule runs first. If it is unsatisfied, the whole field is dimmed and read-only as described above; option rules on that field are never evaluated, because there is nothing to pick from while the field is inaccessible.
2. If the property rule passes (or no property rule exists), the option rules filter what appears in the dropdown.

In short: the property rule decides whether the field is in play; the option rules then decide which choices are valid inside it. Cascade clearing covers both layers in one pass — a stored value can be cleared because the option it points to is no longer valid (option-rule failure) or because the whole property hosting it is no longer visible (property-rule failure). The chain icon on a property's editor label, and the small chain badge in the table column header, both surface the active rule's controller(s) on hover so annotators can quickly see why a field is dimmed or why their list of options is narrower than expected.

Transcript Panel

When Transcript is on, the Transcript button in the playback controls opens a docked panel below the player. The panel lists timed transcript segments — one row per segment, each with start / end times and the transcribed text.

• Click a row to seek the playhead to that segment.
• The currently-playing segment is highlighted as playback advances.
• Each row carries small action icons — re-extract via AI, link to a Segment annotation, jump.

Auto-Transcription

The first time a user opens the transcript panel on an item with no transcript yet, the editor:

1. Sends the active media's audio (or the audio track of a video) to the configured AI proxy.
2. Asks for segmented output — one entry per natural speech segment, each with start, end, and text.
3. Populates the transcript panel from the response.
4. Optionally creates one Segment annotation per transcript segment, depending on the project configuration.

For OpenAI proxies, transcription uses Whisper (whisper-1) with verbose JSON segment timestamps. For Gemini proxies, the admin-selected model handles transcription via an inline-data path that's bounded at ~12 MB per call — long media will fail on Gemini and need a shorter clip or an OpenAI proxy.

Editing Transcript Segments

When Editable Transcript is on, segment text is editable inline both in the transcript panel and in the table view's Transcript column. Off, transcripts are read-only.

Linked Annotations

Transcript segments and Segment annotations align naturally — both have start / end times. When a transcript segment is linked to an annotation (linkedAnnotationId), AI autofill (AI Text and AI Select) on that annotation reads the transcript text directly instead of re-transcribing the audio. This is the fast path most projects use.

Comments

Comments let reviewers and annotators leave scoped notes on a specific annotation without cluttering the source media. Typical uses:

• Flagging ambiguous segments for a second opinion.
• Recording rationale for borderline class decisions.
• QA feedback that doesn't belong in property values.

Each comment has an author, a timestamp, the message text, and a resolved flag. Comments are a flat list per annotation — there is no nested reply threading. Resolving a comment is gated by the Resolve Comments (Roles) allow-list, and deleting by Delete Comments (Roles). Comments are exported alongside the rest of the structure.

Relationships

Relationships capture the links between annotations — which segment refers to which, how two things are related. They turn a flat list of annotations into a graph suitable for relation extraction, event modelling, or speaker-diarisation cross-references.

• Enabled when Instance Relationships is on in configuration.
• The relationship-type taxonomy is admin-curated under Feature Control → Relationship Types; annotators pick from that list (no freeform types).
• From an annotation row, click the relationship icon, pick a relationship type, then pick the target annotation.
• Each annotation can hold one target per relationship type (a same-type, same-source link replaces the previous target).
• Relationships are directional (source → target). Symmetry isn't a per-edge flag — model it by adding a second relationship type, or by adding the inverse link manually.

Class Changes

To reclassify one annotation, click its class chip in the annotation panel and choose a class from the menu. The annotation's timing or geometry stays unchanged; only its class and property values are updated. To reclassify a group, use the Edit action described in Grouping & Bulk Edit.

• Eligible classes. The menu lists only visible, editable classes with the same tool type as the annotation. A Segment can become another Segment, but not a Box, because their data shapes differ. To convert across tool types, delete the original and redraw it under the new class.
• Strict property matching. A populated value is retained only when the destination class has one property with the exact same name and type and an identical value-shape configuration. This includes Select options and order, single/multi-select mode, defaults, visibility rules and their controllers, text display mode, numeric bounds/step/unit, rating maximum, role-visibility settings, and whether each of those fields is absent or explicitly set. Property IDs are remapped as they are unique and can't match.
• What does not block retention. Required status, helper text, and AI extraction settings such as prompts, model routing, and prompt-edit permission can differ. They affect future validation, help, or extraction rather than the stored value itself.
• Rules and access are enforced. The destination property must be editable for the current user. After all compatible values are mapped, the destination's property and option visibility rules are evaluated together; a value whose controller does not allow it is removed. Invalid or stale values are not retained. Destination defaults fill properties that have no retained value.
• Confirmation and Undo. If any populated value cannot be retained, the confirmation dialog reports retained and removed counts before applying the change. The same summary is used for a grouped class change. One Undo restores the original class and every property value.

Unknown class

When a class is deleted, or its tool type is changed in configuration, annotations that use its previous type are shown as Unknown instead of being converted or deleted. They render in neutral grey on the waveform and in the annotation panel until the original class is restored with the same ID and type.

• An Unknown annotation keeps its timing or geometry and its place on the audio timeline; only its class identity is unresolved.
• It can be reclassified. The class menu offers visible, editable classes with a tool type compatible with the stored annotation.
• Stored properties remain unchanged but are unavailable while the annotation is Unknown. AI extraction does not run on Unknown annotations.

Annotation Isolation

Annotation Isolation is a configuration-level privacy mechanism, not a per-annotation dim toggle. When isolation is set to By User, by default each user only sees the annotations they themselves created. A role on Bypass Isolation (Roles), or the item's current status in Bypass Isolation (Statuses), lets that viewer see everyone's annotations. Matching either bypass is enough.

• Use isolation to prevent annotator bias by hiding peer annotations during the labelling pass.
• Reviewers in the bypass list can see all annotators' work side by side for QA.
• Creator filter chips — when isolation is on and the user is a bypasser, a row of chips appears at the top of the annotation panel labelled by creator. Toggle a chip off to hide that creator's annotations on the canvas / video / transcript and in the panel; toggle back on to bring them back.
• The eye icons in the panel let users hide individual annotations from their own view independently of isolation.

Tags under isolation

System-generated tags (item-scope and media-scope) participate in isolation alongside instances, but with a few rules of their own:

• Lazy creator stamping (ON and OFF) — tag rows are rendered in the panel as soon as an item is opened, but no createdBy / createdAt is written to the JSON until the user makes their first JSON change anywhere in the item. That first change synchronously stamps every visible placeholder with the current viewer's email, role, and timestamp. An item that's only been viewed produces zero tag rows in the saved JSON and downloads.
• Isolation ON — one row per user, per scope — the system auto-generates one tag row per user per visible tag class, on each scope (item-scope or media-scope), excluding admins (role id 3). Two annotators opening the same item end up with two independent rows for each tag class — each can edit their own row's properties and comments without seeing the other's, and a bypass reviewer sees all rows side by side. Re-opening an item where the user already has a row never creates a duplicate.
• Mid-project rollback — if isolation is turned off after items have already accumulated multi-user copies, all existing copies stay intact. New users opening those items don't get a fresh copy; they edit whichever row already exists for the class. Brand-new items opened after the rollback follow the OFF rule (one row per class).
• Admins leave no footprint on passive view — admins never trigger tag materialization or stamping on open. An admin only becomes a tag's createdBy if they actively create a row that didn't exist yet (no row for their email under iso ON, or no row at all under iso OFF). Admin edits to a tag created by someone else preserve the original creator and only land the property / comment change.
• Creator chips and table columns extend to tags — the bypass-mode creator-chip filter buckets tag rows by their stamped creator just like it buckets instances. The Created By, Creator Role, and Created At columns in the panel's table view populate for tag rows once stamped, and they're searchable / filterable.
• Deletion stays locked — tags are system artefacts and cannot be deleted by any role, including bypass viewers. Bypass viewers can read and edit other users' tag properties and comments; non-bypass viewers only ever see their own rows.

Undo / Redo

The tool maintains a single history stack of annotations and transcript segments. Ctrl(⌘)+Z reverts to the previous snapshot; Ctrl(⌘)+Shift+Z (or Ctrl(⌘)+Y) re-applies it. Both annotation actions and transcript edits undo together — there's no separate sub-stack to fall through.

Import / Export

Items arrive into a project through JSONL bulk upload at the SuperAnnotate platform level. The editor reads each item's data.audio_annotation_tool.value payload when it's opened. Items leave through the editor's Download button as a ZIP — round-trip-safe, so an exported annotations.jsonl can be re-imported into another project. Media bytes can either be uploaded to SuperAnnotate storage or URL-linked from elsewhere; the editor handles both via the same payload shape.

JSONL Import

JSONL (one JSON object per line) is the platform ingest format. Each line is one item. The editor doesn't have a direct JSONL upload button — items appear in the editor after the platform creates them from the JSONL.

Payload Shape

Each item must have:

• metadata.name — display name (required).
• data.audio_annotation_tool.value — the tool-specific payload. Inside value, items use a mediaFiles array (multi-file) or a top-level media object (single-file legacy shape — both are accepted on import; export always uses mediaFiles for new items).

Each entry in mediaFiles is a StoredMediaFile with exactly one of uploadedFile or url:

• uploadedFile — { uniqueName, fileName, fileType, fileSize }. Bytes live in SuperAnnotate storage; the platform resolves the bytes via uniqueName.
• url — a string URL with a sibling urlKind (see URL-linked media) and optional fileType / fileSize hints.

Each entry can also carry peaksFile, instances, transcript, and tags arrays.

Minimum required keys: metadata.name and data.audio_annotation_tool.value.mediaFiles (at least one entry). Each mediaFiles entry needs a fileName (or, for URL-linked entries, the editor falls back to the trailing path segment of url) and exactly one of uploadedFile or url. Everything else — urlKind, peaksFile, instances, transcript, tags, itemTags — is optional and can be added incrementally.

Uploaded Media — Two Files

{
  "metadata": { "name": "interview-001" },
  "data": {
    "audio_annotation_tool": {
      "value": {
        "mediaFiles": [
          {
            "id": "media-1",
            "name": "Part 1",
            "uploadedFile": {
              "uniqueName": "abc123.mp3",
              "fileName": "interview-part1.mp3",
              "fileType": "audio/mpeg",
              "fileSize": 4823104
            },
            "peaksFile": {
              "uniqueName": "abc123.mp3.peaks.json",
              "fileName": "interview-part1.peaks.json",
              "fileType": "application/json",
              "fileSize": 21048
            },
            "instances": [
              {
                "id": "ann-1",
                "instanceNumber": 1,
                "classId": "class-speaker",
                "type": "segment",
                "start": 12.34,
                "end": 18.7,
                "propertyValues": { "prop-speaker-name": "Alice" }
              }
            ],
            "transcript": [
              { "id": "tr-1", "start": 12.34, "end": 18.7, "text": "Hello and welcome.", "linkedAnnotationId": "ann-1" }
            ],
            "tags": [
              { "tagClassId": "tc-quality", "propertyValues": { "prop-score": "0.95" } }
            ]
          },
          {
            "id": "media-2",
            "name": "Part 2",
            "uploadedFile": {
              "uniqueName": "def456.mp3",
              "fileName": "interview-part2.mp3",
              "fileType": "audio/mpeg",
              "fileSize": 5102321
            },
            "instances": [],
            "transcript": [],
            "tags": []
          }
        ],
        "itemTags": [
          { "tagClassId": "tag-en", "propertyValues": {} }
        ]
      }
    }
  }
}

URL-Linked Media

To point at media that lives outside SuperAnnotate, replace uploadedFile with a url + urlKind pair:

{
  "metadata": { "name": "field-recording" },
  "data": {
    "audio_annotation_tool": {
      "value": {
        "mediaFiles": [
          {
            "id": "media-1",
            "name": "Recording",
            "url": "https://storage.example.com/audio/recording.wav",
            "urlKind": "presigned",
            "fileType": "audio/wav",
            "fileSize": 8123456
          }
        ]
      }
    }
  }
}

urlKind tells the editor how to access the URL:

Peaks Files

To skip re-decoding a long audio file every time it's opened, the editor stores a small JSON peaks file alongside each media file:

• How it's produced. The first time a user opens a media file, WaveSurfer decodes the audio and the editor exports a downsampled peaks array ({ peaks, duration }). The JSON is uploaded to SuperAnnotate storage and recorded on the StoredMediaFile.peaksFile field.
• Cache key. For SuperAnnotate-uploaded media, the peaks file's uniqueName is ${mediaUniqueName}.peaks.json. For URL-linked media, it's ext-${hash}.peaks.json where the hash is stable on origin + pathname (so the peaks survive presigned-URL refreshes).
• Re-use across users. Once any user has uploaded peaks for a media file, every subsequent open reads from the cached JSON instead of re-decoding the bytes.
• JSONL imports can pre-supply peaksFile if you've generated peaks externally — the editor will use them and skip the decode step.

Structure Keys

Download / Export

The Download button (when allowed by Access Control → Download Annotations) produces annotations.zip containing the current item.

Export Structure

The ZIP always contains:

The ZIP does not include original media bytes. Per-file URL references and uploaded-file metadata remain in annotations.json and annotations.jsonl, so imports retain the source information.

Tags

Tags are split into two scopes in the export:

• Item-level tags — stored in the top-level itemTags array. Apply to the whole item.
• Media-level tags — stored per-file in mediaFiles[i].tags. Apply to that specific file only.

Each tag entry references a tag class by ID and carries its own propertyValues object. The name2id.json file maps tag class IDs back to names.

// Item-level
"itemTags": [
  { "tagClassId": "tag-en", "propertyValues": {} }
]
// Per-file (media-level)
"mediaFiles": [{ ..., "tags": [
  { "tagClassId": "tc-quality", "propertyValues": { "prop-score": "0.95" } }
]}]

Properties

Each annotation carries a propertyValues object keyed by property ID. Values are stored as strings:

• Free Text / AI Text — the raw string value.
• Numeric — the number serialised as a string.
• Rating — the selected star count serialised as a string ("1" through the configured max); the key is omitted when unset.
• Select / AI Select (single) — the option label.
• Select / AI Select (multi) — option labels joined with ", ".
• Approval — the literal string "true" when approved or "false" when disapproved. The key is omitted from propertyValues when no verdict has been given (rather than being written as an empty string), matching how other property types treat blank values.

"propertyValues": {
  "prop-speaker-name": "Alice",
  "prop-emotion": "Excited",
  "prop-tags": "Lecture, English",
  "prop-confidence": "0.92",
  "prop-verdict":     "true"
}

Relationships

Relationships are stored on the source annotation as a single Record<relationshipTypeId, targetInstanceId> map. Each relationship type can hold one target per source annotation — adding a new target on the same type replaces the previous one. Relationships are directional; model bidirectional links by adding the inverse relationship from the target side.

"relationships": {
  "rel-replies-to":  "ann-2",
  "rel-references": "ann-7"
}

Transcript

Each media file's transcript is exported as a flat array of StoredTranscriptSegment:

"transcript": [
  {
    "id": "tr-1",
    "start": 12.34,
    "end": 18.7,
    "text": "Hello and welcome to the show.",
    "linkedAnnotationId": "ann-1"
  }
]

linkedAnnotationId is the bridge between transcript rows and Segment annotations — it lets AI autofill (AI Text and AI Select) read the transcript text directly without re-transcribing audio.

Comments

Comments are exported as a flat array per annotation. Each comment captures author identity, message text, resolved state, and a creation timestamp. There is no nested replies structure.

"comments": [
  {
    "id": "cmt-1",
    "authorEmail": "reviewer@example.com",
    "authorName": "Pat Reviewer",
    "text": "Confirmed — start time aligned with the door slam.",
    "resolved": false,
    "createdAt": "2026-04-20T14:02:11Z"
  }
]

Item Context

Item Context values are serialised as a top-level itemContext map of { slotId: string }. Keys are the stable slot ids from the project's Item Context configuration (the same ids surfaced under itemContext in name2id.json). Values use the same markdown-like plain-text format as rich-text properties — the editor renders them with full formatting but the on-disk representation stays plain text for backward compatibility.

"itemContext": {
  "ctx-abc123": "You are reviewing a financial report.\n\n**Key rules:**\n- Flag any unverified claims\n- Mark numerical inconsistencies with `[ERROR]`\n\n> Focus on the executive summary first.",
  "ctx-def456": "## Entity guidelines\n\nAnnotate all named entities mentioned in the document.\n\n1. People — full name only\n2. Organizations — use official name"
}

• Role-hidden slots are still exported. Per-role visibility is a UI concern; downloads always carry the full set of stored values so QA / export pipelines see everything.
• Orphan keys are preserved. If a slot was deleted in config (or arrived via JSONL with an id no longer in config), its value is kept on disk and carried through every save and export. This mirrors the comments-style "non-destructive" precedent — admins can re-enable a feature later without rebuilding past data.
• Empty strings are valid values — they represent "user explicitly cleared the field". The itemContext key is omitted from the output entirely only when the merged map is empty.
• JSONL upload — the same itemContext shape is accepted on the inbound side. Use the itemContext mapping in name2id.json to translate human-readable slot names to ids when authoring upload payloads.

Explore Keys

The tool automatically publishes four top-level summary values on every item — instance_count, comment_state, class_list, and valid — surfaced to the SuperAnnotate Explore view so you can search, filter, and sort items by their annotation state. They are computed for you and written alongside the item's annotation data; there is nothing to configure.

A few details worth knowing:

• valid gates submission. It is registered as a required Explore key, so the platform blocks an item's status change by non-Admin users until the value is truthy ("True"). An empty value ("") prevents submission.
• valid is per-user / per-role. It reflects what the current user can see and edit — properties on hidden or view-only classes, or rows hidden by isolation rules, never count against them. Because required fields can differ by role, the same item can read "True" for an annotator and "" for a reviewer who has additional required fields to fill.
• Opening an item is non-destructive. Simply viewing an item does not create an unsaved change. The one exception is a safety case: if an item was stored as "True" but is no longer complete for the user who just opened it, valid is corrected to "" and saved immediately, so an incomplete item can't be submitted by mistake.

Auto-Save

Users should never lose work. The auto-save system runs on two tiers:

• Debounced local save — annotation actions (draw, resize, property change, comment, relationship, tag, transcript edit) coalesce and persist to the in-tool data layer ~1 s after the last change. Rapid edits collapse into a single save.
• Server auto-save (60 s interval) — while the item has unsaved changes, the editor pushes to the SuperAnnotate server every 60 seconds in the background.

There is no manual Save button on the main editor toolbar — auto-save handles persistence. (A "Save & Close" button exists inside the Rich Text Modal for property values.) See Auto-Save Timing for browser-close guidance.

Solutions

The tool's value isn't a feature list — it's how features combine to solve real audio / video annotation challenges end-to-end. Each solution below walks through a common workflow: the goal, the configuration, and the step-by-step flow, with links to every relevant part of the tool. Adapt the class names, tags, and prompts to your domain and you have a production-ready pipeline.

Audio-Event Annotation Workflow

Goal: Produce a labelled audio-event dataset — every speech, music, SFX, and silence segment timed and classified, with reviewer sign-off and exportable for training a sound-event classifier.

Configuration

• Access control: admins, annotators, reviewers; isolation set to By User with admins / reviewers in the bypass list.
• Feature Control: Audio Waveform on; Video Player off (audio-only); Transcript off if speech content isn't relevant; Overlapping Segments on so concurrent events (speech + music bed) can be labelled.
• Classes: Speech, Music, SFX, Ambient, Silence — all of type Segment. Arrange the five most-used first to lock in 1–5 shortcuts.
• Properties: a Single Select Confidence (Low / Medium / High), a Numeric Loudness (dB), optional Free Text Notes.

Workflow

1. Admin uploads the dataset to the project at the SuperAnnotate platform level as JSONL (with uploadedFile entries or URL-linked clips).
2. Annotators open items, scrub through the waveform with , / . for fine seeking and Space to play in context.
3. For each event, press 1–9 to pick the class — the Segment tool auto-selects — then drag across the waveform to mark start and end. Resize edges to nudge the boundaries.
4. Use Segment Loops to tighten in / out points: select the segment, hit play, and the segment auto-loops until you nudge the edges into place.
5. Reviewers open items, use the Table View grouped by class to scan all properties across the item, and leave comments where they see issues.
6. Annotators resolve comments; admin exports the ZIP and feeds it into the training pipeline.

Speech Transcription & Diarisation Workflow

Goal: Turn raw recorded speech into a clean, segmented transcript with per-segment metadata — speaker, intent, sentiment — using AI for the heavy lifting and humans for review.

Configuration

• Feature Control: Audio Waveform on; Transcript on; Editable Transcript on.
• Classes: Speaker (Segment) for diarisation; Intent (Entity) for fine-grained spans across transcript text.
• Properties on the Speaker class: Free Text Speaker Name; Single Select Role (Host / Guest / Caller); AI Text Summary with prompt "Summarise this speaker turn in one sentence."; optional AI Select Sentiment (Positive / Neutral / Negative).
• AI proxy configured (OpenAI for files larger than ~12 MB; Gemini works for shorter clips).

Workflow

1. Annotator opens an item with raw audio. The waveform decodes and the peaks file uploads in the background.
2. They open the transcript panel — auto-transcription kicks off and populates timed segments. Each transcript segment can optionally seed a Speaker annotation.
3. The annotator scrubs the timeline, listens to each segment, and assigns the correct Speaker class to each segment annotation.
4. For each speaker turn, they press Extract on the AI Text Summary property — the linked-segment fast path reads the transcript text directly and returns a one-line summary.
5. For finer-grained labels (e.g. "user expresses frustration"), they switch to the Intent class (an Entity) and drag-select transcript text to mark exact spans.
6. Reviewer scans the Table View sorted by speaker, edits any miss-transcribed text inline, then resolves comments.
7. Export ZIP — annotations.json contains the transcript array per file, plus segment + entity annotations. Downstream pipelines can re-derive a clean RTTM or VTT file from this structure.

Video Bounding-Box Tracking Workflow

Goal: Track an object across a video clip with a moving bounding box and a class label, suitable for object-tracking model training.

Configuration

• Feature Control: Video Player on; Audio Waveform optional (most tracking projects keep audio off to free vertical space).
• Classes: per-object classes of type Box — e.g. Person, Vehicle, Animal.
• Properties: a Single Select Visibility (Full / Partial / Occluded), Numeric Confidence, and a Free Text Track ID if multiple instances of the same class need to be distinguished.

Workflow

1. Annotator opens the item; the video appears with the optional waveform alongside.
2. They scrub to the first frame where the object is visible, pick the class (the Box tool auto-selects), and drag a rectangle on the video frame.
3. They scrub forward to a frame where the object has moved, select the same box, and add a new keyframe — the box's position interpolates between keyframes.
4. Repeat at each "kink" in the trajectory; the box smoothly tracks the object across the clip.
5. Use Video Adjustments to dial Brightness / Contrast for hard-to-see footage and turn down Shape Opacity when overlapping annotations obscure the frame.
6. Switch to Table View to sort by start time and verify each box has a complete track and visibility property.
7. Export — each Box annotation carries its bbox rect at start time plus a bboxKeyframes array of (time, rect) pairs.

In-Browser Recording Workflow

Goal: Capture fresh audio (e.g. user-voice prompts, evaluator narration, controlled samples) directly in the tool, label it, and export as labelled training data.

Configuration

• Upload Files: include the recording role.
• Recording: on.
• Classes: project-specific — e.g. Prompt, Response, Disfluency (all Segment).

Workflow

1. Annotator opens an item with no media. The drop zone is visible.
2. They press Record Audio in the playback controls, capture the take, then press Finish. The recording is uploaded as a new media file in the item.
3. The waveform appears for the new file. They retake (or add additional takes as new media files) up to the 10-file cap.
4. They draw segments on the waveform, fill properties, and add item-level tags for whole-clip metadata (speaker, environment, language).
5. Optional: open the transcript panel to auto-transcribe each take.
6. Export ZIP. annotations.json contains the labels and the recordings' source references; the ZIP does not include the original recording bytes.

Tips & Limitations

Small tricks that compound across thousands of annotations, plus the edges of the tool you should know before rolling out a large project.

Efficiency Tips

Class Shortcuts (1–9)

The first nine classes in your project bind to 1–9. With hundreds of regions to draw per session, keyboard shortcuts save real minutes — and because picking a class auto-selects its matching tool (Segment / Box / Entity), pressing the digit before each draw is the fastest possible flow. Put the nine most-used classes first in configuration and train the muscle memory.

Tool Shortcuts (S / G / B / D / E)

Even though picking a class auto-selects a tool, you can switch tools manually with S (Select), G (Segment), B (Box), E (Entity). S in particular is worth memorising — drop into Select mode to inspect / move existing annotations without accidentally drawing new ones.

Fast Seeking on the Waveform

Sub-second precision matters for tight in/out points. The seek shortcuts skip dropdown-hunting:

• Space — play / pause.
• , / . — seek 3 s back / forward.
• < / > — seek 10 s back / forward.
• M — mute / unmute.
• Tab / Shift+Tab — jump to the next / previous annotation.

Every shortcut on this list works in Split View as well — they target the card you most recently played, paused, seeked, muted, or selected from the panel.

Combine with Segment Loops to nail boundaries: select a segment, hit play, the segment loops automatically while you nudge edges with the mouse.

Filtering & Grouping

Reviewing 500 annotations in an unsorted list is impractical. The annotation panel filtering, grouping, and ordering controls turn QA from random browsing into structured inspection.

• Group By — Media Name (multi-file default), Class Name, or Tool Type.
• Order By — JSON Export, Class Name, Tool Type, Start Time, Created By, Creator Role, or Created At.
• Class filter — narrow to one class at a time.
• Property filter — filter by configured property values.
• Table View + column sort / filters — fastest way to catch outliers.

Overlapping Segments

Segments on the same waveform can overlap when Overlapping Segments is on — useful when concurrent events need separate annotations (e.g. a music bed under speech). The editor renders overlapping regions as layered fills so each stays visible; click panel rows to disambiguate which annotation to select. When the toggle is off, draws and resizes that would create an overlap are blocked at draw time.

Tags vs Properties

Both store structured metadata — the question is scope:

• Item-level tags describe the whole item. Use for dataset partition, language, source.
• Media-level tags describe a single media file. Use for per-file quality, speaker count, environment.
• Properties describe a single annotation. Use for region-level attributes (speaker name, confidence, visibility).

If you find yourself wanting a property on every annotation in a media file, it probably belongs as a media-level tag instead.

Use Linked Transcript Segments for AI Autofill

When a Segment annotation has a linked transcript segment with non-empty text, AI Text autofill takes the fast path and reads the transcript text directly — no extra Whisper call per extraction. This is roughly 5–10× faster than the audio-segment path, and free of the Gemini ~12 MB ceiling. The simplest way to set this up: turn Transcript on in Feature Control and let auto-transcription seed both transcript segments and Segment annotations on first open.

Auto-Save Timing

Auto-save debounces to the local data layer ~1 second after annotation actions; the server push runs on a 60-second interval whenever unsaved changes exist. There's no manual Save button on the main toolbar, so wait a couple of seconds after your last edit before closing the tab to ensure the local layer has captured your work — and ideally wait for the next 60-second server push cycle for full server-side persistence.

Limitations

Browser Compatibility

Best in Chrome and Edge (Chromium), where the WebAudio decode path and the Media Recorder API are most reliable. Safari and Firefox are supported with minor rendering differences (especially around waveform anti-aliasing and video overlay positioning); in-browser recording quality may also vary.

Multi-File Cap

An item supports up to 10 audio / video files (MAX_MEDIA_FILES = 10). Additional in-editor uploads beyond that limit are rejected. If imported item data contains more than 10 media files, the editor does not open a partial item: it shows an unsupported-item message and leaves the stored data unchanged. Reduce the source item to the supported limit before opening it here. If your workflow regularly hits this cap, split sessions into separate items rather than packing everything in one.

Gemini Inline-Data Limit

Gemini's inline_data path used for transcription has a request-size ceiling around 20 MB; the editor enforces a safer ~12 MB per call to leave room for base64 bloat and JSON wrapping. Calls over this cap fail upfront with a clear error message. Mitigations:

• Use shorter clips for Gemini-routed projects.
• Switch to an OpenAI proxy — Whisper accepts larger uploads.
• Pre-segment long media into multiple files in one item (still subject to the 10-file cap).

API Rate Limits

AI autofill and auto-transcription calls are routed through your configured AI proxies, and the underlying provider enforces its own rate limits (OpenAI / Gemini for transcription; OpenAI / Gemini / Anthropic for AI property extraction). Running autofill on hundreds of annotations back-to-back will eventually hit those limits — the tool surfaces the upstream error inline. Mitigations:

• Fill properties in batches and pause briefly between batches.
• Prefer the linked-transcript fast path over per-segment audio extraction — it uses chat-tier quota only, not transcription quota.
• Check quota in SuperAnnotate → Team Settings → Security → Proxies.
• Switch to a higher-tier key if you routinely hit limits.

Cross-Type Class Changes

Reclassifying an annotation only allows the new class to share the same tool type as the old one — a Segment can become another Segment but not a Box (or vice versa), since the underlying data shape is different. To convert across types, delete the original annotation and redraw it under the new class. If a class is deleted or its tool type is changed in configuration, affected annotations become Unknown until reclassified or the original class is restored.