# Sync

> Timeline sync, an otio-rust extension and not part of OpenTimelineIO: sharing a timeline between programs while it is edited.

Symbols in this group are spelled `otio_ext_sync_…`. An SDK drops that prefix.

## `apply`

`otio_ext_sync_apply` · free

Applies the JSON list of patches `patches` to the timeline JSON `timeline`, as Furnace's `otiodiff` does, and writes the patched timeline to `out_timeline` as compact JSON.

| Parameter | Type | Role |
| --- | --- | --- |
| `timeline` | `text` | input |
| `patches` | `text` | input |
| `out_timeline` | `text` | output |
| `out_error` | `text` | error |

## `apply_to`

`otio_ext_sync_apply_to` · free

Applies the JSON list of patches `patches` to `timeline` in place.

The timeline keeps its handle, as does every synced object in it that the patches keep; one they remove is stale afterwards. On failure the document is left as it was.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `patches` | `text` | input |
| `out_error` | `text` | error |

## `begin`

`otio_ext_sync_begin` · free

Starts a transaction on `timeline`, which is `sequence_id` at `generation`: stamps any missing GUIDs, and writes the timeline as it is to `out_before` as a snapshot.

The snapshot is the transaction. Keep it, edit the timeline, and pass it to `otio_ext_sync_commit` for the patches, or to `otio_ext_sync_rollback` to undo the edits.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `sequence_id` | `text` | input |
| `generation` | `int64` | input |
| `out_before` | `text` | output |
| `out_error` | `text` | error |

## `commit`

`otio_ext_sync_commit` · free

Ends the transaction `otio_ext_sync_begin` wrote as `before`, writing the patches that take the timeline as it was to the timeline as it is, the next generation, to `out_patches` as a compact JSON list.

An edit that changed nothing writes `[]`.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `before` | `text` | input |
| `out_patches` | `text` | output |
| `out_error` | `text` | error |

## `commit_journal`

`otio_ext_sync_commit_journal` · free

Takes what the journal of the document `timeline` is in recorded since it started or was last committed, runs the `document_changed` hook on the document's root with it if anything changed, and writes whether anything did to `out_changed`.

The hook's arguments are `touched`, the GUIDs of the synced objects that were added or may have changed, and `root_changed`.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `out_changed` | `bool` | output |
| `out_error` | `text` | error |

## `diff`

`otio_ext_sync_diff` · free

Works out the patches that take the snapshot `old_snapshot` to the snapshot `new_snapshot`, as Furnace's `otiodiff` does, and writes them to `out_patches` as a JSON list.

A snapshot is JSON as Furnace sends one: `sequenceId`, `generation`, and the timeline as `otioJson`. With `pretty`, the list is indented as Furnace's golden files are; otherwise it is compact. A change too large for patches, or one between sequences or back in generation, is one `replace_timeline` patch; `otio_ext_sync_diff_stats` says why.

| Parameter | Type | Role |
| --- | --- | --- |
| `old_snapshot` | `text` | input |
| `new_snapshot` | `text` | input |
| `pretty` | `bool` | input |
| `out_patches` | `text` | output |
| `out_error` | `text` | error |

## `diff_stats`

`otio_ext_sync_diff_stats` · free

Writes what `otio_ext_sync_diff` does with the same snapshots to `out_stats`, as a JSON object: `insertOps`, `moveOps`, `removeOps`, `setPropertyOps`, `totalOps`, `nodeCount`, `fellBack` and `fallbackReason`.

| Parameter | Type | Role |
| --- | --- | --- |
| `old_snapshot` | `text` | input |
| `new_snapshot` | `text` | input |
| `out_stats` | `text` | output |
| `out_error` | `text` | error |

## `enable`

`otio_ext_sync_enable` · free

Turns timeline sync on. The same as `otio_ext_enable("sync")`.

Enabling it again does nothing and succeeds.

| Parameter | Type | Role |
| --- | --- | --- |
| `out_error` | `text` | error |

## `find`

`otio_ext_sync_find` · free · may answer nothing

Finds the object under `timeline` that carries the GUID `guid`, and writes it to `out_node`.

Reports `OTIO_STATUS_NO_VALUE` when none does, and `OTIO_STATUS_INVALID_ARGUMENT` when two do; stamp first to rule that out.

| Parameter | Type | Role |
| --- | --- | --- |
| `source` (optional) | `document` | document in |
| `timeline` | `node` | input |
| `guid` | `text` | input |
| `out_node` | `node` | output |
| `out_error` | `text` | error |

## `guid`

`otio_ext_sync_guid` · free · may answer nothing

Writes the GUID `node` carries in `metadata.sync.guid` to `out_guid`.

Reports `OTIO_STATUS_NO_VALUE` for an object that carries none.

| Parameter | Type | Role |
| --- | --- | --- |
| `source` (optional) | `document` | document in |
| `node` | `node` | input |
| `out_guid` | `text` | output |
| `out_error` | `text` | error |

## `handle`

`otio_ext_sync_handle` · free

