Basic Example¶

This is a basic processor file which can be considered a barebone and a start point for your own. All it does is to syncronize all the objects between the master and the slaves machines.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

 import blendervr

 if blendervr.is_console():
     class Processor(blendervr.processor.getProcessor()):
         def __init__(self, console):
             global try_wait_user_name, try_chooser, try_console_arc_balls
             super(Processor, self).__init__(console)

         def useLoader(self):
             return True

 elif blendervr.is_creating_loader():
     import bpy

     class Processor(blendervr.processor.getProcessor()):
         def __init__(self, creator):
             super(Processor, self).__init__(creator)

 elif blendervr.is_virtual_environment():
     import bge

     class Processor(blendervr.processor.getProcessor()):
         def __init__(self, parent):
             super(Processor, self).__init__(parent)

             if self.blenderVR.isMaster():
                 self.blenderVR.getSceneSynchronizer().\
                         getItem(bge.logic).activate(True, True)

The file is split in three parts:

1. Console
2. Update Loader
3. Virtual Environment

The processor file is called three times, and each time a section of it is called.

if blendervr.is_console():
    class Processor(blendervr.processor.getProcessor()):
        def __init__(self, console):
            global try_wait_user_name, try_chooser, try_console_arc_balls
            super(Processor, self).__init__(console)

        def useLoader(self):
            return True

elif blendervr.is_creating_loader():
    import bpy

    class Processor(blendervr.processor.getProcessor()):
        def __init__(self, creator):
            super(Processor, self).__init__(creator)

elif blendervr.is_virtual_environment():
    import bge

    class Processor(blendervr.processor.getProcessor()):
        def __init__(self, parent):
            super(Processor, self).__init__(parent)

            if self.blenderVR.isMaster():
                self.blenderVR.getSceneSynchronizer().\
                        getItem(bge.logic).activate(True, True)

Introduction¶

OSC is integrated as a BlenderVR plugin, to be defined in the .xml configuration file. The OSC API is e.g. used for BlenderVR synchornization with the Max/MSP based Sound Rendering Engine.

As a start, you’ll want to adapt BlenderVR configuration file to your architecture, process detailed in the how to use OSC section.

For the sake of illustration, say you’re using a configuration file which <osc> subsection looks like:

<plugins>

  <osc host='localhost' port='3819' configuration='Laptop SPAT' max_audio_objects='8'>

    <user listener='Binaural 1' viewer='user A' />
    <user listener='Ambisonic' />
    <user listener='Stereo' />

  </osc>

</plugins>

Every parameter defined in these lines will be sent to the OSC client at BlenderVR startup (but for osc host and port), see the how to use OSC section for more details on each flag.

Received by the OSC client at BlenderVR start:

/global configuration Laptop SPAT
/global max_audio_objects 8
/user 0 name Binaural 1
/user 1 name Ambisonic
/user 2 name Stereo

OSC = self.blenderVR.getPlugin('osc')

with self representing the BlenderVR processor object, granting access to BlenderVR OSC module and its API (OSC in python code bellow refers to this module).

From there, BlenderVR OSC API proposes 4 different class of messages: global, user, object and objectUser.

Global Messages¶

Global messages can be used for global configuration of the Sound Engine (e.g. global volume, start, etc.).

osc_global = OSC.getGlobal()
osc_global.start(True)
osc_global.mute(True)
osc_global.volume('%45')

will send the following messages to the Sound Engine:

/global start 1
/global mute 1
/global volume %45

with volume being either absolute balue (e.g. %45) or +/- relative add (e.g. +3 or -7).

User Messages¶

User messages can be used for user specific configuration of the Sound Engine (e.g. user volume, ``user start`, etc.). See OSC users as listeners, or rather as the media + rendering technique that produces a sound (speakers set + ambisonic, headset + binaural, etc.).

osc_user = OSC.getUser('Binaural 1')
# or equivalently
bvr_user = self.blenderVR.getUserByName('user A')
osc_user = OSC.getUser(bvr_user)
# --
osc_user.start(True)
osc_user.mute(True)
osc_user.volume('%45')

The first line grants access to the OSC user named Binaural 1 in the configuration file (attached to BlenderVR ``user A`, see above). Thanks to the definition of user / listener in the configuration file, each BlenderVR user position/orientation (‘user A’ here) will be synchronized form BlenderVR to the sound rendering engine.

The next lines will send the following messages to the Sound Engine:

/user 1 start 1
/user 1 mute 1
/user 1 volume %45

and BlenderVR will constantly update osc user position with messages like:

/user 1 position 1. 0. 0. 0. 0. -1. -0. 0. 0. 0. -1. 0. 0. 0. 0. 1.

where the 16 floats represent the 4x4 homogeneous Matrix of user position/orientation in the virtual world.

Object Messages¶

