###############################################################################
#
# VSpace Example Script
# ---------------------
#
# VSpace makes recordings of sounds played back in a virtual acoustic
# space. It is a self-contained program forming part of MNLib, a set
# of C++ libraries and programs for audio processing and music. MNLib is
# designed with portable C++ code for use on Linux, Microsoft platforms
# and others. VSpace, MNLib and their documentation are Copyright 
# 1999-2000 Richard W.E. Furse (all rights reserved).
#
# VSpace, this example script and the audio files that this script 
# depends on may all be downloaded from:
#	http://www.muse.demon.co.uk/mn_download.html.
#
# To run this script, place the required Wave files (voice.wav and 
# csaudio.wav) in the same directory as the script (example.vsp) and then
# execute:
#	vspace example.vsp
#
# A number of new files will appear in the directory, one for each
# recording device below. `.wav' files are conventional Wave files,
# `.fmh' files are FMH encoded and need special player software. This
# can be downloaded from the site above.
#
# Don't be put off by the length of this script. It is long because it
# is full of comments and uses most of the features in VSpace. In 
# practice VSpace scripts are often just a few dozen lines long.
#
# Note that lines beginning with hash characters are ignored by the
# VSpace program. Many instructions end in semicolons. When
# instructions have optional parts these parts often have to appear in
# a particular order.
#
###############################################################################
#
# General Settings
# ----------------
#
# At the top of the file general settings are placed.

# Set the early reflection time (see manual). This affects image
# quality and computation time. When you run the program, if you use
# the -v (verbose) flag then you will be told the number of early
# reflection room images are in use. Usually, computation time is
# approximately proportional to this value. For preview purposes early
# reflections can be turned off using the -e flag when you run the
# program. This reduces room images to one.
#
# After the early reflection time the late reflection engine takes
# over. This can be disabled using -l. Various general settings are
# available to control the late reflection engine.

early reflection time 0.6;

# Set the early reflection minimum gain (see manual). This affects
# image quality and computation time.

early reflection minimum gain 0.005;

# Set the tempo. Times are interpreted as beats relative to this tempo
# (in bpm).

tempo 60;

# Set the units we are to use below.

distance unit metre;

# There are a variety of other options available, particularly
# relating to late reflection reverb settings.
#
###############################################################################
#
# Room Settings
# -------------
#
# In this section we describe the room in which our recording will take
# place.

room {
	# Set the dimensions of the room. The room is assumed to
	# be box shaped with walls parallel to the X, Y and Z axes.
	# In order, we determine range of valid X, Y and Z values.
	# (e.g. -26 < X < 33.)
	#
	# Note that positive X is generally considered `forward',
	# positive Y is generally considered `left' and Z `up.'

	dimensions	-26, 57, -35, 48, -1, 23;

	# Determine how reflective each wall is. A value of 1 indicates
	# that the wall is full reflective, 0 indicates total
	# absorption.

	reflections	0.7, 0.7, 0.7, 0.7, 0.3, 0.9;
}

###############################################################################
#
# Recording Devices
# ------------------
#
# In this section we describe recording devices within the
# room. Normally only one is needed, however a number are included
# here to demonstrate the different types available. This increases
# calculation time hugely. Recordings are written to file.

# A recording device consisting of two coincident cardioid microphones
# at 90 degrees to each other. Output is written to file
# "stereo.wav". The microphone is located at the origin (<0,0,0>).
#
# Individual cardioid microphones are also available and they can be
# configured from cardioid to figure-of-eight or omnidirectional
# response or anywhere in between.

recording stereo.wav {

	device cardioid pair;

	# Specify the location of the two microphones (they don't have
	# to be at the origin and don't have to be coincident.

	location <0, 0, 0>, <0, 0, 0>;

	# Specify vectors giving the directions the microphones are
	# pointing in. They are pointing forward left and forward
	# right.
	
	direction <1, 1, 0>, <1, -1, 0>;

}

# A recording device consisting of a second-order Ambisonic
# microphone. The output file (`ambisonic.fmh') is written out in FMH
# format. These files can be played back of arrays of speakers using
# programs such as the AmbisonicPlayer available from
# http://www.muse.demon.co.uk/mn_download.html. B-Format (first order)
# Ambisonics is also available.

