Skip to content
Feeding a clanker? Grab this page as raw .md →

AnnotationWidget API#

Bases: AnyWidget

Annotation input widget with buttons, keyboard shortcuts, gamepad, and speech-to-text.

This widget provides a UI input surface for annotation workflows. It does NOT render the object being annotated — the notebook handles content display and reacts to the action traitlet.

The action_timestamp traitlet changes on every action, even repeated ones, so observe always fires.

Examples:

import marimo as mo
from wigglystuff import AnnotationWidget

widget = mo.ui.anywidget(AnnotationWidget())
widget
Source code in wigglystuff/annotation.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def __init__(
    self,
    *,
    actions: Optional[Sequence[str]] = None,
    keyboard_mapping: Optional[dict[str, str]] = None,
    gamepad_mapping: Optional[dict[str, str]] = None,
    debounce_ms: Optional[int] = None,
    width: Optional[int] = None,
    **kwargs: Any,
) -> None:
    init_kwargs: dict[str, Any] = {}
    action_list = list(actions) if actions is not None else list(DEFAULT_ACTIONS)
    if actions is not None:
        init_kwargs["actions"] = action_list
    init_kwargs["keyboard_mapping"] = (
        _default_keyboard_mapping(action_list)
        if keyboard_mapping is None
        else dict(keyboard_mapping)
    )
    init_kwargs["gamepad_mapping"] = (
        _default_gamepad_mapping(action_list)
        if gamepad_mapping is None
        else dict(gamepad_mapping)
    )
    if debounce_ms is not None:
        init_kwargs["debounce_ms"] = debounce_ms
    if width is not None:
        init_kwargs["width"] = width
    super().__init__(**init_kwargs, **kwargs)

Synced traitlets#

Traitlet Type Notes
action str Name of the most recently triggered action (e.g., accept, fail).
action_timestamp float Timestamp (ms since epoch) of the latest action; changes on every trigger so observe always fires, even for repeats.
note str Free-form note text, populated by typing or speech-to-text.
listening bool True while speech-to-text is actively transcribing.
disabled bool When True, all input controls are inert.
show_save bool Toggles visibility and availability of the footer Save button.
actions list[str] Ordered list of main action button labels. Defaults to ["previous", "accept", "fail", "defer"].
keyboard_mapping dict[str, str] Maps keys to action names. By default, action buttons are mapped to number keys in order (1, 2, ...), with s for save and m for mic. The special target mic toggles the speech-to-text microphone.
gamepad_mapping dict[str, str] Maps gamepad button indices (as strings) to action names. By default, action buttons are mapped to gamepad buttons in order (0, 1, ...), followed by save and mic. The mic target works here too.
debounce_ms int Minimum interval between accepted action triggers, in milliseconds.
width int Widget width in pixels.