Spacemap File

In this article:


Create a Spacemap File

A spacemap is an XML document that primarily maps each physical speaker in a space to a Spatial Reality computer and specifies the location of each speaker in 3-dimensional space. Spatial Reality uses the Spacemap to determine information about your speakers and then renders the Scene based on that information and your specific layout. 

Here are some of the basic details you will need to get started with creating a Spacemap:


  • Device ID
    The unique device id (e.g. UUID) of the computer that contributes this speaker's output. On a Mac, the UUID of playback computer can be discovered via the Spatial Reality app computer settings page. You can also find the UUID via the menu bar —  → About This Mac → System Report → Hardware UUID.
  • Channel
    Corresponds to the audio interface (physical hardware, virtual soundcard or virtual aggregate device) channel number for a particular computer→speaker combination. 
  • Position 
    3D position coordinates of a speaker relative to the measurement reference of the Space.


Here's an example of a Spacemap for a Space that utilizes a computer group with two computers and a total of 9 channels. You can learn more about the format for the Spacemap file here

<speaker id="11111111-2222-2222-2222-111111111111" channel="0"
position="-2.0 -2.0 2.0"
type="medium" volumedb="0" name="1"/>
<speaker id="11111111-2222-2222-2222-111111111111" channel="1"
position="-2.0 0 2.0"
type="medium" volumedb="0" name="2"/>
<speaker id="11111111-2222-2222-2222-111111111111" channel="2"
position="-2.0 +2.0 2.0"
type="medium" volumedb="0" name="3"/>
<speaker id="11111111-2222-2222-2222-111111111111" channel="3"
position="0 +2.0 2.0"
type="medium" volumedb="0" name="4"/>
<speaker id="22222222-4444-4444-4444-222222222222" channel="0"
position="+2.0 +2.0 2.0"
type="medium" volumedb="0" name="5"/>
<speaker id="22222222-4444-4444-4444-222222222222" channel="1"
position="+2.0 0 2.0"
type="medium" volumedb="0" name="6"/>
<speaker id="22222222-4444-4444-4444-222222222222" channel="2"
position="+2.0 -2.0 2.0"
type="medium" volumedb="0" name="7"/>
<speaker id="22222222-4444-4444-4444-222222222222" channel="3"
position="0 -2.0 2.0"
type="medium" volumedb="0" name="8"/>
<speaker id="22222222-4444-4444-4444-222222222222" channel="4"
position="-2.0 -2.0 0"
type="subwoofer" volumedb="0" name="9"/>


Replace id, channel, position and add/subtract speakers based on your particular setup. Make sure to save this file with a .spacemap file extension.

Note regarding origin:

Prior to Spatial Reality engine 8.20.0

Explicitly specify the acoustic origin (<origin x="0" y="0" z="0"/>) in your Spacemap. Origin is generally in the center of a Space and all speaker locations are measured from the origin. 

Spatial Reality engine 8.20.0+

Spatial Reality engine will compute the acoustic origin based on the speaker positions. If you need to override the acoustic origin — specify origin (<origin position="0 0 0"/>) in your Spacemap. 


Add a Space Using Spatial Control

Creating a New Space

Once you have created your Spacemap file — you can import it using Spatial Control to create a new Space. You'll want to make sure that this file is available on your phone through the Files app (either via iCloud, 3rd party cloud storage services or AirDrop).

  1. Menu → Manage → (Select a Site) → Create  new Space
  2. Specify a unique Space name
  3. Select the computer group that will be used to drive this Space (a computer group can drive multiple Spaces).


  4. Tap Import File.
  5. From the Files app — select the .spacemap file that you created before.
  6. Tap Done to create the Space. You'll be prompted to restart Spatial Reality to ensure that this newly created Space is activated and available for Spatial Studio and Spatial Control. 


Uploading a New Spacemap for an Existing Space

Navigate to the Space that you would like to upload a new Spacemap for: 

Menu → Manage → (Select a Site) → (Select a Space) → Edit Spacemap



  • To select a new Spacemap for this file — tap Import new Spacemap

    Note: selecting a new .spacemap file will overwrite the existing Spacemap for this Space. We recommend downloading the existing Spacemap first, before making any changes. 

  • From the Files app — select a new .spacemap file. 

    Note: The file must have a .spacemap file extension, and adhere to the Spatial spacemap schema

  • You'll be prompted to restart Spatial Reality to ensure that this newly created Space is activated and available for Spatial Studio and Spatial Control. 
Was this article helpful?
0 out of 0 found this helpful