Acts on the JSON `event` from `otio_ext_sync_session_poll_event` in `timeline`, the program's copy of the timeline the event names, and writes what it did to `out_handled` as a JSON object: `handled`, one of `applied`, `replaced`, `rejected`, `joined` or `ignored`, and for `rejected` the script's `message`.

A `timeline` event runs `sync_before_apply`, whose scripts may refuse it, applies its patches so the timeline and the objects that survive keep their handles, falling back to the whole snapshot if the patches do not fit (`replaced`), runs the default media linker on what it inserted, then `sync_after_apply`. A `joined` event runs `sync_joined`. Every other event is the program's to act on, and is `ignored`.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `event` | `text` | input |
| `out_handled` | `text` | output |
| `out_error` | `text` | error |

## `is_enabled`

`otio_ext_sync_is_enabled` · free

Writes whether timeline sync is on to `out_enabled`.

| Parameter | Type | Role |
| --- | --- | --- |
| `out_enabled` | `bool` | output |
| `out_error` | `text` | error |

## `new_guid`

`otio_ext_sync_new_guid` · free

Writes a new GUID, a version 4 UUID, to `out_guid`.

| Parameter | Type | Role |
| --- | --- | --- |
| `out_guid` | `text` | output |
| `out_error` | `text` | error |

## `rollback`

`otio_ext_sync_rollback` · free

Ends the transaction `otio_ext_sync_begin` wrote as `before`, putting the timeline back as it was.

The timeline and every synced object that was in it keep their handles.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `before` | `text` | input |
| `out_error` | `text` | error |

## `session_cancel_review`

`otio_ext_sync_session_cancel_review` · free

Stops sending the review commit `client_mutation_id`, and writes whether it was waiting to `out_cancelled`.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `client_mutation_id` | `text` | input |
| `out_cancelled` | `bool` | output |
| `out_error` | `text` | error |

## `session_close`

`otio_ext_sync_session_close` · free

Releases `session`, whose number names nothing afterwards. Closing one already closed does nothing and succeeds. A session another call is using is released when that call returns.

It sends nothing: call `otio_ext_sync_session_leave` and send the goodbye first to leave politely.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_error` | `text` | error |

## `session_commit_review`

`otio_ext_sync_session_commit_review` · free

Commits a review comment, the JSON object `commit`, to the session's ledger, and writes its id to `out_id`.

`commit` holds `anchor`, `bodyMarkdown`, `annotationCommands` and `clientMutationId`, which is made up if left out. The commit is sent again after every reconnect until the server acknowledges or refuses it.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `commit` | `text` | input |
| `out_id` | `text` | output |
| `out_error` | `text` | error |

## `session_connect`

`otio_ext_sync_session_connect` · free

Starts joining on a new connection: call it once the socket is open, and again after a reconnect. The hello is the next frame to send.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_error` | `text` | error |

## `session_disconnected`

`otio_ext_sync_session_disconnected` · free

Tells `session` the socket closed. It waits for `otio_ext_sync_session_connect`, keeping its timelines and the review commits not yet acknowledged.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_error` | `text` | error |

## `session_leave`

`otio_ext_sync_session_leave` · free

Leaves the session: the goodbye is the next frame to send, after which the socket can close.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_error` | `text` | error |

## `session_may_send`

`otio_ext_sync_session_may_send` · free

Writes whether `session` may send on `channel` now to `out_may`: it has joined, and its role holds the channel's lease.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `channel` | `text` | input |
| `out_may` | `bool` | output |
| `out_error` | `text` | error |

## `session_new`

`otio_ext_sync_session_new` · free

Makes a session from the JSON object `settings`, and writes the number that names it to `out_session`. Release it with `otio_ext_sync_session_close`.

`settings` holds `token`, the token the server issued; `identity`, who the client is (`displayName`, `app`, `appVersion`, `credential`, `deviceId`, `clientKind`, `formFactor`, `deviceName` and `capabilities`); and `encodings`, the compression it accepts (`br`, `gzip`). Each may be left out: `{}` is a guest desktop editor accepting every encoding.

| Parameter | Type | Role |
| --- | --- | --- |
| `settings` | `text` | input |
| `out_session` | `uint64` | output |
| `out_error` | `text` | error |

## `session_poll_event`

`otio_ext_sync_session_poll_event` · free · may answer nothing

Writes the next event to `out_event` as a JSON object, whose `type` is `joined`, `timeline`, `playhead`, `selection`, `roster`, `leader`, `review_relay`, `review_committed`, `review_rejected`, `error`, `ended` or `message`.

