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
|
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.03 [en] (X11; I; IRIX 6.3 IP32) [Netscape]">
<TITLE>THE_CSOUND_COMMAND</TITLE>
</HEAD>
<BODY>
<CENTER><A NAME="The_CSOUND_Command"></A>
<HR><B><A HREF="../REFER.html">QUICK-REF</A></B> - <B><A HREF="../TITLE.html"><FONT SIZE=+1>C</FONT>soundManual</A></B>
- <B><U><A HREF="../Cscore/CSCORE.html">Previous Section</A></U></B> -
<B><U><A HREF="../Utility/UTILITIES.html">Next Section</A></U></B> - <A HREF="../CONTENTS.html">Contents</A>
- <A HREF="../INDEX.html">Index</A> - <A HREF="scsor.html">Next</A>
<HR></CENTER>
<H2>
The CSOUND Command</H2>
<B><TT>csound</TT></B> is a command for passing an <A NAME="1" HREF="../Tutorial/orcfile.html"></A><A HREF="../Tutorial/orcfile.html" NAME="1">orchestra
file</A> and <A NAME="2" HREF="../Tutorial/scofile.html"></A><A HREF="../Tutorial/scofile.html" NAME="2">score
file</A> to <B>Csound</B> to generate a soundfile. The score file can be
in one of many different formats, according to user preference. Translation,
sorting, and formatting into orchestra-readable numeric text is handled
by various preprocessors; all or part of the score is then sent on to the
orchestra. Orchestra performance is influenced by command flags, which
set the level of displays and console reports, specify 1/0 filenames and
sample formats, and declare the nature of realtime sensing and control.
<P><B>IMPORTANT NOTE:</B> These are generic Csound command flags. Various
platform implementations may not react the same way to different flags!
<P>The format of a command is:
<PRE><TT> <B>csound </B>[-flags] orchname scorename</TT></PRE>
where the arguments are of 2 types: <I>flag</I> arguments (beginning with
a "-"), and <I>name</I> arguments (such as filenames). Certain flag arguments
take a following name or numeric argument. The available flags are:
<PRE>-U unam run utility program unam
-C use Cscore processing of scorefile
-I I-time only orch run
-n no sound onto disk
-i fnam sound input filename
-o fnam sound output filename
-b N sample frames (or -kprds) per software sound I/O buffer
-B N samples per hardware sound I/O buffer
-A create an AIFF format output soundfile
-W create a WAV format output soundfile
-h no header on output soundfile
-c 8-bit signed_char sound samples
-a alaw sound samples
-8 8-bit unsigned_char sound samples
-u ulaw sound samples
-s short_int sound samples
-l long_int sound samples
-f float sound samples
-r N orchestra srate override
-k N orchestra krate override
-v verbose orch translation
-m N tty message level. Sum of: 1=note amps, 2=out-of-range msg, 4=warnings
-d suppress all displays
-g suppress graphics, use ascii displays
-G suppress graphics, use Postscript displays
-S score is in Scot format
-x fnam extract from score.srt using extract file 'fnam'
-t N use uninterpreted beats of the score, initially at tempo N
-L dnam read Line-oriented realtime score events from device 'dnam'
-M dnam read MIDI realtime events from device 'dnam'
-F fnam read MIDIfile event stream from file 'fnam'
-P N MIDI sustain pedal threshold (0 - 128)
-R continually rewrite header while writing soundfile (WAV/AIFF)
-H print a heartbeat character at each soundfile write
-N notify (ring the bell) when score or miditrack is done
-T terminate the performance when miditrack is done
-D defer GEN01 soundfile loads until performance time
-z List opcodes in this version</PRE>
<PRE></PRE>
<B><U>PC Windows-specific flags</U></B>
<PRE>-j num set the number of console text rows (default 25)
-J num set the number of console text columns (default 80)
-K num enables MIDI IN. 'num' (optional) = MIDI IN port device id number
-q num WAVE OUT device id number (use only if more WAVE devices are installed)
-p num number of WAVE OUT buffers (default 4; max. 40)
-O suppresses all console text output for better realtime performance
-e allows any sample rate (to use only with WAVE cards supporting this feature)
-y doesn't wait for keypress on exit
-E allows graphic display for WCSHELL by Riccardo Bianchini
-Q num enable MIDI OUT. 'num' (optional) = MIDI OUT port device id number
-Y suppresses realtime WAVE OUT for better MIDI OUT timing performance
-* yields control to the system until audio output buffer is full
</PRE>
<B><U>DESCRIPTION:</U></B>
<BR>
<P>Flags may appear anywhere in the command line, either separately or
bundled together. A flag taking a Name or Number will find it in that argument,
or in the immediately subsequent one. The following are thus equivalent
commands:
<PRE><TT> <B>csound</B> -nm3 orchname -Sxxfilename scorename
<B>csound</B> -n -m 3 orchname -x xfilename -S scorename</TT></PRE>
All flags and names are optional. The default values are:
<PRE><TT> <B>csound</B> -s -otest -b1024 -B1024 -m7 -P128 orchname scorename</TT></PRE>
where orchname is a file containing Csound orchestra code, and scorename
is a file of score data in <A NAME="3" HREF="../NumScore/NUMSC.html"></A><A HREF="../NumScore/NUMSC.html" NAME="3">standard
numeric score format</A>, optionally presorted and time-warped. If scorename
is <I>omitted</I>, there are two default options: 1) if realtime input
is expected (-L, -M or -F), a dummy scorefile is substituted consisting
of the single statement 'f 0 3600' (i.e. listen for RT input for one hour);
2) else <B>csound</B> uses the previously processed <I>score.srt</I> in
the <I>current directory</I>.
<P><B>Csound</B> reports on the various stages of score and orchestra processing
as it goes, doing various syntax and error checks along the way. Once the
actual performance has begun, any error messages will derive from either
the instrument loader or the unit generators themselves. A <B>csound</B>
command may include any rational combination of the following flag arguments,
with default values as described:
<BR>
<BR>
<DT>
<B>csound -U</B></DT>
<DD>
Invoke Utility Preprocessing programs: <A NAME="3" HREF="../Utility/sndinfo.html"></A><A HREF="../Utility/sndinfo.html" NAME="3">sndinfo</A>, <A NAME="4" HREF="../Utility/hetro.html"></A><A HREF="../Utility/hetro.html" NAME="4">hetro</A>, <A NAME="5" HREF="../Utility/lpanal.html"></A><A HREF="../Utility/lpanal.html" NAME="5">lpanal</A>, <A NAME="6" HREF="../Utility/pvanal.html"></A><A HREF="../Utility/pvanal.html" NAME="6">pvanal</A>,
<A HREF="../Utility/convolve.html">cvanal</A>.</DD>
<BR>
<DT>
<B>csound -I</B></DT>
<DD>
I-time only. Allocate and initialize all instruments as per the score,
but skip all P-time processing (no k-signals or a-signals, and thus no
amplitudes and no sound). Provides a fast validity check of the score pfields
and orchestra <B>i</B>-variables.</DD>
<BR>
<DT>
<B>csound -n</B></DT>
<DD>
Nosound. Do all processing, but bypass writing of sound to disk. This flag
does not change the execution in any other way.</DD>
<BR>
<DT>
<B>csound -i isfname</B></DT>
<DD>
Input soundfile name. If not a full pathname, the file will be sought first
in the current directory, then in that given by the environment variable <A NAME="6" HREF="../Syntax/dir.html"></A><A HREF="../Syntax/dir.html" NAME="6">SSDIR</A>
(if defined), then by <A NAME="6" HREF="../Syntax/dir.html"></A><A HREF="../Syntax/dir.html" NAME="6">SFDIR</A>.
The name <I>stdin</I> will cause audio to be read from standard input.
If <B>RTAUDIO </B>is enabled, the name <I>devaudio</I> will request sound
from the host audio input device.</DD>
<BR>
<BR>
<DT>
<B>csound -o osfname</B></DT>
<DD>
Output soundfile name. If not a full pathname, the soundfile will be placed
in the directory given by theenvironment variable <A NAME="6" HREF="../Syntax/dir.html"></A><A HREF="../Syntax/dir.html" NAME="6">SFDIR</A>
(if defined), else in the current directory. The name <I>stdout</I> will
cause audio to be written to standard output. If no name is given, the
default name will be <I>test</I>. If <B>RTAUDIO </B>is enabled, the name
<I>devaudio</I> will send to the host audio output device.</DD>
<BR>
<DT>
<B>csound -b Numb</B></DT>
<DD>
Number of audio sample-frames per soundio <I>software</I> buffer. Large
is efficient, but small will reduce audio I/O delay. The default is 1024.
<B>In realtime performance</B>, <B>Csound</B> waits on audio I/O on <I>Numb</I>
boundaries. It also processes audio (and polls for other input like MIDI)
on orchestra <I>ksmps</I> boundaries. The two can be made synchronous.
For convenience, if Numb = -N (is negative) the effective value is <I>ksmps
* N</I> (audio synchronous with k-period boundaries). With N small (e.g.
1) polling is then frequent and also locked to fixed DAC sample boundaries.</DD>
<BR>
<DT>
<B>csound -B Numb</B></DT>
<DD>
Number of audio sample-frames held in the DAC <I>hardware</I> buffer. This
is a threshold on which <I>software</I> audio I/O (above) will wait before
returning. A small number reduces audio I/O delay; but the value is often
hardware limited, and small values will risk data lates. The default is
1024.</DD>
<BR>
<DT>
<B>csound -h</B></DT>
<DD>
No header on output soundfile. Don't write a file header, just binary samples.</DD>
<BR>
<DT>
<B>csound {-c, -a, -u, -s, -l, -f}</B></DT>
<DD>
Audio sample format of the output soundfile. One of:</DD>
<PRE> c 8-bit signed character
a 8-bit a-law
u 8-bit u-law
s short integer
l long integer
f single-precision float (not playable, but can be read by <B>-i, <A NAME="8" HREF="../In+Out/in.html"></A><A HREF="../In+Out/in.html" NAME="8">soundin</A></B> and <A NAME="9" HREF="../Function/gen01.html"></A><B><A HREF="../Function/gen01.html" NAME="9">GEN01</A></B>)</PRE>
<DT>
<B>csound -A</B></DT>
<DD>
Write an AIFF output soundfile. Restricts the above formats to <B>c</B>,<B>
s</B>, or <B>l</B>.</DD>
<BR>
<DT>
<B>csound -v</B></DT>
<DD>
Verbose translate and run. Prints details of orch translation and performance,
enabling errors to be more clearly located.</DD>
<BR>
<DT>
<B>csound -m Numb</B></DT>
<DD>
Message level for standard (terminal) output. Takes the <I>sum</I> of 3
print control flags, turned on by the following values: 1 = note amplitude
messages, 2 = samples out of range message, 4 = warning messages. The default
value is <I>m7</I> (all messages on).</DD>
<BR>
<DT>
<B>csound -d</B></DT>
<DD>
Suppress all displays.</DD>
<BR>
<DT>
<B>csound -g</B></DT>
<DD>
Recast graphic displays into <B>ascii</B> characters, suitable for any
terminal.</DD>
<BR>
<DT>
<B>csound -S</B></DT>
<DD>
Interpret <B>scorename</B> as a <A NAME="10" HREF="CsScot.html#"></A><A HREF="CsScot.html#" NAME="10">Scot
file</A> and create a standard score file (named "score") from it, then
sort and perform that.</DD>
<BR>
<DT>
<B>csound -x xfile</B></DT>
<DD>
Extract a portion of the sorted score <B>score.srt</B>, according to <B>xfile</B>
( <A NAME="11" HREF="extract.html"></A><A HREF="extract.html" NAME="11">see
Extract</A>).</DD>
<BR>
<DT>
<B>csound -t Numb</B></DT>
<DD>
Use the uninterpreted beats of <I>score.srt</I> for this performance, and
set the initial tempo at <I>Numb</I> beats per minute. When this flag is
set, the tempo of score performance is also controllable from within the
orchestra ( <A NAME="12" HREF="../Sensing/xyin.html"></A><A HREF="../Sensing/xyin.html" NAME="12">see
the tempo unit</A>).</DD>
<BR>
<DT>
<B>csound -L devname</B></DT>
<DD>
Read Line-oriented realtime score events from device <I>devname</I>. The
name <I>stdin</I> will permit score events to be typed at your terminal,
or piped from another process. Each line-event is terminated by a carriage-return.
Events are coded just like those in a <A NAME="12a" HREF="CsNumScore.html#"></A><I><A HREF="CsNumScore.html#" NAME="12a">standard
numeric score</A> </I>, except that an event with p2=0 will be performed
immediately, and an event with p2=T will be performed T seconds after arrival.
Events can arrive at any time, and in any order. The score <I>carry feature</I>
is legal here, as are held notes (p3 negative) and string arguments, but
ramps and pp or np references are not.</DD>
<BR>
<DT>
<B>csound -M devname</B></DT>
<DD>
Read MIDI events from device <I>devname</I>.</DD>
<BR>
<DT>
<B>csound -F mfname</B></DT>
<DD>
Read MIDI events from midifile <I>mfname</I>.</DD>
<BR>
<DT>
<B>csound -P Numb</B></DT>
<DD>
Set MIDI sustain pedal threshold (0 - 128). The official switch value of
64 is normally too low, and is more realistic above 100. The default value
of 128 will block all pedal info.</DD>
<BR>
<DT>
<B>csound -N</B></DT>
<DD>
Notify (ring the bell) when score or miditrack is done.</DD>
<BR>
<DT>
<B>csound -T</B></DT>
<DD>
Terminate the performance when miditrack is done.</DD>
<BR>
<P><B><U>PC/Windows-specific flags</U></B>
<BR>
<DT>
<B>csound -K num</B></DT>
<DD>
MIDI device id number (optional, use only if MIDI devices are more than
one)</DD>
<BR>
<DT>
<B>csound -q num</B></DT>
<DD>
WAVE OUT device id number (optional, use only if WAVE OUT devices are more
than one)</DD>
<BR>
<DT>
<B>csound -p num</B></DT>
<DD>
number of WAVE OUT buffers (optional; default=4, maximum=40). -b (buffer
length) and -p flags are related each other. Finding the optimum values
for "-b" and "-p" flags requires some experimentation: more buffer length
means more latency delay but also more safety from dropouts and sound interruptions
(flag "-B" is now obsolete, don't use it). You now can drastically reduce
buffer length and delay by using -e flag and 'rounded' sr and kr.</DD>
<DD>
Note that sometimes a samller buffer length can handle sound flow better
than a larger. Only experiments can lead you toward optimal '-b' values.
-b and -p flags value can now be reduced considerably by using "rounded"
ar and kr values (for example ar=32000 and kr=320; ar=40000 and kr=400
and so on) together with -e flag (till now this feature was tested only
with a SB16 ASP and with an AWE32 card. I don't know if other cards support
it). Reducing "-b" and "-p" flag values means reducing latency delay and
so a more interactive realtime playing.</DD>
<BR>
<DT>
<B>csound -j num</B></DT>
<DD>
console virtual text rows number.</DD>
<BR>
<DT>
<B>csound -J num</B></DT>
<DD>
console virtual text columns number.</DD>
<BR>
<DT>
<B>csound -O (uppercase letter)</B></DT>
<DD>
suppresses all printf for better realtime performance. This switch is better
than '-m0' because '-m0' still leaves some message output to the console.
Use both switches together for maximum performance speed.</DD>
<BR>
<DT>
<B>csound -e</B></DT>
<DD>
allows arbitrary output sample rate (for cards that support this feature).</DD>
<BR>
<DT>
<B>csound -y</B></DT>
<DD>
doesn't wait for keypress on exit.</DD>
<BR>
<DT>
<B>csound -E</B></DT>
<DD>
graphic display for WCSHELL by Riccardo Bianchini.</DD>
<BR>
<DT>
<B>csound -Q num</B></DT>
<DD>
enables MIDI OUT operations and optionally chooses device id num (if num
argument is present). This flag allows parallel MIDI OUT and DAC performance.
Unfortunately the realtime timing implemented in Csound is completely managed
by DAC buffer sample flow. So MIDI OUT operations can present some time
irregularities. These irregularities can be fully eliminated when suppressing
DAC operations themselves (see -Y flag).</DD>
<BR>
<DT>
<B>csound -Y</B></DT>
<DD>
disables WAVE OUT (for better MIDI OUT timing performances). This enhances
timing of midi out operations when used in conjunction with "-Q" flag.
It is recommended to use "-Y" with low krates (max. kr=1000). As in Win95
maximum timer resolution is 1/1000 of second, unpredictable results can
occurr when using it at krates greater than 1000. Also it is very important
to set only kr values in which the following division: 1000/kr produces
integer results (some example: kr = 10; 20; 50; 100; 125; 200; 250 etc.)
because Win95 timer only handles integer periods in milliseconds.</DD>
<DD>
If you use a kr value that produces a non integer result in the above formula
Csound seems to run normally but times will be not reliable. With my computer
I work very well with a value of kr=200. Maybe with slower computers a
lower value works better. Experiment! I recommend to use kr=200 or less
because with values greater than 200 increases the overhead affecting the
entire system and do not give a notable precision improvement. A time resoultion
of 1/200 of sec is enough precise for almost all MIDI application. You
must respect sr/kr/ksmps ratio even if sr value is meaningless when using
"-Y" flag, or an error message will stop the performance.</DD>
<BR>
<DT>
<B>csound -*</B></DT>
<DD>
compells Csound to yield control to system until audio output buffer content
passes a certain threshold. Below this threshold Csound continues processing,
while over this threshold Csound yields control to Windows. This gives
a big enhanchement in multitasking processes. Enabling this option reduces
polyphony a bit when using short buffer space. So the user should increase
the number ('-p' flag) and the length ('-b' flag) of buffers when setting
'-*' flag. Experiment to find best values. Do not use this flag when time
response to gestual actions is critical.</DD>
<BR>
<CENTER><P>
<HR><B><A HREF="../REFER.html">QUICK-REF</A></B> - <B><A HREF="../TITLE.html"><FONT SIZE=+1>C</FONT>soundManual</A></B>
- <B><U><A HREF="../Cscore/CSCORE.html">Previous Section</A></U></B> -
<B><U><A HREF="../Utility/UTILITIES.html">Next Section</A></U></B> - <A HREF="../CONTENTS.html">Contents</A>
- <A HREF="../INDEX.html">Index</A> - <A HREF="scsor.html">Next</A>
<HR></CENTER>
<P><CENTER>
<B><I><FONT COLOR="#006600">HTML Csound Manual - <FONT SIZE=-1>©
Jean Piché & Peter J. Nix, 1994-97</FONT></FONT></I></B>
</CENTER>
</HTML>
|
