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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
<TITLE></TITLE>
<META NAME="GENERATOR" CONTENT="LibreOffice 4.0.1.2 (Windows)">
<META NAME="CREATED" CONTENT="20130611;20113632">
<META NAME="CHANGED" CONTENT="20150409;8311847">
<STYLE TYPE="text/css">
<!--
@page { size: 8.5in 11in; margin: 0.79in }
P { margin-bottom: 0.08in }
H1 { margin-bottom: 0.08in; page-break-after: avoid }
H1.western { font-family: "Arial", sans-serif; font-size: 16pt; font-weight: bold }
H1.cjk { font-family: "Microsoft YaHei"; font-size: 16pt; font-weight: bold }
H1.ctl { font-family: "Mangal"; font-size: 16pt; font-weight: bold }
PRE.western { font-family: "Courier New", monospace; font-size: 10pt }
PRE.cjk { font-family: "NSimSun", monospace; font-size: 10pt }
PRE.ctl { font-family: "Courier New", monospace; font-size: 10pt }
H2 { margin-bottom: 0.08in; page-break-after: avoid }
H2.western { font-family: "Arial", sans-serif; font-size: 14pt; font-style: italic; font-weight: bold }
H2.cjk { font-family: "Microsoft YaHei"; font-size: 14pt; font-style: italic; font-weight: bold }
H2.ctl { font-family: "Mangal"; font-size: 14pt; font-style: italic; font-weight: bold }
A:link { color: #000080; so-language: zxx; text-decoration: underline }
A:visited { color: #800000; so-language: zxx; text-decoration: underline }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" LINK="#000080" VLINK="#800000" DIR="LTR">
<H1 CLASS="western" ALIGN=CENTER STYLE="margin-top: 0.08in; margin-bottom: 0in">
User Guide<BR>Csound 6.05.0 for Android
</H1>
<P ALIGN=CENTER STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>Michael
Gogins</B></I></P>
<P ALIGN=CENTER STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>9
April 2015</B></I></P>
<P ALIGN=CENTER STYLE="margin-top: 0.08in; margin-bottom: 0in"><BR>
</P>
<H1 CLASS="western" STYLE="margin-top: 0.08in; margin-bottom: 0in">Introduction</H1>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">This is an
extremely basic guide to using the Csound 6 app for Android. It
should be just enough to get you started if you already have some
experience with Csound or, at least, some other “Music N”
type software synthesizer.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Csound6 app is
an Android version of Csound, an audio and music synthesis and
processing language of great power, created by Barry Vercoe in 1984,
maintained with complete backward compatibility since then, and
widely used and taught for the creation of electroacoustic and
computer music. Desite its age, Csound6 continues to be actively
developed. It has many advanced features for sound synthesis
including user-designable instruments, an easy to learn programming
language with a type system, several phase vocoders, several sample
players, a plethora of digital oscillators, filters, and envelope
generators, transparent multi-threading for high performance on
multi-core systems, and an embedded Lua just-in-time compiler.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Csound app is
by Victor Lazzarini, Steven Yi, Michael Gogins, and others. The app
contains virtually all of Csound, including some of the more
frequently used plugin opcodes:</P>
<UL>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The signal
flow graph opcodes, for chaining instruments into effects chains and
so on.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Fluidsynth
opcodes for playing SF2 samples.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The libstdutil
library.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Lua
opcodes, which embed LuaJIT and enable arbitrary Lua code to execute
in Csound either for signal processing or for score generation or,
indeed, for any purpose. Particularly amazing is that LuaJIT has a
foreign function interface that is capable of loading any shared
library that Android permits, and calling any exported function in
that library.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The scanned
synthesis opcodes.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Open Sound
Control (OSC) opcodes which allow Csound to communicate over
networks with other software in a low-latency and flexible manner.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in">The Doppler
opcode.</P>
</UL>
<H1 CLASS="western" STYLE="margin-top: 0.08in; margin-bottom: 0in">User
Interface</H1>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Csound6 has a
preset user interface consisting a row of menu buttons, a widget
area, three context menu help buttons, and a scrolling display at the
bottom of the screen that prints messages output by Csound as it
runs.The menu buttons perform the following functions:
</P>
<UL>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>New</B></I>
– creates a blank template CSD file in the root directory of
the user's storage for the user to edit. The CSD file will be
remembered and performed by Csound.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>Open </B></I><SPAN STYLE="font-variant: normal">–
</SPAN><SPAN STYLE="font-variant: normal"><SPAN STYLE="font-style: normal"><SPAN STYLE="font-weight: normal">opens
an existing CSD file in the root directory of the user's storage.</SPAN></SPAN></SPAN>
The user's storage filesystem can be navigated to find other files.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>Edit</B></I>
– opens a text editor to edit the current CSD file. Be sure to
save the file before you perform it! I recommend the free, open
source <A HREF="https://play.google.com/store/apps/details?id=jp.sblo.pandora.jota&hl=en">Jota</A>
text editor on smartphones and, though I haven't tried Jota on
tablets, it probably works well there as well.</P>
<LI><P STYLE="margin-top: 0.08in; margin-bottom: 0in"><I><B>Start/Stop</B></I>
– if a CSD file has been loaded, starts running Csound; if
Csound is running, stops it. If the <FONT FACE="Courier New, monospace"><CsOptions></FONT>
element of the CSD file contains <FONT FACE="Courier New, monospace">-odac</FONT>,
Csound's audio output will go to the device audio output. If the
element contains <FONT FACE="Courier New, monospace">-osoundfilename</FONT>,
Csound's audio output will go to the file <FONT FACE="Courier New, monospace">soundfilename</FONT>,
which should be a valid Linux pathname in the user's storage
filesystem.</P>
</UL>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">There are actually
two types of widget area: one with pre-defined widgets, and one with
user-defined widgets.
</P>
<H2 CLASS="western">Predefined Widgets</H2>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The widgets are
assigned control channel names <FONT FACE="Courier New, monospace">slider1</FONT>
through <FONT FACE="Courier New, monospace">slider5</FONT>, <FONT FACE="Courier New, monospace">butt1</FONT>
through <FONT FACE="Courier New, monospace">butt5</FONT>, <FONT FACE="Courier New, monospace">trackpad.x</FONT>,
and <FONT FACE="Courier New, monospace">trackpad.y</FONT>. In
addition, the accelerometer on the Android device is available as
<FONT FACE="Courier New, monospace">accelerometerX</FONT>,
<FONT FACE="Courier New, monospace">accelerometerY</FONT>, and
<FONT FACE="Courier New, monospace">accelerometerZ</FONT>.
</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The values of these
widgets are normalized between 0 and 1, and can be read into Csound
during performance using the <FONT FACE="Courier New, monospace">chnget</FONT>
opcode, like this:
</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in"><FONT FACE="Courier New, monospace">kslider1_value
chnget “slider1”</FONT></P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in"><BR>
</P>
<H2 CLASS="western"><IMG SRC="Csound6_User_Guide_html_773f6605.png" NAME="graphics1" ALIGN=LEFT HSPACE=19 VSPACE=19 WIDTH=297 HEIGHT=586 BORDER=0><BR CLEAR=LEFT>User-Defined
Widgets</H2>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">User-defined
widgets are defined in a new <FONT FACE="Courier New, monospace"><CsHtml5></FONT>
element of the CSD file. This can in principle contain any valid
HTML5 code, including document elements, JavaScript, and styles.
JavaScript event handlers can be attached to any elements, including
range inputs (sliders). Such event handlers can call Java methods of
the <FONT FACE="Courier New, monospace">CsoundAppActivity</FONT>
application object (<FONT FACE="Courier New, monospace">csoundApp</FONT>)
and the <FONT FACE="Courier New, monospace">CsoundObj</FONT> object
(<FONT FACE="Courier New, monospace">csound</FONT>), for example to
get or set control channel values, or to send new score events to
Csound.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The ability to send
score events to Csound from JavaScript means that JavaScript can be
used as a high-level programming language in the CSD file for the
purposes of algorithmic composition, even interactive composition.
All methods callable from <FONT FACE="Courier New, monospace">CsoundAppActivity</FONT>
and <FONT FACE="Courier New, monospace">CsoundObj</FONT>are marked
with the <FONT FACE="Courier New, monospace">@JavascriptInterface</FONT>
attribute in the Csound for Android source code. For a basic example
of a user-defined widget setup, see the <FONT FACE="Courier New, monospace">Drone-HTML5.csd</FONT>
example file. Here is a snippet showing a slider's <FONT FACE="Courier New, monospace">onInput</FONT>
event handler setting a Csound control channel:</P>
<PRE CLASS="western" STYLE="page-break-inside: avoid; page-break-before: auto; page-break-after: auto"><script>
function gk_Reverb_FeedbackUpdate(value) {
var numberValue = parseFloat(value)
csoundApp.setControlChannel('gk_Reverb_Feedback', numberValue);
}
</script></PRE><H1 CLASS="western" STYLE="margin-top: 0.08in; margin-bottom: 0in">
Examples</H1>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The menu of the
Csound app features a number of built-in examples. Selecting an
example will cause its file or files to be copied to the app's
external storage area and loaded into the app, ready to be performed
or edited. Not all of the examples use the widgets. The examples
demonstrate not only some techniques for using the Csound6 Android
app, but also a few of the many different ways of making music with
Csound.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">When I first
encountered the Csound app, I was very impressed. Now that I have
been able to contribute to its development, I have come to realize
that a high end smartphone, not to mention a tablet, is in every
sense of the word a real computer. The limits to what can be
programmed on it are indefinable. On a high-end personal computer, it
is easier to type, and Csound runs quite a bit faster; but there is
no <I>essential</I> difference between running Csound on a computer
and running it on a smartphone.</P>
<H1 CLASS="western" STYLE="margin-top: 0.08in; margin-bottom: 0in">A
Tutorial Example</H1>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">This example will
take you through the process of creating a new Csound piece, step by
step. Obviously, this piece is not going to reveal anything like the
full power of Csound. It is only intended to get you to the point of
being able to create, edit, and run a Csound piece that will actually
make sound on your Android device – from scratch.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Before you get
started, install the <A HREF="https://play.google.com/store/apps/details?id=jp.sblo.pandora.jota&hl=en">Jota</A>
text editor on your device. Other text editors might work with the
Csound app, but this one is known to work.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Run the Csound6
app...</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Press the <B>New</B>
button. You should be presented with an input dialog asking you for a
filename for your piece. Type in <FONT FACE="Courier New, monospace">toot.csd</FONT>,
and press the <B>Ok</B> button. The file will be stored in the root
directory of your user storage on your device. You can save the file
to another place using Jota's <B>File</B> menu, if you like.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">The text editor
should open with a “template” CSD file. Your job is to
fill out the minimum to hear something.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Create a blank line
between <FONT FACE="Courier New, monospace"><CsOptions></FONT>
and <FONT FACE="Courier New, monospace"></CsOptions></FONT>,
and type <FONT FACE="Courier New, monospace">-odac -d -m3</FONT>.
This means send audio to the real-time output (<FONT FACE="Courier New, monospace">-odac</FONT>),
do not display any function tables (<FONT FACE="Courier New, monospace">-d</FONT>),
and log some informative messages during Csound's performance (<FONT FACE="Courier New, monospace">-m3</FONT>).</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Create a blank line
between <FONT FACE="Courier New, monospace"><CsInstruments></FONT>
and <FONT FACE="Courier New, monospace"></CsInstruments></FONT>
and type the following text:</P>
<PRE CLASS="western">sr = 44100
ksmps = 10
nchnls = 1
<FONT COLOR="#000000"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 9pt">instr 1</FONT></FONT></FONT>
asignal oscil 10000, 440
<FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 9pt">out asignal</FONT></FONT>
<FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 9pt">endin</FONT></FONT></PRE><P STYLE="margin-top: 0.08in; margin-bottom: 0in">
<BR>This is just about the simplest possible Csound orchestra. The
orchestra header specifies an audio signal sampling rate of 44,100
frames per second, with 10 audio frames per control signal sample,
and one channel of audio output. The instrument is just a simple sine
oscillator. It plays a loud tone at concert A.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Create a blank line
between <FONT FACE="Courier New, monospace"><CsScore></FONT>
and <FONT FACE="Courier New, monospace"></CsScore></FONT> and
type:</P>
<PRE CLASS="western" STYLE="margin-top: 0.08in; margin-bottom: 0.08in">i1 0 5</PRE><P STYLE="margin-top: 0.08in; margin-bottom: 0in">
This means play instrument 1 starting at time 0 for 5 seconds.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Press the text
editor's <B>Save</B> button and then its <B>Quit</B> button.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">Press the Csound
app's <B>Start</B> button. You should hear a loud sine tone for 5
seconds.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">If you want to save
your audio output to a soundfile named <FONT FACE="Courier New, monospace">test.wav</FONT>,
change <FONT FACE="Courier New, monospace">-odac</FONT> above to
<FONT FACE="Courier New, monospace">-o/sdcard/test.wav</FONT>.</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in">That's it!</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-top: 0.08in; margin-bottom: 0in"><BR>
</P>
</BODY>
</HTML>
|
