> For the complete documentation index, see [llms.txt](https://help.movin3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.movin3d.com/movin-tracin-stage/reference/osc-format.md).

# OSC message format

OSC address, type tag, and argument reference for point cloud, skeleton, and test messages — for building your own receiving integration.

Use this reference when building your own receiving integration. For the network and first-message check, see [OSC output](/movin-tracin-stage/setup/live-settings.md#osc-output) in Stage 2.

The messages below describe the current sender implementation. If you maintain an integration for an older installation, inspect the received type tags, especially for the legacy skeleton layout.

## Transport

* OSC over UDP; set the receiver's port to the same value as **Target port**.
* Message addresses are case-sensitive. Point-cloud addresses can be customized in an installation; `/MOVIN/PointCloud` is the default.
* OSC numeric arguments are big-endian. Use an OSC decoder for string padding, addresses, and type tags instead of treating a datagram as plain text.
* UDP packets can be lost, duplicated, or arrive out of order. Do not treat receipt of one packet as receipt of a complete frame.

## Connection test

`/movin/test` has type tag `,i`: one signed 32-bit integer. It is a test value, not a tracked-person count. The workspace sends it when **Test connection** is selected, including during preview.

## Point cloud

Default address: `/MOVIN/PointCloud`.

Each message contains five integer arguments, followed by XYZ float triples:

```
seq, total_points, chunk_idx, num_chunks, chunk_n, x1, y1, z1, ...
```

| Field          | Meaning                                                    |
| -------------- | ---------------------------------------------------------- |
| `seq`          | Frame sequence number; group chunks with the same sequence |
| `total_points` | Point count in the complete frame                          |
| `chunk_idx`    | Zero-based index of this chunk                             |
| `num_chunks`   | Number of chunks in the frame                              |
| `chunk_n`      | Number of points in this chunk                             |
| XYZ triples    | `3 × chunk_n` float32 arguments, in meters                 |

The type tag is `,iiiii` followed by `3 × chunk_n` occurrences of `f`. For a one-point chunk, it is `,iiiiifff`. This is a list of OSC arguments, not a blob.

To assemble a frame:

1. Group packets by `seq` and validate that the frame counts agree.
2. Store each chunk by `chunk_idx`; ignore duplicate copies of that chunk.
3. Once indices `0` through `num_chunks - 1` are present, concatenate their points in chunk order and check the count against `total_points`.
4. Expire incomplete frames after a timeout appropriate to your application. Do not combine chunks from different frames. Reset stale state after reconnecting.

An empty selected cloud produces no point-cloud chunks. Use a receiver timeout to clear or mark stale content; do not display the last frame indefinitely.

## Skeletons

One message is sent per bone. Root uses `/VMC/Ext/Root/Pos`; the remaining bones use `/VMC/Ext/Bone/Pos`. The current layout is:

```
type tag: ,ssfffffffi
arguments: actor, bone, px, py, pz, qx, qy, qz, qw, frame_idx
```

* `actor` and `bone` are strings. The default actor prefix is `MOVIN`, followed by a slot suffix, for example `MOVIN_0`. Group by actor as well as frame.
* Actor names identify output slots, not a permanent identity across runs.
* Positions are in meters; quaternion order is **x, y, z, w**.
* Root and Hips use live positions; other bones carry rig offsets. Rotations are local to the skeleton hierarchy. Do not place every bone as an independent world-space point or assume the position fields are interchangeable.
* `frame_idx` is an int32 frame index, not a timestamp in seconds. Standard VMC has no such field, so a generic VMC receiver may not accept these messages as is.
* Handle missing actors with a timeout. OSC reception alone does not animate a character; map the bone names and transforms to your rig.

The current bone names are:

```
Root, Hips, Spine, Chest, Neck, Head,
LeftShoulder, LeftUpperArm, LeftLowerArm, LeftHand,
RightShoulder, RightUpperArm, RightLowerArm, RightHand,
LeftUpperLeg, LeftLowerLeg, LeftFoot, LeftToes,
RightUpperLeg, RightLowerLeg, RightFoot, RightToes
```

The hierarchy is Root → Hips → Spine → Chest → Neck → Head. Both shoulder chains attach to Chest; each continues through UpperArm → LowerArm → Hand. Both leg chains attach to Hips and continue through UpperLeg → LowerLeg → Foot → Toes.

### Legacy skeleton layout

Older integrations may use `,sfffffffi`: the same numeric fields but only the `bone` string, without `actor`. In that layout the bones now called `Spine` and `Chest` were named `Chest` and `UpperChest`. Detect the layout from the received type tags; do not feed a legacy message into the current parser.

## Coordinate check in your application

The processing/display frame is Y-up. By default the sender flips X on output, and for skeleton rotations also flips quaternion Y and Z. Installations may configure that conversion differently; do not infer wire axes solely from the workspace screenshot or apply an extra mirror without checking.

Use one performer to check origin, scale, forward, and right in the receiving application. Then raise one arm to verify left/right bone mapping. Apply the conversion required by your engine once, consistently to points and skeletons.

If packets arrive but the content is wrong, first check chunk assembly, type tags, bone mapping, and coordinates before changing sensor calibration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.movin3d.com/movin-tracin-stage/reference/osc-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.