EXA Remix allows any Unity app to play and customize musical performances that were created with EXA: The Infinite Instrument.

There are a few main steps for using EXA Remix in your Unity app:

• Import the EXA Remix package into your Unity project.
  
• Install the desired Layout and Soundfont files.
  
• Add some prefabs to your scene.
  
• Write some code that triggers layout loading and playback.
  
• Optionally, customize the appearance and sound of a layout.

The following sections provide details for each of these steps.

First, obtain ExaRemix.unityPackage directly from Zach -- you can request a copy via email, zach at aesthetic interactive dot com.

Import ExaRemix.unityPackage into your Unity project. The import process adds files to three main directories:

• /Assets/Exa
  
• /Assets/Plugins/Exa
  
• /Assets/StreamingAssets/Exa

You'll also find three example scenes in "/Assets/Exa/Scenes". Note that you'll need to install some Layout and Soundfont files (see the next section) before these scenes will work:

• ExaRemix-FirstExample: Includes a single Layout that loads itself automatically at startup.
  Using in-editor menus/tools (rather than code), you can play the Layout, adjust its audio, and move it around.
  
• ExaRemix-CustomizeAvatarExample: Includes two Layouts that customize the Motion avatars in different ways (all vs. individual customizations).
  
• ExaRemix-ServerTimeExample: Uses the ExaServerTimeSimulator to receive fake server times, which it then uses to update ExaTimeManager. The "SectionStarter" objects allow you to enter a fake server time for a starting a scheduled section playback (in the future or past).

When importing a new version, it's best to first remove the old version (by deleting the directories listed above). You may need to close Unity to fully delete the "Exa.Native.Audio.dll" file, due to the way Unity locks non-managed libraries.

The EXA Remix Unity package does not contain any Layout or Soundfont files, so you'll need to add those manually after importing the package.


EXA ships with several "musical performance" Layouts and hundreds of Soundfonts. You can copy these from EXA's installation directory to create an initial collection for EXA Remix:

[STEAM_DIR]/steamapps/common/EXA - The Infinite Instrument/EXA_Data/StreamingAssets/

• .../ExampleLayouts/
  
• .../Soundfonts/

To find your Steam directory, open your Steam library, right click on "EXA: The Infinite Instrument", and select "Properties". In the popup that appears, open the "Local Files" tab, and then click the "Browse Local Files" button.


The default directories for placing Layout and Soundfont files are:

• /Assets/StreamingAssets/Exa/Layouts/
  
• /Assets/StreamingAssets/Exa/Soundfonts/

Using the files found in the previous step, copy-paste individual Layout files to the "Layouts" directory, and the Soundfont file/folder hierarchy to the "Soundfonts" directory. You don't need to copy all of the Soundfont files -- only the ones that your selected Layouts will need to use.

Regardless of the number of Soundfont files you copy, it is important to maintain their folder structure, since a Layout will search for each Soundfont using both its file name and its relative path (for example: "/Strings/Guitars/acoustic_guitars.sf2").

Let's get some EXA Remix content into your Unity scene.


Add the "ExaRemixLayout" prefab to your scene. This action automatically adds the "ExaRemixShared" prefab to the scene (if necessary), and also adds various "Shared" prefab references to the "Layout" prefab.


The "ExaRemixLayout" prefab has an ExaRemixLoader component attached at its root level. This loader has three main properties for specifying the path to a Layout file:

• Directory Type: Choose "Absolute" if you want to specify the full path to a Layout file. Choose "Relative To Streaming Assets" if the Layout file is within your Unity project's "StreamingAssets" directory.
  
• Directory: Enter a directory path based on your "Directory Type" choice. By default, the relative directory is "Exa/Layouts/". You must include the slash at the end of this path, but not the beginning.
  
• File Name: Enter the full name of the Layout file. By default, the file is "EXA-Show-CircleStyle.exaLayout".

If you want the Layout to load immediately upon app startup, check the "Click To Load Layout" checkbox. This checkbox can also be clicked at runtime; it has the same effect as calling ExaRemixLoader.LoadLayout() via code.


