- Getting started
- Controlling Csound from Unity
- Controlling Csound from the Unity Editor
- Reading files with Csound
In order to use CsoundUnity you will need to install the packages available from the following links:
To install the package, simply create a new Unity project, then go to Assets, Import Package, Custom package and select the CsoundUnity package for your platform. Then select 'Import All' and hit Ok. The package comes with a simple scene that demonstrates how it can be used. If you installed CsoundUnity from the Assets Store, you will need to also install Csound. Information on this is given below in the troubleshooting section.
CsoundUnity is a simple component that can be added to any GameObject in a scene. To do so simple hit AddComponent in the inspector, then click Audio and add CsoundUnity.
CsoundUnity requires the presence of an AudioSource. If the GameObject you are trying to attach a CsoundUnity component to does not already have an AudioSource attached, one will be added automatically.
Once a CsoundUnity component has been added to a GameObject, you will need to attach a Csound file to it. Csound files MUST be placed somewhere in the Assets/Scripts folder. In the sample CsoundUnity package they are kept in a sub-folder within Assets/Scripts called CsoundFiles. This is not required, but may help to better organise your assets. To attach a Csound file to a CsoundUnity component, simply drag it from the Assets folder to the 'Drag and Drop Csound file here' field in the CsoundUnity component inspector. When your game starts, Csound will feed audio from its output buffer into the AudioSource. Any audio produced by Csound can be accessed through the AudioSource component. This is currently restricted to stereo files, but will work for any amount of channels. See CsoundUnity::processBlock()
Your Csound files should always include the -n -d flags in the CsOptions section.
This ensures Csound does not try to open any audio devices. This is left to entirely up to Unity. If you fail to disable writing of audio from Csound to a realtime audio output device, both Csound and Unity will try to access the computer's audio devices at the same time. This will inevitably lead to problems. Any Csound instruments that are set to start after 0 seconds will begin to play as soon as you enter 'Play' mode in Unity. This can be seen in several of the instruments provided in the sample package. You can also start an instrument to play at any time using the CsoundUnity::sendScoreEvent() method.
Controlling Csound from Unity
Once you have attached a Csound file to a CsoundUnity componet, you may wish to control aspects of that instrument in realtime. To do this, you can use Csound's channel system. Csound allows data to be sent and received over its channel system. To access data in Csound, one must use the chnget opcode. In the following code example, we access data being sent from Unity to Csoud on a channel named speed. The variable kSpeed will constantly update according to the value stored on the channel named speed.
In order to send data from Unity to Csound we must use the CsoundUnity::setChannel(string channel, double value) method. Before calling any CsoundUnity methods, one must first access the component using the GetComponent() method. This can be seen the simple script that follows. One usually calls GetComponent() in your script's Awake() method. Once the CsoundUnity componet has been accessed, any of its member method can be called. In the update() method of the script below,
Channels can also be used to trigger one-shot instruments to play. The simplest way to achieve this is to use Csound's event opcode. In the following Csound code example the JUMP instrument will be triggered whenever the value of the "jump" channel changes. Instrument TriggerInstrument will start as soon as the game does. Its job is to listen for changes to the values stored on the channel named "jump". When the channel value changes the variable kJumpButton will change, causing the changed opcode to output a 1. At this point the code contained within the if block will be triggered and the instrument named JUMP will be triggered to play for one second.
Controlling Csound from the Unity Editor
In order to control Csound instruments in standalone gameplay, you will need to use the methods described above. However, you can also control Csound channels using the Unity Editor while you are developing your game's sounds. To do so, you must provide a short
Each control MUST specify a channel. The range() identifier must be used if the controller type is a slider. The text() identifier can be used to display unique text beside a control but it is not required. If it is left out, the channel() name will be used as the control's label. The caption() identifier, used with form, is used to display some simple help text to the user.
When a Csound file which contains a valid
Reading files with Csound
If you wish to read files with Csound through its file reading opcodes, i.e, diskin, fink, etc, you should create a folder in your Assets folder called CsoundFiles. It's good practice to place all files Csound needs access to in this folder. You can access the path for this folder in your Csound code by using the chnget opcode. You will need to pass it the channel name "CsoundFiles". For example, the following code will read a file called mix from the CsoundFile directory.
When you build a standalone version of your game all files in the Assets/CsoundFiles folder will be copied to the StreamingAssets folder so that Unity does not try to compress and reformat them. The 'CsoundFiles' channel will also be updated so your Csound code will still work. CsoundUnity also provides the channels for accessing the Assets/StreamingAssets folder, and the Assets/Audio folder.
SStreamingAssets chnget "StreamingAssets" ;return the path to the streaming assets folder
SAudio chnget "AudioPath" ; returns the path to the audio assets folder
If you installed CsoundUnity from the Assets Store and don't already have Csound, you should simply install one of the following packages instead:
On Windows, the csound64.dll must reside in the SmtreaingAssets folder. If it is not there, CsoundUnity will display an error. One OSX, the CsoundLib64.framework must reside in the StreamingAssets folder. If it is not, CsoundUnity will display an error.
If you have Csound installed you can simple place it to the correct location, although it is far easier to use the package provided. They will not have any effect on any existing Csound installation.
If your game crashes at any point, the best place to look for answers will be in the Editor Logs. If you continue to have issues with CsoundUnity, please use the github Issue Tracker to file an issue.
Below is a list of all the methods currently available in CsoundUnity.
public void setChannel(string channel, float val)
- Sets a Csound channel. Used in connection with a chnget opcode in your Csound instrument.
public void setStringChannel(string channel, string val)
- Sets a string channel in Csound. Used in connection with a chnget opcode in your Csound instrument.
public void sendScoreEvent(string scoreEvent)
- Send a score event to Csound in the form of "i1 0 10 ...."
public double getChannel(string channel)
- Gets a Csound channel. Used in connection with a chnset opcode in your Csound instrument.
public double getTableSample(int tableNumber, int index)
- Retrieves a single sample from a Csound function table.
public double get0dbfs()
- Get 0dbfs
public int performKsmps()
- Processes a ksmps-sized block of samples
public double getKr()
- Returns the current control rate
public uint getKsmps()
- Get the current control rate
public void processBlock(float samples, int numChannels)
- Processes a block of samples
public double getSample(int frame, int channel)
- Get a sample from Csound's audio output buffer
public void setSample(int frame, int channel, double sample)
- Set a sample in Csound's input buffer (is known to cause problems! Please only use this method if absolutely needed).