# Timeline

> A whole edit: a stack of tracks and where its clock starts.

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

## `clear_global_start_time`

`otio_timeline_clear_global_start_time` · clearer

Clears where a timeline begins.

```c
OtioStatus otio_timeline_clear_global_start_time(
    OtioDocument *target,
    OtioNode node_handle,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `node_handle` | `node` | receiver |
| `out_error` | `text` | error |

## `global_start_time`

`otio_timeline_global_start_time` · getter · may answer nothing

Returns where a timeline begins, such as `01:00:00:00`.

Reports `OTIO_STATUS_NO_VALUE` for a timeline that does not say.

```c
OtioStatus otio_timeline_global_start_time(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioRationalTime *out_time,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `source` (optional) | `document` | document in |
| `node_handle` | `node` | receiver |
| `out_time` | `OtioRationalTime` | output |
| `out_error` | `text` | error |

## `new`

`otio_timeline_new` · constructor

Creates a timeline, with an empty stack named `"tracks"` already in it.

Upstream's `Timeline()` builds that stack in its constructor, and its own tests append to a fresh timeline's tracks without making one first, so a timeline from here arrives the same way rather than leaving every binding to invent the difference. Replace it with [`otio_timeline_set_tracks`] to use a stack of your own; the one built here is thrown away with the document.

```c
OtioStatus otio_timeline_new(
    OtioDocument *target,
    const char *name,
    OtioNode *out_node,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `name` (optional) | `text` | input |
| `out_node` | `node` | output |
| `out_error` | `text` | error |

## `set_global_start_time`

`otio_timeline_set_global_start_time` · setter

Sets where a timeline begins.

```c
OtioStatus otio_timeline_set_global_start_time(
    OtioDocument *target,
    OtioNode node_handle,
    OtioRationalTime time,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `node_handle` | `node` | receiver |
| `time` | `OtioRationalTime` | input |
| `out_error` | `text` | error |

## `set_tracks`

`otio_timeline_set_tracks` · setter

Sets the stack holding a timeline's tracks.

The stack's parent is set to the timeline, as upstream's does.

Passing `otio_node_none` puts a fresh empty stack there rather than nothing, because that is what upstream's setter does: its own `test_timeline.py` sets `tracks` to `None` and then asserts that `tl.tracks` is still a `Stack`. A timeline with no tracks at all is not a thing a caller can reach through upstream's API, so it is not one they can reach through this one.

Whatever stack was there is not destroyed. It stays in the document, parentless, so it can be put somewhere else; dropping it is a separate `otio_document_remove` call. That is the same bargain `otio_composition_detach_child` makes, and leaving its parent pointing at the timeline instead would mean an object claiming a parent that has disowned it. A displaced stack that some other timeline has since taken as its own keeps that timeline as its parent, since this one is not the timeline disowning it.

```c
OtioStatus otio_timeline_set_tracks(
    OtioDocument *target,
    OtioNode node_handle,
    OtioNode tracks,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `target` | `document` | document mut |
| `node_handle` | `node` | receiver |
| `tracks` (optional) | `node` | input |
| `out_error` | `text` | error |

## `tracks`

`otio_timeline_tracks` · getter · may answer nothing

Returns the stack holding a timeline's tracks.

Reports `OTIO_STATUS_NO_VALUE` for a timeline that has none.

```c
OtioStatus otio_timeline_tracks(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioNode *out_tracks,
    OtioBuffer *out_error);
```

| Parameter | Type | Role |
| --- | --- | --- |
| `source` (optional) | `document` | document in |
| `node_handle` | `node` | receiver |
| `out_tracks` | `node` | output |
| `out_error` | `text` | error |

---

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