Skip to content

argv

Returns application arguments as a string array.

Use argv to pass file paths or settings to an orchestra without editing the CSD. Put them after -- on the command line, with the CSD filename and all Csound options before it.

Syntax

Sargs[] = argv()

Sargs[] argv

Initialization

argv takes no inputs. It fills Sargs[] at initialization with one string for each argument after --, in the order given, leaving out the separator itself and everything before it.

Array indices start at zero. Use lenarray to check how many arguments you have before reading an element. With no application arguments, the array is empty.

For example, csound piece.csd -- flute 440 returns "flute" at index 0 and "440" at index 1. Both are strings. Use strtod or strtol when you need a number.

Quote an argument that contains spaces, such as "field recording.wav", to keep it in one array element. An empty quoted argument, "", also occupies one element. After the separator, even a value such as --quiet is an application argument and Csound does not treat it as an option.

You can also put -- and application arguments in <CsOptions>. A command-line -- replaces that list, and a command-line -- with nothing after it clears the list.

A host using the Csound API can supply the list with csoundSetCommandLineArgs(). The opcode copies the current list when it initializes and does not refresh it during performance.

Examples

This small command-line tool prints the length of each sound file you pass to it. It produces no audio. Download argv.csd, fox.wav and beats.wav into the same folder, then run the following command from that folder.

csound argv.csd -- fox.wav beats.wav

To inspect your own recording, pass its path instead.

csound argv.csd -- "field recording.wav"
Print the length of each sound file
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr 1
  Sfiles[] argv
  iFileCount = lenarray(Sfiles)

  ; Check the count before reading any array elements.
  if iFileCount == 0 then
    prints "Run csound argv.csd -- file.wav [more files]\n"
  else
    ; Each argument is one path, including paths quoted to keep spaces.
    iIndex = 0
    while iIndex < iFileCount do
      iSeconds filelen Sfiles[iIndex]
      prints "%s lasts %.3f seconds\n", Sfiles[iIndex], iSeconds
      iIndex += 1
    od
  endif
endin
</CsInstruments>
<CsScore>
i 1 0 0.01
e
</CsScore>
</CsoundSynthesizer>

Running csound argv.csd without arguments prints a short usage message.

See also

lenarray, strtod, strtol, filelen

Credits

Opcode by Hlöðver Sigurðsson, 2026.

New in Csound 7.