# lsdtools.compositions reference
URL: https://lsd.tools/docs/sdk-lsdtools-compositions
Updated: 2026-10-19

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `170db6f659e9f79609ddaaec494ffad41f1d659a96001371132843e0c17a7e27`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
Lazy public API for authoring compositions: what plays together, on which clock.

A composition is a project asset (``compositions/<id>``): its members (entities with a runtime
role, each with optional per-participant settings and a play window), its clock (fixed steps
per second of play time, solver substeps, wall-clock speed), per-participant ``systems``
settings, the active camera and the timeline. A package that ships a playable template authors
one here and commits it through ``Engine.workspace.commit_project_compositions``; the runtime
plays it, the Timeline editor edits it, an export bakes it. ``RUN_ALL_ID`` names the implicit
composition of every entity with a participant.
```


## `lsdtools.compositions.CompositionClock`

Kind: class. Source: `core/lsd/src/lsd/packages/project_compositions.py:96`.

Source docstring:

```text
Fixed steps per second of play time, solver substeps per step, and the wall-clock multiplier.
```


Implementation alias: `lsd.packages.project_compositions.CompositionClock`.

### `lsdtools.compositions.CompositionClock.hz`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:99`.

```python
hz: int
```


```python
hz = 60
```


### `lsdtools.compositions.CompositionClock.substeps`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:100`.

```python
substeps: int
```


```python
substeps = 4
```


### `lsdtools.compositions.CompositionClock.speed`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:101`.

```python
speed: float
```


```python
speed = 1.0
```


### `lsdtools.compositions.CompositionClock.to_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:119`.

```python
to_dict(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.compositions.CompositionClock.from_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:123`.

```python
from_dict(cls, value: Any) -> 'CompositionClock'
```


```python
cls: (unannotated)
value: Any
```


## `lsdtools.compositions.CompositionMember`

Kind: class. Source: `core/lsd/src/lsd/packages/project_compositions.py:135`.

Source docstring:

```text
One entity that plays: its per-participant settings and its play window in seconds since Play.
```


Implementation alias: `lsd.packages.project_compositions.CompositionMember`.

### `lsdtools.compositions.CompositionMember.entity_id`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:138`.

```python
entity_id: str
```


### `lsdtools.compositions.CompositionMember.settings`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:139`.

```python
settings: Mapping[str, Mapping[str, Any]]
```


```python
settings = None
```


### `lsdtools.compositions.CompositionMember.from_s`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:140`.

```python
from_s: float
```


```python
from_s = 0.0
```


### `lsdtools.compositions.CompositionMember.until_s`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:141`.

```python
until_s: Optional[float]
```


```python
until_s = None
```


### `lsdtools.compositions.CompositionMember.window_us`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:158`.

```python
window_us(self) -> tuple[int, Optional[int]]
```


```python
self: (unannotated)
```


Source docstring:

```text
The play window in integer microseconds since Play (``None`` = forever).
```


### `lsdtools.compositions.CompositionMember.to_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:164`.

```python
to_dict(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.compositions.CompositionMember.from_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:173`.

```python
from_dict(cls, value: Any) -> 'CompositionMember'
```


```python
cls: (unannotated)
value: Any
```


## `lsdtools.compositions.CompositionRecord`

Kind: class. Source: `core/lsd/src/lsd/packages/project_compositions.py:190`.

Source docstring:

```text
One composition document, validated for shape (the runtime validates meaning).
```


Implementation alias: `lsd.packages.project_compositions.CompositionRecord`.

### `lsdtools.compositions.CompositionRecord.id`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:193`.

```python
id: str
```


### `lsdtools.compositions.CompositionRecord.name`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:194`.

```python
name: str
```


```python
name = ''
```


### `lsdtools.compositions.CompositionRecord.members`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:195`.

```python
members: Tuple[CompositionMember, ...]
```


```python
members = ()
```


### `lsdtools.compositions.CompositionRecord.clock`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:196`.

```python
clock: CompositionClock
```


```python
clock = CompositionClock()
```


### `lsdtools.compositions.CompositionRecord.systems`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:197`.

```python
systems: Mapping[str, Mapping[str, Any]]
```


```python
systems = None
```


### `lsdtools.compositions.CompositionRecord.active_camera`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:198`.

```python
active_camera: Optional[Mapping[str, str]]
```


```python
active_camera = None
```


### `lsdtools.compositions.CompositionRecord.timeline`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:199`.

```python
timeline: Optional[Timeline]
```


```python
timeline = None
```


