# OSC for Duit
[](https://pypi.org/project/duit-osc/)
[
](https://github.com/cansik/duit-osc)
Open Sound Control communication for duit datafields.
This is an addon module for the data ui toolkit ([duit](https://github.com/cansik/duit)) which adds OSC in and output support for [DataFields](https://cansik.github.io/duit/duit.html#data-field).
## Installation
The package can ben installed directly from [PyPI](https://pypi.org/project/duit-osc/).
```
pip install duit-osc
```
## Documentation
Duit-osc uses [python-osc](https://pypi.org/project/python-osc/) (`~=1.8`) as OSC backend to receive and send message. The main class is the `OscService` which handles the incoming and outgoing OSC server and client. It also maps the annotated `DataFields` to the corresponding route.
### OscEndpoint
It is possible to annotate existing `DataFields` with the `OscEndpoint` annotation. This annotation later tell the `OscService` if the field has to be exposed over OSC. It is recommended to gather all DataFields in a single object:
```python
from duit_osc.OscEndpoint import OscEndpoint
class Config:
def __init__(self):
self.name = DataField("Cat") | OscEndpoint()
```
By default, the name of the variable (e.g. `name`) is used as OSC address identifier. It is possible to change the name through the `OscEndpoint` annotation.
```python
self.name = DataField("Cat") | OscEndpoint(name="the-cats-name")
```
#### Direction
By default, an annotated `DataField` sends out an OSC message on change and is changed by incoming OSC messages. This behaviour can be controlled by the `OscDirection` option of the `OscEndpoint` annotation.
```python
from duit_osc.OscDirection import OscDirection
# ...
self.name = DataField("Cat") | OscEndpoint(direction=OscDirection.Send)
```
- `OscDirection`
- Send - *Does only send the datafield value on change.*
- Receive - *Does only receive the datafield value.*
- Bidirectional (Default) - *Sends and receives the value over OSC*
### OscService
As already mentioned, the OscService handles the OSC server and mapping with the `DataFields`. Here is a simple example on how to create an `OscService`, add the previous defined config and start the service.
```python
# create an actual instance of the config
config = Config()
# create an osc service
osc_service = OscService()
# add the config object (create mapping) under the route "/config"
osc_service.add_route("/config", config)
# print the api description of the service (experimental)
print(osc_service.api_description())
# run the service
osc_service.run()
```
#### Settings
The `OscService` has several default arguments, like the `host`, `in_port`, `out_port` and so on. These can be changed before the service is started:
```python
# OscService parameters and the default values
host: str = "0.0.0.0", # on which interface the service is running
in_port: Optional[int] = 8000, # on which port the OscServer is started
out_port: Optional[int] = 9000, # on which port the OscClient is sending
allow_broadcast: bool = True, # if broadcasting is allowed
send_on_receive: bool = False # Indicated if a message that has been received should be also sent out again (reply the change back)
```
#### Routes
It is possible to add various objects to the OscService, each with a unique route (address).
```python
osc_service.add_route("/config", config)
```
Each `DataField` is added under this route, so for example the `name` field would get the OSC address `/config/name`.
#### Receiving Data and Events
On receiving an address that corresponds to a DataField, the arguments of the message are passed as the value to DataField. If no arguments are passed, the `on_change` event of the DataField is fired, or if it's value is a `method`, the method is called.
#### Start
To start the service, it is necessary to call `run()`. This is a blocking method, which does not return until the service is shutdown. If it should run as a background thread, use the `run_async()` method:
```python
# run blocking
osc_service.run()
# run in seperate thread
osc_service.run_async()
```
#### API Description
It is possible to print an API description. This is highly experimental and will change in the future:
```python
print(osc_service.api_description())
```
## About
Copyright (c) 2024 Florian Bruggisser
Raw data
{
"_id": null,
"home_page": "https://github.com/cansik/duit-osc",
"name": "duit-osc",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Florian Bruggisser",
"author_email": "github@broox.ch",
"download_url": null,
"platform": null,
"description": "# OSC for Duit\n[](https://pypi.org/project/duit-osc/)\n[\n](https://github.com/cansik/duit-osc)\n\n\nOpen Sound Control communication for duit datafields.\n\nThis is an addon module for the data ui toolkit ([duit](https://github.com/cansik/duit)) which adds OSC in and output support for [DataFields](https://cansik.github.io/duit/duit.html#data-field).\n\n## Installation\nThe package can ben installed directly from [PyPI](https://pypi.org/project/duit-osc/).\n\n```\npip install duit-osc\n```\n\n## Documentation\nDuit-osc uses [python-osc](https://pypi.org/project/python-osc/) (`~=1.8`) as OSC backend to receive and send message. The main class is the `OscService` which handles the incoming and outgoing OSC server and client. It also maps the annotated `DataFields` to the corresponding route.\n\n### OscEndpoint\nIt is possible to annotate existing `DataFields` with the `OscEndpoint` annotation. This annotation later tell the `OscService` if the field has to be exposed over OSC. It is recommended to gather all DataFields in a single object:\n\n```python\nfrom duit_osc.OscEndpoint import OscEndpoint\n\nclass Config:\n def __init__(self):\n self.name = DataField(\"Cat\") | OscEndpoint()\n```\n\nBy default, the name of the variable (e.g. `name`) is used as OSC address identifier. It is possible to change the name through the `OscEndpoint` annotation.\n\n```python\nself.name = DataField(\"Cat\") | OscEndpoint(name=\"the-cats-name\")\n```\n\n#### Direction\nBy default, an annotated `DataField` sends out an OSC message on change and is changed by incoming OSC messages. This behaviour can be controlled by the `OscDirection` option of the `OscEndpoint` annotation.\n\n```python\nfrom duit_osc.OscDirection import OscDirection\n\n# ...\nself.name = DataField(\"Cat\") | OscEndpoint(direction=OscDirection.Send)\n```\n\n- `OscDirection`\n - Send - *Does only send the datafield value on change.*\n - Receive - *Does only receive the datafield value.*\n - Bidirectional (Default) - *Sends and receives the value over OSC*\n\n### OscService\nAs already mentioned, the OscService handles the OSC server and mapping with the `DataFields`. Here is a simple example on how to create an `OscService`, add the previous defined config and start the service.\n\n```python\n# create an actual instance of the config\nconfig = Config()\n\n# create an osc service\nosc_service = OscService()\n\n# add the config object (create mapping) under the route \"/config\"\nosc_service.add_route(\"/config\", config)\n\n# print the api description of the service (experimental)\nprint(osc_service.api_description())\n\n# run the service\nosc_service.run()\n```\n\n#### Settings\n\nThe `OscService` has several default arguments, like the `host`, `in_port`, `out_port` and so on. These can be changed before the service is started:\n\n```python\n# OscService parameters and the default values\nhost: str = \"0.0.0.0\", # on which interface the service is running\nin_port: Optional[int] = 8000, # on which port the OscServer is started\nout_port: Optional[int] = 9000, # on which port the OscClient is sending\nallow_broadcast: bool = True, # if broadcasting is allowed\nsend_on_receive: bool = False # Indicated if a message that has been received should be also sent out again (reply the change back)\n```\n\n#### Routes\nIt is possible to add various objects to the OscService, each with a unique route (address).\n\n```python\nosc_service.add_route(\"/config\", config)\n```\n\nEach `DataField` is added under this route, so for example the `name` field would get the OSC address `/config/name`.\n\n#### Receiving Data and Events\nOn receiving an address that corresponds to a DataField, the arguments of the message are passed as the value to DataField. If no arguments are passed, the `on_change` event of the DataField is fired, or if it's value is a `method`, the method is called.\n\n#### Start\nTo start the service, it is necessary to call `run()`. This is a blocking method, which does not return until the service is shutdown. If it should run as a background thread, use the `run_async()` method:\n\n```python\n# run blocking\nosc_service.run()\n\n# run in seperate thread\nosc_service.run_async()\n```\n\n#### API Description\nIt is possible to print an API description. This is highly experimental and will change in the future:\n\n```python\nprint(osc_service.api_description())\n```\n \n## About\nCopyright (c) 2024 Florian Bruggisser\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "OSC communication support for duit datafields.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/cansik/duit-osc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1eba35717f3b9293e929c63c0986b37f540c7e6b92c53ddf5f7921405c32a78b",
"md5": "7d1c1dd3c96217e2ad49081e75762eaa",
"sha256": "5ba4eac91fd4944a2314fdf909a109de53c5ad6d8dd64c4da438bd91ac6d152d"
},
"downloads": -1,
"filename": "duit_osc-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d1c1dd3c96217e2ad49081e75762eaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10707,
"upload_time": "2024-11-01T13:43:28",
"upload_time_iso_8601": "2024-11-01T13:43:28.748955Z",
"url": "https://files.pythonhosted.org/packages/1e/ba/35717f3b9293e929c63c0986b37f540c7e6b92c53ddf5f7921405c32a78b/duit_osc-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-01 13:43:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cansik",
"github_project": "duit-osc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "duit-osc"
}
JSON
