# ADM-OSC
An industry initiative to standardization of Object Based Audio (OBA) positioning data in live production ecosystems, by implementing the Audio Definition Model (ADM) over Open Sound Control (OSC).
[https://immersive-audio-live.github.io/ADM-OSC/](https://immersive-audio-live.github.io/ADM-OSC/)
## Project Originators
[L-Acoustics](https://www.l-acoustics.com/), [FLUX::](https://www.flux.audio/), [Radio-France](https://www.radiofrance.com/innovation-nouveaux-formats)
## Project Contributors
Adamson, d&b Audiotechnik, DiGiCo, Dolby, Lawo, Magix, Merging Technologies, Meyer Sound, Steinberg
## Context
Immersive audio is gaining ground in different industries, from music streaming to gaming, from live sound to broadcast. [ADM](https://adm.ebu.io/) or Audio Definition Model, is becoming a popular standard metadata model in some of these industries, with serialADM used in broadcast or ADM bwf or xml files used in the studio.
## Motivation and goals
* To facilitate the sharing of audio objects metadata between a live ecosystem and a broadcast or studio ecosystem.
* To define a basic layer of interoperability between Object Editors and Object renderers while not aiming at replacing more complete manufacturer specific protocols or grammars.
* To define a direct translation of the most relevant ADM Object Properties onto a communication protocol widely used in the live industry, [OSC](https://opensoundcontrol.stanford.edu/index.html).
* Keeping the grammar scope aligned with the ADM properties.
* Share this proposal with the EBU so they can become a relay, publish and support this initiative.
* Extend this small grammar to more ADM properties (beds, etc.) in the future.
## Approach
Bijective mapping of the Object subset of ADM with a standard OSC grammar.
## Why OSC ?
* Lightweight network protocol
* Easy to implement
* Human readable
* Supports wildcards and bundles
* Specification: [Open Sound Control website](http://opensoundcontrol.org/)
* Available in a plethora of professional audio hardware and software devices
## General principles
* Sender (client)
* Object Editor sending positioning data to one or more receivers.
* Position data is always normalized
* Receiver (server)
* Handles the (optional) local scaling of normalized data: x, y, z, distance
* The receiver can be a DAW, an ADM renderer, an object editor, a bridge (ADM-OSC <-> sADM)
## Current status
The current dictionary covers most Object properties from the Audio Definition model.
A more complete dictionary is being discussed to cover the remaining parts of the Audio Definition model.
OSC Live test tool (talker and listener OSC Live test tool) is now available.
## Current Specification
See Repository.
## Current Discussions
See Issues.
## Current development & tests tools
* [**Specifications**](https://github.com/immersive-audio-live/ADM-OSC/blob/main/Source/ADM-OSC%20Specification.xlsx)
* [Chataigne module](https://github.com/madees/ADM-OSC-Chataigne-Module) (Mathieu Delquignies / d&b audiotechnik)
* to retreive parameters or control ADM-OSC object based audio (OBA) software or hardware with OSC protocol.
* Tester **Desktop application** (Jose Gaudin / Meyer Sound)
* [download from resources directory](https://github.com/immersive-audio-live/ADM-OSC/tree/main/Resources)
* Validator, Test and Stress Test **Python Module** (Gael Martinet / FLUX:: SE)
* adm_osc module is available to install through pip :
```shell
pip install adm-osc
```
quick examples:
```python
from adm_osc import OscClientServer
# create a basic client/server that implement basic ADM-OSC communication with stable parameters
# + command monitoring and analyze
cs = OscClientServer(address='127.0.0.1', out_port=9000, in_port=9001)
# send some individual parameters
cs.send_object_position_azimuth(object_number=1, v=-30.0)
cs.send_object_position_elevation(object_number=1, v=0.0)
cs.send_object_position_distance(object_number=1, v=2.0)
# or pack them
cs.send_object_polar_position(object_number=1, pos=[-30.0, 0.0, 2.0])
# in cartesian coordinates
cs.send_object_cartesian_position(object_number=1, pos=[-5.0, 8.0, 0.0])
# see documentation for full list of available functions
# when receiving an adm osc command its analyze will be printed on the command output window
#
# e.g.
#
# >> received valid adm message for obj :: 1 :: gain (0.7943282127380371)
# >> received valid adm message for obj :: 1 :: position aed (20.33701515197754, 0.0, 0.8807612657546997)
# >> received valid adm message for obj :: 1 :: position xyz (-0.2606865465641022, 0.8273822069168091, 0.0)
# >>
# >> ERROR: unrecognized ADM address : "/adm/obj/1/bril" ! unknown command "/bril/"
# >> ERROR: arguments are malformed for "/adm/obj/1/gain :: (1.4791083335876465,)":
# >> argument 0 "1.4791083335876465" out of range ! it should be less or equal than "1.0"
```
```python
from adm_osc import TestClient
from adm_osc.protocol import ValueType as vt
# create a test client, assume default address (local: '127.0.0.1')
# test client can be used to test how receiver will handle all kind of parameters and parameters value range
sender = TestClient(out_port=9000)
# all stable parameters for a specific object
sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Min)
sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Max)
sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Default)
sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Random)
# all stable parameters for a range of objects
sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Min)
sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Max)
sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Default)
sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Random)
# all stable parameters for all objects
sender.set_all_objects_stable_parameters_predefined_value(vt.Min)
sender.set_all_objects_stable_parameters_predefined_value(vt.Max)
sender.set_all_objects_stable_parameters_predefined_value(vt.Default)
sender.set_all_objects_stable_parameters_predefined_value(vt.Random)
# see documentation for full list of available functions
```
```python
from adm_osc import StressClient
# create a stress client, assume default address (local: '127.0.0.1')
# stress client will send huge amount of data to stress test the receivers
sender = StressClient(out_port=9000)
# do stress test in cartesian coordinates
sender.stress_cartesian_position(number_of_objects=64, duration_in_second=60.0, interval_in_milliseconds=10.0)
# do stress test in polar coordinates
sender.stress_polar_position(number_of_objects=64, duration_in_second=60.0, interval_in_milliseconds=10.0)
```
* [full documentation](Source/adm_osc/doc/documentation.md).
* [Source directory](https://github.com/immersive-audio-live/ADM-OSC/tree/main/Source)
## Currently supported in
SPAT Revolution (FLUX::), L-ISA Controller (L-Acoustics), Ovation (Merging Technologies), Nuendo (Steinberg), SpaceMap Go (Meyer Sound), QLAB 5 (Figure 53), Space Controller (Sound Particles), Modulo Kinetic (Modulo Pi), Iosono (Barco). FletcherMAchine (Adamson)
Raw data
{
"_id": null,
"home_page": "https://github.com/immersive-audio-live/ADM-OSC",
"name": "adm-osc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "adm, osc, clientServer, validation, tests, stress, setuptools, development",
"author": "Gael Martinet",
"author_email": "gael@flux.audio",
"download_url": "https://files.pythonhosted.org/packages/6b/2c/914fd8d5c4edf1a98a312ee6b10225f8e16eed8331fb7b43d6cf0402dbd1/adm_osc-1.0.1.tar.gz",
"platform": null,
"description": "# ADM-OSC\n\nAn industry initiative to standardization of Object Based Audio (OBA) positioning data in live production ecosystems, by implementing the Audio Definition Model (ADM) over Open Sound Control (OSC).\n\n[https://immersive-audio-live.github.io/ADM-OSC/](https://immersive-audio-live.github.io/ADM-OSC/)\n\n## Project Originators\n\n[L-Acoustics](https://www.l-acoustics.com/), [FLUX::](https://www.flux.audio/), [Radio-France](https://www.radiofrance.com/innovation-nouveaux-formats)\n\n## Project Contributors\n\nAdamson, d&b Audiotechnik, DiGiCo, Dolby, Lawo, Magix, Merging Technologies, Meyer Sound, Steinberg\n\n## Context\n\nImmersive audio is gaining ground in different industries, from music streaming to gaming, from live sound to broadcast. [ADM](https://adm.ebu.io/) or Audio Definition Model, is becoming a popular standard metadata model in some of these industries, with serialADM used in broadcast or ADM bwf or xml files used in the studio.\n\n## Motivation and goals\n\n* To facilitate the sharing of audio objects metadata between a live ecosystem and a broadcast or studio ecosystem.\n* To define a basic layer of interoperability between Object Editors and Object renderers while not aiming at replacing more complete manufacturer specific protocols or grammars.\n* To define a direct translation of the most relevant ADM Object Properties onto a communication protocol widely used in the live industry, [OSC](https://opensoundcontrol.stanford.edu/index.html).\n* Keeping the grammar scope aligned with the ADM properties.\n* Share this proposal with the EBU so they can become a relay, publish and support this initiative.\n* Extend this small grammar to more ADM properties (beds, etc.) in the future.\n\n## Approach\n\nBijective mapping of the Object subset of ADM with a standard OSC grammar.\n\n## Why OSC ?\n\n* Lightweight network protocol\n* Easy to implement\n* Human readable\n* Supports wildcards and bundles\n* Specification: [Open Sound Control website](http://opensoundcontrol.org/)\n* Available in a plethora of professional audio hardware and software devices\n\n## General principles\n\n* Sender (client)\n * Object Editor sending positioning data to one or more receivers.\n * Position data is always normalized\n* Receiver (server)\n * Handles the (optional) local scaling of normalized data: x, y, z, distance\n * The receiver can be a DAW, an ADM renderer, an object editor, a bridge (ADM-OSC <-> sADM)\n \n## Current status\n\nThe current dictionary covers most Object properties from the Audio Definition model.\nA more complete dictionary is being discussed to cover the remaining parts of the Audio Definition model.\nOSC Live test tool (talker and listener OSC Live test tool) is now available.\n\n## Current Specification\n\nSee Repository.\n\n## Current Discussions\n\nSee Issues.\n\n## Current development & tests tools\n\n* [**Specifications**](https://github.com/immersive-audio-live/ADM-OSC/blob/main/Source/ADM-OSC%20Specification.xlsx)\n\n* [Chataigne module](https://github.com/madees/ADM-OSC-Chataigne-Module) (Mathieu Delquignies / d&b audiotechnik)\n * to retreive parameters or control ADM-OSC object based audio (OBA) software or hardware with OSC protocol.\n \n* Tester **Desktop application** (Jose Gaudin / Meyer Sound)\n * [download from resources directory](https://github.com/immersive-audio-live/ADM-OSC/tree/main/Resources)\n\n* Validator, Test and Stress Test **Python Module** (Gael Martinet / FLUX:: SE)\n * adm_osc module is available to install through pip :\n \n ```shell\n pip install adm-osc\n ```\n\n quick examples:\n\n ```python\n from adm_osc import OscClientServer\n \n # create a basic client/server that implement basic ADM-OSC communication with stable parameters \n # + command monitoring and analyze\n cs = OscClientServer(address='127.0.0.1', out_port=9000, in_port=9001)\n\n # send some individual parameters \n cs.send_object_position_azimuth(object_number=1, v=-30.0)\n cs.send_object_position_elevation(object_number=1, v=0.0)\n cs.send_object_position_distance(object_number=1, v=2.0)\n\n # or pack them\n cs.send_object_polar_position(object_number=1, pos=[-30.0, 0.0, 2.0])\n \n # in cartesian coordinates\n cs.send_object_cartesian_position(object_number=1, pos=[-5.0, 8.0, 0.0])\n \n # see documentation for full list of available functions\n \n # when receiving an adm osc command its analyze will be printed on the command output window\n #\n # e.g.\n #\n # >> received valid adm message for obj :: 1 :: gain (0.7943282127380371)\n # >> received valid adm message for obj :: 1 :: position aed (20.33701515197754, 0.0, 0.8807612657546997)\n # >> received valid adm message for obj :: 1 :: position xyz (-0.2606865465641022, 0.8273822069168091, 0.0)\n # >>\n # >> ERROR: unrecognized ADM address : \"/adm/obj/1/bril\" ! unknown command \"/bril/\"\n # >> ERROR: arguments are malformed for \"/adm/obj/1/gain :: (1.4791083335876465,)\":\n # >> argument 0 \"1.4791083335876465\" out of range ! it should be less or equal than \"1.0\"\n \n ```\n \n ```python\n from adm_osc import TestClient\n from adm_osc.protocol import ValueType as vt\n # create a test client, assume default address (local: '127.0.0.1')\n # test client can be used to test how receiver will handle all kind of parameters and parameters value range\n sender = TestClient(out_port=9000)\n \n # all stable parameters for a specific object\n sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Min)\n sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Max)\n sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Default)\n sender.set_object_stable_parameters_predefined_value(object_number=1, vt.Random)\n \n # all stable parameters for a range of objects\n sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Min)\n sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Max)\n sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Default)\n sender.set_objects_stable_parameters_predefined_value(objects_range=range(1, 64), vt.Random)\n \n # all stable parameters for all objects\n sender.set_all_objects_stable_parameters_predefined_value(vt.Min)\n sender.set_all_objects_stable_parameters_predefined_value(vt.Max)\n sender.set_all_objects_stable_parameters_predefined_value(vt.Default)\n sender.set_all_objects_stable_parameters_predefined_value(vt.Random)\n \n # see documentation for full list of available functions\n ```\n\n ```python\n from adm_osc import StressClient\n # create a stress client, assume default address (local: '127.0.0.1')\n # stress client will send huge amount of data to stress test the receivers\n sender = StressClient(out_port=9000)\n # do stress test in cartesian coordinates\n sender.stress_cartesian_position(number_of_objects=64, duration_in_second=60.0, interval_in_milliseconds=10.0)\n # do stress test in polar coordinates\n sender.stress_polar_position(number_of_objects=64, duration_in_second=60.0, interval_in_milliseconds=10.0)\n ```\n\n * [full documentation](Source/adm_osc/doc/documentation.md).\n * [Source directory](https://github.com/immersive-audio-live/ADM-OSC/tree/main/Source)\n\n## Currently supported in\n\nSPAT Revolution (FLUX::), L-ISA Controller (L-Acoustics), Ovation (Merging Technologies), Nuendo (Steinberg), SpaceMap Go (Meyer Sound), QLAB 5 (Figure 53), Space Controller (Sound Particles), Modulo Kinetic (Modulo Pi), Iosono (Barco). FletcherMAchine (Adamson)\n",
"bugtrack_url": null,
"license": null,
"summary": "ADM-OSC client/server Python module for ADM-OSC protocol validation, tests and stress",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/immersive-audio-live/ADM-OSC/issues",
"Homepage": "https://github.com/immersive-audio-live/ADM-OSC",
"Source": "https://github.com/immersive-audio-live/ADM-OSC/"
},
"split_keywords": [
"adm",
" osc",
" clientserver",
" validation",
" tests",
" stress",
" setuptools",
" development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01fcbb406b4467faca95018f894c9c1f237896f811dfb45dd4cabaa7d4082c27",
"md5": "0c7dd1ed545a1084bc63f92b750a6464",
"sha256": "68565749faabe161e388a79f0eb5ac94b57e0627e21c02e2f6fe8358c10a5d79"
},
"downloads": -1,
"filename": "adm_osc-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c7dd1ed545a1084bc63f92b750a6464",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 23090,
"upload_time": "2024-10-01T12:56:32",
"upload_time_iso_8601": "2024-10-01T12:56:32.972249Z",
"url": "https://files.pythonhosted.org/packages/01/fc/bb406b4467faca95018f894c9c1f237896f811dfb45dd4cabaa7d4082c27/adm_osc-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b2c914fd8d5c4edf1a98a312ee6b10225f8e16eed8331fb7b43d6cf0402dbd1",
"md5": "3c50578a7be67b67033e679217b6041c",
"sha256": "90468ad18b9586ce2aedb01e22b8fe2d7f7559246fda85530d6fef28785028e6"
},
"downloads": -1,
"filename": "adm_osc-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3c50578a7be67b67033e679217b6041c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 23996,
"upload_time": "2024-10-01T12:56:34",
"upload_time_iso_8601": "2024-10-01T12:56:34.314313Z",
"url": "https://files.pythonhosted.org/packages/6b/2c/914fd8d5c4edf1a98a312ee6b10225f8e16eed8331fb7b43d6cf0402dbd1/adm_osc-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-01 12:56:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "immersive-audio-live",
"github_project": "ADM-OSC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "adm-osc"
}
JSON
