Quick start

Create your first Csound program and generate sound in minutes

Quick start

This guide will help you create and run your first Csound program. In just a few minutes, you’ll be generating sound and understanding the basics of Csound’s architecture.

Make sure you have installed Csound before proceeding.

Your first Csound program

Let’s start with a simple “Hello World” example that generates a sine wave tone.

1. Create a new file

   Create a new file called hello.csd with your favorite text editor.

   The .csd extension stands for “Csound Document” and contains all the code needed for a Csound program.

2. Add the basic structure

   A Csound program has three main sections:

   hello.csd

   <CsoundSynthesizer>
   <CsOptions>
   -o dac
   </CsOptions>
   
   <CsInstruments>
   sr = 44100
   ksmps = 32
   nchnls = 2
   0dbfs = 1
   
   instr 1
     ; Generate a 440 Hz sine wave
     asig oscil 0.3, 440
     outs asig, asig
   endin
   </CsInstruments>
   
   <CsScore>
   i 1 0 2
   e
   </CsScore>
   </CsoundSynthesizer>
   

   Let’s break this down:

   CsOptions: Command-line options for Csound

   • -o dac outputs audio to your speakers in real-time

   CsInstruments: The orchestra defines your instruments

   • sr = 44100: Sample rate (44.1 kHz)
   • ksmps = 32: Control rate (samples per control period)
   • nchnls = 2: Number of output channels (stereo)
   • 0dbfs = 1: 0 dB full scale = 1.0 (amplitude reference)
   • instr 1: Defines instrument number 1
   • oscil: Oscillator opcode generating a sine wave
   • outs: Outputs to stereo channels

   CsScore: When instruments play and with what parameters

   • i 1 0 2: Play instrument 1, starting at time 0, for duration 2 seconds
   • e: End of score
3. Run your program

   Execute your Csound program from the terminal:

   csound hello.csd
   

   You should hear a 440 Hz tone (concert A) playing for 2 seconds!

Understanding Csound architecture

Csound uses a modular architecture with two main components:

Orchestra

The orchestra (CsInstruments) contains your instrument definitions. Think of it as your synthesizer design.

Score

The score (CsScore) controls when instruments play and what parameters they receive. Think of it as your sequencer.

Signal types

Csound uses different variable prefixes to indicate signal types:

• i-rate (i-variables): Initialized once at note start
• k-rate (k-variables): Control rate, updated every ksmps samples
• a-rate (a-variables): Audio rate, updated every sample
• S-rate (S-variables): String variables

A more interesting example

Let’s create a simple plucked string instrument using the example from the Csound source:

pluck.csd

<CsoundSynthesizer>
<CsOptions>
-o dac
</CsOptions>

<CsInstruments>
sr = 44100
ksmps = 300
nchnls = 2
0dbfs = 1

instr Pluck
  kamp = 0.8
  kcps = p4        ; Frequency from score p4
  icps = 100
  ifn = 0
  imeth = 1
  
  apluck pluck kamp, kcps, icps, ifn, imeth
  outs apluck, apluck
endin

instr Sine
  kamp = 0.4
  kcps = p4        ; Frequency from score p4
  ifn = 1          ; Use function table 1
  
  asine oscil kamp, kcps, ifn
  outs asine, asine
endin
</CsInstruments>

<CsScore>
; Create a sine wave function table
f 1 0 16384 10 1

; Play plucked strings
i "Pluck" 0   0.5 440
i "Pluck" 0.5 0.5 550
i "Pluck" 1   0.5 660

; Play sine wave notes
i "Sine"  1.5 0.5 440
i "Sine"  2   0.5 330

e
</CsScore>
</CsoundSynthesizer>

The second example is adapted from the famous “Xanadu” piece included in the Csound source repository.

Score notation

The score uses a simple text format:

Instrument statements (i-statements)

i [name/number] [start] [duration] [p4] [p5] ...

• i: Instrument statement
• name/number: Instrument identifier (can be number or string)
• start: Start time in seconds
• duration: Duration in seconds
• p4, p5, …: Additional parameters passed to the instrument

Function tables (f-statements)

f [number] [start] [size] [GEN] [args...]

• f: Function table statement
• number: Table number for reference
• start: Creation time (usually 0)
• size: Table size (usually power of 2)
• GEN: Generator routine number
• args: Arguments for the generator

GEN10 creates a waveform using sine wave harmonics. f 1 0 16384 10 1 creates a simple sine wave.

Real-time vs. rendering

Csound can output audio in two ways:

Real-time output

Play audio through your speakers immediately:

csound -o dac hello.csd

The -o dac option sends output to your audio device (DAC = Digital-to-Analog Converter).

Render to file

Save audio to a file for later:

csound -o output.wav hello.csd

This renders the audio offline to a WAV file.

Common opcodes to explore

Here are some essential opcodes to experiment with:

oscil / oscili

Basic oscillators for generating waveforms (sine, saw, square, etc.)

pluck

Karplus-Strong plucked string algorithm

reverb / freeverb

Add reverb and spatial effects

moog

Moog-style low-pass filter

delay / delayr/delayw

Create echo and delay effects

lfo

Low-frequency oscillator for modulation

Useful command-line options

Audio output

-o dac          # Output to speakers
-o file.wav     # Render to WAV file
-o file.aif     # Render to AIFF file

Next steps

Now that you’ve created your first Csound programs:

Explore opcodes

Browse the Csound Reference Manual for thousands of opcodes

Learn the API

Embed Csound in your own applications

Join the community

Connect with other Csound users and developers

Study examples

Check the examples directory in the Csound source repository

Tips for learning

Start simple: Begin with basic oscillators and gradually add complexity. Csound has a steep learning curve, but the power is worth it.

Read the manual: The Csound Reference Manual is comprehensive and well-written. Each opcode includes examples.

Experiment: Modify examples and see what happens. Csound is very forgiving and won’t damage your speakers (as long as you keep amplitudes reasonable).

Always test with low volume first! Some synthesis techniques can produce unexpectedly loud output.