recording ambisonic.fmh {

	device second order ambisonic;

	# Specify the location of the two microphone. Ambisonic
	# microphones are not directional.

	location <0, 0, 0>;

	# Optionally, specify a core radius (see manual) to help deal
	# with sounds that pass close to the microphone.
	
	core radius 1;

}

# An omnidirectional microphone in a far corner of the room picking up
# a rather different balance of sound to the others.
#
# Note that if this microphone was just be preview purposes then a
# `simple' microphone could be used instead. These use much less
# computation time but do not use a delay/Doppler model. In this
# context early reflections should be switched off.

recording distant.wav {

	device omnidirectional;

	# Put the microphone far away (it must be in the room).

	location <50, 42, 1>;

	# Optionally, turn up the gain on the microphone to make the image
	# clearer.

	gain 5;

}

###############################################################################
#
# Fixed Location Sound
# --------------------
#
# In this section a track is playing at a single point to the left of
# the listener and then jumps to the distant right. A `track' consists
# of a list of sounds to mix together and instructions on how this mix
# of sounds should be placed in space.

track {
	mix	{

		# Read in the file `voice.wav' from disk. Mix in the
		# entire file. Start playing at time zero (the
		# beginning). This is a recording of the word `VSpace.'

		0	voice.wav;

		# Play the sound again after two beats. Apply a gain
		# to make the sound louder to compensate for the
		# distance (see below). The sound will be more
		# reverberant for the microphones at <0, 0, 0>.

		2	voice.wav	gain 10;
	}

	motion	{

		# Start out static, just to the left.

		0	fixed	<0, 1, 0>;

		# Second time, jump to the distant right (slightly
		# in front).

		2	fixed	<5, -20, 0>;
	}
}

###############################################################################
#
# Moving Sounds 1
# ---------------
#
# In this section two sounds are mixed together and moved from left to
# right in front of the origin.

track {
	mix	{

		# Read in ten seconds of sound from the file
		# `csaudio.wav', playing for 10 beats (10 seconds at this
		# tempo), 5 seconds into the performance. Apply a gain 
		# to make it louder.

		5	csaudio.wav	gain 1.5 from 0 to 10;

		# Say `VSpace' three times.

		5	voice.wav	gain 1.5;
		10	voice.wav	gain 1.5;
		15	voice.wav	gain 1.5;
	}

	motion	{

		# Move the sound from left to right, passing a few metres
		# in front.

		5 to 15	line	<3, 10, 0> to <3, -10, 0>;

	}
}

###############################################################################
#
# Moving Sounds 2
# ---------------
#
# In this section a sound rotate around the origin. Sounds become
# directional.

track {
	mix	{
		18	csaudio.wav	from 0 to 10;
	}

	motion	{

		# Rotate the sound around the origin starting ten
		# metres in front and moving around to the left in a
		# half second. A complete circle therefore takes two
		# seconds.

		18 to 28	arc	centre	<0, 0, 0>
					start	<6, 0, 0>
					to	<0, 6, 0>
					in	0.5;
	}

	direction {

		# Start out with the usual (omnidirectional) profile,
		# but switch to being highly directional towards the
		# left. This means the sound is louder when it is to
		# the right of the microphone.

		23 to 23.5	line	<0, 0, 0> to <0, 1, 0>;

	}
}

###############################################################################
#
# Lots of Sounds at Once
# ----------------------
#

track {
	mix	{
		30	csaudio.wav	from 15 to 20;
		33	csaudio.wav	from 10 to 20;
		40	csaudio.wav	from 10 to 15;
	}
	motion	{

		# The `magnitude' keyword changes the length of a
		# vector without changing its direction.

		0	fixed	<6, 4, 0> magnitude 4;
	}
}
track {
	mix	{
		30	csaudio.wav	from 10 to 20;
		35	csaudio.wav	from 10 to 20;
		40	csaudio.wav	from 15 to 20;
	}
	motion	{
		0	fixed	<-7, -1, 0> magnitude 4;
	}
}
track {
	mix	{
		34	csaudio.wav	from 10 to 20;
		30	csaudio.wav	from 17 to 20;
		38	csaudio.wav	from 10 to 17;
	}
	motion	{
		0	fixed	<2, -7, 0> magnitude 4;
	}
}

###############################################################################
# eof