Each "ExaRemixLayout" prefab behaves independently from the others, which means that you can add multiple Layouts to your scene. Multiple Layouts can be present, visible, and playing simultaneously, but note a current limitation is that multiple Layouts cannot be loading simultaneously.


You can choose where a Layout will appear in your scene by moving the position and rotation of the "ExaRemixLayout" prefab. You can do this before or during runtime. See the customization sections below for details about moving and scaling individual elements within a Layout.


Each "ExaRemixLayout" routes all of its Layout's audio through a single Unity AudioSource component. By default, this is configured for spatial audio, with a four-meter audible radius from the center of the Layout. Your app may have vastly different requirements for sound, so adjust these settings accordingly.


The "ExaRemixShared" prefab provides an "Allow Remote Log" checkbox (with "on" default). This provides basic info (i.e. events like ExaRemix started, layout loaded/played, errors) to the EXA server. This remote logging only occurs in builds (not within the Unity editor).

Almost everything about the EXA Remix tool occurs at runtime. Importantly, your app is responsible for telling each "ExaRemixLayout" prefab when to load and play a Layout.


You can specify which Layout file to load via the Unity editor (see the previous section), or by setting these properties via code at runtime.

Each "ExaRemixLayout" prefab has one ExaRemixLoader component attached at the root level. To trigger the loading and building of the Layout file, call the ExaRemixLoader.LoadLayout() method. You can do this at any point during runtime, and should only call this method one time per Layout.

Loading and building a Layout is an asynchronous process, with work spread out across several frames. This is important, as it avoids freezing the app on a particular frame. You can access the progress of these steps using the ExaRemixLoader.GetLoaderProgress() and ExaRemixLoader.GetBuilderProgress() methods. First, the "loader" progress will transition from zero to one (0 to 100%), and then the "builder" progress will do the same. The Layout does not become visible until it is fully loaded, so in some cases, you may wish to provide visual feedback about this progress.


Once the Layout is finished loading and building, it becomes visible in the scene, and it is ready for your app to start its playback.

Every Layout is different, but many of them contain a single main "section" (a collection of "loops" that play in sequence). Because of this, there is no well-defined command to play an entire layout -- instead, a common action is to play its first section.


Find a Layout's section via the ExaRemixPlayer.Sections array, then start its playback immediately via ISection.Play(). Use ISection.Stop() to stop the playback.

Note that some sections include a few "empty" beats at the beginning, so after calling Play(), it may take a moment before the performance audibly/visibly begins.


Find a Layout's loop via the ExaRemixPlayer.Loops array, then start its playback immediately via ILoop.PlayLooped(), which repeats forever, or ILoop.PlayOnce(), which does not repeat. Use ILoop.Stop() to stop the playback.


Both ISection and ILoop also provide "Play" methods for starting playback at a particular time (using a DateTime parameter in UTC format). This time can be in the future or in the past. For times in the past, the section or loop will begin playing somewhere after its beginning point -- as if it had started playing at that past time.


Starting playback at a scheduled time is useful for multi-player scenarios, where you want the musical performance to be synchronized for all users.

EXA Remix provides the ExaTimeManager component to help synchronize a user's local time with your app's server time. Upon app startup, and periodically during runtime, your app should send the current server time (DateTime UTC) as a parameter to the ExaTimeManager.UpdateLatestSync() method.

To synchronize playback across users, your app must pick a server time for playback to start for all users. Send this server time as a parameter to the ExaTimeManager.GetLocalTime() method, which returns the corresponding local time. Then, send the newly-obtained local time as a parameter to one of the ISection or ILoop "Play" methods.

If all goes well, the playback will be closely synchronized for all users. Users that are present from the start will see the entire performance, while users that enter your app later would see the performance already in progress.

There are many ways (not all are covered here) to modify, control, and customize a layout using the EXA Remix tool.


There are no requirements for the space that surrounds a particular Layout -- you could try simple stages, shared social spaces, tiny layouts that play on a table, huge performances looming above an audience, futuristic audio-reactive environments, and beyond!

Of course, there are various factors to consider, like ensuring the Layout does not clip through other surfaces, has a reasonable position and scale, doesn't interfere with interfaces in your app, etc.


