Tutorial: Advanced use

All that you need to know to fully enjoy AudioSpace.

Visualization modes

At the core of AudioSpace are the various visualization elements and their adjustments. Please read the tutorial for basic use first if you are not yet familiar with how to move and look around or how to open the menu and use it.

Visualizations are divided in three groups:

• 2D visualizations for the walls, floor and roof
  
• 3D visualizations inside the room
  
• 3D visualizations in the surrounding space

For the walls, floor and roof, following set of 2D-visualization modes are available:

• vectorscope: reflects the properties of a stereo audio signal
  
• phase wheel: based on audio phase and magnitude analysis
  
• spectrum columns: spectral contents of the audio (with adjustable resolution)
  
• spectrogram: scrolling spectra, magnitude visualized with brightness at each frequency
  
• waveforms: separate waveforms for low, mid and high frequency bands, or a single full-band waveform when all frequency bands are turned off
  
• media layers: pictures, videos and audio playback (more info in the next chapter)

Each visualization can be toggled on and off with the corresponding button. Initially each wall (and floor and roof) consist of a single, full-size visualization panel. More visualization panels can be added on the same wall with the small + buttons, either below or to next to the panel for with the menu was opened (indicated with a green rectangle around the panel). In the above picture, menu is currently open for the spectral columns panel that fills the bottom half of the wall. Turning spectral columns off (by zapping the spectral columns button) would hide this panel, and the wall would be split with the remaining two panels: multiband waveform on the left and vectorscope on the right, both using the full height of the wall.

Color adjustments (below the visualization mode selection) affect always the panel for which the menu is open; selected color palette remains unchanged when a different visualization mode is selected for this panel. Color for the low, mid and high frequency bands can be selected separately (with the hue/saturation circle and the lightness slider next to it), but most of the time the palette presets on the left will be enough. Using the auto-palette will vary colors depending on the location.

The parameter sliders on the lower right corner are specific to each visualization mode and will remember their settings as long as the panel exists. What these do depend on the mode, but usually the leftmost will adjust visualization brightness, the middle one is for speed / liveliness, and the right one changes the appearance in some way(s).

Randomization is available for both the color palette and the parameters. When activated with the button and the small triangular arrows for any (or even all) of these, new colors or values are selected at random whenever there is a silent moment in the audio stream. Typically this happens between the tracks of a playlist.


ROOM group visualization modes are 3D elements that are located inside the room:

• shape of sound: a mesmerizing, swirling swarm of dancing particles
  
• floor spectrogram: scrolling 3D spectrogram over the floor
  
• tunnel spectrogram: about the same, just wrapped around as a tunnel
  
• level meter: volume level columns by the doorway
  
• VU meter: the old-school way of monitoring average level of audio volume, either for each frequency band separately or for full-band directly from the waveform

SPACE group contains 3D-visualization elements that expand beyond the room boundaries:

• aurora: can be seen over the polar areas, reflecting both amplitude and spectral data
  
• warp tunnel: highly configurable, from delicate and calm to bright and energetic
  
• trinity flux: polygonal flow; sharp and responsive or smooth and calm - your choice!
  
• nebula wavefronts: flying towards the light over a waveform scenery

Same logic applies to color and parameter adjustments within all visualization element groups.

Media playback

Audio and video files can be played with AudioSpace in the following ways:
- with Explorer context menu: right click a file or folder and select "Play with AudioSpace"
- with drag & drop on AudioSpace icon or AudioSpace window (after Alt+Tab or Alt+Enter)
- with media playback related programming commands (see the "Programming" chapter)
- by editing Documents/AudioSpace/media/layers.ini directly before starting AudioSpace; info about current contents of media layers and playback states are saved in this file

Following audio formats are supported: .aac, .adts, .m4a, .mp3, .wav, .wma
Following playlist formats are supported: .b4s, .m3u, .pls, .vlc, .wpl, .xspf
For the best compatibility and performance with videos, it is recommended to use H.264 encoded .mp4 files, though some other formats/containers may also work.
Following picture formats are supported: .jpg, .jpeg, .png, .webp

