# Animation

> Animation editing in development, what the current editor can do, and what remains before filmmaking is ready.

Source: https://graspable.dev/docs/animation

Version **0.17.2** adds an early animation and filmmaking workspace. Open a web project and choose **Animate** to edit poses, keyframes, shots and sound. The broader filmmaking workspace remains in development; the limits below describe what this release supports.

## Edit a take on desktop

Open a web 3D project and choose **Animate** in its header. The preview stays above the timeline.

1. With **Edit scene** selected, click an object in the preview. If needed, choose **Animate this object** to give it an identity that survives reloading the project. **Select parent** chooses the authored group containing it.
2. Choose a property, set its value, and choose **Set keyframe**.
3. Move the playhead to another frame and set the next pose. Choose **Play** or scrub the playhead to inspect the motion.
4. Choose **Save take**. The take stays in the project and can be reopened from the Animation file field.

**Edit scene** intercepts primary clicks on the 3D canvas so selecting an object does not trigger its gameplay action. Click empty space to clear selection; hidden objects and editor helpers are excluded from picking. **Interact** returns control to the experience. The object menu and timeline remain available for selection.

For an object with an animation identity, choose **Move**, **Rotate** or **Scale** and drag a handle in the scene. Releasing records position, rotation and scale at the current frame as one pose; **Undo** reverses the whole gesture. Press Escape during a drag to cancel. Moving the playhead or leaving edit mode also cancels an unfinished gesture. Move and Rotate use world axes; Scale uses the object's local axes. Handles are unavailable during playback or an agent edit, and are hidden while immersed in XR. These desktop handles do not replace the experimental XR controls below.

The initial editor supports position, rotation, scale, opacity and visibility. Linear interpolation moves evenly between poses; Smooth ease in/out starts and ends each interval gently; Hold keeps the earlier pose until the next key. Rotation uses four quaternion components in this development build. A motion path shows the selected object's position track.

The pose inspector sits beside the timeline. Use **Previous key** and **Next key** to move through the selected channel, or **Show curves** to compare its component values over time. Selecting a curve key moves the same playhead used by the scene and inspector. Change its value or interpolation and choose **Set keyframe** to apply it. Smooth interpolation has fixed easing; editable curve tangents are still planned.

Click a diamond to visit its keyframe. Drag it to change its time, or focus it and use the arrow keys; Shift moves ten frames. Delete removes the selected key. Undo and Redo apply to edits in the current editor session.

Dragging shows the destination frame before you release. After retiming, the playhead and keyboard focus follow the moved key. The ruler uses regular frame intervals, and channel names stay visible when you scroll a zoomed timeline.

**Zoom** changes smoothly in fine increments and keeps the visible playhead in place. If the playhead is offscreen or behind the track names, zoom centers on the visible timeline. Pinch or hold Ctrl/Cmd while scrolling to zoom around the pointer. **Fit take** shows the whole timeline again. Zoom does not change keyframes or mark the take as edited; reduced-motion preferences remove the transition.

Use **In** and **Out** to limit playback to an inclusive frame range, and enable **Loop** to repeat it. **Full take** resets the range. These are session playback controls; they do not trim or change your saved animation. Space plays or pauses when the animation workspace has focus. Text fields and buttons keep their usual keyboard behavior.

If a take changes on disk, the editor keeps your draft and asks you to load the latest version before saving. Saving is paused while the agent is working. Objects created by repeated components need distinct animation identities for each instance.

## Camera shots

Frame the scene in the viewport and choose **Capture view at frame…**. A shot stores that camera position, direction and lens. Set its In and Out frames, rename it, or change its field of view. Shots cannot overlap. Trim the first shot before capturing the next one. **Preview film camera** follows the shot sequence while you scrub or play; turn it off to frame another view. Camera cuts never move your head in XR.

For a moving shot, turn off **Preview film camera**, frame a second view and choose **Capture ending view**. The camera moves smoothly between the two poses and reaches the ending pose on the shot's final frame. **Ending field of view** adds a lens change. **Remove camera move** restores a static shot. These film-camera moves do not control the XR viewer's head.

Choose **Edit opening camera** or **Edit ending camera** to see the camera from outside. **Move camera** and **Rotate camera** give you handles in the scene, with a live viewfinder showing the composition through that camera. Right-drag orbits your editing view; scroll moves closer or farther away. Release a handle to record the endpoint, or press Escape during a drag to cancel. **Done positioning** returns to ordinary scene editing. Moving your editing view does not change the shot. An ending pose is added only when you complete a camera gesture.

With **Edit in XR** enabled, squeeze the camera with a controller to move and rotate it, then release to record the endpoint. Squeeze the floating viewfinder to reposition the monitor. Choose **Enter camera** on the XR panel to look around from the shot's position; **Return** restores your editing viewpoint. This changes your position and horizontal facing while keeping head tracking live. Bringing the monitor close to your face does not automatically move you. These controls have been checked in the headset emulator; physical Quest testing and hand gestures remain outstanding. The viewfinder is a composition preview, not a final-resolution render or a stereoscopic 360 video export.

## Add sound

In **Sound**, choose an audio file already in the project and select **Add at playhead**. In the desktop app, **Import audio** copies a file into the project first. The clip initially ends at the shorter of the source file or the end of the take.

Each clip shows its waveform and position in the take. Set **Start** and **Frames** to move or trim it, and **Source in (s)** to skip the beginning of the recording. **Volume** runs from 0 to 1; **Fade in** and **Fade out** are measured in frames. These edits leave the original recording intact. Mute a clip to exclude it from playback and export. Audio edits use the same save and undo history as animation keys.