If you wish to achieve a similar visual appearance as EXA, you can follow some of the app's various settings. EXA uses deferred rendering, HDR, a bloom filter, and the linear color space. It has no skybox, no ambient color, no shadows, and uses a few point lights to dimly light the avatars and the environment.

Enable the "Use Ringer Lights" checkbox on the "ExaDefaultBuilder" component before loading a layout. This compliments the bloom filter's glow effect -- when the ringer is hit, the ringer lights will illuminate nearby avatars and other geometry.

If your app is set to use the linear color space (via the Unity "Player" settings), ensure that the "Use Linear Color Space" checkbox is enabed on the "ExaDefaultBuilder" component.


Before runtime, you can move/rotate an entire layout via the "ExaRemixLayout" prefab's transform. During runtime, after a layout is loaded, you can move/rotate/scale individual Ringers (and/or their Group containers) using their transforms.

The easiest way to access these items at runtime is with ExaRemixPlayer's Ringers and Groups arrays, and your code can find a specific item via its unique ID. When moving a Ringer, be sure to adjust its main transform (the one with the Ringer component) and not its child transform (which contains its mesh).

The robot avatars will follow the position, rotation, and scale of the Ringers that they touch. This allows you to "remix" the actual performers' motions to suit your app's needs. Note: no scaling changes should be applied to the "Motions" (robot avatars) transforms or their parents -- this would cause the avatar scale changes to be doubly-applied.


Within the "ExaRemixLayout" prefab, the ExaBuilderDefault component is responsible for building and configuring all of the layout's items (Ringers, Loops, Motions, etc.). This default component has properties for customizations like setting the Ringer material and the prefabs to use for the Motion avatars.

The ExaRemixLoader.Builder property must reference a builder component that is a subclass of ExaBuilder. You can implement your own builder component, or create a subclass of ExaBuilderDefault that overrides certain methods.


As mentioned above, the ExaBuilderDefault component has properties for setting the desired Motion avatar prefabs. This includes the "Motion Headset Path To Glow Renderers" array of strings, which tells the Motion class which materials to glow (via the Material.color property). Setting the Motion prefabs within ExaBuilderDefault will cause all of the avatars to have the specified appearance.

To change the appearance of individual Motion avatars, attach one or more ExaBuilderMotionOverride components as siblings of ExaBuilderDefault. This component provides the same Motion-related properties as above, but also provides an array for specifying Loop IDs. Each Motion avatar belongs to a specific Loop, so the Loop ID array tells the ExaBuilderDefault when to apply ExaBuilderMotionOverride's settings.

Note that the Motion avatar's "handles" will automatically have playing tools snapped onto them. This can occur at both ends of the handle. There are currently two versions of the handle prefabs (for Vive and Oculus) due to their different real-world controller sizes. You can use the default avatar's prefabs as a size and position guide.


Each Layout routes its audio through a single AudioSource component, which is contained within the "ExaRemixLayout" prefab. Aside from the "Loop" property (which must be true), all other AudioSource properties are customizable. You can also add effects, add filters, route the audio to a Unity audio mixer, etc. -- you can use it just like any other AudioSource.


There are many other possibilities for customizing or enhancing the Layout playback, but for now, they're beyond the scope of this document.

For example, you could change the sounds that the loops play, change the playback tempo, listen and react to realtime note events, change the appearance of the playing tools that snap to the Motion avatar handles, create dynamic environments that react to various Layout events, build interactive "jukeboxes" that allow users to switch between Layouts, and more. Please contact Zach for more information about these topics.

The license text for EXA Remix is included within the Unity package. In general, the license allows your app to use this package (and the code/assets within it) only for playing EXA Layouts. The license does not, for example, grant permission to reuse its code or libraries for other purposes. You can find this license in the "/Assets/Exa" folder.

EXA Remix also includes some third-party libraries, and the license notes above do not apply to them. Each of these libraries is covered by its own license -- they're all open-source and permissive. You can find these licenses in the "/Assets/StreamingAssets/Exa" folder.

EXA Remix works within Unity, for Windows 64-bit applications. The application does not need to have VR enabled.

UWP/HoloLens, Mac, iOS, and other non-Windows builds are not currently supported.