### `lsdtools.compositions.CompositionRecord.member_ids`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:239`.

```python
member_ids(self) -> tuple[str, ...]
```


```python
self: (unannotated)
```


### `lsdtools.compositions.CompositionRecord.member`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:242`.

```python
member(self, entity_id: str) -> Optional[CompositionMember]
```


```python
entity_id: str
self: (unannotated)
```


### `lsdtools.compositions.CompositionRecord.to_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:245`.

```python
to_dict(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.compositions.CompositionRecord.from_dict`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:258`.

```python
from_dict(cls, value: Any) -> 'CompositionRecord'
```


```python
cls: (unannotated)
value: Any
```


### `lsdtools.compositions.CompositionRecord.canonical_bytes`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:296`.

```python
canonical_bytes(self) -> bytes
```


```python
self: (unannotated)
```


### `lsdtools.compositions.CompositionRecord.describe`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:310`.

```python
describe(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


Source docstring:

```text
The bounded summary a chooser shows: no timeline body, no settings bodies.
```


## `lsdtools.compositions.MAX_COMPOSITIONS`

Kind: value. Source: `core/lsd/src/lsd/packages/project_compositions.py:29`.

```python
MAX_COMPOSITIONS = 256
```


Implementation alias: `lsd.packages.project_compositions.MAX_COMPOSITIONS`.

## `lsdtools.compositions.MAX_MEMBERS`

Kind: value. Source: `core/lsd/src/lsd/packages/project_compositions.py:30`.

```python
MAX_MEMBERS = 256
```


Implementation alias: `lsd.packages.project_compositions.MAX_MEMBERS`.

## `lsdtools.compositions.ProjectCompositionLibrary`

Kind: class. Source: `core/lsd/src/lsd/packages/project_compositions.py:339`.

Source docstring:

```text
Immutable project composition set with optimistic revision checks.
```


Implementation alias: `lsd.packages.project_compositions.ProjectCompositionLibrary`.

### `lsdtools.compositions.ProjectCompositionLibrary.compositions`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:342`.

```python
compositions: Tuple[CompositionRecord, ...]
```


```python
compositions = ()
```


### `lsdtools.compositions.ProjectCompositionLibrary.revision`

Kind: attribute. Source: `core/lsd/src/lsd/packages/project_compositions.py:343`.

```python
revision: int
```


```python
revision = 0
```


### `lsdtools.compositions.ProjectCompositionLibrary.__iter__`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:362`.

```python
__iter__(self)
```


```python
self: (unannotated)
```


### `lsdtools.compositions.ProjectCompositionLibrary.get`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:368`.

```python
get(self, composition_id: str) -> Optional[CompositionRecord]
```


```python
composition_id: str
self: (unannotated)
```


### `lsdtools.compositions.ProjectCompositionLibrary.save`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:377`.

```python
save(self, record: CompositionRecord, *, expected_revision: Optional[int]=None) -> 'ProjectCompositionLibrary'
```


```python
expected_revision: Optional[int]
record: CompositionRecord
self: (unannotated)
```


### `lsdtools.compositions.ProjectCompositionLibrary.remove`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:386`.

```python
remove(self, composition_id: str, *, expected_revision: Optional[int]=None) -> 'ProjectCompositionLibrary'
```


```python
composition_id: str
expected_revision: Optional[int]
self: (unannotated)
```


### `lsdtools.compositions.ProjectCompositionLibrary.members_of`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:397`.

```python
members_of(self, entity_id: str) -> tuple[str, ...]
```


```python
entity_id: str
self: (unannotated)
```


Source docstring:

```text
The ids of every composition ``entity_id`` plays in.
```


### `lsdtools.compositions.ProjectCompositionLibrary.to_section`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:401`.

```python
to_section(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.compositions.ProjectCompositionLibrary.from_section`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:408`.

```python
from_section(cls, value: Any) -> 'ProjectCompositionLibrary'
```


```python
cls: (unannotated)
value: Any
```


### `lsdtools.compositions.ProjectCompositionLibrary.describe`

Kind: method. Source: `core/lsd/src/lsd/packages/project_compositions.py:430`.

```python
describe(self) -> list[dict[str, Any]]
```


```python
self: (unannotated)
```


## `lsdtools.compositions.RUN_ALL_ID`

Kind: value. Source: `core/lsd/src/lsd/packages/project_compositions.py:28`.

```python
RUN_ALL_ID = 'all'
```


Implementation alias: `lsd.packages.project_compositions.RUN_ALL_ID`.