> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/io-api/osc.md).

# OSC

### Accessing an OSC Object

OSC Objects are accessed through their Scripting ID.

For example:

```python
sp.OSC1
```

If multiple OSC Objects exist in the project, each Object uses its own Scripting ID:

```python
sp.OSC1
sp.OSC2
```

The OSC Object's configured destination and connection settings are used when sending messages from scripting.

### `send()`

Sends an OSC message using the Python value type to determine the message value.

The following value types have been verified:

* `bool`
* `int`
* `float`
* `str`

#### Syntax

```python
sp.OSC1.send(path, value)
```

#### Parameters

| Parameter | Type                          | Description   |
| --------- | ----------------------------- | ------------- |
| `path`    | `str`                         | OSC address   |
| `value`   | `bool`, `int`, `float`, `str` | Value to send |

#### Returns

`None`

#### Boolean

```python
sp.OSC1.send(
    "/api/test/bool",
    True
)
```

#### Integer

```python
sp.OSC1.send(
    "/api/test/int",
    13
)
```

#### Float

```python
sp.OSC1.send(
    "/api/test/float",
    12.5
)
```

#### String

```python
sp.OSC1.send(
    "/api/test/string",
    "Hello"
)
```

### `send_bool()`

Sends a Boolean OSC value.

#### Syntax

```python
sp.OSC1.send_bool(path, value)
```

#### Parameters

| Parameter | Type   | Description   |
| --------- | ------ | ------------- |
| `path`    | `str`  | OSC address   |
| `value`   | `bool` | Boolean value |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_bool(
    "/api/test/enabled",
    True
)
```

### `send_integer()`

Sends an Integer OSC value.

#### Syntax

```python
sp.OSC1.send_integer(path, value)
```

#### Parameters

| Parameter | Type  | Description   |
| --------- | ----- | ------------- |
| `path`    | `str` | OSC address   |
| `value`   | `int` | Integer value |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_integer(
    "/api/test/count",
    13
)
```

### `send_float()`

Sends a Float OSC value.

#### Syntax

```python
sp.OSC1.send_float(path, value)
```

#### Parameters

| Parameter | Type    | Description          |
| --------- | ------- | -------------------- |
| `path`    | `str`   | OSC address          |
| `value`   | `float` | Floating-point value |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_float(
    "/api/test/distance",
    12.5
)
```

### `send_string()`

Sends a String OSC value.

#### Syntax

```python
sp.OSC1.send_string(path, value)
```

#### Parameters

| Parameter | Type  | Description  |
| --------- | ----- | ------------ |
| `path`    | `str` | OSC address  |
| `value`   | `str` | String value |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_string(
    "/api/test/name",
    "Camera A"
)
```

### `send_point()`

Sends a two-component Point value.

#### Syntax

```python
sp.OSC1.send_point(path, value)
```

#### Parameters

| Parameter | Type   | Description             |
| --------- | ------ | ----------------------- |
| `path`    | `str`  | OSC address             |
| `value`   | `list` | Point value as `[x, y]` |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_point(
    "/api/test/point",
    [1.0, 2.0]
)
```

### `send_vector()`

Sends a three-component Vector value.

#### Syntax

```python
sp.OSC1.send_vector(path, value)
```

#### Parameters

| Parameter | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `path`    | `str`  | OSC address                 |
| `value`   | `list` | Vector value as `[x, y, z]` |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_vector(
    "/api/test/position",
    [1.0, 2.0, 3.0]
)
```

### `send_color()`

Sends a Color value.

#### Syntax

```python
sp.OSC1.send_color(path, value)
```

#### Parameters

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `path`    | `str`  | OSC address                                |
| `value`   | `list` | Color value as `[red, green, blue, alpha]` |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_color(
    "/api/test/color",
    [1.0, 0.0, 0.0, 1.0]
)
```

### `send_trigger()`

Sends an OSC Trigger message without an additional value.

#### Syntax

```python
sp.OSC1.send_trigger(path)
```

#### Parameters

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `path`    | `str` | OSC address |

#### Returns

`None`

#### Example

```python
sp.OSC1.send_trigger(
    "/api/test/trigger"
)
```

### Generic vs. Typed Send Functions

Use `send()` when sending a simple Boolean, Integer, Float or String value:

```python
sp.OSC1.send("/api/test/value", 12.5)
```

Use the corresponding typed function when the intended OSC data type should be explicit or when sending Point, Vector, Color or Trigger values:

```python
sp.OSC1.send_vector(
    "/api/test/position",
    [1.0, 2.0, 3.0]
)
```

### Quick Reference

| API                         | Value                         | Returns |
| --------------------------- | ----------------------------- | ------- |
| `send(path, value)`         | `bool`, `int`, `float`, `str` | `None`  |
| `send_bool(path, value)`    | `bool`                        | `None`  |
| `send_integer(path, value)` | `int`                         | `None`  |
| `send_float(path, value)`   | `float`                       | `None`  |
| `send_string(path, value)`  | `str`                         | `None`  |
| `send_point(path, value)`   | `[x, y]`                      | `None`  |
| `send_vector(path, value)`  | `[x, y, z]`                   | `None`  |
| `send_color(path, value)`   | `[r, g, b, a]`                | `None`  |
| `send_trigger(path)`        | —                             | `None`  |