<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>instr</title>
<link rel="stylesheet" type="text/css" href="csound.css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" />
<link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
<link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
<link rel="prev" href="insglobal.html" title="insglobal" />
<link rel="next" href="int.html" title="int" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">instr</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="insglobal.html">Prev</a> </td>
<th width="60%" align="center">Orchestra Opcodes and Operators</th>
<td width="20%" align="right"> <a accesskey="n" href="int.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="refentry" title="instr">
<a id="instr"></a>
<div class="titlepage"></div>
<a id="IndexInstr" class="indexterm"></a>
<div class="refnamediv">
<h2>
<span class="refentrytitle">instr</span>
</h2>
<p>instr —
Starts an instrument block.
</p>
</div>
<div class="refsect1" title="Description">
<a id="idp27374256"></a>
<h2>Description</h2>
<p>
Starts an instrument block.
</p>
</div>
<div class="refsect1" title="Syntax">
<a id="idp27374920"></a>
<h2>Syntax</h2>
<pre class="synopsis"><span class="command"><strong>instr</strong></span> i, j, ...</pre>
</div>
<div class="refsect1" title="Initialization">
<a id="idp27375952"></a>
<h2>Initialization</h2>
<p>
Starts an instrument block defining instruments <span class="emphasis"><em>i, j</em></span>, ...
</p>
<p>
<span class="emphasis"><em>i, j</em></span>, ... must be numbers, not expressions. Any positive integer is legal, and in any order, but excessively high numbers are best avoided.
</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>
There may be any number of instrument blocks in an orchestra.
</p>
</td>
</tr>
</table>
</div>
<p>
Instruments can be defined in any order (but they will always be both initialized and performed in ascending instrument number order, with the exception of notes triggered by real time events that are initialized in the order of being received but still performed in ascending instrument number order). Instrument blocks cannot be nested (i.e. one block cannot contain another).
</p>
</div>
<div class="refsect1" title="Performance">
<a id="idp27379344"></a>
<h2>Performance</h2>
<div class="refsect2" title="Calling an Instrument within an Instrument">
<a id="InstrSubinstrument"></a>
<h3>Calling an Instrument within an Instrument</h3>
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Warning]" src="images/warning.png" />
</td>
<th align="left">Warning</th>
</tr>
<tr>
<td align="left" valign="top">
<p>
This behavior is not fully available in Csound 5. In Csound 5,
you must use
the <a class="link" href="subinstr.html" title="subinstr"><em class="citetitle">subinstr</em></a>
opcode.
</p>
</td>
</tr>
</table>
</div>
<p>
You can call an instrument within an instrument as if it were an opcode either with the <a class="link" href="subinstr.html" title="subinstr"><em class="citetitle">subinstr</em></a> opcode or by specifying an instrument with a text name:
</p>
<div class="informalexample">
<pre class="programlisting">
<span class="oblock">instr</span> <span class="command"><strong>MyOscil</strong></span>
...
<span class="oblock">endin</span></pre>
</div>
<p>
</p>
<p>
By default, all output parameters correspond to the called instrument's output with the <a class="link" href="SigioOutput.html" title="Signal Output"><em class="citetitle">signal output</em></a> opcodes. All input parameters are mapped to the called instrument's p-fields starting with the fourth one, p4. The values of the called instrument's second and third p-fields, p2 and p3, are automatically set to those of the calling instrument's.
</p>
<p>
A named instrument must be defined before any instrument that calls it.
</p>
<div class="note" title="Hint" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Hint">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Hint</th>
</tr>
<tr>
<td align="left" valign="top">
<p>
If you use the <a class="link" href="outc.html" title="outc"><em class="citetitle">outc</em></a> opcode, you can create an instrument that will compile and function in any orchestra of any number of channels greater than or equal to the output channels of the instrument.
</p>
<p>
A nice feature to use with named instruments is the <a class="link" href="include.html" title="#include"><em class="citetitle">#include</em></a> feature. You can then define your named instruments in separate files, using #include when you need to use one.
</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="refsect1" title="Examples">
<a id="idp27388016"></a>
<h2>Examples</h2>
<p>
Here is an example of the instr opcode. It uses the file <a class="ulink" href="examples/instr.csd" target="_top"><em class="citetitle">instr.csd</em></a>.
</p>
<div class="example">
<a id="idp27388976"></a>
<p class="title">
<strong>Example 371. Example of the instr opcode.</strong>
</p>
<div class="example-contents">
<p>See the sections <a class="link" href="UsingRealTime.html" title="Real-Time Audio"><em class="citetitle">Real-time Audio</em></a> and <a class="link" href="CommandFlags.html" title="Csound command line"><em class="citetitle">Command Line Flags</em></a> for more information on using command line flags.</p>
<pre class="programlisting">
<span class="csdtag"><CsoundSynthesizer></span>
<span class="csdtag"><CsOptions></span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">; Audio out Audio in</span>
-odac -iadc <span class="comment">;;;RT audio I/O</span>
<span class="comment">; For Non-realtime ouput leave only the line below:</span>
<span class="comment">; -o instr.wav -W ;;; for file output any platform</span>
<span class="csdtag"></CsOptions></span>
<span class="csdtag"><CsInstruments></span>
<span class="comment">; Initialize the global variables.</span>
<span class="ohdr">sr</span> <span class="op">=</span> 44100
<span class="ohdr">kr</span> <span class="op">=</span> 4410
<span class="ohdr">ksmps</span> <span class="op">=</span> 10
<span class="ohdr">nchnls</span> <span class="op">=</span> 1
<span class="comment">; Instrument #1.</span>
<span class="oblock">instr</span> 1
iamp <span class="op">=</span> 10000
icps <span class="op">=</span> 440
iphs <span class="op">=</span> 0
a1 <span class="opc">oscils</span> iamp, icps, iphs
<span class="opc">out</span> a1
<span class="oblock">endin</span>
<span class="csdtag"></CsInstruments></span>
<span class="csdtag"><CsScore></span>
<span class="comment">; Play Instrument #1 for 2 seconds.</span>
<span class="stamnt">i</span> 1 0 2
<span class="stamnt">e</span>
<span class="csdtag"></CsScore></span>
<span class="csdtag"></CsoundSynthesizer></span>
</pre>
</div>
</div>
<p><br class="example-break" />
</p>
</div>
<div class="refsect1" title="See Also">
<a id="idp27391280"></a>
<h2>See Also</h2>
<p>
<a class="link" href="endin.html" title="endin"><em class="citetitle">endin</em></a>,
<a class="link" href="in.html" title="in"><em class="citetitle">in</em></a>,
<a class="link" href="out.html" title="out"><em class="citetitle">out</em></a>,
<a class="link" href="opcode.html" title="opcode"><em class="citetitle">opcode</em></a>,
<a class="link" href="endop.html" title="endop"><em class="citetitle">endop</em></a>,
<a class="link" href="setksmps.html" title="setksmps"><em class="citetitle">setksmps</em></a>,
<a class="link" href="xin.html" title="xin"><em class="citetitle">xin</em></a>,
<a class="link" href="xout.html" title="xout"><em class="citetitle">xout</em></a>,
<a class="link" href="subinstr.html" title="subinstr"><em class="citetitle">subinstr</em></a>,
<a class="link" href="subinstrinit.html" title="subinstrinit"><em class="citetitle">subinstrinit</em></a>
</p>
</div>
<div class="refsect1" title="Credits">
<a id="idp27396648"></a>
<h2>Credits</h2>
<p>Example written by Kevin Conder.</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="insglobal.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="OpcodesTop.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="int.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">insglobal </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> int</td>
</tr>
</table>
</div>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
b707d9a4ee443103660a75ccb6e51334
>
files
>
2025