Overlay pictures are typically things like lyric texts, watermarks or frames. Underlay pictures form a background for visualization graphics, but can also be used as a mask for the video layer. All layers expect the video layer (which is the bottom layer) support transparency, so use .png whenever you need transparency (alpha channel in images). Note that .jpg images don't have alpha channel and thus don't have any transparency.

Files opened with drag & drop or context menu go to the first wall with active media layer in priority order, or the default wall if no media players are active. Wall where files were opened most recently becomes the default target wall for future drag & drop and context menu actions. Pictures are opened on the background layer (underlay) unless that is already in use, in which case they are shown on the foreground (overlay).

Playback controls include playlist looping and shuffling as well as speed adjustment (when supported). Note that volume adjustment affects the master output volume of AudioSpace, and thus also the visualization when monitoring audio output. This means that no visualizations are visible when volume is 0 even when using some other player than AudioSpace.

Presets

At the top of the menu you can see a row of preset buttons. A preset contains full configuration for your AudioSpace room, as well as your position and orientation. All changes are automatically saved to current preset, so when you restart AudioSpace, everything should be just as when you left. Exception is your position and orientation, those you can save to current preset by pressing Enter (or a controller button, see the in-game console) at any time. Saved positions in VR mode may not work as expected when not in VR due to different movement & orientation system. Best practice is to save intended positions and orientations into presets when not in VR mode.

You can change the current preset either with a number key (0..9) or by zapping a preset button in the menu. If 10 presets are not enough, press Page Up or Page Down to access another set of 10 presets. All in all, 100 presets are available, from 0 to 99.

Presets can also be randomized in the same way as color palettes and visualization parameters: when enabled, a random (configured) preset is selected whenever there is a moment of silence in the audio stream. This way you can easily vary the visualization of playlists with your favorite presets. Same button has also a secondary mode: loop through the presets in sequence instead of a random order. You can include and exclude presets from this automation with the small arrows under the preset keys.

Streaming, video production, live stages...

Good news for all streamers, video producers and performing artists: AudioSpace is built with all of you in mind, and can be used as much as you like without any royalty costs! Just send a message to [e-mail] about where and when this will happen - and if you are a streamer, mentioning that anyone can get their own copy of AudioSpace from Steam would naturally be appreciated! 😁

So, wait no longer to raise the audiovisual experience of your audience to the next level! Just set AudioSpace window as a source in OBS Studio (or other streaming tool), or capture some visualizations for your video productions, or project it as a backdrop for your live stage. When visualizing live audio (e.g. sound from microphone), try to minimize the latency delay to keep things in sync.

To help you reach the best possible quality in professional use, AudioSpace has a few options available in Documents/AudioSpace/config.ini that you can experiment with, including:

• use ASIO sound drivers, if available, for audio capturing (instead of WASAPI)
  
• limit max. frame rate (FPS); especially useful for video captures
  
• select sample count for multi-sample anti-aliasing, or use temporalAA
  
• select resolution of the wall panel textures (heavy impact on performance)

ASIO support is for input sources only, as audio output sources (speakers, line-out etc.) must be captured in shared mode and WASAPI is better suited for this. Many ASIO drivers don't even support shared / loopback capturing of output sources. However, they usually do provide the lowest latency for audio input capturing, on par or even better than the WASAPI exclusive mode. Make sure to check the "Allow applications to take exclusive control of this device" box in the Windows Sound Control Panel whenever low latency is important. Usually you can get about 10 ms latency with shared mode WASAPI, and down to 2-3 ms latency with exclusive mode WASAPI or ASIO input capturing.

Recording

Activating the record function will save to disk any audio that is captured from the currently active input our output source. Silent moments will trigger saving to a new file, and a few seconds of silence will automatically stop saving the current file. Location of saved files is displayed on the console.

Any discontinuities in the audio stream will deactivate the recording mode, so you can be sure that whatever is saved to file will be free of glitches. These shouldn't occur unless you are using too low buffer size for input capturing or your PC is otherwise running at its limits. Safest bet is of course to turn off all visualizations while you are recording, but usually one of the less demanding visualizations (such as the level meter) should not be too much.

