> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Natural object interaction

Natural object interaction makes support visible: the hand contacts the product before moving it, and the base reaches the table before the fingers release. This guide uses a speaker on a table to coordinate dialogue, speaking motion, and idle motion. Add these rules for product demonstrations; ordinary conversation does not need them.

### 1. Prepare a scene where the action is visible

The starting picture should show the hands, speaker, and tabletop, with the speaker within reach. Leave room for the lift and avoid hiding the contact behind the body or table edge. A reference image preserves appearance; it does not establish that the product is already in the scene.

Use a model version confirmed to support object references. There is no additional client switch that enables this on every model. Check grip and placement with your actual images.

### 2. Register the product reference

Replace the URL with your speaker reference image and send this over the session control connection. Keep the ID and visual description consistent. asset.added confirms registration, not successful handling.

```json wrap theme={null}
{
  "event_id": "speaker_asset_01",
  "type": "asset.add",
  "assets": {
    "images": [
      {
        "asset_id": "OBJ_0",
        "url": "https://YOUR_CDN.example/speaker.png",
        "mime_type": "image/png",
        "description": "An upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base"
      }
    ]
  }
}
```

### 3. Assign each prompt its job

[Response instructions](/streaming-avatar/character/spoken-instructions) interpret the request and determine what can be claimed. [Speaking motion](/streaming-avatar/character/speaking-motion) describe contact, grip, lifting, placement, and release. [Idle motion](/streaming-avatar/character/listening-motion) preserve the resulting object and support between replies.

#### Dialogue: acknowledge the request without claiming completion

Merge these rules into the existing character instructions, replacing any conflicting rule that prohibits product handling. Demonstration and handling do not imply inventory lookup or purchasing capabilities.

```text wrap theme={null}
## Product demonstration
Explain the dark gray cylindrical speaker in natural language. Use the product name in speech, not its reference ID.
For an explicit request to pick up or put down the speaker, briefly acknowledge the requested action. A question about the speaker is not a handling request. If a handling request does not identify an available product, ask which one the user means; do not interrupt ordinary conversation with product-selection questions.
Do not claim that a physical action has finished unless the current visual state supports that claim. Do not invent stock, price, or purchase results; use the relevant business tool when available.

## Current picture
{VLM}
Use the picture to distinguish the speaker resting on the table from the speaker held in a hand. If the state is unclear, avoid a completion claim.
```

#### Speaking: describe contact and support changes

Extend Motion Rules in the general speaking template with handling and identity rules. Retain Character Context, Current Frame, and the output contract. This is a scenario extension, not a complete session request.

```text wrap theme={null}
## Product identity and current state
Use the current picture to identify the speaker, its location, and its support. The reference catalog defines its appearance, not whether it is visible now.
Canonical description: an upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base.
When the speaker is visible at any point in a segment, include this description and its matching tag exactly once at the first mention. Later mentions preserve its identity and support without repeating the tag. If identity is uncertain, preserve the observed silhouette without assigning a reference tag.

## Handling rules
PICK UP: only when the speaker is visibly resting within reach on the table. Move the free hand toward it, establish palm and finger contact around its body, then lift the base a short distance above the table. End with continuous hand support. If already held, preserve the existing grip instead of repeating a pickup.
HOLD: keep the existing hand and grip. A free hand or the head may make a small compatible gesture. Do not transfer the speaker between hands or set it down without a request.
PUT DOWN: only when the speaker is visibly held. Lower it until the flat base contacts the table, transfer its weight to the table, then release the fingers and withdraw the hand. End with the speaker upright and table-supported.
If the picture does not support the requested action, preserve the current state and use a small compatible body movement. Do not create an absent speaker in the hand. Use a separate, fully described retrieval path if your scene requires off-screen retrieval.

## VMP and output
Each segment states the camera, current person and scene, absolute starting support, one main action, and ending support. Keep mouth behavior unspecified. Output only plural motions with nonempty vmp and a positive duration for every item.
```

#### Idle: preserve held or table-supported states

Merge these rules into Motion Rules in the general idle template. Remove conflicting requirements such as returning both hands to the table while one hand is holding the product.

```text wrap theme={null}
## Product continuity
Preserve the current speaker's identity, position, and support while the character listens. The reference catalog is not evidence that the speaker is visible.
When the speaker is reliably identified, use this descriptor and tag once at the first mention: an upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base.
A held speaker keeps its existing palm and finger contact. A table-supported speaker keeps its flat base on the table. Do not automatically put it down, pick it up again, switch hands, or remove it. If identity is uncertain, preserve the observed shape and position without selecting a reference tag.
Choose one small head or shoulder movement, or a compatible free-hand movement. Keep occupied hands committed to their support. Output only singular motion containing exactly one item with a nonempty vmp and no duration.
```

### 4. Check the generated output

These two segments illustrate an explicit request to pick the speaker up and put it back. For a pickup-only request, end with it held rather than adding placement. Each segment uses `<OBJ_0>` once at the first mention, without repeating it at the endpoint. Durations are planning values.

```json wrap theme={null}
{
  "motions": [
    {
      "vmp": "A fixed medium shot shows a person seated behind a wooden table. On the table within reach is an upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base. Both hands start beside it. The right hand approaches, wraps its palm and fingers around the cylindrical body, and lifts the flat base a hand-width above the table. The left hand rests on the table; the right hand keeps continuous contact at the end.",
      "duration": "4s"
    },
    {
      "vmp": "A fixed medium shot shows a person seated behind a wooden table, holding an upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base in the right hand a hand-width above the tabletop. The hand lowers it until its base contacts the wood, transfers its weight to the table, releases the fingers, and rests beside it. The speaker ends upright with its base supported by the table.",
      "duration": "4s"
    }
  ]
}
```

If the speaker remains held after speech, idle output preserves that grip. Note singular motion, exactly one item, and no duration.

```json wrap theme={null}
{
  "motion": [
    {
      "vmp": "A fixed medium shot shows a person seated behind a wooden table. The right hand holds an upright dark gray cylindrical speaker<OBJ_0> with a perforated grille, a flat top, and a flat circular base a hand-width above the tabletop, with palm and fingers in contact. The left forearm rests on the table. The head inclines slightly toward the camera and settles upright while the right hand preserves the grip and height."
    }
  ]
}
```

### 5. Test three requests

Test “pick up the speaker”, “tell me about it”, and “put it back”, watching the following idle interval each time. Check contact before movement, the same supporting hand during the explanation, and base contact before release. Ask an ordinary question afterward to ensure the character does not fetch it again.