Reports `OTIO_STATUS_NO_VALUE` when there is none. Pass a `timeline` or `joined` event to `otio_ext_sync_handle` to apply it.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_event` | `text` | output |
| `out_error` | `text` | error |

## `session_poll_transmit`

`otio_ext_sync_session_poll_transmit` · free · may answer nothing

Writes the next frame to send to `out_bytes`, stamped with `now` in Unix milliseconds, and whether to send it as a binary WebSocket frame rather than a text one to `out_binary`.

Reports `OTIO_STATUS_NO_VALUE` when there is nothing to send. Call it until then after every other session call.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `now` | `int64` | input |
| `out_bytes` | `bytes` | output |
| `out_binary` | `bool` | output |
| `out_error` | `text` | error |

## `session_publish`

`otio_ext_sync_session_publish` · free

Sends `timeline`, as the sequence `sequence_id`, to the session, and writes the patches from the version sent before to `out_patches` as a JSON list. Only the host may.

Stamps missing GUIDs and runs `sync_before_send`, whose scripts may stop it. Sending a timeline that has not changed sends nothing and writes `[]`, unless it switches the active sequence.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `sequence_id` | `text` | input |
| `out_patches` | `text` | output |
| `out_error` | `text` | error |

## `session_receive`

`otio_ext_sync_session_receive` · free

Hands `session` a frame that arrived: `binary` says whether it was a binary WebSocket frame rather than a text one.

A failure means the connection broke the protocol or lost frames: close the socket, call `otio_ext_sync_session_disconnected`, and connect again.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `data` | `bytes` | bytes |
| `len` | `size` | length |
| `binary` | `bool` | input |
| `out_error` | `text` | error |

## `session_register_channel`

`otio_ext_sync_session_register_channel` · free

Registers the channel `name`, for another extension's messages, with the delivery rule `delivery`: `latest_wins`, `ordered` or `transient`.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `name` | `text` | input |
| `delivery` | `text` | input |
| `out_error` | `text` | error |

## `session_send`

`otio_ext_sync_session_send` · free

Sends a message of type `kind` with the JSON `payload` on `channel`.

It is for what sync has no call of its own for: on Furnace, `signal` on the signal channel, and the host's `bin`, `lan_mode_set` and `lan_decision` on the control channel. Furnace closes a connection that sends a type it does not know, so anything else is refused with `OTIO_STATUS_UNSUPPORTED` when it is about to be sent.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `channel` | `text` | input |
| `kind` | `text` | input |
| `payload` | `text` | input |
| `out_error` | `text` | error |

## `session_set_leader`

`otio_ext_sync_session_set_leader` · free

Makes `participant` the playback leader. Only the host may.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `participant` | `text` | input |
| `out_error` | `text` | error |

## `session_set_muted`

`otio_ext_sync_session_set_muted` · free

Mutes or unmutes `participant`. Only the host may.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `participant` | `text` | input |
| `muted` | `bool` | input |
| `out_error` | `text` | error |

## `session_set_playhead`

`otio_ext_sync_session_set_playhead` · free

Moves this client's playhead in `sequence_id` to `frame`, playing at `rate` or stopped.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `sequence_id` | `text` | input |
| `frame` | `double` | input |
| `playing` | `bool` | input |
| `rate` | `double` | input |
| `out_error` | `text` | error |

## `session_set_selection`

`otio_ext_sync_session_set_selection` · free

Selects the objects in `sequence_id` whose GUIDs the JSON list `guids` holds.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `sequence_id` | `text` | input |
| `guids` | `text` | input |
| `out_error` | `text` | error |

## `session_state`

`otio_ext_sync_session_state` · free

Writes where `session` stands to `out_state` as a JSON object: `joined`, `ended`, `sessionId`, `selfId`, `selfUserId`, `role`, `leader`, `peers`, `activeSequence`, `sequences`, `pendingReviews`, and the protocol `version` and `encodings` the server chose.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `out_state` | `text` | output |
| `out_error` | `text` | error |

## `session_timeline`

`otio_ext_sync_session_timeline` · free · may answer nothing

Writes the latest snapshot of `sequence_id` that `session` sent or received to `out_snapshot`.

Reports `OTIO_STATUS_NO_VALUE` when it has none.

| Parameter | Type | Role |
| --- | --- | --- |
| `session` | `uint64` | input |
| `sequence_id` | `text` | input |
| `out_snapshot` | `text` | output |
| `out_error` | `text` | error |

## `set_guid`

`otio_ext_sync_set_guid` · free

Gives `node` the GUID `guid`, replacing any it had.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `node` | `node` | input |
| `guid` | `text` | input |
| `out_error` | `text` | error |

## `stamp`

`otio_ext_sync_stamp` · free

Gives every object sync addresses under `timeline` a GUID, if it lacks one or shares one with an object met earlier, and writes how many it gave one to to `out_count`.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `out_count` | `size` | output |
| `out_error` | `text` | error |

## `start_journal`

`otio_ext_sync_start_journal` · free

Starts recording which objects any edit to the document `timeline` is in touches.

The journal is the document's, so it records edits anywhere in it; the timeline only says which document. Recording again does nothing and succeeds.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `out_error` | `text` | error |

## `stop_journal`

`otio_ext_sync_stop_journal` · free

Stops recording edits to the document `timeline` is in, and forgets what was recorded since the last commit.

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `timeline` | `node` | input |
| `out_error` | `text` | error |

---

Page: https://otio-rust-docs.vercel.app/reference/sync/