AudioSpace recognizes and respects most audio stream formats so that (practically) lossless copy is saved to a .wav file when recording. This includes 16, 24 and 32 bit integer samples as well as 32 and 64 bit floats. Also multichannel streams are supported up to 32 channels. Following speaker placements are assigned for playback with certain number of channels:

• 3 channel stream is saved as 2.1 surround sound (left, right and sub)
  
• 4 channels: 4.0 surround (left, right, center and back)
  
• 5 channels: 5.0
  
• 6 channels: 5.1
  
• 7 channels: 7.0
  
• 8 channels: 7.1

Greater channel counts are saved without speaker assignments and will play back in whatever order the playback system has the channel ports defined. Note that as the output file is uncompressed .wav, channels are easily extracted and reordered as desired afterwards. This flexibility and losslessness comes with a drawback of large file sizes, so it is advisable to take care (move away, compress, delete etc.) of the recorded files right away to avoid filling up the disk.

Naturally, any illegal use of AudioSpace's recording functionality is forbidden. Respect copyrights.

Programming

AudioSpace can be programmed to execute a series of timed actions. This functionality is mainly designed for music video production so that multiple presets can be easily utilized together with
camera and scene animations.Longer-term plan is to have a separate timeline-based graphical editor for creating and managing programs, but meanwhile the below documentation explains how programs can be defined in a simple text file named with ".asprog" extension.

In a program file, "#" starts a comment (rest of the line is ignored).
Each executable line starts with a time and is followed by a command:
min:sec [command]

Global commands are as follows: (things inside [] are optional)
pX = load and apply preset X; e.g. "p3"
mX [S] = move to preset X position and orientation in S seconds; e.g. "m7 3"
lX = change current location (in space) to X; e.g. "l1" = go to Earth orbit
la X [Y [S]] = move from latitude X to Y in S seconds; e.g. "la 30 350 5"
lo X [Y [S]] = move to longitude X to Y in S seconds; e.g. "lo -60 60 30"
rs X = select room style, X = "luminous", "dark", "translucent" or "space"
wo X [Y [S]] = fade wall opacity from X to Y in S seconds,
X and Y range from 0 to 1; e.g. "wo 0 1 3"

Media layers can be selected for WALLS, FLOOR and ROOF like this:
ml group [layer] [options] = source
- group is one of these: left, right, front, back, floor, roof
- for audio and video, layer is "audio" or "video" (they share the same layer)
- for pictures, layer is either "fg" (or "overlay") or "bg" (or "underlay")
- options include the following keywords:
"fill" = fill the wall instead of fitting; aspect ratio is always maintained
"loop" = turn playlist looping on (default is off)
"shuffle" = turn playlist shuffling on (default is off)
"precache" = try to load the whole file into memory before playback
"indexN" = start playback at playlist index N (if not shuffling)
"secondsN" = start playback at time of N seconds (if not shuffling)
"paused" = don't start playback, open media in paused state
- source is an URL or a full path to a playlist or media file;
supported playlists include .asx, .b4s, .m3u, .pls, .vlc, .wpl, and .xspf
- if source is empty or "off", the given layer or, if no layer is given,
all media layers are turned off for the given group
- if source is "on", media layers are turned on for the given group

To control media playback, following commands are available:
mp [group] play
mp [group] pause
mp [group] stop
mp [group] prev
mp [group] next
mp [group] index N (N is a playlist index, starting at 0)
mp [group] seek N (N is time in seconds on currently selected playlist index)
mp volume X [Y [S]] = set playback volume to X (0..1) & fade to Y in S seconds
mp mute (mutes audio if not already muted)
mp unmute (unmute, has effect only if audio is currently muted)
If group is not provided, target is the first active media player (if any)
in a priority order of front, left, right, back, roof, floor.

