Actions

Actions are the trigger layer for user-initiated operations in OpenCut. They provide a unified interface for keyboard shortcuts, UI interactions, and programmatic invocations.

Overview

The actions system separates “what to do” (the action) from “how to trigger it” (shortcuts, buttons, menu items). All action definitions live in a single source of truth: @/lib/actions/definitions.ts.

When to use actions

Use invokeAction() for user-triggered operations in components:

import { invokeAction } from '@/lib/actions';

// Good - uses action system with UX feedback
const handleSplit = () => invokeAction("split");

// Avoid - bypasses UX layer (toasts, validation feedback)
const handleSplit = () => editor.timeline.splitElements({ ... });

Direct editor.xxx() calls are for internal use (commands, tests, complex multi-step operations).

invokeAction()

Invokes an action by name, optionally passing arguments and trigger information.

action

TAction

required

The action name to invoke (e.g., "toggle-play", "split", "undo")

args

TActionArgsMap[A]

Arguments for actions that accept parameters. Only required for actions with args:

seek-forward / seek-backward: { seconds: number }
jump-forward / jump-backward: { seconds: number }

trigger

TInvocationTrigger

How the action was triggered. Values: "keypress" or "mouseclick". Used for analytics and conditional behavior.

Examples

import { invokeAction } from '@/lib/actions';

// Simple action without arguments
invokeAction("toggle-play");

// Action with arguments
invokeAction("seek-forward", { seconds: 5 });

// Action with trigger information
invokeAction("split", undefined, "keypress");

Action handlers

Actions are handled using the useActionHandler hook in React components. This connects action invocations to their implementations.

import { useActionHandler } from '@/hooks/actions/use-action-handler';
import { useEditor } from '@/hooks/use-editor';

function MyComponent() {
  const editor = useEditor();

  useActionHandler(
    "toggle-play",
    () => {
      editor.playback.toggle();
    },
    undefined, // isActive: when to bind this handler
  );
}

useActionHandler

Registers a handler for a specific action.

action

TAction

required

The action name to handle

handler

TActionFunc<A>

required

Function to execute when action is invoked. Receives action arguments and optional trigger.

isActive

boolean | MutableRefObject<boolean> | undefined

required

Controls when the handler is active:

undefined: Always active
boolean: Static active state
MutableRefObject<boolean>: Dynamic active state (useful for conditional handlers)

Available actions

All actions are defined in the ACTIONS constant in @/lib/actions/definitions.ts.

Playback

Action	Description	Default Shortcuts	Arguments
`toggle-play`	Play/Pause	`space`, `k`	-
`stop-playback`	Stop playback	-	-
`seek-forward`	Seek forward 1 second	`l`	`{ seconds?: number }`
`seek-backward`	Seek backward 1 second	`j`	`{ seconds?: number }`

Action	Description	Default Shortcuts	Arguments
`frame-step-forward`	Frame step forward	`right`	-
`frame-step-backward`	Frame step backward	`left`	-
`jump-forward`	Jump forward 5 seconds	`shift+right`	`{ seconds?: number }`
`jump-backward`	Jump backward 5 seconds	`shift+left`	`{ seconds?: number }`
`goto-start`	Go to timeline start	`home`, `enter`	-
`goto-end`	Go to timeline end	`end`	-

Editing

Action	Description	Default Shortcuts	Arguments
`split`	Split elements at playhead	`s`	-
`split-left`	Split and remove left	`q`	-
`split-right`	Split and remove right	`w`	-
`delete-selected`	Delete selected elements	`backspace`, `delete`	-
`copy-selected`	Copy selected elements	`ctrl+c`	-
`paste-copied`	Paste elements at playhead	`ctrl+v`	-
`toggle-snapping`	Toggle snapping	`n`	-

Selection

Action	Description	Default Shortcuts	Arguments
`select-all`	Select all elements	`ctrl+a`	-
`duplicate-selected`	Duplicate selected element	`ctrl+d`	-
`toggle-elements-muted-selected`	Mute/unmute selected elements	-	-
`toggle-elements-visibility-selected`	Show/hide selected elements	-	-

History

Action	Description	Default Shortcuts	Arguments
`undo`	Undo	`ctrl+z`	-
`redo`	Redo	`ctrl+shift+z`, `ctrl+y`	-

Timeline

Action	Description	Default Shortcuts	Arguments
`toggle-bookmark`	Toggle bookmark at playhead	-	-

Action definition

Each action is defined with the following properties:

description

string

required

Human-readable description of what the action does

Adding new actions

To add a new action:

Define the action in @/lib/actions/definitions.ts:

export const ACTIONS = {
  "my-action": {
    description: "What the action does",
    category: "editing",
    defaultShortcuts: ["ctrl+m"],
  },
  // ...
};

Add the handler in @/hooks/use-editor-actions.ts (or your component):

useActionHandler(
  "my-action",
  () => {
    // Implementation
    editor.timeline.doSomething();
  },
  undefined,
);

If the action takes arguments, add type definitions in @/lib/actions/types.ts:

export type TActionArgsMap = {
  "my-action": { value: number };
  // ...
};

Commands - Command pattern for undo/redo
CommandManager - Managing command history

Core

Actions & Commands

Hooks

Overview

When to use actions

invokeAction()

Examples

Action handlers

useActionHandler

Available actions

Playback

Navigation

Editing

Selection

History

Timeline

Action definition

Adding new actions

Build docs developers (and LLMs) love

Core

Actions & Commands

Hooks

Documentation Index

​Overview

​When to use actions

​invokeAction()

​Examples

​Action handlers

​useActionHandler

​Available actions

​Playback

​Navigation

​Editing

​Selection

​History

​Timeline

​Action definition

​Adding new actions

​Related

Build docs developers (and LLMs) love

Overview

When to use actions

invokeAction()

Examples

Action handlers

useActionHandler

Available actions

Playback

Navigation

Editing

Selection

History

Timeline

Action definition

Adding new actions

Related