Object messages can be used for object specific configuration of the Sound Engine (e.g. object volume, object start, etc.). See OSC objects as a virtual sound source instantiated in the Sound Engine, that will be attached to a BlenderVR object (e.g. a Blender KX_Game_Object) in the scene and eventually heard by one/many OSC user/listener (see objectUser messages bellow).

scene = bge.logic.getCurrentScene()
kx_object = scene.objects['Cube']
osc_object = OSC.getObject(kx_object)
osc_object.sound('HeyPachuco.wav')
osc_object.start(True)
osc_object.mute(False)
osc_object.volume('%45')

The first line grants access to the OSC object that will be attached to the KX_GameObject Cube in the blender scene. This first line triggers a callback that will synchronize the object position in the The next lines will send the following messages to the Sound Engine:

/object 1 sound HeyPachuco.wav
/object 1 start 1
/object 1 mute 0
/object 1 volume %45

and BlenderVR will constantly update osc object position with messages like:

/object 1 position 0.54156 0.132934 -0.830085 0. -0.840592 0.07291 -0.536739 0. -0.01083 0.98844 0.151228 0. -11.07954 0.250764 -14.501128 1.

ObjectUser Messages¶

This class of messages allow to dynamically route object sounds to osc users (listeners) audio input. basically, sending:

/objectUser 1 0 mute 0

will tell the sound engine to route osc object 1 to osc user 0 (Binaural 1 here, see above), hence the listener Binaural 1 will hear the sound of kx_object 1.

The line SC.getObjectUser(osc_object, osc_user)` grants access to the OSC objectUser that will control the link between the sound from the osc object (attached to the blender object ``Cube) to the osc user ``Binaural 1`. The next two lines will send the following messages to the Sound Engine:

/objectUser 1 0 mute 0
/objectUser 1 0 volume %50

Example¶

The basic-osc.blend in the BlenderVR samples will send the following OSC messages to the Sound Engine (it’s actually the code in the basic-osc.processor.py along with the osc plugin definition in the ``//blender-vr/configuration/main.xml` configuration file that will send the following messages):

/global configuration Laptop SPAT
/global max_audio_objects 20
/global volume %40
/global start 1
/global mute 0
/object 1 sound HeyPachuco.wav
/object 1 loop 1
/object 1 volume %45
/object 1 start 1
/object 1 position 0.54156 0.132934 -0.830085 0. -0.840592 0.07291 -0.536739 0. -0.01083 0.98844 0.151228 0. -11.07954 0.250764 -14.501128 1.
/object 1 mute 0
/user 2 name Ambisonic
/user 2 hrtf 0
/user 2 volume %50
/user 2 position
/user 2 start 0
/user 2 mute 0
/user 2 warmth 0
/user 2 brightness 0
/user 2 presence 0
/user 2 reverb_volume 0
/user 2 running_reverb 0
/user 2 late_reverb 0
/user 2 envelop 0
/user 2 heavyness 0
/user 2 livelyness 0
/user 0 name Binaural 1
/user 0 hrtf 0
/user 0 volume %80
/user 0 position 1. 0. 0. 0. 0. -1. -0. 0. 0. 0. -1. 0. 0. 0. 0. 1.
/user 0 start 1
/user 0 mute 0
/user 0 warmth 0
/user 0 brightness 0
/user 0 presence 0
/user 0 reverb_volume 0
/user 0 running_reverb 0
/user 0 late_reverb 0
/user 0 envelop 0
/user 0 heavyness 0
/user 0 livelyness 0
/user 1 name Binaural 2
/user 1 hrtf 0
/user 1 volume %50
/user 1 position 1. 0. 0. 0. 0. -1. -0. 0. 0. 0. -1. 0. 0. 0. 0. 1.
/user 1 start 0
/user 1 mute 0
/user 1 warmth 0
/user 1 brightness 0
/user 1 presence 0
/user 1 reverb_volume 0
/user 1 running_reverb 0
/user 1 late_reverb 0
/user 1 envelop 0
/user 1 heavyness 0
/user 1 livelyness 0
/user 3 name Stereo
/user 3 hrtf 0
/user 3 volume %50
/user 3 position
/user 3 start 0
/user 3 mute 0
/user 3 warmth 0
/user 3 brightness 0
/user 3 presence 0
/user 3 reverb_volume 0
/user 3 running_reverb 0
/user 3 late_reverb 0
/user 3 envelop 0
/user 3 heavyness 0
/user 3 livelyness 0
/objectUser 1 0 volume %50
/objectUser 1 0 mute 0
/object 1 position 0.529771 0.133939 -0.837498 0. -0.848072 0.071046 -0.525097 0. -0.01083 0.98844 0.151228 0. -11.182952 0.225004 -14.340163 1.
/object 1 position 0.517878 0.134918 -0.844748 0. -0.855386 0.069169 -0.513353 0. -0.01083 0.98844 0.151228 0. -11.284078 0.199052 -14.177782 1.
(... moving objects / users position updates ...)