Visualization element specific commands start like this:
group [panelN] [mode]
- group is one of these: left, right, front, back, floor, roof, room, space
- panel is the wall panel number (from 1 up, doesn't apply for room & space)
- mode is one of these for WALLS, FLOOR and ROOF:
"vec" for vectorscope
"pha" for phase wheel
"col" for spectrum columns
"spe" for spectrogram
"wav" for waveforms
- mode is one of these for the ROOM group:
"sos" for shape of sound
"fsp" for floor spectrogram
"tsp" for tunnel spectrogram
"lev" for level meter
"vum" for VU meter
- mode is one of these for the SPACE group:
"aurora"
"warp" for warp tunnel
"flux" for trinity flux
"nebula" for nebula wavefronts

Command then continues with one of these:
on = turn on the given visualization mode; e.g. "left panel2 wav on"
off = turn elements off, e.g. "front panel2 off", "room lev off", "all off";
if element is not specified, also group's media layers are turned off
bands LMH = turn on/off frequency bands; e.g. "roof bands 101"
(this would set low & high bands on and mid band off)
pal X [Y [S]] = use palette preset X & morph to palette Y in S seconds,
index of 0 = auto-palette (based on location)
rgb band R1G1B1 [R2B2G2 [S]] = set key color of a frequency band as RGB,
optionally morphing colors in S seconds;
if R2B2G2 is not given, target is R1G1B1;
band = "low", "mid" or "high", color in hex;
e.g. "space rgb mid 00FF00 FFFF00 10"
hsv band H,S,V [H2,S2,V2 [S]] = same as the rgb-command, but using
hue (0-360), saturation (0-1) and value (0-1)
color space. Note: no space around commas.
psA X [Y [S]] = set param slider A to X [-1..1] & morph to Y in S seconds;
use psB and psC commands for the other parameter sliders
ppX [S] = morph to parameters of preset X in S seconds;
if no element is specified, uses first active element of group;
if no mode is specified, uses the mode of selected element;
e.g. "left vec pp42 3"
(warning is shown if selected mode is not active in preset X)

If panel is not given, panel 0 is assumed.
If mode is not given, command is applied to first active mode of the group;
exception is the "on" command, which naturally always needs the mode.

If duration S of 0 is given (or Y-value is missing or equals the X-value),
animation completes immediately. If no duration S is given, it is calculated
so that the animation is finished by the time of the next program line.

All commands with X, Y and S values can be appended with animation easing
with given mode & power as well as the total duration (if looping is desired).
Easing modes are as follows:
"lin" = linear interpolation from start to end value
"pinX" = power ease in, X = exponent
"pouX" = power ease out, X = exponent
"pioX" = power ease in & out, X = exponent
"sinX" = sinusoidal curve, optional X = exponent (mostly for looping)
"triX" = triangular curve, optional X = exponent (mostly for looping)
"squ" = square curve, i.e. alterate between values (mostly for looping)

Use "sin" or "tri" mode for looping without discontinuity at the loop end.
Here's a complete, executable program line as an example:
0:20 la -60 60 10 sin 300
This would start looping 20 seconds after playback starts between latitude
values -60 and 60 every 10 seconds using sinusoidal interpolation curve.
Looping would go on for 300 seconds.

Program clock starts when audio playback starts. Negative execution time
means that execution should be done immediately (audio or no audio).

Another example:
-1 p10
0 front wav on
0:10 front psC 0 -1 30 pin3.5

This program would load preset 10 at startup (even before the music starts).
At first audio, it would turn on multiband waveforms at the front wall.
10 seconds after, it would move parameter C slider all the way down in 30
seconds using ease-in with exponent of 3.5 (i.e. slow start, sudden stop).

As you can see, AudioSpace programming interface is quite versatile and can
be used for creating very complex dynamic visualizations. Typically one would
first listen to a song and mark down key time points and transition durations.
Next step would be to create the presets in a desired style. After this,
writing the program file can be done in just a few minutes; usually one would
just load the predefined presets with the "p" commands at key times and then
optionally add some movement/color/parameter transitions for some extra wows.
Be sure to upload your best creations for everyone to see. Have fun!