File: csound_android_manual.tex

package info (click to toggle)
csound 1%3A6.18.1%2Bdfsg-4
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 63,220 kB
  • sloc: ansic: 192,643; cpp: 14,149; javascript: 9,654; objc: 9,181; python: 3,376; java: 3,337; sh: 1,840; yacc: 1,255; xml: 985; perl: 635; lisp: 411; tcl: 341; lex: 217; makefile: 128
file content (537 lines) | stat: -rw-r--r-- 29,403 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
\documentclass[11pt]{article}

\usepackage{hyperref}
\usepackage{listings}
\usepackage{color}
\usepackage{xcolor}
\usepackage{caption}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{graphicx}
\usepackage{comment}
\usepackage{underscore}


%\DeclareCaptionFont{white}{\color{white}}
%\DeclareCaptionFormat{listing}{\colorbox{gray}{\parbox{\textwidth}{#1#2#3}}}
%\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white}

\DeclareCaptionFont{white}{\color{white}}
\DeclareCaptionFormat{listing}{\colorbox[cmyk]{0.43, 0.35, 0.35,0.01}{\parbox{\textwidth}{\hspace{15pt}#1#2#3}}}
\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white, singlelinecheck=false, margin=0pt, font={bf,footnotesize}}

\lstset{ %
language=[Objective]C, 
%breakindent=40pt,
basicstyle=\ttfamily\footnotesize,       % the size of the fonts that are used for the code
%numbers=left,                   % where to put the line-numbers
numberstyle=\ttfamily\footnotesize,      % the size of the fonts that are used for the line-numbers
%stepnumber=1,                   % the step between two line-numbers. If it is 1 each line will be numbered
numbersep=5pt,                  % how far the line-numbers are from the code
backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
showspaces=false,               % show spaces adding particular underscores
showstringspaces=false,         % underline spaces within strings
showtabs=false,                 % show tabs within strings adding particular underscores
%frame=single,           % adds a frame around the code
%frame=shadowbox,
%frame=tb,
tabsize=2,          % sets default tabsize to 2 spaces
%captionpos=b,           % sets the caption-position to bottom
breaklines=true,        % sets automatic line breaking
breakatwhitespace=false,    % sets if automatic breaks should only happen at whitespace
escapeinside={\%*}{*)},          % if you want to add a comment within your code
%stringstyle=\color{white}\ttfamily,
 xleftmargin=17pt,
         framexleftmargin=17pt,
         framexrightmargin=5pt,
         framexbottommargin=4pt
}

\author{Victor Lazzarini, Steven Yi and Martin O'Shea}
%\date{2012.08.xx}
\date{\today}
\title{Csound for Android}

\begin{document}
\maketitle

\section{Introduction}

Welcome to Csound for Android! This document will discuss the details about using Csound for Android OS using the Android Studio IDE. 

For those with knowledge of Csound, hopefully you will see that the value of your knowledge is only enhanced by offering a new platform on which to create musical software and works. 

\subsection{Regarding the Csound for Android Examples Project}

This documentation covers discussion of the Csound for Android API.  Users interested in diving in to see how the API is used may want to download the Csound for Android Examples Project which contains a set of examples that cover different use cases of the API. The code for each example may be useful in giving you a jump-start in building your own application.

\subsection{Regarding the LGPL License}

The Csound for Android includes Csound and \href{http://mega-nerd.com/libsndfile/}{libsndfile}. These are distributed as static libraries. Users of the Csound for Android API must comply with the licensing requirements of the GNU Lesser General Public License v2.1, which both libraries use. Please carefully review the license files that accompany each project (you can view a generic version of the LGPL v2.1 license at \href{http://www.gnu.org/licenses/lgpl-2.1.html}{http://www.gnu.org/licenses/lgpl-2.1.html}). 

%======

\section{Getting and Using the Csound for Android API}

The Csound for Android library is distributed as a Zip release from the Csound Sourceforge page. The Zip archive includes:

\begin{itemize}
  \item CsoundForAndroid Android Studio Project, which includes:
  \begin{itemize}
  \item CsoundAndroid - main Csound library module, contains libcsound.so native library (compiled as universal binaries for armeabi and armeabi-v7a CPU architecturesi), CsoundObj and Csound APIs
  \item CsoundAndroidExamples - Examples application module that illustrates how to use CsoundObj and Csound APIs on Android
  \item CsoundApplication - Csound6 application module, originally by Victor Lazzarini (CSDPlayer) and now developed and mainained by Michael Gogins
  \end{itemize}
  \item pluginLibs - Android Native Development Kit (NDK) projects for building Csound plugin libraries (i.e. fluidsynth, lua opcodes) 
  \item Documentation - This PDF manual
\end{itemize} 

To develop applications with Csound, you will use the CsoundAndroid library module from the Android Studio project.  This library is delivered with all of the native parts pre-compiled. You do \emph{not} have to have the NDK installed to use this library.  

To create a new Csound-based Android application, first create your application project using the appropriate application module template for your work. Next, import the CsoundAndroid library module into your project.  To do this, do the following:

\begin{enumerate}
\item From the ``File'' menu, choose ``New'', then ``Import Module''.
\item A dialog will appear asking you for the source folder to use.  Navigate to the CsoundForAndroid/CsoundAndroid folder to select it, then press okay.  The library module will be copied into your projec.   
\item Finally, in the projects view, right-click your application module and choose ``Open Module Settings''. In the dialog that appears, select your application module.  On the right-hand side, choose the ``Dependencies'' tab. Click the + button, then choose ``Add Module Dependency'' from the menu that appears.  Select the ``CsoundAndroid'' module.
\end{enumerate}

At this point, your application now has a dependency on the CsoundAndroid library module and you can begin developing your Csound-based Android application. All of the Java classes and native libraries from CsoundAndroid will now be a part of your application and you can use any of the CsoundObj and Csound API classes. 

%======

\section{Introduction to the API}
\subsection{CsoundObj and Csound API's}

Csound for Android is released with the standard Csound C API as well as a custom Java CsoundObj API that has been designed to make developing on Android OS convenient.  The CsoundObj API includes methods for binding widgets to channels (used to communicate to and from Csound), enabling hardware sensors, and more.  For further detail, please consult the \texttt{CsoundObj.java} class.

While the CsoundObj API has been designed to ease things for Android OS development and to follow conventions of Java, the decision was made not to wrap everything in the Csound C API. . The Csound java Object that a CsoundObj class holds can be accessed via the \textbf{getCsound} method in CsoundObj.  For more information about the Csound C API, consult \texttt{Csound.java} class.

\section{Using the CsoundObj API}

The CsoundObj API revolves around the Java CsoundObj class. This class contains a Csound Object and has methods for running Csound, as well as convenience methods to help aid developers in connecting elements to Csound. By itself, CsoundObj can take in a CSD file and render it.  By using CsoundBindings, objects can interact to read values from and write values to Csound.  Beyond that, extended features can be accessed by using the Csound C API together with the Csound object.

\subsection{Designing Csound CSD projects to work with Hosts}

To communicate to and from a host program with Csound, you will most likely use \textbf{chnset} and \textbf{chnget} opcodes. These opcodes will allow you to read from and write values to a named channel.  Your host program will also be writing to and reading from these same channels.  As a byproduct of using named channels, your CSD will be portable to work on other platforms (Desktop, IOS); porting over apps to/from Android then will only involve redoing the application and UI code, while your audio engine (Csound) should ``just work.'' 

\subsubsection{CsOptions}

Csound will use the CsOptions you provide.  A standard set of flags to use are ``{\tt -odac -dm0 -+msg\_color=0}''. This will tell Csound to play to dac in realtime, turn off displays, use message level 0, and turn of message colors.  This will minimize messages going out to the console or to your message handler if you set one.  You may also need ``{\tt -iadc}'' if your project uses audio input. (You can always consult the Csound Examples project to see what CsOptions are used in the CSD's for that project.) 

\emph{Note: In Csound5 for Android, it was previously required to set \linebreak ``{\tt -+rtaudio=null}'' when using audio. This is no longer required for Csound 6 for Android.}
 

\subsection{CsoundBinding for Communicating with Csound}

The CsoundObj API has been created to ease communication with Csound by using objects that implement the CsoundBinding interface.  The interface definition is as follows:

\begin{lstlisting}[caption=CsoundBinding interface Definition]

public void setup(CsoundObj csoundObj);
	
public void updateValuesToCsound();
	
public void updateValuesFromCsound();
	
public void cleanup();

\end{lstlisting}

CsoundBindings are used to both read values from Csound as well as write values to Csound.  The lifecycle of CsoundBindings is as follows:

\begin{itemize}
\item \textbf{setup} - this has now been changed. This method is called after Csound's compile call but before the main performance loop. CsoundBindings should use this method to cache any channel pointers and any other values they will need during performance.
\item \textbf{updateValuesToCsound} and \textbf{updateValuesFromCsound} - these methods are called during the Csound performance loop. \textbf{updateValuesToCsound} is called before each call to csoundPerformKsmps, while \textbf{updateValuesFromCsound} is called after each call. 
\item \textbf{cleanup} - this method is called after Csound has completed its run and should be used by CsoundBindings to free up any allocated data and remove references to channel pointers.
\end{itemize}

By using CsoundBindings, CsoundObj functionality can be extended to communicate with as many items as you would like. The Csound for the Android API contains pre-made wrapper classes for common UI classes (Slider, Button) as well as hardware sensors (Accelerometer).  CsoundObj has helper methods for the CsoundBindings that come with the CsoundObj API, as well as the generic \textbf{addBinding} and \textbf{removeBinding} methods for adding custom CsoundBindings. Please consult these classes as well as their use in context within the Csound for Android Examples project.


%======

\section{Common CsoundObj API Methods}

\subsection{Binding Widgets to CsoundObj}

The CsoundUI class provides the following methods for binding widgets:

\begin{lstlisting}[caption=Methods for Widget Binding]
public CsoundBinding addButton(Button button, String channelName))
public CsoundBinding addButton(Button button, String channelName,int type)
public CsoundBinding addSlider(SeekBar seekBar, String channelName, double min, double max)}
\end{lstlisting}

To use the CsoundUI class, first instantiate an instance of the class, providing the CsoundObj object to use, then call methods on the CsoundUI class:

\begin{lstlisting}[caption=Using the CsoundUI class]
CsoundUI ui = new CsoundUI(csoundObj);
CsoundBinding binding = ui.addButton(btn, "button-channel-1");
\end{lstlisting}


These methods allow for easy binding of SeekBars and Buttons. The methods return the CsoundBinding that was created to wrap the widget. If the design of your app requires that you remove a widget from being used with CsoundObj, you can use the returned CsoundBinding and pass it to the removeCsoundBinding method. To bind your own custom widgets, you will need to create your own CsoundBinding.  There are examples of both using the convenience widget binding methods as well as custom CsoundBindings in the Csound for Android Examples project.
%======

\section{Interfacing with Hardware}
\subsection{Audio Input and Output}

CsoundObj has been designed to connect everything necessary for audio input and output from Csound to \textit(OpenSL) in the when the CsoundLib Library is compiled in with the NDK, the CsoundObj can also interact with audio track at run time (this is to allows for  downward compatibility with 2.2 and lower).  Enabling input and output depends on what commandline arguments are given when running Csound.  The commandline arguments should be supplied as part of the CSD's \textbf{CsOptions} section.  To enable audio output, use \textbf{-o dac} and to enable audio input, use \textbf{-i adc}. 

\subsection{Accelerometer}

The CsoundMotion class provides support for using the accelerometer found in Android devices. CsoundMotion has the following method to enable these features:


\begin{lstlisting}[caption=CsoundObj Accelerometer Method]
public CsoundBinding enableAccelerometer(Context context)
]
\end{lstlisting}

The CsoundMotion class is used in the same way as CsoundUI: users will first instantiate an instance of CsoundMotion, then call methods that return CsoundBindgs. When the accelerometer is enabled, CsoundBindings that wrap the sensor will send values into Csound via hardcoded channels:

\begin{itemize}

\item Acclerometer
\begin{itemize}
\item accelerometerX
\item accelerometerY
\item accelerometerZ
\end{itemize}

\end{itemize} 

Once a sensor has been enabled, you can access those values in Csound using \textbf{chnget}. For further study, please see the \emph{Hardware Test} example in the Examples project. 

%======

\section{Csound for Android Examples}

The Examples project contains a number of simple examples that illustrate different aspects of working with Csound for Android.  The following is a brief description of each of the examples.

\subsection{Simple Test 1}

Simple example that plays ascending notes.  The pitch of the notes can be altered by using the SeekBar.  Also, a ToggleButton is used to turn on/off the rendering of Csound.  In the code, you'll find that the callback that is connected to the ToggleButton shows the basic usage of CsoundObj to render a CSD that is included as a resource for the project:

\begin{lstlisting}[caption=Example code showing configuring and starting a CsoundObj]
public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {
				if(isChecked) {
					String csd = getResourceFileAsString(R.raw.test);
					File f = createTempFile(csd);
					csoundObj.addSlider(fSlider, "slider", 0.,
							1.);
					csoundObj.addListener(SimpleTest1Activity.this);
					csoundObj.startCsound(f);
				} else {
					csoundObj.stopCsound();
				}
				
			}
		});
\end{lstlisting}

\subsection{Simple Test 2}

This is a generative music example that contains a number of SeekBars that affect the rate of notes generated, the duration of notes, and the ADSR envelope for each note. 


\subsection{Button Test}

This example uses a CSD based on the one used for Simple Test 2, but depends on the user to trigger a button to generate each note.  The two buttons in this example show two different ways in which to integrate buttons with CsoundObj:

\begin{enumerate}
\item Using CsoundUI's \textbf{addButton} method, which will setup a k-rate channel for Csound, the value will be 0 when the button is not pressed, and will be 1 for one ksmps period when a button is pressed (it returns to 0 the following ksmps period). 
\item Using a standard button callback, the callback will create a string score and send that to Csound using CsoundObj's \textbf{sendScore} method. (See code below.)
\end{enumerate}


\begin{lstlisting}[caption=Example code showing sending score text to CsoundObj]
String event = String.format("i2 0 %f", value);
									
csoundObj.sendScore(event);
\end{lstlisting}

Note that the second method will read the value from the duration slider when creating the note, while the first method handles reading the duration from the channel within the CSD code. 

\subsection{Ping Pong Delay}

This example shows processing audio input in realtime, using a Ping Pong Delay. The use of audio input is controlled by the standard Csound flag \textbf{-i adc} that is found in the CSD's \textbf{CsOptions} section.  


\subsection{Harmonizer}

This example highlights the same techniques as the Ping Pong Delay, but shows the use of Csound's streaming Phase Vocoder to create a harmonizer effect. 

\subsection{Accelerometer}

This example shows the use of the accelerometer sensor.  For this example, the accelerometer is enabled and values are read by the CSD to affect the pitch of a vco2 oscillator, as well as cutoff and resonance of a moogladder filter. 

\subsection{Csound Haiku 4}

\emph{Csound Haiku} is a generative art music work by Iain McCurdy.  Number 4 from this set of pieces was chosen to exercise what this platform is of capable.

\subsection{Multitouch XY}

This example demonstrates a multitouch performance surface. The multi-touch code maps each touch down and up to a note on and off.  It also sends continous x and y values to Csound.  The Csound programming in the CSD shows a technique for doing individual per-note control data mapping by dynamically assigning what channels of data each note should read from. 

\subsection{Waveview}

This example demonstrates using a CsoundBinding to read an f-table from Csound and displaying that table.  Note that the WaveView's code is doing some optimization to check if it has already loaded.  It is also checking that the table itself has completed loading before trying to grab any values for the table. 

\begin{lstlisting}[caption=Waveview code demonstrating reading f-tables from Csound]
		public void updateValuesFromCsound() {
			if (!tableLoaded) {
				Csound csound = csoundObj.getCsound();
				CsoundMYFLTArray table = new CsoundMYFLTArray();
				int length = csound.TableLength(1);
				csound.GetTable(table.GetPtr(), 1);
				tableData = new double[length];

				for (int i = 0; i < length; i++) {
					tableData[i] = table.GetValue(i);
				}

				tableLoaded = true;

				new Thread() {
					@Override
					public void run() {

						int width = getWidth();
						int height = getHeight();
						int middle = height / 2;

						points = new int[width];

						int tableLength = tableData.length;

						for (int i = 0; i < width; i++) {
							float percent = i / (float) (width);
							int index = (int) (percent * tableLength);
							points[i] = (int) ((tableData[index] * middle) + middle);
						}

						postInvalidate();

					}
				}.start();
			}
		}
\end{lstlisting}



%======
\section{Making Your First Csound Android App }


This section will walk you through your first Csound-based Android application. Initial setup of your program requires that:

\begin{itemize}
\item Create a new project in Android Studio using an application name of \textit{FirstCsoundApp} and company domain of \textit{example.com}.
\item Use the default settings for the rest of the New Project wizard (e.g., build for phone and tablet, use ``Empty Activity'', use default MainActivity and activity\_main names). This should create a new Project space that has one module called ``app''.  
\item Import the CsoundAndroid library module into your project. This is available from the File menu, under New, using the ``Import Module'' option.  
\item To use the Csound module from the application, you will need to add a dependency.  Right-click the ``app'' module and choose ``Open Module Settings''. For the app module, select the far-right tab called ``Dependencies'', then use the + button to add a ``Module Dependency''. Choose CsoundAndroid.  
\end{itemize}

First let us create the user interface. Android developers will generally use either XML to define the interface or hand-code the UI using Java code. Using XML allows for using Android Studio's GUI editor and we will use this in this tutorial. 

Navigate to the $res>layout>$\textit{activity_main.xml} within the \textit{app} module in the Project Explorer in Android Studio. Double-click the file and the UI editor will appear.  At the bottom fo the editor will be two tabs: Design and Text.  Choose the Text tab and insert the following XML code. This will create three Buttons and a SeekBar as shown.

\begin{lstlisting}[caption=Code to create UI]
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent" >
    
    <!--This is a comment! the following inserts a Button and is 
    soley responsiple for how the Button looks in this app.
    The id section is used for refferencing to the Button throughout
    the rest of the project -->
    
    <LinearLayout 
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:id="@+id/ButtonList"
        android:orientation="horizontal"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        >
    <Button
        android:id="@+id/StartCsound"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:text="StartCsound"
         />
    <Button
        android:id="@+id/StopCsound"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:text="StopCsound"
         />
    <Button
        android:id="@+id/Button1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:text="B1"
         />
    
    </LinearLayout>
    
    <!--This is a comment! the following inserts a SeekBar (comminly reffered to as a slider) and is 
    soley responsiple for how the Button looks in this app.
    The id section is used for refferencing to the SeekBar throughout
    the rest of the project-->
    <SeekBar
        android:id="@+id/SeekBar1" 
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:layout_below="@+id/ButtonList"
        />

</RelativeLayout>
\end{lstlisting}

\begin{center}
\includegraphics[scale=0.30]{images/CsoundBasicAppUIDia}
\end{center}

Next go to your project manifest to add the necessary permissions for fully using the CsoundObj. This is done by selecting AndroidManifest.xml from the Manifests folder for the application module within project explorer. 

Add the following to your Manifest

\begin{center}
\includegraphics[scale=0.60]{images/Manifest}
\end{center}

Now that the UI is built and the manifest has been prepared, proceed to opening the main activity of the project \textit{src}$>$\textit{com.example.firstCsoundApp}$>$\textit{MainActivity.java}. You should see the following when you open the class:

\begin{center}
\includegraphics[scale=0.75]{images/CsoundBasicAppOrignalActivity}
\end{center}

Add the \textit{BaseCsoundActivity.java} class to your project. This can be done by copying it into the \textit{src} folder of your project on your computer from the CsoundAndroidExamples project that comes with the Csound for Android download.

Next you need to import the necessary packages into your package for the application to compile correctly. These include the Csound package and widget packages for the UI. To see all the automatically imported packages click the $+$ button beside the import shown in the last image

\begin{center}
\includegraphics[scale=0.60]{images/ImportedPackages}
\end{center}

Next extend your class with BaseCsoundActivity instead of Activity (note that BaseCsoundActivity extends Activity). Then add your variables and initialise them in the onCreate method as shown below. 

\begin{center}
\includegraphics[scale=0.60]{images/VariblesCreated}
\end{center}

In our Activity class we have to connect our UI comments to our CsoundObj to allow us to pass information from our UI to our Csound code. In following code the max value of the SeekBar is set to 1 and the minium value is set to 0. To reserve this data in your Csound code use the opcode chnget and button1 and seekBar1. The Button and SeekBar are added each time before every time CsoundObj is set playing to ensure they are in the variable cacheable for the object.

\begin{center}
\includegraphics[scale=0.50]{images/FinalActivity}
\end{center}

To get your Csound code into the project, create a \textit{raw} folder in your project in the \textit{res} folder. This can be done by right-clicking your \textit{res} folder in your project explorer, go to the \textit{New} popup menu option, then choose \textit{Directory}. Name the folder  \textit{raw} and complete the operation. 

Next go to the containing folder of your project on your computer and put your Csound .csd file in the raw folder. Now when you return to Android Studio and run your project by clicking the play button, your first Csound app should be running with your Csound code. Congratulations!


\section{Csound App 2.0}

\emph{This section includes information for an older version of the CsoundApplication included with Csound for Android. This will be updated for Android Studio and the current version of CsoundApplication in the future.} 

This app demonstrates the use of the Csound library in the context of a larger application with multiple Activities, Views, and the ability to load in different .csd files dynamically. It is designed for stand alone use for those that do not want to get their hands dirty with Android programming but still want access to the platform, and for those who want an app with lots of functionality that they can use in their own applications. 

Hence the in order to get up and running with Csound on Android, all you need to do is use chnget in your .csd to get access to the UI values. SeekBars are set from 0 to 1 consequently some scaling may be necessary in your .csd. The Variable names to be used are:

\begin{itemize}
\item Performance1
\begin{itemize}
\item seekBar1
\end{itemize}
Performance 2
\begin{itemize}
\item seekBar2
\end{itemize}
Mixer
\begin{itemize}
\item seekBar3
\item seekBar4
\item seekBar5
\item seekBar6
\item seekBar7
\item seekBar8
\end{itemize}
\end{itemize}

\begin{itemize}
\item Performance1
\begin{itemize}
\item B1
\item B2
\item B3
\item B4
\item B5
\item B6
\item B7
\item B8
\item B9
\item B10
\item B11
\item B12
\item B13
\item B14
\item B15
\item B16
\item B17
\item B18
\item B19
\end{itemize}
Performance 2
\begin{itemize}
\item B20
\item B21
\item B22
\item B23
\item B24
\end{itemize}
\end{itemize}

\begin{lstlisting}[caption=Exampe of code to be used in .csd to connect Seekbars and Buttons]
kVolume chnget "seekBar1"
kOnOff  chnget "B1"
\end{lstlisting}

To use the xy pad in tab Performance2 use the following
\begin{lstlisting}[caption=Exampe of code to be used in .csd to connect xy pad]
S_xName sprintf "touch.%d.x", i_instanceNum
S_yName sprintf "touch.%d.y", i_instanceNum

kx chnget S_xName
ky chnget S_yName
\end{lstlisting}

For those who want to customise the app and understand its workings the following, along with the comments in the apps code should help. This application has been designed to allow user changes to the source code and was built to demonstrate the use of a singleton design process to preserve a CsoundObj for the whole Android lifecycle of an application. There are several situations that have to be taken into consideration.

\begin{enumerate}
\item Adding the UI controls to the CsoundObj when Android Activities are created and destroyed by the Android OS to recover RAM.
\item The selecting of new .csd files to be loaded into the application, and creating a new CsoundObj object for this event. 
\item The consistency between different activities and views to allow users to change between views during a performance.
\end{enumerate}

Many of these features are achieved by extending Application. It is used to store the CsoundObj, the current file path, the current features of each application and view. it is also used to give all activities a set of methods which will always have to be called and which will never be destroyed by the Android life cycle, thus ensuring their constant availability
It is important to note that throughout this app BaseCsoundActivity.java is extended instead of Activity (As BaseCsoundActivity.java extends Acitivity). BaseCsoundActivity.java is used to take advantage of it methods such as:
\begin{itemize}
\item protected String getResourceFileAsString(int resId)
\item protected File createTempFile(String csd)
\end{itemize}
Hence this may be a design choice worth remembering when coding your own apps.

\section{Conclusion}

We hope that this document has helped you to become familiar with the design and usage of the Csound for Android API. The example Java and Csound CSD code should hopefully give you a good starting point for your own musical projects, and we encourage you to take these examples and run with it.  We look forward to hearing your questions and feedback on this API, and most of all, look forward to seeing what you will create with all of this.  Best of luck and enjoy! 

\end{document}