Playback follows the playhead, including pauses, seeks and loops. Overlapping clips mix together. Missing files, unsupported audio and trims beyond the source recording produce an error; use **Retry audio** after replacing a file. This build supports source files up to 32 MB and up to 128 MB of decoded sound per take. Long recordings may need trimming before import.

For generated narration or sound effects, open **Create sound with connected apps**. Connect ElevenLabs in **Settings → Connected services**, add it to this project, and ask the agent to generate and save an audio file. The existing connected-service approvals and charges apply. The audio picker refreshes as files arrive; add the resulting file to the take. This is an agent-assisted workflow through the connected service, not a separate generation service built into the timeline.

## Export a film

Set **In** and **Out**, choose the format and size under **Export film**, then **Export video**. Graspable saves the take before rendering its camera cuts, motion and unmuted audio. Completed films are saved in the project, with a local player and a download. They can be selected under **Publish → Rendered film**.

Choose MP4 or WebM for a framed film, **360° MP4** for a surrounding panorama, or **Stereo MP4** for separate left/right views. Supported Macs also encode native Apple spatial and 360° video. See [Share immersive films](https://graspable.dev/docs/film-delivery.md) for YouTube, Vision Pro, headset playback and publishing workflows.

Exports are limited to two minutes, 4096 × 2048 and 192 MB locally. Cloud delivery has an 80 MiB limit per media file. Missing audio or an unsupported encoder stops export with an error. Leave an immersive XR session before exporting. If an older project asks you to update its preview tools, do that before rendering immersive formats.

## Editing with agents

Saving uses a revision check and a unique operation ID. Retrying the same save does not apply it twice. Other authenticated agents can read and edit the same take through the motion tools; a stale edit is refused, and your local draft stays available. Current editing is coordinated by one running Graspable agent. Remote invitations, participant presence and simultaneous conflict merging are not yet available.

**Saved edit history** shows recent accepted changes, including object identities, keyframes, shots and sound settings. Starting an agent request saves the open animation draft first. If it cannot be saved, the request stays in the composer so you can resolve the problem. Each new request receives recent saved-edit summaries and recent project versions, including when you continue a conversation. The run's **Context** pane shows this information. Session labels describe the caller; they are not verified participant identities.

This context is bounded: up to 32 recent saved operations, subject to a size limit, and six recent project versions. The current project files remain authoritative. Older changes remain available through project history, but the agent does not automatically receive the entire history or unsaved source-code drafts.

## Repeat motion across objects

Select an animated object and open **Copy animation to objects**. Choose destination objects with animation identities, the channels to copy, and any frame stagger or position offset. Random variation uses a seed, so the same settings produce the same result. Position values are copied from the source with the chosen offsets; this does not automatically preserve each destination's starting position.

Preview the counts before applying. Existing destination channels are protected unless you explicitly choose replacement. Applying changes the draft as one undoable action; save to share it with agents. Agents can use the same bulk operation through the motion editing tool.

This build expands the result into editable tracks, with a limit of 4,096 tracks and 100,000 keyframes per take. Millions of objects will need an instanced, procedural animation system; that capability is not implemented here.

## Edit in XR

Enable **Edit in XR**, then enter VR in the preview. A panel in the scene provides previous/next frame, play/pause, set pose, undo and save, plus shot navigation, capture and recentering. Point at its timeline to seek. Point at an animated object to select it. Hold the controller's squeeze button to move and rotate the selected object, then release to set one undoable pose. Playback, a changed frame, loss of tracking or leaving XR cancels an unfinished gesture.

For a real headset on the same Wi-Fi, enable **Edit in XR** and choose **Connect headset**. Open the QR code or editing link in the headset browser, accept the local preview certificate if asked, then enter VR. Keep the desktop take open: it remains the authority for edits and saves. The link expires after 30 minutes; **Disconnect headset editing**, closing the take or stopping its preview removes editing access. Anyone with the link can edit this take while it is active.

The real-headset connection has been exercised with a browser through the native WebXR path. Physical Quest 3/3S controller comfort, hand input and readability still need hardware testing. Headset audio monitoring and autonomous editing without the desktop are not implemented. The current XR panel uses controller rays and squeeze gestures; hand manipulation and a fuller immersive workspace remain in development.

## Filmmaking work still ahead

The timeline can export a saved take as USDA animation and cameras or an OpenTimelineIO shot/audio schedule. Save the take before exporting. Agents can also prepare supported OTIO editorial changes for review and apply them through the same revision-checked motion operations. A take export does not reconstruct scene geometry or rigs. For actual scene inspection, layered edits and supported USD/glTF model conversion, use the [OpenUSD inspector in Assets](https://graspable.dev/docs/openusd.md). See [interchange files](https://graspable.dev/docs/api.md) for the take formats and limitations.

Agents now read a small film overview, then request the channels, keys or shots needed for an edit. They can check a revision or ask which items changed without repeatedly reading the whole take. Successful edits return short receipts; the saved motion document remains editable JSON.

Rig and clip editing in the timeline, editable curve tangents, broader collaboration, stereo panoramic capture and longer production export workflows remain unfinished. The controls above are development features, not a claim that the filmmaking milestone is complete. Native Unity and Unreal workflows will use their own editable animation assets and engine tools; they are not implemented by the web timeline.

For the current motion document format and read-only agent tools, see [motion inspection](https://graspable.dev/docs/api.md).