[musicians-guide] reformatted pre tags and added some inlinemediaobject where appropriate
crantila
crantila at fedoraproject.org
Sat Aug 7 05:44:35 UTC 2010
commit dd19b2f43095cec30dd18de905e70dab769eb0d4
Author: Christopher Antila <crantila at fedoraproject.org>
Date: Sat Aug 7 01:43:55 2010 -0400
reformatted pre tags and added some inlinemediaobject where appropriate
en-US/Ardour.xml | 143 +-
en-US/Audio_Vocabulary.xml | 20 +-
en-US/Digital_Audio_Workstations.xml | 50 +-
en-US/LilyPond/LilyPond-orchestra.xml | 38 +-
en-US/LilyPond/LilyPond-piano.xml | 33 +-
en-US/LilyPond/LilyPond-syntax.xml | 31 +-
en-US/Planet_CCRMA_at_Home.xml | 57 +-
en-US/Qtractor.xml | 24 +-
en-US/Real_Time_and_Low_Latency.xml | 2 +-
en-US/Revision_History.xml | 33 +
en-US/Rosegarden.xml | 14 +-
en-US/Solfege.xml | 2 +-
en-US/Sound_Servers.xml | 34 +-
.../SuperCollider-Basic_Programming.xml | 2799 ++++++++++----------
en-US/SuperCollider/SuperCollider-Composing.xml | 655 +++---
en-US/SuperCollider/SuperCollider.xml | 18 +-
en-US/SuperCollider/examples/Busses-Audio_Rate.sc | 82 +
en-US/images/FMG-Ardour-Connections.png | Bin 0 -> 155557 bytes
18 files changed, 2119 insertions(+), 1916 deletions(-)
---
diff --git a/en-US/Ardour.xml b/en-US/Ardour.xml
index 7c71cbf..8d192f6 100644
--- a/en-US/Ardour.xml
+++ b/en-US/Ardour.xml
@@ -8,7 +8,7 @@
<title>Ardour</title>
<para>
- Ardour is a feature-rich application designed for multi-track recording situations.
+ <application>Ardour</application> is a feature-rich application designed for multi-track recording situations.
</para>
<section id="sect-Musicians_Guide-Ardour-Requirements_and_Installation">
@@ -17,25 +17,25 @@
<section id="sect-Musicians_Guide-Ardour-Knowledge_Requirements">
<title>Knowledge Requirements</title>
<para>
- Ardour's user interface is similar to other DAWs. We recommend that you read <xref linkend="sect-Musicians_Guide-DAW_User_Interface" /> if you have not used a DAW before.
+ The <application>Ardour</application> user interface is similar to other DAWs. We recommend that you read <xref linkend="sect-Musicians_Guide-DAW_User_Interface" /> if you have not used a DAW before.
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Software_Requirements">
<title>Software Requirements</title>
<para>
- Ardour uses the JACK Audio Connection Kit. You should install JACK before installing Ardour. Follow the instructions in <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> to install JACK.
+ <application>Ardour</application> uses the <systemitem>JACK Audio Connection Kit</systemitem>. You should install <systemitem>JACK</systemitem> before installing <application>Ardour</application>. Follow the instructions in <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> to install <systemitem>JACK</systemitem>.
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Hardware_Requirements">
<title>Hardware Requirements</title>
<para>
- You need an audio interface to use Ardour. If you will record audio with Ardour, you must have at least one microphone connected to your audio interface. You do not need a microphone to record audio signals from other JACK-aware programs like <code>FluidSynth</code> and <code>SuperCollider</code>.
+ You need an audio interface to use <application>Ardour</application>. If you will record audio with <application>Ardour</application>, you must have at least one microphone connected to your audio interface. You do not need a microphone to record audio signals from other <systemitem>JACK</systemitem>-aware programs like <application>FluidSynth</application> and <application>SuperCollider</application>.
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Installation">
<title>Installation</title>
<para>
- Use PackageKit or KPackageKit to install the "ardour" package. Other required software is installed automatically.
+ Use <application>PackageKit</application> or <application>KPackageKit</application> to install the <package>ardour</package> package. Other required software is installed automatically.
</para>
</section>
</section>
@@ -43,43 +43,41 @@
<section id="sect-Musicians_Guide-Ardour-Recording_a_Session">
<title>Recording a Session</title>
<para>
- Recording a session usually happens all at once, but sometimes recording can happen over several days or even weeks. Mixing and mastering happen after a session has been recorded. Remember that JACK must have the same sample rate and sample format settings each time you open a session.
+ Recording a session usually happens all at once, but sometimes recording can happen over several days or even weeks. Mixing and mastering happen after a session has been recorded. Remember that <systemitem>JACK</systemitem> must have the same sample rate and sample format settings each time you open a session.
</para>
<section id="sect-Musicians_Guide-Ardour-Recording-Running_Ardour">
- <title>Running Ardour</title>
+ <title>Running <application>Ardour</application></title>
<procedure>
- <step><para>Ardour uses the JACK sound server. You should start JACK with QjackCtl before running Ardour, or Ardour will start JACK for you.</para></step>
- <step><para>Ardour asks you to choose a location to save your new session. Ardour automatically creates a directory to store the session's files. You can also open an existing session.</para></step>
+ <step><para><application>Ardour</application> uses the <systemitem>JACK</systemitem> sound server. Use <application>QjackCtl</application> to start <systemitem>JACK</systemitem> before <application>Ardour</application>, or <application>Ardour</application> starts <systemitem>JACK</systemitem> for you.</para></step>
+ <step><para><application>Ardour</application> asks you to choose a location to save your new session. <application>Ardour</application> automatically creates a directory to store the session's files. You can also open an existing session.</para></step>
</procedure>
</section>
<section id="sect-Musicians_Guide-Ardour-Recording-Interface">
<title>The Interface</title>
<!-- [[File:Ardour-interface.xcf]] -->
<para>
- This section explains some of the graphical interface components that are unique to Ardour. Components that are consistent through most DAWs are explained in <xref linkend="sect-Musicians_Guide-DAW_Interface_Vocabulary" />.
+ This section explains some of the graphical interface components that are unique to <application>Ardour</application>. Components that are consistent through most DAWs are explained in <xref linkend="sect-Musicians_Guide-DAW_Interface_Vocabulary" />.
</para>
- <mediaobject>
- <imageobject>
+ <para>
+ <inlinemediaobject><imageobject>
<!-- [[File:Ardour-interface-editor_mixer.png|300px|Editor mixer]]-->
<imagedata fileref="./images/Ardour-interface-editor_mixer.png" format="PNG" />
- </imageobject>
- </mediaobject>
- <para>
- This image shoes the editor mixer, located at the left of Ardour's main window. The editor mixer shows only one mixer strip at a time. It shows the fader and its controls, in the middle of the mixer strip, the panner and its controls, at the bottom of the mixer strip, and the "Comments" and outgoing connections buttons.
+ </imageobject></inlinemediaobject>
+ This image shoes the editor mixer, located at the left of the main <application>Ardour</application> window. The editor mixer shows only one mixer strip at a time. It shows the fader and its controls, in the middle of the mixer strip, the panner and its controls, at the bottom of the mixer strip, and the "Comments" and outgoing connections buttons.
</para>
- <mediaobject><imageobject>
+ <para>
+ <inlinemediaobject><imageobject>
<!-- [[File:Ardour-interface-session_sidebar.png|300px|Session sidebar]] -->
<imagedata fileref="./images/Ardour-interface-session_sidebar.png" format="PNG" />
- </imageobject></mediaobject>
- <para>
- This image shows the session sidebar, located at the right of Ardour's main window. In this image, the "Regions" tab is selected, so the sidebar shows a list of regions currently in the session. You can see blue ones which were directly imported, white ones which were created from blue regions, and the arrows to the left of some blue regions, indicating that there are white-coloured sub-regions associated with those blue regions.
+ </imageobject></inlinemediaobject>
+ This image shows the session sidebar, located at the right the main <application>Ardour</application> window. In this image, the "Regions" tab is selected, so the sidebar shows a list of regions currently in the session. You can see blue ones which were directly imported, white ones which were created from blue regions, and the arrows to the left of some blue regions, indicating that there are white-coloured sub-regions associated with those blue regions.
</para>
- <mediaobject><imageobject>
+ <para>
+ <inlinemediaobject><imageobject>
<!-- [[File:Ardour-interface-toolbar.png|300px|Toolbar]] -->
<imagedata fileref="./images/Ardour-interface-toolbar.png" format="PNG" />
- </imageobject></mediaobject>
- <para>
+ </imageobject></inlinemediaobject>
This image shows the main toolbar, located underneath the transport controls, and above the timeline and its rulers. In the middle of the toolbar are three unlabeled, but highly useful multiple-choice menus: the "snap mode" menu (currently set to "No Grid"); the "grid mode" menu (currently set to "Bars"); and then "edit point" menu (currently set to "Mouse"). To the left of these menus are the tool-selection buttons, the most important of which are the two left-most buttons: Select/Edit Object, and Select/Edit Range.
</para>
</section>
@@ -87,7 +85,7 @@
<title>Setting up the Timeline</title>
<para>
<orderedlist>
- <listitem><para>At the top of the main Ardour window, to the right of the transport's toolbar, are two relatively large clocks.</para></listitem>
+ <listitem><para>At the top of the main <application>Ardour</application> window, to the right of the transport's toolbar, are two relatively large clocks.</para></listitem>
<listitem><para>Right-click to choose what you want them to display:
<itemizedlist>
<listitem><para>"Bars:Beats" displays the number of bars and beats (how to use it?)</para></listitem>
@@ -130,9 +128,9 @@
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Recording-Connecting_Audio_Sources">
- <title>Connecting Audio Sources to Ardour</title>
+ <title>Connecting Audio Sources to <application>Ardour</application></title>
<para>
- The name of the track onto which you want to record should be the name of the input in JACK
+ The name of the track onto which you want to record should be the name of the input in <systemitem>JACK</systemitem>
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Recording-Setting_up_Busses_and_Tracks">
@@ -177,33 +175,33 @@
The nature of digital audio is such that there is a distinct number of volume levels at which something can be recorded. If a sound is either below or above that range, then it will not be correctly recorded. When such an improperly-recorded sound is played back, whether too quite or too loud, humans will usually perceive it as "nothing but noise."
</para>
<para>
- It's easy to imagine how Ardour acts when it records silence. When Ardour thinks that a portion of audio is too loud, it outlines the wave-form representation in red, as shown in this image:
- </para>
- <mediaobject><imageobject>
+ It's easy to imagine how <application>Ardour</application> acts when it records silence. When <application>Ardour</application> thinks that a portion of audio is too loud, it outlines the wave-form representation in red, as shown in this image:
+ <inlinemediaobject><imageobject>
<!-- [[File:Ardour-red_peaks.png|This audio is too loud.]] -->
<imagedata fileref="./images/Ardour-red_peaks.png" format="PNG" />
- </imageobject></mediaobject>
+ </imageobject></inlinemediaobject>
+ </para>
<para>
There are three simple strategies that can be used to change the input level of an audio signal:
<orderedlist>
<listitem><para>Move the microphone closer or farther from the source</para></listitem>
<listitem><para>Route the microphone through a mixer before it hits the audio interface</para></listitem>
- <listitem><para>Route the audio through a bus in Ardour before it gets recorded</para></listitem>
+ <listitem><para>Route the audio through a bus in <application>Ardour</application> before it gets recorded</para></listitem>
</orderedlist>
</para>
<para>
Here are the pros and cons of each approach.
</para>
<para>
- There are some circumstances where it is either impractical, impossible, or not advisable to move the microphone or route it through a hardware mixer. In these cases, you can use a bus in Ardour to modify the volume of the input signal before it is recorded.
+ There are some circumstances where it is either impractical, impossible, or not advisable to move the microphone or route it through a hardware mixer. In these cases, you can use a bus in <application>Ardour</application> to modify the volume of the input signal before it is recorded.
<orderedlist>
- <listitem><para>Create a new bus by 'Track > Add Track/Bus'</para></listitem>
+ <listitem><para>Choose <menuchoice><guimenu>Track</guimenu><guimenuitem>Add Track/Bus</guimenuitem></menuchoice>.</para></listitem>
<listitem><para>Select "busses" in the window that pops up.</para></listitem>
- <listitem><para>Choose the number of busses that you wish to add. You will need one for every track that you are recording, and of which you want to adjust the volume. It's also possible to record at several different volumes.</para></listitem>
+ <listitem><para>Choose the number of busses that you wish to add. You need one for every track that you are recording, and of which you want to adjust the volume. It is also possible to record at several different volumes.</para></listitem>
<listitem><para>Set the number of channels that youw ant int he bus.</para></listitem>
<listitem><para>Once you have the new bus, change its name by doing whatever. I suggest naming it something that makes it obvious you are using the bus for recording, rather than exporting, like "REC-Bus."</para></listitem>
- <listitem><para>Ardour automatically sets up busses to be used with audio being outputted. Furthermore, the volume/level control only works on audio beign outputted from a track or bus. This is why you cannot use the track's volume/level control to adjust the input volume for that track.</para></listitem>
- <listitem><para>You will need to use QjackCtl (or a similar application) to re-connect as follows (reading "Routing Audio and Managing JACK Connections" for help)
+ <listitem><para><application>Ardour</application> automatically sets up busses to be used with audio being outputted. Furthermore, the volume/level control only works on audio beign outputted from a track or bus. This is why you cannot use the track's volume/level control to adjust the input volume for that track.</para></listitem>
+ <listitem><para>Use <application>QjackCtl</application> to reconnect like this (for help, refer to <xref linkend="sect-Musicians_Guide-Ardour-Recording-Routing_Audio" />):
<orderedlist>
<listitem><para>Disconnect all of the connections to/from the bus you want to use for recording ("recording bus").</para></listitem>
<listitem><para>Ensure that nothing is connected to the input of the track onto which you want to record ("recording track").</para></listitem>
@@ -219,7 +217,7 @@
Here is an algorithm to test whether your tracks are set at a good recording volume. This should be done before arming any tracks for recording. Unfortunately, you can never know that you have chosen the best input level until after a region is recorded. It takes both instinct and experience to be able to choose good input levels reliably.
<orderedlist>
<listitem><para>Set up all microphones as required.</para></listitem>
- <listitem><para>Set up connections in JACK as required.</para></listitem>
+ <listitem><para>Set up connections in <systemitem>JACK</systemitem> as required.</para></listitem>
<listitem><para>Set up any recording busses as required (see above).</para></listitem>
<listitem><para>On the audio tracks being recorded, set the "metering point" to "input" (here's how to do that).</para></listitem>
<listitem><para>Ask the performers to demonstrate the loudest passages they will be doing in the session. Adjust the input level so that the maximum level falls between -3 dB and -6 dB (by looking here). You can reset the maximum-level-seer by clicking on it.</para></listitem>
@@ -241,11 +239,11 @@
<listitem><para>See "Adjusting Recording Volume" below, and do it now</para></listitem>
<listitem><para>Arm the track for recording: either press "Record" in the track's mixer in the left, or press the small red record button on the track itself</para></listitem>
<listitem><para>the buttons will remain lighted to show that the tracks are armed</para></listitem>
- <listitem><para>arm Ardour for recording by select the big red record button on the transport</para></listitem>
+ <listitem><para>arm <application>Ardour</application> for recording by select the big red record button on the transport</para></listitem>
<listitem><para>start the transport in in the normal way (big play button)</para></listitem>
<listitem><para>when you're done recording, stop the transport with the big stop button</para></listitem>
<listitem><para>each time you start and stop the transport, a new "region" is produced</para></listitem>
- <listitem><para>each time you stop the transport, Ardour "un-arms" itself, but any tracks that you selected are still armed</para></listitem>
+ <listitem><para>each time you stop the transport, <application>Ardour</application> "un-arms" itself, but any tracks that you selected are still armed</para></listitem>
<listitem><para>When you've finished recording a region, use the "Regions" box-thing on the right of the interface to rename the region:
<orderedlist>
<listitem><para>Find the region that you just recorded (by default they are named like "Audio 1-1" which is the name of the recording track followed by a hyphen, then a number in ascending sequeuence representing the "take"). Select it.</para></listitem>
@@ -279,7 +277,7 @@
<section id="sect-Musicians_Guide-Ardour-Recording-Capture_Additional_Parts">
<title>To Capture an Additional Part of Something That Is already Recorded</title>
<para>
- A technique often used for studio recordings is to separately record parts that would normally be played together, and which will later be made to sound together (see the "Prepearing a Session" section, below). For example, consider a recording where one trumpeter wants to record both parts of a solo written for two trumpets. The orchestra could be brought into the studio, and would play the entire solo piece without any trumpet solo. Ardour will record this on one track. Then, the trumpet soloist goes to the studio, and uses Ardour to simultaneously listen to the previously-recorded orchestra track while playing one of the solo trumpet parts, which is recorded onto another track. The next day, the trumpeter returns to the studio, and uses Ardour to listen to the previously-recorded orchestra track and previously-recorded solo trumpet part while playing the other solo trumpet part, which is recorded onto a third track. The recording engineer uses Audacity's mixing
and editing features to make it sound as though the trumpeter played both solo parts at the same time, while the orchestra was there.
+ A technique often used for studio recordings is to separately record parts that would normally be played together, and which will later be made to sound together (see the "Prepearing a Session" section, below). For example, consider a recording where one trumpeter wants to record both parts of a solo written for two trumpets. The orchestra could be brought into the studio, and would play the entire solo piece without any trumpet solo. <application>Ardour</application> will record this on one track. Then, the trumpet soloist goes to the studio, and uses <application>Ardour</application> to simultaneously listen to the previously-recorded orchestra track while playing one of the solo trumpet parts, which is recorded onto another track. The next day, the trumpeter returns to the studio, and uses <application>Ardour</application> to listen to the previously-recorded orchestra track and previously-recorded solo trumpet part while playing the other solo trumpet part, whi
ch is recorded onto a third track. The recording engineer uses Audacity's mixing and editing features to make it sound as though the trumpeter played both solo parts at the same time, while the orchestra was there.
</para>
<para>
Coordinating the timing of musicians across tracks recorded separately is difficult. A "click track" is a track with a consistent clicking noise at the desired tempo. Click tracks are played through headphones to the musicians being recorded, or to a musician who leads the others. Click tracks are not included in the final mix.
@@ -302,7 +300,7 @@
<section id="sect-Musicians_Guide-Ardour-Recording-Redo_a_Take">
<title>To Capture a Better Recording of Something That Is already Recorded</title>
<para>
- If you have already recorded all or most of a session, you can re-record *part* of the session in order to "fix up" any issues. Ardour allows you to record onto the pre-existing tracks, keeping the first take, putting the newly-recorded region over it. Later, you will get to choose the exact points at which the outputted recording is to switch between regions/takes.
+ If you have already recorded all or most of a session, you can re-record *part* of the session in order to "fix up" any issues. <application>Ardour</application> allows you to record onto the pre-existing tracks, keeping the first take, putting the newly-recorded region over it. Later, you will get to choose the exact points at which the outputted recording is to switch between regions/takes.
<orderedlist>
<listitem><para>Record the session.</para></listitem>
<listitem><para>Ensure that you have the connections and levels set as they were during the first time you recorded the regions over which you're recording now.</para></listitem>
@@ -317,12 +315,12 @@
</section>
</section>
<section id="sect-Musicians_Guide-Ardour-Recording-Routing_Audio">
- <title>Routing Audio and Managing JACK Connections</title>
+ <title>Routing Audio and Managing <systemitem>JACK</systemitem> Connections</title>
<para>
- Ardour will automatically save the state of JACK connections when it saves a session.
+ <application>Ardour</application> automatically saves the state of <systemitem>JACK</systemitem> connections when it saves a session.
</para>
<para>
- Ardour will offer the following output ports, assuming a stereo (two-channel) setup:
+ <application>Ardour</application> offers the following output ports, assuming a stereo (two-channel) setup:
<itemizedlist>
<listitem><para>two channels per track, called "track_name/out 1" and "track_name/out 2". These will usually be connected to the master bus, or to a sub-mixing bus, when you are using one.</para></listitem>
<listitem><para>two channels per bus, called "bus_name/out 1" and "bus_name/out 2". These will usually be connected to the master bus, unless you are using two levels of sub-mixing busses.</para></listitem>
@@ -332,7 +330,7 @@
</itemizedlist>
</para>
<para>
- Ardour will offer the following input ports, assuming a stereo (two-channel) setup:
+ <application>Ardour</application> offers the following input ports, for a stereo (two-channel) setup:
<itemizedlist>
<listitem><para>two channels per track, called "track_name/in 1" and "track_name/in 2". These should both be connected to the same input device. If you are using a recording bus, then these should be connected to that bus.</para></listitem>
<listitem><para>two channels per bus, called "bus_name/in 1" and "bus_name/in 2". These should be connected to whatever channels you want to be mixed into them. If you are using it as a recording bus, then these should be connected to the same input device.</para></listitem>
@@ -340,16 +338,16 @@
</itemizedlist>
</para>
<para>
- In most setups, Ardour will automatically set the channel connections correctly. There are ways to change the connections from within Ardour, but they offer limited flexibility. For this reason, it is recommended that users use QjackCtl to monitor connections, since through QjackCtl it is also possible to monitor and change many other features of JACK.
+ In most setups, <application>Ardour</application> automatically sets the channel connections correctly. There are ways to change the connections from within <application>Ardour</application>, but they offer limited flexibility. For this reason, it is recommended that users use <application>QjackCtl</application> to monitor connections, since through <application>QjackCtl</application> it is also possible to monitor and change many other features of <systemitem>JACK</systemitem>.
</para>
<para>
- Learning to make the right connections is a valuable trick for people using Ardour. The fact that Ardour uses JACK for both its internal and external connections allows tricks such as the earlier-mentioned recording bus (which adjusts the input level of a source), flipping the left and right audio channels, and creating a multi-channel audio output by combining many input channels. Undoubtedly, other tricks exist.
+ Learning to make the right connections is a valuable trick for people using <application>Ardour</application>. The fact that <application>Ardour</application> uses <systemitem>JACK</systemitem> for both its internal and external connections allows tricks such as the earlier-mentioned recording bus (which adjusts the input level of a source), flipping the left and right audio channels, and creating a multi-channel audio output by combining many input channels. Undoubtedly, other tricks exist.
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Recording-Importing_Existing_Audio">
<title>Importing Existing Audio</title>
<para>
- When you record audio, Ardour automatically save it to disk and adds a representation of that file in the program as a "region." You can also use pre-existing audio files as regions, which can then be added to any track.
+ When you record audio, <application>Ardour</application> automatically save it to disk and adds a representation of that file in the program as a "region." You can also use pre-existing audio files as regions, which can then be added to any track.
</para>
<para>
To import an existing audio file:
@@ -367,14 +365,14 @@
</para></listitem>
<listitem><para>Using "Browse Files," navigate to a sound that you want to add. Although certain other file formats are supported (like FLAC), it is probably best to add WAV or AIFF files.</para></listitem>
<listitem><para>Certain information about the audio file will be displayed on the right-hand side of the window. This portion of the window also allows you to "audition" the file before importing it (that is, you can hear it by using the "Play" and "Stop" buttons in the window, without affecting your current project.</para></listitem>
- <listitem><para>If the file that you selected has a sample-rate that is not the same as that of the current project, then the sample-rate will be highlighted in red. You can choose to import it anyway, in which case Ardour will warn you again. If you import a file in a different sample rate than that of the current project, it will be played back in the project's sample rate. This will result in incorrect speed and pitch.</para></listitem>
+ <listitem><para>If the file that you selected has a sample-rate that is not the same as that of the current project, then the sample-rate will be highlighted in red. You can choose to import it anyway, in which case <application>Ardour</application> warns you again. If you import a file in a different sample rate than that of the current project, it will be played back in the project's sample rate. This will result in incorrect speed and pitch.</para></listitem>
<listitem><para>There are a number of other options, displayed along the bottom of the window.</para></listitem>
<listitem><para>You can choose to add files:
<itemizedlist>
<listitem><para>"as new tracks," which puts each file in its own track, set to normal mode, then adds it to the region list</para></listitem>
<listitem><para>"as new tape tracks," which puts each file in its own track, set to tape mode, then adds it to the region list</para></listitem>
<listitem><para>"to region list," which puts each file in the region list, but does not automatically put it in any tracks.</para></listitem>
- <listitem><para>Note that when you choose to automatically create new tracks, Ardour will add the region to the new track, with the region starting at the current location of the transport.</para></listitem>
+ <listitem><para>Note that when you choose to automatically create new tracks, <application>Ardour</application> adds the region to the new track, with the region starting at the current location of the transport.</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>The other options in this list are self-explanatory. It is usually best to convert using the best quality, since quality can always be reduced later (which saves space).</para></listitem>
@@ -390,10 +388,10 @@
These tutorial files represent the material required to create a finished version of a song called "Here Is How," written by Esther Wheaton. The song was released as part of her first album, "Not Legendary," and she has released the source files for this song under !!I!! this licence (probably CC-BY-SA) !!I!! For more information on the artist, please refer to her <citetitle>Esther Wheaton's MySpace Page</citetitle>, available at <ulink url="http://www.myspace.com/estherwheaton" />.
</para>
<para>
- The material presented for your use is a folder containing an Ardour file and the associated audio files required to start the tutorial. The tutorial itself comprises the following sections about editing, mixing, and mastering (or exporting). The program used to record the audio files split the left and right channels into separate files, so they are imported into Ardour as separate regions. Therefore, the setup is more complex than it would be if the song were originally recorded in Ardour, but this gives the opportunity to learn in greater detail about busses, creating and using the stereo image, and volume level adjustments.
+ The material presented for your use is a folder containing an <application>Ardour</application> file and the associated audio files required to start the tutorial. The tutorial itself comprises the following sections about editing, mixing, and mastering (or exporting). The program used to record the audio files split the left and right channels into separate files, so they are imported into <application>Ardour</application>as separate regions. Therefore, the setup is more complex than it would be if the song were originally recorded in <application>Ardour</application>, but this gives the opportunity to learn in greater detail about busses, creating and using the stereo image, and volume level adjustments.
</para>
<para>
- The unique setup also means that none of the audio regions are in the right place on the timeline, and most of them require extensive editing. This would be bad if the objective of the tutorial were to create a finished version of the song as quickly as possible; but the objective is to learn how to use Ardour, and this is almost guaranteed.<!-- !! what about the singers !! (What was this supposed to mean?) -->
+ The unique setup also means that none of the audio regions are in the right place on the timeline, and most of them require extensive editing. This would be bad if the objective of the tutorial were to create a finished version of the song as quickly as possible; but the objective is to learn how to use <application>Ardour</application>, and this is almost guaranteed.<!-- !! what about the singers !! (What was this supposed to mean?) -->
</para>
<para>
!!EL!! Links to the files !!I!! I don't know where to put them!<!-- TODO -->
@@ -412,7 +410,7 @@
<section id="sect-Musicians_Guide-Ardour-Editing-Add_Tracks_and_Busses">
<title>Add Tracks and Busses</title>
<para>
- The program used to record these tracks was configured to record onto a separate track for the left and right channels, so Ardour will also have to be configured this way. It requires more setup, more memory, and more processing power, but it offers greater control over the stereo image and level balancing. We will use one track for vocals, clarinet, and strings, and two tracks for the marimba. This needs to be doubled to handle the stereo audio, so a total of ten tracks are needed. It might still be useful to manipulate the stereo tracks together, so we're going to combine them with five busses. This gives us the option of modifying both stereo channels or just one - you'll see how it works as the tutorial progresses. All of these actions take place within Ardour.
+ The program used to record these tracks was configured to record onto a separate track for the left and right channels, so <application>Ardour</application> will also have to be configured this way. It requires more setup, more memory, and more processing power, but it offers greater control over the stereo image and level balancing. We will use one track for vocals, clarinet, and strings, and two tracks for the marimba. This needs to be doubled to handle the stereo audio, so a total of ten tracks are needed. It might still be useful to manipulate the stereo tracks together, so we're going to combine them with five busses. This gives us the option of modifying both stereo channels or just one - you'll see how it works as the tutorial progresses. All of these actions take place within <application>Ardour</application>.
</para>
<para>
<orderedlist>
@@ -430,7 +428,7 @@
<listitem><para>At the left-most side of the canvas area, each bus has a space with controls, including a box with the bus' name.</para></listitem>
<listitem><para>To rename a bus, use the mouse to left-click inside the box with the bus' name.</para></listitem>
<listitem><para>The box will turn into a text-editing box. Erase the contents, and write the new name.</para></listitem>
- <listitem><para>When you have entered the new name, press "Enter" on the keyboard to set it in Ardour.</para></listitem>
+ <listitem><para>When you have entered the new name, press "Enter" on the keyboard to set it in <application>Ardour</application>.</para></listitem>
<listitem><para>The box will no longer be a text-editing box.</para></listitem>
<listitem><para>
<itemizedlist>
@@ -482,7 +480,7 @@
<section id="sect-Musicians_Guide-Ardour-Editing-Connect_Tracks_and_Busses">
<title>Connect the Tracks and Busses</title>
<para>
- Although we have created a system of busses in our mind, we still haven't told Ardour about it. You can use QjackCtl to confirm this: all of the additional tracks and busses are connected to output audio to the master bus. Worse still, the additional busses have no input signal at all. There are two approaches to letting Ardour know how we want to connect the tracks and busses. They will both be demonstrated, and you will be left to fill in the rest.
+ Although we have created a system of busses in our mind, we still have not told <application>Ardour</application> about it. You can use <application>QjackCtl</application> to confirm this: all of the additional tracks and busses are connected to output audio to the master bus. Worse still, the additional busses have no input signal at all. There are two approaches to letting <application>Ardour</application> know how we want to connect the tracks and busses. They will both be demonstrated, and you will be left to fill in the rest.
</para>
<para>
<orderedlist>
@@ -500,8 +498,8 @@
<listitem><para>The 'Remove' button removes an output channel.</para></listitem>
<listitem><para>The 'Disconnect All' button removes all of the track's output connections.</para></listitem>
<listitem><para>Clicking a connection in this list will remove it.</para></listitem>
- <listitem><para>The right side, labeled "Available connections," contains a list of all of the inputs offered by JACK.</para></listitem>
- <listitem><para>Each JACK-aware application has a tab with its connections listed underneath.</para></listitem>
+ <listitem><para>The right side, labeled "Available connections," contains a list of all of the inputs offered by <systemitem>JACK</systemitem>.</para></listitem>
+ <listitem><para>Each <systemitem>JACK</systemitem>-aware application has a tab with its connections listed underneath.</para></listitem>
<listitem><para>Clicking a connection in this list will add it to the last-selected output channel.</para></listitem>
</itemizedlist>
</para></listitem>
@@ -516,7 +514,7 @@
</para></listitem>
<listitem><para>The other way to change connections is much faster for large-scale changes like the ones required here.
<orderedlist>
- <listitem><para>From the menu, select 'Window > Track/Bus Inspector'
+ <listitem><para>Choose <menuchoice><guimenu>Window</guimenu> <guimenuitem>Track/Bus Inspector</guimenuitem></menuchoice>.
<itemizedlist>
<listitem><para>The "Track/Bus Inspector" window will appear. It has a list of the tracks and busses on the left side, and four tabs of information on the right side.</para></listitem>
<listitem><para>The "Inputs" and "Outputs" tabs allow you to view and configure the input and output connections of the selected track or bus. The two "Redirects" tabs allow you to configure plug-in settings, which are not discussed in this tutorial.</para></listitem>
@@ -536,7 +534,10 @@
</orderedlist>
</para></listitem>
</orderedlist>
- [[File:FMG-Ardour-Connections.png]]
+ <inlinemediaobject><imageobject>
+ <!-- [[File:FMG-Ardour-Connections.png]] -->
+ <imagedata fileref="./images/FMG-Ardour-Connections.png" format="PNG" />
+ </imageobject></inlinemediaobject>
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Editing-Edit_Groups">
@@ -561,7 +562,7 @@
You guessed it though - there's more to it than that, and it mostly has to do with the setup of this particular file. You will notice that the region list has many similarly-named regions, and that most of the names correspond to particular tracks and a bus. The files are named so that you know what's on them. They are given a number so that you know the sequence in which they're to be added ("Marimba_1" regions before "Marimba_2"), and a letter "L" or "R" at the end to signify whether the region is the left or the right channel. Furthermore, the regions that start with "ens-" belong on the "voice" tracks ("ens" is short for "ensemble," meaning that those regions contain a small vocal ensemble, whereas the "Voice... " regions contain just one singer). The "Here_Is_How" regions belong before the "Create_the_Inconceivable" regions. Remember: there is no technical reason that the regions are named as they are. The names are there to help you edit and mix the song. W
e don't need to use the "marimba2" tracks or bus yet, so just add all of the "Marimba_" regions to the "marimba1" tracks.
</para>
<para>
- As you add the regions, you will learn a lot about manipulating regions in Ardour. Here are some tips to help:
+ As you add the regions, you will learn a lot about manipulating regions in <application>Ardour</application>. Here are some tips to help:
<itemizedlist>
<listitem><para>Use the mouse's scrollwheel (if you have one) to scroll vertically, seeing all the tracks.</para></listitem>
<listitem><para>Hold down the 'Ctrl' button on the keyboard and use the mouse's scrollwheel to adjust the amount of time visible in the canvas window.</para></listitem>
@@ -585,12 +586,12 @@
<listitem><para>Listen to the first clarinet region by pressing "Home" on the keyboard to set the transport's playhead to the beginning, then pressing the space key to start the transport.</para></listitem>
<listitem><para>There is approximately 20 seconds of near-silence before the clarinet starts to play. If you listen carefully, you can hear the room, and somebody counting measure numbers.</para></listitem>
<listitem><para>If the channels aren't synchronized, you'll need to adjust their placement in the timeline. Use the yellow clock that appears when you drag regions - it's set to the same units as the secondary clock, and shows you the time of the beginning of the file. It's important to get it synchronized before the next step!</para></listitem>
- <listitem><para>Choose either the "L" or "R" region. If you're using edit groups, it doesn't matter which you choose, because Ardour will realize that the regions in both tracks are "group equivalent" (that is, they're basically the same, so they probably belong together).</para></listitem>
+ <listitem><para>Choose either the "L" or "R" region. If you're using edit groups, it doesn't matter which you choose, because <application>Ardour</application> will realize that the regions in both tracks are "group equivalent" (that is, they're basically the same, so they probably belong together).</para></listitem>
<listitem><para>Use the mouse to click in the coloured bar of the region, close to where the clarinet starts.</para></listitem>
- <listitem><para>Ardour will automatically move the start of the region ''in both tracks''.</para></listitem>
+ <listitem><para><application>Ardour</application> will automatically move the start of the region ''in both tracks''.</para></listitem>
<listitem><para>Move the playhead by clicking in the rulers at the point where you want the playhead to be, so that you can listen to the regions to ensure that you didn't cut out any of the useful audio.</para></listitem>
<listitem><para>If you want to adjust the beginning of the region, carefully move the mouse cursor to the start of the region, in the coloured bar. The cursor should turn into a double-ended left-and-right arrow. If you happened to accidentally remove some of the useful clarinet sound, you'll notice that it's still there. In fact, the beauty of trimming regions in this way is that it's "non-destructive," meaning that the entire original region is still there!</para></listitem>
- <listitem><para>Notice that when you made the first adjustment, Ardour put an arrow beside the region name in the region list of the session sidebar. If you click on the arrow, you will see that there is another copy of the same region underneath, but it's white. Ardour wants you to know that the white-coloured region is a modification of the blue-coloured region. If you drag the white-coloured region into the canvas area, you'll notice that it starts at the same time as the region you just modified. It can ''also'' be dragged out to the full size of the original region, which would create another modified version of the original. While it seems like Ardour stores multiple copies of the region, it actually just stores one copy, and the information required to make it seem like there are many.</para></listitem>
+ <listitem><para>Notice that when you made the first adjustment, <application>Ardour</application> put an arrow beside the region name in the region list of the session sidebar. If you click on the arrow, you will see that there is another copy of the same region underneath, but it's white. <application>Ardour</application> wants you to know that the white-coloured region is a modification of the blue-coloured region. If you drag the white-coloured region into the canvas area, you'll notice that it starts at the same time as the region you just modified. It can ''also'' be dragged out to the full size of the original region, which would create another modified version of the original. While it seems like <application>Ardour</application> stores multiple copies of the region, it actually just stores one copy, and the information required to make it seem like there are many.</para></listitem>
<listitem><para>Adjust the end of the region so that there isn't too much silence after the clarinet. Be extra careful with this, so that you don't cut out any of the clarinet, which gets very quiet at the end of the region. There isn't much to cut off! Note that you cannot click in the coloured bar when adjusting the end of a region, so you'll have to click-and-drag.</para></listitem>
</orderedlist>
</para>
@@ -671,7 +672,7 @@
<listitem><para>The cursor will change to look like a text-editing "I"</para></listitem>
<listitem><para>Scroll to the end of the "Clarinet_3B" regions, so you can see the part the sounds like the "Clarinet_1" regions.</para></listitem>
<listitem><para>Click and drag the mouse over the "Clarinet_1"-like region in one of the tracks, to select them.</para></listitem>
- <listitem><para>Because of the edit group, Ardour will automatically select the same area of both tracks.</para></listitem>
+ <listitem><para>Because of the edit group, <application>Ardour</application> will automatically select the same area of both tracks.</para></listitem>
<listitem><para>We have to be sure to select all of the "Clarinet_1"-like material, so after you've selected a range, right-click on the range, and select 'Play Range' from the menu.</para></listitem>
<listitem><para>If you want to adjust the selected range, use the darker squares at the top corners of the range-selection box. When you put the cursor over one of these boxes, it will change into a double-ended, left-to-right arrow.</para></listitem>
<listitem><para>Now create a new region from the range. Right-click on the selected range, and select 'Bounce range to region list' from the menu.</para></listitem>
@@ -738,7 +739,7 @@
</orderedlist>
</para></listitem>
<listitem><para>When you are happy with the range that you've selected, right-click on the range and choose 'Consolidate range' from the menu.</para></listitem>
- <listitem><para>Ardour will create a region from the range that you selected, leaving it in-place. It will also divide the space in the region before and after the new region, leaving you with many smaller regions, all conveniently collected in the session toolbar's Regions list, under the blue-coloured "Voice_2--L" and "Voice_2--R" regions.</para></listitem>
+ <listitem><para><application>Ardour</application> will create a region from the range that you selected, leaving it in-place. It will also divide the space in the region before and after the new region, leaving you with many smaller regions, all conveniently collected in the session toolbar's Regions list, under the blue-coloured "Voice_2--L" and "Voice_2--R" regions.</para></listitem>
<listitem><para>Trim the rest of the original Voice_2 region, so that it starts with "golden," and does not contain any of the previous word ("flax-"). You don't need to use the range tool, but you can if you wish.</para></listitem>
<listitem><para>Then, push the two regions together, so that it sounds like "I have your flax-golden tails to... "</para></listitem>
<listitem><para>This isn't going to sound perfect, but you might prefer it to simply trimming the beginning off the Voice_2 region.</para></listitem>
@@ -767,7 +768,7 @@
<para>
There are two takes of the same material in this region.
<orderedlist>
- <listitem><para>Listen to them both, and decide which you prefer - it's up to your preference. Remember, you can also reverse your choice later, because Ardour won't delete the material that you remove by trimming the region.</para></listitem>
+ <listitem><para>Listen to them both, and decide which you prefer - it's up to your preference. Remember, you can also reverse your choice later, because <application>Ardour</application> will not delete the material that you remove by trimming the region.</para></listitem>
<listitem><para>Use the range tool to select the range which includes the take that you prefer.</para></listitem>
<listitem><para>Use the transport's looping mechanism, if you wish, to be sure that you selected the right range.</para></listitem>
<listitem><para>Right-click on the range, then choose 'Crop region to range,' which will automatically trim the region for you.</para></listitem>
@@ -796,7 +797,7 @@
<listitem><para>When you have made sure that the "Marimba_1" regions are not cropped or trimmed, and that they start at 00:00:00.000, we can lock it in place.
<orderedlist>
<listitem><para>Right-click on the regions, and navigate to the 'Selected regions' menu, then click 'Lock' from that menu.</para></listitem>
- <listitem><para>Notice that Ardour puts > and < around the name of the region, in the canvas area.</para></listitem>
+ <listitem><para>Notice that <application>Ardour</application> puts > and < around the name of the region, in the canvas area.</para></listitem>
<listitem><para>Also notice that you can no longer move the region with the "Select/Move Objects" tool.</para></listitem>
</orderedlist>
</para></listitem>
@@ -814,7 +815,7 @@
<itemizedlist>
<listitem><para>We can change the mode using the toolbar just above the canvas area. The pop-down menu probably says "Magnetic," indicating that it's in "Magnetic Snapping Mode," but it might also say "No Grid" or "Grid."</para></listitem>
<listitem><para>No Grid: This mode gives the user full control over where they will place a region. It is useful for doing highly-precise alignment, as we're about to do.</para></listitem>
- <listitem><para>Grid: This mode only allows the user to place regions where they will start on a grid-line. Unless you changed it, your grid is set to two seconds, so you can only start regions in two-second intervals - Ardour will not allow you to place a region so that it starts on an odd-numbered second, or anywhere in between.</para></listitem>
+ <listitem><para>Grid: This mode only allows the user to place regions where they will start on a grid-line. Unless you changed it, your grid is set to two seconds, so you can only start regions in two-second intervals - <application>Ardour</application> will not allow you to place a region so that it starts on an odd-numbered second, or anywhere in between.</para></listitem>
<listitem><para>Magnetic: This mode allows the user to place a region wherever they like, but when the start of the region is near a grid-line (an even-numbered second, in this session), the start of the region will automatically "snap" to that point. It behaves as if the start of regions were magnetically attracted to the grid lines.</para></listitem>
</itemizedlist>
</para></listitem>
@@ -1063,7 +1064,7 @@
<section id="sect-Musicians_Guide-Ardour-Mastering-Ways_to_Export">
<title>Ways to Export Audio</title>
<para>
- There are three ways to export audio from an Ardour session:
+ There are three ways to export audio from an <application>Ardour</application> session:
<orderedlist>
<listitem><para>by region,</para></listitem>
<listitem><para>by range, or</para></listitem>
@@ -1104,13 +1105,13 @@
<section id="sect-Musicians_Guide-Ardour-Mastering-Choosing_Tracks_to_Export">
<title>Choose Which Tracks to Export</title>
<para>
- By default, Ardour will export all audio in the range or session being exported. What it actually exports is all audio routed through the master output bus. You can see the list of tracks to export on the right side of the "Export" window. If you click the 'Specific Tracks' button, you will be able to choose from a list of all the tracks and busses in a session. Choosing specific tracks only makes sense if you do not want to export the master bus' output, so you should probably de-select that first.
+ By default, <application>Ardour</application> will export all audio in the range or session being exported. What it actually exports is all audio routed through the master output bus. You can see the list of tracks to export on the right side of the "Export" window. If you click the 'Specific Tracks' button, you will be able to choose from a list of all the tracks and busses in a session. Choosing specific tracks only makes sense if you do not want to export the master bus' output, so you should probably de-select that first.
</para>
</section>
<section id="sect-Musicians_Guide-Ardour-Mastering-Choosing_Export_Format">
<title>Choose the Export Format</title>
<para>
- Ardour offers quite a variety of output formats, and knowing which to choose can be baffling. Not all options are available with all file types. Fedora Linux does not support MP3 files by default, for legal reasons. For more information, refer to <citetitle>MP3 (Fedora Project Wiki)</citetitle> <ulink url="http://fedoraproject.org/wiki/Multimedia/MP3" />.
+ <application>Ardour</application> offers quite a variety of output formats, and knowing which to choose can be baffling. Not all options are available with all file types. Fedora Linux does not support MP3 files by default, for legal reasons. For more information, refer to <citetitle>MP3 (Fedora Project Wiki)</citetitle> <ulink url="http://fedoraproject.org/wiki/Multimedia/MP3" />.
</para>
<para>
The tutorial's regions have 24-bit samples, recorded at a 48 kHz rate. Exporting any part of the session with a higher sample format or sample rate is likely to result in decreased audio quality.
diff --git a/en-US/Audio_Vocabulary.xml b/en-US/Audio_Vocabulary.xml
index 52be13d..ef8da51 100644
--- a/en-US/Audio_Vocabulary.xml
+++ b/en-US/Audio_Vocabulary.xml
@@ -19,16 +19,18 @@
<section id="sect-Musicians_Guide-Vocabulary-Bus">
<title>Busses, Master Bus, and Sub-Master Bus</title>
- <mediaobject><imageobject>
+ <para>
+ <inlinemediaobject><imageobject>
<!-- [[File:FMG-bus.xcf]] -->
<!-- [[File:FMG-bus.png|200px|How audio busses work.]] -->
<imagedata fileref="./images/FMG-bus.png" format="PNG" />
- </imageobject></mediaobject>
- <mediaobject><imageobject>
+ </imageobject></inlinemediaobject>
+ <inlinemediaobject><imageobject>
<!-- [[File:FMG-master_sub_bus.xcf]] -->
<!-- [[File:FMG-master_sub_bus.png|200px|The relationship between the master bus and sub-master busses.]] -->
<imagedata fileref="./images/FMG-master_sub_bus.png" format="PNG" />
- </imageobject></mediaobject>
+ </imageobject></inlinemediaobject>
+ </para>
<para>
An '''audio bus''' sends audio signals from one place to another. Many different signals can be inputted to a bus simultaneously, and many different devices or applications can read from a bus simultaneously. Signals inputted to a bus are mixed together, and cannot be separated after entering a bus. All devices or applications reading from a bus receive the same signal.
</para>
@@ -117,12 +119,12 @@
<section id="sect-Musicians_Guide-Vocabulary-Routing_and_Multiplexing">
<title>Routing and Multiplexing</title>
- <mediaobject><imageobject>
- <!-- [[File:FMG-routing_and_multiplexing.png|200px|left|Illustration of routing and multiplexing in the "Connections" window of the QjackCtl interface.]] -->
- <!-- [[FMG-routing_and_multiplexing.xcf]] -->
- <imagedata fileref="./images/FMG-routing_and_multiplexing.png" format="PNG" />
- </imageobject></mediaobject>
<para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:FMG-routing_and_multiplexing.png|200px|left|Illustration of routing and multiplexing in the "Connections" window of the QjackCtl interface.]] -->
+ <!-- [[FMG-routing_and_multiplexing.xcf]] -->
+ <imagedata fileref="./images/FMG-routing_and_multiplexing.png" format="PNG" />
+ </imageobject></inlinemediaobject>
'''Routing''' audio transmits a signal from one place to another - between applications, between parts of applications, or between devices. On Linux systems, the JACK Audio Connection Kit is used for audio routing. JACK-aware applications (and PulseAudio ones, if so configured) provide inputs and outputs to the JACK server, depending on their configuration. The QjackCtl application can adjust the default connections. You can easily reroute the output of a program like FluidSynth so that it can be recorded by Ardour, for example, by using QjackCtl.
</para>
<para>
diff --git a/en-US/Digital_Audio_Workstations.xml b/en-US/Digital_Audio_Workstations.xml
index 7ac1ae2..64f6c40 100644
--- a/en-US/Digital_Audio_Workstations.xml
+++ b/en-US/Digital_Audio_Workstations.xml
@@ -170,21 +170,25 @@
<section id="sect-Musicians_Guide-Messages_Pane">
<title>"Messages" Pane</title>
- <mediaobject><imageobject>
- <!-- [[File:Qtractor-interface-messages.png|300px|"Messages" Pane]] -->
- <imagedata fileref="./images/Qtractor-interface-messages.png" format="PNG" />
- </imageobject></mediaobject>
<para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:Qtractor-interface-messages.png|300px|"Messages" Pane]] -->
+ <imagedata fileref="./images/Qtractor-interface-messages.png" format="PNG" />
+ </imageobject></inlinemediaobject>
+ </para>
+ <para>
The "messages" pane, shown in the above diagram, contains messages produced by the DAW, and sometimes messages produced by software used by the DAW, such as JACK. If an error occurs, or if the DAW does not perform as expected, you should check the "messages" pane for information that may help you to get the desired results. The "messages" pane can also be used to determine whether JACK and the DAW were started successfully, with the options you prefer.
</para>
</section>
<section id="sect-Musicians_Guide-DAW_Clock">
<title>Clock</title>
- <mediaobject><imageobject>
- <!-- [[File:Qtractor-interface-clocks.png|300px|Clock]] -->
- <imagedata fileref="./images/Qtractor-interface-clocks.png" format="PNG" />
- </imageobject></mediaobject>
+ <para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:Qtractor-interface-clocks.png|300px|Clock]] -->
+ <imagedata fileref="./images/Qtractor-interface-clocks.png" format="PNG" />
+ </imageobject></inlinemediaobject>
+ </para>
<para>
The clock shows the current place in the file, as indicated by the transport. In the image, you can see that the transport is at the beginning of the session, so the clock indicates "0". This clock is configured to show time in minutes and seconds, so it is a "time clock." Other possible settings for clocks are to show BBT (bars, beats, and ticks - a "MIDI clock"), samples (a "sample clock"), or an SMPTE timecode (used for high-precision synchronization, usually with video - a "timecode clock"). Some DAWs allow the use of multiple clocks simultaneously.
</para>
@@ -195,10 +199,12 @@
<section id="sect-Musicians_Guide-Track_Info_Pane">
<title>"Track Info" Pane</title>
- <mediaobject><imageobject>
- <!-- [[File:Qtractor-interface-track_info.png|300px|"Track Info" Pane]] -->
- <imagedata fileref="./images/Qtractor-interface-track_info.png" format="PNG" />
- </imageobject></mediaobject>
+ <para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:Qtractor-interface-track_info.png|300px|"Track Info" Pane]] -->
+ <imagedata fileref="./images/Qtractor-interface-track_info.png" format="PNG" />
+ </imageobject></inlinemediaobject>
+ </para>
<para>
The "track info" pane contains information and settings for each track and bus in the session. Here, you can usually adjust settings like the routing of a track's or bus' input and output routing, the instrument, bank, program, and channel of MIDI tracks, and the three buttons shown on this image: "R" for "arm to record," "M" for "mute/silence track's output," and "S" for "solo mode," where only the selected tracks and busses are heard.
</para>
@@ -212,10 +218,12 @@
<section id="sect-Musicians_Guide-Track_Pane">
<title>"Track" Pane</title>
- <mediaobject><imageobject>
- <!-- [[File:Qtractor-interface-track.png|300px|"Track" Pane]] -->
- <imagedata fileref="./images/Qtractor-interface-track.png" format="PNG" />
- </imageobject></mediaobject>
+ <para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:Qtractor-interface-track.png|300px|"Track" Pane]] -->
+ <imagedata fileref="./images/Qtractor-interface-track.png" format="PNG" />
+ </imageobject></inlinemediaobject>
+ </para>
<para>
The "track" pane is the main workspace in a DAW. It shows regions (also called "clips") with a rough overview of the audio wave-form or MIDI notes, allows you to adjust the starting-time and length of regions, and also allows you to assign or re-assign a region to a track. The "track" pane shows the transport as a vertical line; in this image it is the left-most red line in the "track" pane.
</para>
@@ -226,10 +234,12 @@
<section id="sect-Musicians_Guide-DAW_Transport_Controls">
<title>Transport Controls</title>
- <mediaobject><imageobject>
- <!-- [[File:Qtractor-interface-transport.png|300px|Transport Controls]] -->
- <imagedata fileref="./images/Qtractor-interface-transport.png" format="PNG" />
- </imageobject></mediaobject>
+ <para>
+ <inlinemediaobject><imageobject>
+ <!-- [[File:Qtractor-interface-transport.png|300px|Transport Controls]] -->
+ <imagedata fileref="./images/Qtractor-interface-transport.png" format="PNG" />
+ </imageobject></inlinemediaobject>
+ </para>
<para>
The transport controls allow you to manipulate the transport in various ways. The shape of the buttons is somewhat standardized; a similar-looking button will usually perform the same function in all DAWs, as well as in consumer electronic devices like CD players and DVD players.
</para>
diff --git a/en-US/LilyPond/LilyPond-orchestra.xml b/en-US/LilyPond/LilyPond-orchestra.xml
index 4c13cf6..4179215 100644
--- a/en-US/LilyPond/LilyPond-orchestra.xml
+++ b/en-US/LilyPond/LilyPond-orchestra.xml
@@ -67,11 +67,12 @@
</para>
<para>
When you first setup the score, Frescobaldi will have created many sections for you by default. The program avoids making too many stylistic choices for you, which allows you to create your own style. It also sets up the default sections in a logical way:
- [pre]version
+ <literallayout>version
header
widely-used settings like tempoMark and "global"
individual parts
- score formatting[/pre]
+ score formatting
+ </literallayout>
The specific ordering will become more obvious to you as you get used to LilyPond.
</para>
<para>
@@ -81,17 +82,17 @@
<listitem><para>Use different levels of dividers (like <code>%%%% OBOE %%%%</code> for the oboe) to show sub-sections</para></listitem>
<listitem><para>Add blank lines between large sections, to separate them more obviously</para></listitem>
<listitem><para>Begin braces on new lines, like
- [pre]\header
+ <literallayout>\header
{
title = "Symphony"
...
}
- [/pre] instead of on the same line, like
- [pre]\header {
+ </literallayout>instead of on the same line, like
+ <literallayout>\header {
title = "Symphony"
...
}
- [/pre] This is simply a matter of personal taste, resulting from prior experience with C and C-like programming languages.</para></listitem>
+ </literallayout>This is simply a matter of personal taste, resulting from prior experience with C and C-like programming languages.</para></listitem>
<listitem><para>Familiarize myself with the sections and commands created by Frescobaldi, getting a sense of what the section/command does (even if I don't understand what each specific command does). This makes it easier to sort out problems and customization down the road. Sometimes, when the setup is quite complex, I make comments about what seems to be going on.</para></listitem>
<!-- End the portion taken from the Piano example -->
<listitem><para>Change the instrument names to replicate what my score indicates. You don't necessarily need to do this, so long as the people using your score will understand what the instruments are. Since my goal is to replicate this Dover edition score, I will change the names.</para>
@@ -166,8 +167,8 @@
<step><para>It is, but we're still missing some formatting. Use the "Quick Insert" toolbar-thing to add staccato markings to the first measure. You can add a staccato to the eighth-rest, but this doesn't make sense, so you shouldn't.</para></step>
<step><para>Slurs begin at ( and end at ). Add a slur from the g to c-sharp.</para></step>
<step><para>Preview the score to make sure that you entered these articulations correctly. Your code should be:
- [pre]r8 d-. g-. bes-. d-. bes-. |
- g8( cis) cis4 r |[/pre]</para></step>
+ <literallayout>r8 d-. g-. bes-. d-. bes-. |
+ g8( cis) cis4 r |</literallayout></para></step>
</substeps>
</step>
<step><para>Now to add the "forte" marking. You can add text (or any object, for that matter) onto a note (or rest, etc.) with one of these three symbols:
@@ -184,9 +185,8 @@
<step><para>When you preview this, you will see that it now looks exactly like a typical "forte" marking. Not all dynamic markings have these short-forms, but most do.</para></step>
<step><para>The "a 2" marking, meaning "to be played by two players," does need the text-in-quotes format, however. Put that marking ''above'' the d following the eighth rest.</para></step>
<step><para>Those two measures should now look like this:
- [pre]r8\f d-.^"a 2" g-. bes-. d-. bes-. |
- g8( cis) cis4 r |
- [/pre]
+ <literallayout>r8\f d-.^"a 2" g-. bes-. d-. bes-. |
+ g8( cis) cis4 r |</literallayout>
Note that <code>d-.^"a 2"</code> gives the same result as <code>d^"a 2"-.</code></para></step>
</procedure>
</section>
@@ -230,13 +230,13 @@
<listitem><para>Short-term Polyphonic Input (Divisi):
<itemizedlist>
<listitem><para>Anything between << and >> is interpreted by LilyPond as happening together. If you take a look at the "score" section at the bottom of the file, you will see that all of the parts are listed in that kind of bracket. This ensures that they all happen simultaneously.</para></listitem>
- <listitem><para>For short-term polyphonic input, use the formula [pre]<< { upper-voice notes } \\ { lower-voice notes } >>[/pre]. Remember that the "upper voice" has upward-pointing stems, and the "lower voice" has downward-pointing stems.</para></listitem>
+ <listitem><para>For short-term polyphonic input, use the formula <code><< { upper-voice notes } \\ { lower-voice notes } >></code>. Remember that the "upper voice" has upward-pointing stems, and the "lower voice" has downward-pointing stems.</para></listitem>
</itemizedlist></para></listitem>
- <listitem><para>Ties: These can be written by adding ~ to the end of the note beginning the tie: [pre]c4~ c8[/pre]</para></listitem>
+ <listitem><para>Ties: These can be written by adding ~ to the end of the note beginning the tie: <code>c4~ c8</code></para></listitem>
<listitem><para>Grace Notes: These take up no logical time, and are smaller than ordinary notes. Any notes appearing <code>\grace { in here }</code> would be considered grace notes.</para></listitem>
<listitem><para>Crescendo and Diminuendo Markings:
<itemizedlist>
- <listitem><para>These are added like other dynamic markings, attached with a backslash to the note where they begin. A crescendo is triggered with \< and a diminuendo with \>.</para></listitem>
+ <listitem><para>These are added like other dynamic markings, attached with a backslash to the note where they begin. A crescendo is triggered with <code>\<</code> and a diminuendo with <code>\></code>.</para></listitem>
<listitem><para>The left-most point of the marking (its beginning) is indicated by where you put \< or \></para></listitem>
<listitem><para>The right-most (or end-)point is indicated by either another dynamic marking of any sort, or the special cancellation character (<code>\!</code>).</para></listitem>
</itemizedlist></para></listitem>
@@ -256,21 +256,19 @@
<step><para>We're going to define a new whatever-thing, like the "global" section created for us by Frescobaldi, and include it in all of the parts.</para></step>
<step><para>The code needed for this is a little bit complicated, but you don't need to write it yourself: just take it from the "tempoMark" section created by Frescobaldi. All you need to do is change "Adagio" to "Allegro spiritoso," and add the barline indicator. This is also easy because of Frescobaldi: 'LilyPond > Bar Lines > Repeat start'</para></step>
<step><para>You end up with
- [pre]startExposition =
+ <literallayout>startExposition =
{
\once \override Score.RehearsalMark #'self-alignment-X = #LEFT
\once \override Score.RehearsalMark #'break-align-symbols = #'(time-signature key-signature)
\mark \markup \bold "Allegro spiritoso"
\bar "|:"
- }
- [/pre]</para></step>
+ }</literallayout></para></step>
<step><para>Add the reference to this in all of your parts. Because of how I named it, this also serves as a handy way to find your way through the LilyPond markup file.
- [pre] r4 r r\fermata |
+ <literallayout> r4 r r\fermata |
\startExposition
- R2.*4 |
- [/pre]</para></step>
+ R2.*4 |</literallayout></para></step>
<step><para>The barline and tempo-change will not appear unless you write some music after them, so put in some or all of the rests that follow, just to test it.</para></step>
</procedure>
</section>
diff --git a/en-US/LilyPond/LilyPond-piano.xml b/en-US/LilyPond/LilyPond-piano.xml
index 9864ccd..1d539d1 100644
--- a/en-US/LilyPond/LilyPond-piano.xml
+++ b/en-US/LilyPond/LilyPond-piano.xml
@@ -65,11 +65,11 @@
</para>
<para>
When you first setup the score, Frescobaldi will have created many sections for you by default. The program avoids making too many stylistic choices for you, which allows you to create your own style. It also sets up the default sections in a logical way:
- [pre]version
+ <literallayout>version
header
widely-used settings like tempoMark and "global"
individual parts
- score formatting[/pre]
+ score formatting</literallayout>
The specific ordering will become more obvious to you as you get used to LilyPond.
</para>
<para>
@@ -78,14 +78,18 @@
<listitem><para>Use section-dividers (like <code>%%%%%%%% NOTES %%%%%%%%</code> for individual parts) to demarcate sections.</para></listitem>
<listitem><para>Use different levels of dividers (like <code>%%%% RIGHT HAND %%%%</code> for the right hand) to show sub-sections</para></listitem>
<listitem><para>Add blank lines between large sections, to separate them more obviously</para></listitem>
- <listitem><para>Begin braces on new lines (as [pre]\header
+ <listitem><para>Begin braces on new lines (as
+ <literallayout>\header
{
title = "Impromptu"
...
- }[/pre]instead of on the same line (as [pre]\header {
+ }</literallayout>
+ instead of on the same line (as
+ <literallayout>\header {
title = "Impromptu"
...
- }[/pre]This is simply a matter of personal taste, resulting from prior experience with C and C-like programming languages.</para></listitem>
+ }</literallayout>
+ This is simply a matter of personal taste, resulting from prior experience with C and C-like programming languages.</para></listitem>
<listitem><para>Familiarize myself with the sections and commands created by Frescobaldi, getting a sense of what the section/command does (even if I don't understand what each specific command does). This makes it easier to sort out problems and customization down the road. Sometimes, when the setup is quite complex, I make comments about what seems to be going on.</para></listitem>
<listitem><para>At this point, I also added the "Dynamics Context" commands, as described below in the "Piano Dynamics" section</para></listitem>
</itemizedlist>
@@ -170,14 +174,14 @@
<title>Polyphonic Sections of Homophonic Music</title>
<para>
Sometimes, especially in piano music, a passage of some measures will require polyphonic (multi-Voice) notation in LilyPond, even though most of the music does not. In this case, you would use the following format:
- [pre]<<
+ <literallayout><<
{
% upper voice notes go here
} \\
{
% lower voice notes go here
}
- >>[/pre]
+ >></literallayout>
This is used a few times in both hands in the example score file.
</para>
<para>
@@ -240,17 +244,17 @@
</para>
<procedure>
<step><para>Between the left and right staves of the PianoStaff, add "<code>\new PianoDynamics = "dynamics" \dynamics</code>". For the Schubert score, this looks like:
- [pre] \new PianoStaff \with
- {
+ \new PianoStaff \with
+ <literallayout> {
instrumentName = "Piano"
}
<<
\new Staff = "right" \right
\new PianoDynamics = "dynamics" \dynamics
\new Staff = "left" { \clef bass \left }
- >>[/pre]</para></step>
+ >></literallayout></para></step>
<step><para>To the layout section, add the following:
- [pre]% Everything below here is for the piano dynamics.
+ <literallayout> % Everything below here is for the piano dynamics.
% Define "PianoDynamics" context.
\context
{
@@ -277,13 +281,14 @@
\PianoStaff
\accepts PianoDynamics
}
- % End of PianoDynamics code.[/pre]
+ % End of PianoDynamics code.</literallayout>
This creates a "PianoDynamics" context, and modifies the "PianoStaff" context so that it will accept a "PianoDynamics" context.</para></step>
- <step><para>Before the "\score" section, add a section called "dynamics," like this:[pre]dynamics =
+ <step><para>Before the "\score" section, add a section called "dynamics," like this:
+ <literallayout>dynamics =
{
% Dynamics go here.
- }[/pre]
+ }</literallayout>
This is where you will input the dynamics.</para></step>
</procedure>
</section>
diff --git a/en-US/LilyPond/LilyPond-syntax.xml b/en-US/LilyPond/LilyPond-syntax.xml
index 8d39162..3e5407c 100644
--- a/en-US/LilyPond/LilyPond-syntax.xml
+++ b/en-US/LilyPond/LilyPond-syntax.xml
@@ -16,7 +16,7 @@
One letter is all that's required to create a note in LilyPond. There are additional symbols and letters that are added to indicate further details, like the register, and whether the note is "sharp" or "flat."
</para>
<para>
- Although it can be changed, the default (and recommended) way to indicate "sharp" or "flat" is by using Dutch note-names: "-is" to indicate a sharp, and "-es" to indicate a flat. For example, the following command would create b-double-flat, b-flat, b, b-sharp, and b-double-sharp: [pre]beses bes b bis bisis[/pre] Getting used to these names happens quickly, and they take less time to input than the English alternative. Furthermore, with these names, it becomes possible to sing note-names when you are ear training!
+ Although it can be changed, the default (and recommended) way to indicate "sharp" or "flat" is by using Dutch note-names: "-is" to indicate a sharp, and "-es" to indicate a flat. For example, the following command would create b-double-flat, b-flat, b, b-sharp, and b-double-sharp: <code>beses bes b bis bisis</code> Getting used to these names happens quickly, and they take less time to input than the English alternative. Furthermore, with these names, it becomes possible to sing note-names when you are ear training!
</para>
<para>
Pitch can be entered either absolutely, or relative to the preceding notes. Usually (for music without frequent large leaps) it is more convenient to use the "relative" mode. The symbols <literal>,</literal> and <literal>'</literal> (comma and apostrophe) are used to indicate register.
@@ -102,10 +102,7 @@
Making use of the << and >> idea to indicate simultaneity, if a note has multiple pitches indicated between > and < then LilyPond assumes that they are in a chord together. Notating a single chord with single > < brackets has two advantages: firstly, it is easier to see that they are a chord and not something more complex; secondly, it allows you to enter information more clearly.
</para>
<para>
- Consider the following examples, which should produce equivalent output:
- [pre]<<g'4->-5 b d>>[/pre]
- [pre]<g' b d>4->-5[/pre]
- With the first example, it is more difficult to see the chord notes, the duration, and what the "5" means. With the second example, it is easy to see that the chord notes are a G, a B, and a D, that they have quarter-note duration, and that the "5" is actually a fingering indication.
+ Consider the following examples, which should produce equivalent output: <code><<g'4->-5 b d>></code> and <code><g' b d>4->-5</code> With the first example, it is more difficult to see the chord notes, the duration, and what the <literal>5</literal> means. With the second example, it is easy to see that the chord notes are a G, a B, and a D, that they have quarter-note duration, and that the <literal>5</literal> is actually a fingering indication.
</para>
<para>
There is another advantage to using < and > for notation of simple chords: they preserve logical continuity in "relative" mode. The following note will always be notated as relative to the lowest note in the chord, regardless of how many octaves the chord covers. This is not true with << and >>, where where following notes will be notated as relative to the last note between the << and >> .
@@ -227,7 +224,7 @@
</para>
<para>
The generic structure of a LilyPond source file is this:
- [pre]\version "whatever_version"
+ <literallayout>\version "whatever_version"
\header { things like title, composer, and so on }
@@ -243,7 +240,7 @@
}
and so on
- }[/pre]
+ }</literallayout>
</para>
<para>
Confusion arises here: for maximum flexibility, LilyPond allows source files to create its own commands. On hearing this, you may think, "Okay that's it - I don't need advanced commands or any of this stuff, so I'm packing it in and just using Finale!" There's no need to do that just yet - commands are easy! Think of commands - whether you wrote them or they were included with LilyPond - as a means of text-substition.
@@ -263,7 +260,7 @@
</para>
<para>
Here is a good template source file, that might be created for you by Frescobaldi:
- [pre]\version "2.12.2"
+ <literallayout>\version "2.12.2"
\header
{
@@ -285,7 +282,7 @@
}
\violin
\layout { }
- }[/pre]
+ }</literallayout>
</para>
<para>
This source file makes use of many commands, and even defines "violin" for its own use. It may not be easy to see from this simple example, but keeping your notes separated from the formatting of a complex ''\score'' section will greatly improve the readability of both sections. Furthermore, you will easily be able to search through thousands of lines of source file to find the section that you want.
@@ -313,10 +310,10 @@
The octave-check symbols is <code>=</code>. The symbol appears after the note, and is followed by a comma (<code>,</code>), apostrophe (<code>'</code>), or neither, depending on the intended relative octave of the pitch.
</para>
<para>
- Here is an example use of the octave-check symbol: [pre]c'='''[/pre]. In this example, the absolute pitch is <code>c'''</code>, which LilyPond knows because of the <code>c</code> at the left, and the <code>'''</code> after the <code>=</code> symbol.
+ Here is an example use of the octave-check symbol: <code>c'='''</code>. In this example, the absolute pitch is <code>c'''</code>, which LilyPond knows because of the <code>c</code> at the left, and the <code>'''</code> after the <code>=</code> symbol.
</para>
<para>
- How does this example work: [pre]c'=4[/pre]? There is a <code>4</code> after the <code>=</code> symbol instead of a comma or apostrophe. The absolute pitch is <code>c</code>, which LilyPond knows because of the <code>c</code> to the left of the <code>=</code> symbol, and because there is no comma or apostrophe to the right of the <code>=</code> symbol. LilyPond understands the <code>4</code> as "quarter note."
+ How does this example work: <code>c'=4</code> ? There is a <code>4</code> after the <code>=</code> symbol instead of a comma or apostrophe. The absolute pitch is <code>c</code>, which LilyPond knows because of the <code>c</code> to the left of the <code>=</code> symbol, and because there is no comma or apostrophe to the right of the <code>=</code> symbol. LilyPond understands the <code>4</code> as "quarter note."
</para>
<para>
You should use the octave-check symbol when you need it. New users use the octave-check symbol more frequently than experienced users.
@@ -332,16 +329,16 @@
</para>
<para>
This example is correct, and will not trigger a warning:
- [pre]\time 4/4
- c4 c c c |
- c4 c c c |[/pre]
+ <literallayout>\time 4/4
+ c4 c c c |
+ c4 c c c |</literallayout>
There are four quarter-notes between each bar-check symbol, which is the right number of beats.
</para>
<para>
This example is incorrect, and will trigger a warning:
- [pre]\time 4/4
- c2 c c c |
- c4 c c c | [/pre]
+ <literallayout>\time 4/4
+ c2 c c c |
+ c4 c c c |</literallayout>
The first bar has four half-notes, which is twice as many beats as are allowed. LilyPond will print a warning at the first bar-check symbol.
</para>
<para>
diff --git a/en-US/Planet_CCRMA_at_Home.xml b/en-US/Planet_CCRMA_at_Home.xml
index 80001ea..0121f29 100644
--- a/en-US/Planet_CCRMA_at_Home.xml
+++ b/en-US/Planet_CCRMA_at_Home.xml
@@ -83,16 +83,16 @@
<section id="sect-Musicians_Guide-Using_Planet_CCRMA_Software">
<title>Using Software from Planet CCRMA at Home</title>
<para>
- The Planet CCRMA at Home software is hosted (stored) on a server at Stanford University. It is separate from the Fedora Linux servers, so yum (the command-line utility used by PackageKit and KPackageKit) must be made aware that you wish to use it. After installing the repository, Planet CCRMA at Home software can be installed through yum, PackageKit, or KPackageKit just as easily as any other software.
+ The Planet CCRMA at Home software is hosted (stored) on a server at Stanford University. It is separate from the Fedora Linux servers, so <command>yum</command> (the command line utility used by PackageKit and KPackageKit) must be made aware that you wish to use it. After installing the repository, Planet CCRMA at Home software can be installed through yum, PackageKit, or KPackageKit just as easily as any other software.
</para>
<section id="sect-Musicians_Guide-CCRMA_Installing_Repository">
<title>Installing the Planet CCRMA at Home Repositories</title>
<para>
The following steps will install the Planet CCRMA at Home repository, intended only for Fedora Linux-based computers.
<orderedlist>
- <listitem><para>Update your computer with PackageKit, KPackageKit, or by running <code>su -c 'yum update'</code> and approving the installation.</para></listitem>
+ <listitem><para>Update your computer with PackageKit, KPackageKit.</para></listitem>
<listitem><para>You will have to use a terminal window for the next portion.</para></listitem>
- <listitem><para>Run the following commands: <code>su -c 'rpm -Uvh http://ccrma.stanford.edu/planetccrma/mirror/fedora/linux/planetccrma/12/i386/planetccrma-repo-1.1-2.fc12.ccrma.noarch.rpm'</code> ADMONITION that this will work for Fedora 12, 13, and 14 and 32-bit and 64-bit</para></listitem>
+ <listitem><para>Run the following commands: <command>su -c 'rpm -Uvh http://ccrma.stanford.edu/planetccrma/mirror/fedora/linux/planetccrma/12/i386/planetccrma-repo-1.1-2.fc12.ccrma.noarch.rpm'</command> This works for Fedora 12, 13, and 14 and 32-bit and 64-bit</para></listitem>
<listitem><para>Update your computer again.</para></listitem>
<listitem><para>You may receive a warning that the RPM database was altered outside of "yum". This is normal.</para></listitem>
<listitem><para>Your repository definition will automatically be updated.</para></listitem>
@@ -100,38 +100,43 @@
</orderedlist>
</para>
<para>
- Although it is necessary to use the "rpm" program directly, all other Planet CCRMA software can be installed through "yum", like all other applications. Here is an explanation of the command-line options used above:
+ Although it is necessary to use the <command>rpm</command> program directly, all other Planet CCRMA software can be installed through <command>yum</command>, like all other applications. Here is an explanation of the command-line options used above:
<itemizedlist>
- <listitem><para>-U means "upgrade," which will install the specified package, and remove any previously-installed version</para></listitem>
- <listitem><para>-v means "verbose," which will print additional information meessages</para></listitem>
- <listitem><para>-h means "hash," which will display hash marks (these: #) showing the progress of installation.</para></listitem>
+ <listitem><para><literal>-U</literal> means "upgrade," which will install the specified package, and remove any previously-installed version</para></listitem>
+ <listitem><para><literal>-v</literal> means "verbose," which will print additional information meessages</para></listitem>
+ <listitem><para><literal>-h</literal> means "hash," which will display hash marks (these: <literal>#</literal>) showing the progress of installation.</para></listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Musicians_Guide-CCRMA_Repository_Priorities">
- <title>Setting Repository Priorities</title>
- <para>
- This is optional, and recommended only for advanced users. Normally, "yum" will install the latest version of a package, regardless of which repository provides it. Using this plugin will change this behaviour, so that yum will choose package versions primarily based on which repository provides it. If a newer version is available at a repository with lower priority, yum will not upgrade the package. If you simply wish to prevent a particular package from being updated, the instructions in "Preventing LINK LINK" are better-suited to your needs.
- <orderedlist>
- <listitem><para>Install the "yum-plugin-priorities" package.</para></listitem>
- <listitem><para>Use a text editor or the "cat" or "less" command to verify that <code>/etc/yum/pluginconf.d/priorities.conf</code> exists, and contains the following text:
- [pre][main]
- enabled = 1[/pre]If you want to stop using the plugin, you can edit this file so that <code>enabled = 0</code>. This allows you to keep the priorities as set in the repository configuration files.</para></listitem>
- <listitem><para>You can set priorities for some or all repositories. To add a priority to a repository, edit its respective file in the <code>/etc/yum.repos.d/*</code> directory, adding a line like: [pre]priority = N[/pre]where N is a number from 1 to 99, inclusive. A priority of 1 is the highest setting, and 99 is the lowest. You will need to set priorities of at least two repositories before this becomes useful.</para></listitem>
- </orderedlist>
- </para>
+ <title>Set Repository Priorities</title>
+ <para>
+ This is optional, and recommended only for advanced users. <application>yum</application> normally installs the latest version of a package, regardless of which repository provides it. Using this plugin will change this behaviour, so that <application>yum</application> will choose package versions primarily based on which repository provides it. If a newer version is available at a repository with lower priority, <application>yum</application> does not upgrade the package. If you simply wish to prevent a particular package from being updated, the instructions in <xref linkend="sect-Musicians_Guide-CCRMA_Preventing_Package_Updates" /> are better-suited to your needs.
+ </para>
+ <procedure>
+ <step><para>Install the <package>yum-plugin-priorities</package> package.</para></step>
+ <step><para>Use a text editor or the <application>cat</application> or <application>less</application> command to verify that <filename>/etc/yum/pluginconf.d/priorities.conf</filename> exists, and contains the following text:
+<programlisting><![CDATA[
+[main]
+enabled = 1
+]]></programlisting>
+ If you want to stop using the plugin, you can edit this file so that <code>enabled = 0</code>. This allows you to keep the priorities as set in the repository configuration files.</para></step>
+ <step><para>You can set priorities for some or all repositories. To add a priority to a repository, edit its respective file in the <filename>/etc/yum.repos.d/<replaceable>*</replaceable></filename> directory, adding a line like: <literal>priority = <replaceable>N</replaceable></literal> where <literal>N</literal> is a number between <literal>1</literal> and <literal>99</literal>, inclusive. A priority of <literal>1</literal> is the highest setting, and <literal>99</literal> is the lowest. You will need to set priorities of at least two repositories before this becomes useful.</para></step>
+ </procedure>
</section>
<section id="sect-Musicians_Guide-CCRMA_Preventing_Package_Updates">
- <title>Preventing a Package from Being Updated</title>
+ <title>Prevent a Package from Being Updated</title>
<para>
- This is optional, and recommended only for advanced users. Normally, "yum" will install the latest version of a package. Using this plugin will allow you to prevent certain packages from being updated. If you wish to prevent packages from a particular repository from being used, then THIS SECTION is better-suited to your needs.
+ This is optional, and recommended only for advanced users. <command>yum</command> normally installs the latest version of packages. This plugin prevents certain packages from being updated. If you wish to prevent packages from a particular repository from being used, then <xref linkend="sect-Musicians_Guide-CCRMA_Repository_Priorities" /> is better-suited to your needs.
<orderedlist>
- <listitem><para>Install the "yum-plugin-versionlock" package.</para></listitem>
- <listitem><para>Use a text editor or the "cat" or "less" command to verify that <code>/etc/yum/pluginconf.d/versionlock.conf</code> exists, and contains the following text:
- [pre]enabled = 1[/pre]</para></listitem>
- <listitem><para>Add the list of packages which you do not want to be updated to <code>/etc/yum/pluginconf.d/versionlock.list</code>. Each package should go on its own line. For example:
- [pre]jack-audio-connect-kit-1.9.4
- qjackctl-0.3.6[/pre]</para></listitem>
+ <listitem><para>Install the <literal>yum-plugin-versionlock</literal> package.</para></listitem>
+ <listitem><para>Use a text editor or the <command>cat</command> or <command>less</command> command to verify that <filename>/etc/yum/pluginconf.d/versionlock.conf</filename> exists, and contains the following text: <code>enabled = 1</code></para></listitem>
+ <listitem><para>Add the list of packages which you do not want to be updated to <filename>/etc/yum/pluginconf.d/versionlock.list</filename>. Each package should go on its own line. For example:
+<programlisting><![CDATA[
+jack-audio-connect-kit-1.9.4
+qjackctl-0.3.6
+]]></programlisting>
+ </para></listitem>
</orderedlist>
</para>
</section>
diff --git a/en-US/Qtractor.xml b/en-US/Qtractor.xml
index 23af616..05757cf 100644
--- a/en-US/Qtractor.xml
+++ b/en-US/Qtractor.xml
@@ -10,7 +10,7 @@
Qtractor is a relatively new application, created and maintained by the same developers who are responsible for QjackCtl and Qsynth (both covered in other chapters of this Guide). It offers much more flexibility than Audacity, but is still easier to use than Ardour or Rosegarden. As such, it serves as the perfect starting-point for people first discovering software-based DAWs.
</para>
<para>
- But Qtractor is much more than just a starting-point: its simplicity is its greatest strength. Ardour and Rosegarden, may offer more features, but Qtractor takes much less time to learn. After the initial learning-curve, you will be able to complete almost every audio or MIDI project with Qtractor. Its interface offers simple, intuitive, point-and-click interaction with clips, integrated control of JACK connections, MIDI control integration with external devices and other MIDI-aware software, and support for <code>LADSPA</code>, <code>DSSI</code>, native <code>VSTi</code>, and <code>LV2</code> plug-ins. With development progressing very quickly, Qtractor is becoming more stable and usable by the minute. The simple interface allows you to focus on creating music to suit your creative needs.
+ But Qtractor is much more than just a starting-point: its simplicity is its greatest strength. Ardour and Rosegarden, may offer more features, but Qtractor takes much less time to learn. After the initial learning-curve, you will be able to complete almost every audio or MIDI project with Qtractor. Its interface offers simple, intuitive, point-and-click interaction with clips, integrated control of JACK connections, MIDI control integration with external devices and other MIDI-aware software, and support for LADSPA, DSSI, native VSTi, and LV2 plug-ins. With development progressing very quickly, Qtractor is becoming more stable and usable by the minute. The simple interface allows you to focus on creating music to suit your creative needs.
</para>
<para>
Beginners and advanced users alike will be pleased to see how Qtractor can work for them.
@@ -34,13 +34,13 @@
<section id="sect-Musicians_Guide-Qtractor-Hardware_Requirements">
<title>Hardware Requirements</title>
<para>
- You need an audio interface to use Qtractor. If you will record audio with Qtractor, you must have at least one microphone connected to your audio interface. You do not need a microphone to record audio signals from other JACK-aware programs like <code>FluidSynth</code> and <code>SuperCollider</code>.
+ You need an audio interface to use Qtractor. If you will record audio with Qtractor, you must have at least one microphone connected to your audio interface. You do not need a microphone to record audio signals from other JACK-aware programs like <application>FluidSynth</application> and <application>SuperCollider</application>.
</para>
</section>
<section id="sect-Musicians_Guide-Qtractor-Other_Requirements">
<title>Other Requirements</title>
<para>
- You need a MIDI synthesizer to use Qtractor as a MIDI sequencer. You can use hardware-based and software-based synthesizers with Qtractor. We recommend using the software-based <code>FluidSynth</code> MIDI synthesizer. See <xref linkend="chap-Musicians_Guide-FluidSynth" /> for information about <code>FluidSynth</code>.
+ You need a MIDI synthesizer to use Qtractor as a MIDI sequencer. You can use hardware-based and software-based synthesizers with Qtractor. We recommend using the software-based <application>FluidSynth</application> MIDI synthesizer. See <xref linkend="chap-Musicians_Guide-FluidSynth" /> for information about <application>FluidSynth</application>.
</para>
</section>
<section id="sect-Musicians_Guide-Qtractor-Installation">
@@ -103,7 +103,7 @@
<section id="sect-Musicians_Guide-Qtractor-Configuration-MIDI_Channel_Names">
<title>Configuring MIDI Channel Names</title>
<para>
- If you're using "<code>FluidSynth</code>" with QSynth, you should tell Qtractor about the SoundFont that you're using. When you do this, you enable Qtractor to help you choose instruments ("patches").
+ If you're using "<application>FluidSynth</application>" with QSynth, you should tell Qtractor about the SoundFont that you're using. When you do this, you enable Qtractor to help you choose instruments ("patches").
<orderedlist>
<listitem><para>Click on 'View > Instruments'</para></listitem>
<listitem><para>In the ''Instruments'' window, click "Import."</para></listitem>
@@ -228,7 +228,7 @@
<section id="sect-Musicians_Guide-Qtractor-Using-Exporting_Audio_and_MIDI_Together">
<title>Exporting a Whole File (Audio and MIDI Together)</title>
<para>
- Qtractor can export all of a session's audio clips as one audio file, but it cannot export the MIDI clips directly into that audio file. This is because Qtractor does not synthesize audio from MIDI signals, but uses an external MIDI synthesizer to do this. Thankfully, there is a relatively simple way to overcome this, allowing both audio and MIDI to be exported in the same audio file: use Qtractor to record the audio signal produced by the MIDI synthesizer. This procedure only works if you use a MIDI synthesizer (like <code>FluidSynth</code>) which outputs its audio signal to JACK.
+ Qtractor can export all of a session's audio clips as one audio file, but it cannot export the MIDI clips directly into that audio file. This is because Qtractor does not synthesize audio from MIDI signals, but uses an external MIDI synthesizer to do this. Thankfully, there is a relatively simple way to overcome this, allowing both audio and MIDI to be exported in the same audio file: use Qtractor to record the audio signal produced by the MIDI synthesizer. This procedure only works if you use a MIDI synthesizer (like <application>FluidSynth</application>) which outputs its audio signal to JACK.
<orderedlist>
<listitem><para>Create a new audio track in Qtractor by clicking on 'Track > Add Track'.</para></listitem>
<listitem><para>Ensure that your MIDI synthesizer is set up correctly to produce output in the usual method (through your speakers).</para></listitem>
@@ -273,13 +273,13 @@
</para>
<para>
If you find it difficult to work with Qtractor's matrix editor, but you find it easy to work with LilyPond, you can use this to your advantage. LilyPond will output a MIDI-format representation of your score if you include a "midi" section in the "score" section. It should look something like this:
- [pre]
- \score
- {
- ...
- \midi { }
- }
- [/pre]
+<programlisting><![CDATA[
+\score
+{
+ ...
+ \midi { }
+}
+]]></programlisting>
You can import LilyPond's MIDI output by clicking 'Track > Import Tracks > MIDI' in Qtractor.
</para>
</section>
diff --git a/en-US/Real_Time_and_Low_Latency.xml b/en-US/Real_Time_and_Low_Latency.xml
index 12bf22c..0906874 100644
--- a/en-US/Real_Time_and_Low_Latency.xml
+++ b/en-US/Real_Time_and_Low_Latency.xml
@@ -68,7 +68,7 @@
You can install the real-time kernel, along with other system optimizations, by following these instructions:
<orderedlist>
<listitem><para>Install the Planet CCRMA at Home repositories by following the instructions in <xref linkend="sect-Musicians_Guide-CCRMA_Installing_Repository" />.</para></listitem>
- <listitem><para>Run the following command in a terminal: [pre]su -c 'yum install planetccrma-core'[/pre] Note that this is a meta-package, which does not install anything by itself, but causes a number of other packages to be installed, which will themselves perform the desired installation and optimization.</para></listitem>
+ <listitem><para>Run the following command in a terminal: <command>su -c 'yum install planetccrma-core'</command> Note that this is a meta-package, which does not install anything by itself, but causes a number of other packages to be installed, which will themselves perform the desired installation and optimization.</para></listitem>
<listitem><para>Shut down and reboot your computer, to test the new kernel. If you decided to modify your GRUB configuration, be sure that you leave a non-real-time kernel available for use.</para></listitem>
</orderedlist>
</para>
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml
index f3b2d90..fe3ff39 100644
--- a/en-US/Revision_History.xml
+++ b/en-US/Revision_History.xml
@@ -84,6 +84,39 @@
</simplelist>
</revdescription>
</revision>
+
+ <revision>
+ <revnumber>5</revnumber>
+ <date>Fri Aug 6 2010</date>
+ <author>
+ <firstname>Christopher</firstname>
+ <surname>Antila</surname>
+ <email>crantila at fedoraproject.org</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Re-formatted ex-<pre> tags.</member>
+ <member>Changed images to <inlinemediaobject>, where appropriate.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <!--
+ <revision>
+ <revnumber>6</revnumber>
+ <date>Sat Aug 7 2010</date>
+ <author>
+ <firstname>Christopher</firstname>
+ <surname>Antila</surname>
+ <email>crantila at fedoraproject.org</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Reviewed use of <code> tags.</member>
+ <member>Added tables to SuperCollider chapter.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ -->
</revhistory>
</simpara>
</appendix>
diff --git a/en-US/Rosegarden.xml b/en-US/Rosegarden.xml
index bf2cd2f..2587d8f 100644
--- a/en-US/Rosegarden.xml
+++ b/en-US/Rosegarden.xml
@@ -119,13 +119,13 @@
<title>Rosegarden and LilyPond</title>
<para>
Rosegarden and LilyPond can be used together, which can greatly enhace your productivity. LilyPond will output a MIDI-format representation of your score if you include a "midi" section in the "score" section. It should look something like this:
- [pre]
- \score
- {
- ...
- \midi { }
- }
- [/pre]
+<programlisting><![CDATA[
+\score
+{
+ ...
+ \midi { }
+}
+]]></programlisting>
This MIDI file can then be imported into Rosegarden by selecting from the menu 'File > Import > Import MIDI File'. Unfortunately, this will erase the current session, so it can be done only once.
</para>
<para>
diff --git a/en-US/Solfege.xml b/en-US/Solfege.xml
index 8a8aa90..e050981 100644
--- a/en-US/Solfege.xml
+++ b/en-US/Solfege.xml
@@ -31,7 +31,7 @@
Please review the "Requirements" section above, before installation.
</para>
<para>
- Use PackageKit, KPackageKit to install the <code>solfege</code> package, or run [pre]su -c 'yum install solfege'[/pre] in a terminal.
+ Use PackageKit, KPackageKit to install the <package>solfege</package> package.
</para>
</section>
<section id="sect-Musicians_Guide-Solfege-Install_Csound">
diff --git a/en-US/Sound_Servers.xml b/en-US/Sound_Servers.xml
index f92a694..5626be0 100644
--- a/en-US/Sound_Servers.xml
+++ b/en-US/Sound_Servers.xml
@@ -53,12 +53,14 @@
<section id="sect-Musicians_Guide-Using_JACK">
<title>Using the JACK Audio Connection Kit</title>
<!-- TODO: Rewrite this section, knowing that jack2 will be in Fedora 14 -->
+ <!-- TODO: If you keep the config-file-tinkering, make sure it's clear why it's there -->
+ <!-- TODO: See if SELinux can be configured to control who/what has access to real-time priority -->
<section id="sect-Musicians_Guide-Install_and_Configure_JACK">
<title>Installing and Configuring JACK</title>
<para>
<orderedlist>
<listitem><para>Ensure that you have installed the Planet CCRMA at Home repositories. For instructions, refer to <xref linkend="sect-Musicians_Guide-CCRMA_Installing_Repository" />.</para></listitem>
- <listitem><para>Use PackageKit or KPackageKit to install the "jack-audio-connection-kit" and "qjackctl" packages, or run the following command in a terminal: [pre]sudo -c 'yum install jack-audio-connection-kit qjackctl'[/pre]</para></listitem>
+ <listitem><para>Use <application>PackageKit</application> or <application>KPackageKit</application> to install the <package>jack-audio-connection-kit</package> and <package>qjackctl</package> packages.</para></listitem>
<listitem><para>Review and approve the installation, making sure that it completes correctly.</para></listitem>
<listitem><para>Run QjackCtl from the KMenu or the Applications menu.</para></listitem>
<listitem><para>To start the JACK server, press the 'Start' button; to stop it, press the 'Stop' button.</para></listitem>
@@ -73,12 +75,15 @@
<listitem><para>Add all of the users who will use JACK to the "audio" group. For instructions to add users to groups, see Chapter 22, <citetitle>Users and Groups</citetitle> of the <citetitle>Fedora Deployment Guide</citetitle>, available at <ulink url="http://docs.fedoraproject.org" />.</para></listitem>
<listitem><para>The default installation automatically enables real-time priority to be requested by any user or process. This is undesirable, so we will edit it.
<orderedlist>
- <listitem><para>Open a terminal, and run the following command: [pre]sudo -c 'gedit /etc/security/limits.conf'[/pre]</para></listitem>
+ <listitem><para>Open a terminal, and run the following command: <command>sudo -c 'gedit /etc/security/limits.conf'</command></para></listitem>
<listitem><para>Be careful! You're editing this important system file as the root user!</para></listitem>
- <listitem><para>Edit the last lines, so that they read:[pre]
- @audio - rtprio 99
- @audio - memlock 4194304
- @audio - nice -10[/pre]</para></listitem>
+ <listitem><para>Edit the last lines, so that they read:
+<programlisting><![CDATA[
+ at audio - rtprio 99
+ at audio - memlock 4194304
+ at audio - nice -10
+]]></programlisting>
+ </para></listitem>
</orderedlist></para></listitem>
</orderedlist>
</para>
@@ -90,12 +95,12 @@
<step><para>Open a terminal. In GNOME, click on 'Applications > System > Terminal'. In KDE, click on the application launcher, then 'System > Konsole'.</para></step>
<step><para>Execute this command: "cat /proc/asound/cards".</para></step>
<step><para>The <code>cat</code> program outputs a list of sound cards in your computer, which looks similar to this list:
-[pre]
+<programlisting><![CDATA[
0 [SB ]: HDA-Intel - HDA ATI SB
HDA ATI SB at 0xf7ff4000 irq 16
1 [MobilePre ]: USB-Audio - MobilePre
M Audio MobilePre at usb-0000:00:13.0-2
-[/pre]
+]]></programlisting>
In this example output, the square brackets surround the name of the sound card. The names of the sound cards in this example output are <code>SB</code> and <code>MobilePre</code>.</para></step>
<step><para>Identify the name of the sound card that you want to use. If you do not see your sound card in the list outputted by <code>cat</code>, then your Fedora does not detect it.</para></step>
<step><para>Start QjackCtl.</para></step>
@@ -118,17 +123,20 @@
<para>
The default configuration of PulseAudio yields control of the audio equipment to JACK when the JACK server starts. PulseAudio will not be able to receive input or send output of any audio signals on the audio interface used by JACK. This is fine for occasional users of JACK, but many users will want to use JACK and PulseAudio simultaneously, or switch between the two frequently. The following instructions will configure PulseAudio so that its input and output is routed through JACK.
<orderedlist>
- <listitem><para>Use PackageKit or KPackageKit to install the "pulseaudio-module-jack" package, or in a terminal run the following command: [pre]su -c 'yum install pulseaudio-module-jack'[/pre]</para></listitem>
+ <listitem><para>Use PackageKit or KPackageKit to install the <package>pulseaudio-module-jack</package> package.</para></listitem>
<listitem><para>Approve the installation and ensure that it is carried out properly.</para></listitem>
<listitem><para>You'll need to edit the PulseAudio configuration file to use the JACK module.
<orderedlist>
<listitem><para>Be careful! You will be editing an important system file as the root user!</para></listitem>
- <listitem><para>Run the following command in a terminal: [pre]sudo -c 'gedit /etc/pulse/default.pa'[/pre]</para></listitem>
+ <listitem><para>Run the following command in a terminal: <command>sudo -c 'gedit /etc/pulse/default.pa'</command></para></listitem>
<listitem><para>Add the following lines, underneath the line that says [code]#load-module module-alsa-sink[/code]:
- [pre]load-module module-jack-sink
- load-module module-jack-source[/pre]</para></listitem>
+<programlisting><![CDATA[
+load-module module-jack-sink
+load-module module-jack-source
+]]></programlisting>
+ </para></listitem>
</orderedlist></para></listitem>
- <listitem><para>Restart PulseAudio by running the following command in a terminal: [pre]killall pulseaudio[/pre] It will start again automatically.</para></listitem>
+ <listitem><para>Restart PulseAudio by running the following command in a terminal: <command>killall pulseaudio</command> PulseAudio restarts automatically.</para></listitem>
<listitem><para>Confirm that this has worked by opening QjackCtl. The display should confirm that JACK is "Active".</para></listitem>
<listitem><para>In the "Connect" window, on the "Audio" tab, there should be PulseAudio devices on each side, and they should be connected to "system" devices on the opposite sides.</para></listitem>
<listitem><para>Open QjackCtl's "Setup" window, then click on the "Options" tab. Uncheck "Execute script after Shutdown: killall jackd". If you did not make this change, then QjackCtl would stop the JACK server from running every time the program quits. Since PulseAudio is still expecting to use JACK after that, you shouldn't do this any more.</para></listitem>
diff --git a/en-US/SuperCollider/SuperCollider-Basic_Programming.xml b/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
index 3bbb2a4..145c752 100644
--- a/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
+++ b/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
@@ -5,28 +5,30 @@
]>
<!-- SC-Basic_Programming- -->
+<!-- TODO: Convert all or most of the <programlisting>+CDATA code examples into <xi:include ... /> -->
<section id="sect-Musicians_Guide-SuperCollider-Basic_Programming">
- <title>Basic Programming in SuperCollider</title>
+ <title>Basic Programming in <application>SuperCollider</application></title>
+
<para>
- As with any programming language, you will start learning SuperCollider with the basic commands, that are of little use by themselves. However, since the language is so flexible, even the most basic commands can be combined in ways that create highly complex behaviours. The example program, "Method One," was written with the goal of illustrating how a single sound-generating object can be used to create an entire composition. This tutorial does not begin with audio-generating code, which helps to emphasize that SuperCollider is primarily a programming language.
+ As with any programming language, you will start learning <application>SuperCollider</application> with the basic commands, that are of little use by themselves. However, since the language is so flexible, even the most basic commands can be combined in ways that create highly complex behaviours. The example program, "Method One," was written with the goal of illustrating how a single sound-generating object can be used to create an entire composition. This tutorial does not begin with audio-generating code, which helps to emphasize that <application>SuperCollider</application> is primarily a programming language.
</para>
<para>
- This portion of the Guide is designed as a "reference textbook," which you can use both to learn the SuperCollider language in the first place, and to remind yourself about the language's features afterwards.
+ This portion of the Guide is designed as a "reference textbook," which you can use both to learn the <application>SuperCollider</application> language in the first place, and to remind yourself about the language's features afterwards.
</para>
<para>
- The Guide will probably be most effective when read only in small portions at once.
+ The section is most effective when read in small portions.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps">
<title>First Steps</title>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Parts_of_SuperCollider">
- <title>The Different Parts of SuperCollider</title>
+ <title>The Different Parts of <application>SuperCollider</application></title>
<para>
- As you discovered when installing SuperCollider, there are actually many different components involved with SuperCollider. Here is a list of some of them, with brief descriptions of their purpose:
+ As you discovered when installing <application>SuperCollider</application>, there are actually many different components involved with <application>SuperCollider</application>. Here is a list of some of them, with brief descriptions of their purpose:
<itemizedlist>
<listitem><para>Programming language: this is an abstract set of rules and guidelines that allow you to write down instructions for producing sounds.</para></listitem>
- <listitem><para>Interpreter: this is what is run in GEdit; it transforms the "programming language" instructions written by you into useful instructions for the server; also called the "client."</para></listitem>
+ <listitem><para>Interpreter: this is what is run in <application>GEdit</application>; it transforms the programming language instructions written by you into useful instructions for the server; also called the "client."</para></listitem>
<listitem><para>Server: this is what synthesizes the sound, according to instructions sent to it by the interpreter.</para></listitem>
<listitem><para>Library: these contain commands and the instructions to be executed when you call the commands; the interpreter looks up commands in the library when you call them.</para></listitem>
</itemizedlist>
@@ -35,52 +37,54 @@
This modular design allows for several advanced capabilities and features. Any particular element could theoretically be replaced without affecting other elements, as long as the methods of communication remain the same. As long as the programming language is the same, portions of the library can be modified, removed, or added at will; this happens often, and Planet CCRMA at Home provides a collection of library extensions. One of the most exciting capabilities is the ability to run the interpreter and server on different physical computers. The networking component is built into these components - they always communicate by UDP or TCP, even when run on the same computer! Although this ability is not used in this Guide, it is not difficult.
</para>
<para>
- The most important thing to remember is that the SuperCollider interpreter is what deals with the programs you write. The SuperCollider server is controlled by the interpreter, but is an independent program. For simple things, like the Hello World Programs below, the server is not even used - after all, there is no audio for it to synthesize.
+ The most important thing to remember is that the <application>SuperCollider</application> interpreter is what deals with the programs you write. The <application>SuperCollider</application> server is controlled by the interpreter, but is an independent program. For simple things, like the Hello World Programs below, the server is not even used - after all, there is no audio for it to synthesize.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Hello_World">
<title>"Hello, World!"</title>
<para>
- The first program that one traditionally makes when learning a new programming language is called "The Hello World Program." This is a simple and trivial application that simply prints outs the phrase, "Hello, World!" (or any variation of it). It might seem useless at first, but the ability to provide feedback to an application's user is very important, and this is essentially what the Hello World Program does.
+ The first program that one traditionally makes when learning a new programming language is called "The Hello World Program." This is a simple and trivial application that simply prints outs the phrase, <literal>Hello, World!</literal> (or a variation of it). It might seem useless at first, but the ability to provide feedback to an application's user is very important, and this is essentially what the Hello World Program does.
</para>
<para>
- Here is the program in SuperCollider:
- [pre]
- "Hello, World!".postln;
- [/pre]
+ Here is the program in <application>SuperCollider</application>:
+<programlisting><![CDATA[
+"Hello, World!".postln;
+]]></programlisting>
</para>
<para>
Here is an extension to that program:
- [pre]
- "Hello, World!".postln;
- "Hello, SC!".postln;
- [/pre]
+<programlisting><![CDATA[
+"Hello, World!".postln;
+"Hello, SC!".postln;
+]]></programlisting>
</para>
<para>
- As with all examples in this Guide, you should paste these programs into GEdit, and execute them with SuperCollider. Look at the output produced by the programs, but don't worry about it for now.
+ As with all examples in this section, you should paste these programs into <application>GEdit</application>, and execute them with <application>SuperCollider</application>. Look at the output produced by the programs, but don't worry about it for now.
</para>
<para>
- These programs are very small, but it highlights some key concepts of the SuperCollider language, described below.
+ These programs are very small, but it highlights some key concepts of the <application>SuperCollider</application> language, described below.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Return_Values">
<title>Return Values</title>
<para>
- Every SuperCollider program must provide the interpreter with a value (some information) when it has carried out all of its instructions. This value is called a "return value," because it is the value given by a program when it "returns" control to the interpreter. In a SuperCollider program, it is the last value stated in a program that automatically becomes the return value - no special command is required. When program execution ends, and control is returned to the SuperCollider interpreter, the interpreter outputs the return value in the "SuperCollider output" pane.
+ Every <application>SuperCollider</application> program must provide the interpreter with a value (some information) when it has carried out all of its instructions. This value is called a "return value," because it is the value given by a program when it "returns" control to the interpreter. In a <application>SuperCollider</application> program, it is the last value stated in a program that automatically becomes the return value - no special command is required. When program execution ends, and control is returned to the <application>SuperCollider</application> interpreter, the interpreter outputs the return value in the "SuperCollider output" pane.
</para>
<para>
In the single-line Hello World Program above, the program produces the following output:
- [pre]Hello, World!
- Hello, World![/pre]
- The program appears to have been executed twice, but that is not the case. The first "Hello, World!" is printed by the program. The second "Hello, World!" appears because <code>"Hello, World!.postln</code> is the last (in this case, the only) value of the program. It is "returned" by the program, and the interpreter prints it.
+<computeroutput>
+Hello, World!
+Hello, World!
+</computeroutput>
+ The program appears to have been executed twice, but that is not the case. The first <literal>Hello, World!</literal> is printed by the program. The second <literal>Hello, World!</literal> appears because <code>"Hello, World!.postln</code> is the last (in this case, the only) value of the program. It is "returned" by the program, and the interpreter prints it.
</para>
<para>
In the two-line Hello World Program above, the program produces the following output:
- [pre]
- Hello, World!
- Hello, SC!
- Hello, SC!
- [/pre]
+<computeroutput>
+Hello, World!
+Hello, SC!
+Hello, SC!
+</computeroutput>
This makes it more clear that the program is not being executed twice, and that it is the last value of a program that is returned to the interpreter.
</para>
<para>
@@ -94,25 +98,25 @@
Can you modify the two-line Hello World Program so that each line is printed only once?
</para>
<para>
- Note: In reality, every "function" must return a value. Functions are described later in this Guide; the difference is not yet important.
+ In reality, every "function" must return a value. Functions are described in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Variables_and_Functions-Functions" />, but the difference is not yet important.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Statements">
<title>Statements</title>
<para>
- A "statement" is a single instruction, which is always ended with a semicolon. Exactly what constitutes a statement will become clear as you gain experience, and including semicolons will quickly become an automatic action.
+ A "statement" is a single instruction, which always ends with a semicolon. Exactly what constitutes a statement will become clear as you gain experience, and you will eventually automatically remember the semicolon.
</para>
<para>
- In the Hello World Programs above, all of the statements contain the single instruction to post a line to the output screen. What happens when you remove the first semicolon, which marks the end of the first statement? The SuperCollider interpreter produces an unhelpful error message, and tells you that an error occurred ''after'' the forgotten semicolon. This is why it is important to always remember statement-concluding semicolons.
+ In the Hello World Programs above, all of the statements contain the single instruction to post a line to the output screen. What happens when you remove the first semicolon, which marks the end of the first statement? The <application>SuperCollider</application> interpreter produces an unhelpful error message, and tells you that an error occurred ''after'' the forgotten semicolon. This is why it is important to always remember statement-concluding semicolons.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Numbers_and_Strings">
<title>Data Types: Numbers and Strings</title>
<para>
- In many programming languages, it is the programmer's responsibility to determine the type of data that is being used, and how it should be stored. The SuperCollider interpreter takes advantage of the power of modern computers, and deals with this on our behalf. This greatly simplifies basic tasks, because there are only two kinds of data to worry about, and they make perfect sense:
+ In many programming languages, it is the programmer's responsibility to determine the type of data that is being used, and how it should be stored. The <application>SuperCollider</application> interpreter takes advantage of the power of modern computers, and deals with this on our behalf. This greatly simplifies basic tasks, because there are only two kinds of data to worry about, and they make perfect sense:
<itemizedlist>
- <listitem><para>Numbers: These are numbers, written simply as numbers. Anything that can be done with real-world numbers can also be done with SuperCollider's numbers. They can be as large or small, positive or negative as you want. They can have any number of digits on either side of the decimal point.</para></listitem>
- <listitem><para>Strings: These are a string of characters, written between two double-quote characters like "this." The double-quote characters are required so that SuperCollider knows where to begin and end the string of characters. A string of character can contain as many characters as you like, including one character and no characters. If you want to include a double-quote character in a string, you should put a blackslash before it. The following is interpreted by SuperCollider as a string with only a double-quote character: <code>"\""</code></para></listitem>
+ <listitem><para>Numbers: These are numbers, written simply as numbers. Anything that can be done with real-world numbers can also be done with <application>SuperCollider</application>'s numbers. They can be as large or small, positive or negative as you want. They can have any number of digits on either side of the decimal point.</para></listitem>
+ <listitem><para>Strings: These are a string of characters, written between two double-quote characters like "this." The double-quote characters are required so that <application>SuperCollider</application> knows where to begin and end the string of characters. A string of character can contain as many characters as you like, including one character and no characters. If you want to include a double-quote character in a string, you should put a blackslash before it. The following is interpreted by <application>SuperCollider</application> as a string with only a double-quote character: <code>"\""</code></para></listitem>
</itemizedlist>
</para>
<para>
@@ -128,10 +132,10 @@
</itemizedlist>
</para>
<para>
- Is the last example a number or a string? You and I recognize that it is a number inside a string, but SuperCollider will only treat it as a string. You can do string things with it, but you cannot do number things with it. You cannot add <code>"6"</code> to something, for example. Notice also that each example ends with a semicolon, which makes them complete statements. The statements don't do anything but represent themselves.
+ Is the last example a number or a string? You and I recognize that it is a number inside a string, but <application>SuperCollider</application> will only treat it as a string. You can do string things with it, but you cannot do number things with it. You cannot add <code>"6"</code> to something, for example. Notice also that each example ends with a semicolon, which makes them complete statements. The statements don't do anything but represent themselves.
</para>
<para>
- Try executing the following single-line programs. Think about why the SuperCollider interpreter produces the output that it does.
+ Try executing the following single-line programs. Think about why the <application>SuperCollider</application> interpreter produces the output that it does.
<itemizedlist>
<listitem><para><code>6 + 3;</code></para></listitem>
<listitem><para><code>"6" + 3;</code></para></listitem>
@@ -142,21 +146,21 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Consecutive_Execution">
<title>Consecutive Execution</title>
<para>
- Complex SuperCollider programs contain many parts, which all do different things. Sometimes, executing all of these together doesn't make sense, and it can be difficult to know which portions of the program are supposed to be executed when. To help with this, the interpreter allows you to mark portions of your program between ( and ) so that you will know to execute them together.
+ Complex <application>SuperCollider</application> programs contain many parts, which all do different things. Sometimes, executing all of these together doesn't make sense, and it can be difficult to know which portions of the program are supposed to be executed when. To help with this, the interpreter allows you to mark portions of your program between ( and ) so that you will know to execute them together.
</para>
<para>
Here is an example:
- [pre]
- (
- "Hello, Fred!".postln;
- "Hello, Wilma!".postln;
- )
- (
- "Goodbye, Fred!".postln;
- "Goodbye, Wilma!".postln;
- )
- [/pre]
- It doesn't make sense to say "hello" and "goodbye" at the same time, so separating these sections with parentheses will serve as a reminder. In case we try to execute all of the code at once, the SuperCollider interpreter will give us an error.
+<programlisting><![CDATA[
+(
+ "Hello, Fred!".postln;
+ "Hello, Wilma!".postln;
+)
+(
+ "Goodbye, Fred!".postln;
+ "Goodbye, Wilma!".postln;
+)
+]]></programlisting>
+ It doesn't make sense to say "hello" and "goodbye" at the same time, so separating these sections with parentheses will serve as a reminder. In case we try to execute all of the code at once, the <application>SuperCollider</application> interpreter will give us an error.
</para>
</section>
</section> <!-- Ends "First Steps" Section --> <!-- SC-Basic_Programming-First_Steps- -->
@@ -179,18 +183,16 @@
</para>
<para>
Run the following two programs. They should result in the same output.
- [pre]
- (
- 5 + 5;
- )
- [/pre]
- [pre]
- (
- var cheese;
- cheese = 5;
- cheese + cheese;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ 5 + 5;
+)
+(
+ var x;
+ x = 5;
+ x + x;
+)
+]]></programlisting>
</para>
<para>
In the first example, the program calculates the value of <code>5 + 5</code>, which is <code>10</code>, and returns that to the interpreter, which prints it out. In the second example, the program tells the interpreter that it wants to use a variable called <code>cheese</code> then it assigns cheese the value <code>5</code>. Finally, the program calculates <code>cheese + cheese</code>, which it understands as meaning <code>5 + 5</code>, and returns <code>10</code> to the interpreter, which prints it out.
@@ -206,21 +208,21 @@
</para>
<para>
A variable must be declared before use, so that the interpreter knows that you want to use that symbol as a variable. All variables must be declared before any statement that does not declare a variable; in other words, you should declare your variables before doing anything else. Variable names are declared like this:
- [pre]var variableName;[/pre]
+ <programlisting>var <replaceable>variableName</replaceable>;</programlisting>
Variables can also be declared in lists, like this:
- [pre]var variableOne, variableTwo;[/pre]
+ <programlisting>var <replaceable>variableName</replaceable>, <replaceable>variableOtherName</replaceable>;</programlisting>
</para>
<para>
Variables can be assigned a value at any time after they have been declared. Any single object can be assigned to a variable. If a variable is already assigned a value, any subsequent assignment will erase the previous assignment; the previously-assigned value will is not retrievable.
</para>
<para>
- The first assignment to a variable is said to "initialize" the variable. Initialization is a special kind of assignment, because a variable cannot be used before it is initialized. If a program attempts to use an un-initialized variable, the SuperCollider interpreter will cause an error. For this reason, you should always initialize a variable when you declare it. There is a special way to do this:
- [pre]var variableName = nil;[/pre]
+ The first assignment to a variable is said to "initialize" the variable. Initialization is a special kind of assignment, because a variable cannot be used before it is initialized. If a program attempts to use an un-initialized variable, the <application>SuperCollider</application> interpreter will cause an error. For this reason, you should always initialize a variable when you declare it. There is a special way to do this:
+ <programlisting>var <replaceable>variableName</replaceable> = nil;</programlisting>
Since you can't always assign a useful value, you can pick an arbitrary one. Assigning "nil" is common practice, because it means "nothing," but without actually being nothing (this avoids ''some'' errors). Assigning zero is another possibility; it is standard practice in many programming languages, and will avoid most errors, even if the variable is eventually supposed to hold another kind of object. Intialization and declaration of multiple variables can also be done as a list:
- [pre]var variableOne = 0, variableTwo = 0;[/pre]
+ <programlisting>var <replaceable>variableName</replaceable> = 0, <replaceable>variableOtherName</replaceable> = 0;</programlisting>
</para>
<para>
- Single-letter variable names have a special purpose in SuperCollider. They are already declared, so you don't have to declare them. They are also already initialized to "nil", so you don't have to do that either. These variable names are intended to be used as a quick fix, while you're experimenting with how to make a program work. You should not use them in good-quality programs.
+ Single-letter variable names have a special purpose in <application>SuperCollider</application>. They are already declared, so you don't have to declare them. They are also already initialized to "nil", so you don't have to do that either. These variable names are intended to be used as a quick fix, while you're experimenting with how to make a program work. You should not use them in good-quality programs.
</para>
<para>
The single-letter variable "s" is automatically assigned to the server on the computer running the interpreter. You should avoid re-assigning that variable.
@@ -244,38 +246,38 @@
</para>
<para>
Here is a Function that is not assigned to a variable, and is executed once.
- [pre]{ "Hello, World!".postln; }.value;[/pre]
+ <programlisting><![CDATA[{ "Hello, World!".postln; }.value;]]></programlisting>
Notice that there are two semicolons: one after the statement within the Function, and one after the "value" message that tells the Function to execute.
</para>
<para>
Here is a Function with identical function, assigned to a variable, and executed twice.
- [pre]
- var myFunction = { "Hello, World!".postln; }; // note two semicolons
- myFunction.value;
- myFunction.value;
- [/pre]
+<programlisting><![CDATA[
+var myFunction = { "Hello, World!".postln; }; // note two semicolons
+myFunction.value;
+myFunction.value;
+]]></programlisting>
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Variables_and_Functions-Function_Arguments">
<title>Function Arguments</title>
<para>
- The most useful aspect of Functions is that they can produce varying results, depending on their input. For whatever reason, the input accepted by a Function is called an "argument." SuperCollider's Functions can accept any number of arguments - zero, one, or many. Argument values (called "parameters") are provided to a Function by adding them in parentheses after the name of the Function, separated with commas, like this: <code>exampleFunction( 5, 7, 9 );</code> Argument variables are declared as the first statement in a Function, like this: <code>arg oneNumber, twoNumber;</code>
+ The most useful aspect of Functions is that they can produce varying results, depending on their input. For whatever reason, the input accepted by a Function is called an "argument." <application>SuperCollider</application>'s Functions can accept any number of arguments - zero, one, or many. Argument values (called "parameters") are provided to a Function by adding them in parentheses after the name of the Function, separated with commas, like this: <code>exampleFunction( 5, 7, 9 );</code> Argument variables are declared as the first statement in a Function, like this: <code>arg oneNumber, twoNumber;</code>
</para>
<para>
This program is significantly more complicated than previous examples, but it shows how useful Functions can be. Notice how the braces in that example are on different lines than the rest of the Function, which gives us more space within the Function to complete some useful work.
- [pre]
- (
- var greeter =
- {
- arg name;
- ( "Hello" + name ).postln;
- };
-
- greeter.value( "Samantha" );
- greeter.value( "Jermain" );
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var greeter =
+ {
+ arg name;
+ ( "Hello" + name ).postln;
+ };
+
+ greeter.value( "Samantha" );
+ greeter.value( "Jermain" );
+ nil;
+)
+]]></programlisting>
Here is how the program works:
<orderedlist>
<listitem><para>A variable named <code>greeter</code> is declared, and assigned a Function.</para></listitem>
@@ -286,29 +288,29 @@
</orderedlist>
</para>
<para>
- Since every argument has a name, SuperCollider allows you to use that name when executing the Function. This example executes the <code>greeter</code> Function from the last example:
- [pre]greeter.value( name:"Myung-Whun" );[/pre] This is more useful if there are many arguments, and you do not remember the order that they appear in the Function's definition.
+ Since every argument has a name, <application>SuperCollider</application> allows you to use that name when executing the Function. This example executes the <code>greeter</code> Function from the last example:
+ <code>greeter.value( name:"Myung-Whun" );</code> This is more useful if there are many arguments, and you do not remember the order that they appear in the Function's definition.
</para>
<para>
- SuperCollider also allows you to specify default values for arguments, so that they do not need to be specified. This allows optional customization of a Function's behaviour, and is therefore very powerful.
+ <application>SuperCollider</application> also allows you to specify default values for arguments, so that they do not need to be specified. This allows optional customization of a Function's behaviour, and is therefore very powerful.
</para>
<para>
This example modifies the one above by adding default-value arguments, and by calling arguments with their name. As you can see, I've been tricking you a bit: <code>postln</code> is actually a Function, but a special kind, explained later.
- [pre]
- (
- var greeter =
- {
- arg name, greeting = "Hello";
- postln( greeting + name );
- };
-
- greeter.value( "Samantha" );
- greeter.value( "Jermain", "Goodbye" );
- greeter.value( name:"Myung-Whun" );
- greeter.value( greeting:"Bienvenue", name:"Marcel" );
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var greeter =
+ {
+ arg name, greeting = "Hello";
+ postln( greeting + name );
+ };
+
+ greeter.value( "Samantha" );
+ greeter.value( "Jermain", "Goodbye" );
+ greeter.value( name:"Myung-Whun" );
+ greeter.value( greeting:"Bienvenue", name:"Marcel" );
+ nil;
+)
+]]></programlisting>
</para>
<para>
Any value can be used as a parameter, as long as the Function expects it. In fact, even Functions can be used as parameters for Functions!
@@ -317,24 +319,24 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Variables_and_Functions-Function_Return_Values">
<title>Function Return Values</title>
<para>
- All SuperCollider Functions return a value to the interpreter when they have finished execution. As with programs, the value returned is the value of the last statement in the Function. The return value of a Function can be captured, assigned to a variable, and used again later.
+ All <application>SuperCollider</application> Functions return a value to the interpreter when they have finished execution. As with programs, the value returned is the value of the last statement in the Function. The return value of a Function can be captured, assigned to a variable, and used again later.
</para>
<para>
This example assigns the result of a Function to a variable.
- [pre]
- (
- var mysticalMath =
- {
- arg input = 0;
- input * 23;
- };
- var someNumber = 9;
-
- someNumber = mysticalMath.value( someNumber );
- someNumber.postln;
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var mysticalMath =
+ {
+ arg input = 0;
+ input * 23;
+ };
+ var someNumber = 9;
+
+ someNumber = mysticalMath.value( someNumber );
+ someNumber.postln;
+ nil;
+)
+]]></programlisting>
Here is how the program works:
<orderedlist>
<listitem><para>A Function and variable are created, and assigned values.</para></listitem>
@@ -344,34 +346,34 @@
</para>
<para>
The program could have been shortened like this:
- [pre]
- (
- var mysticalMath =
- {
- arg input = 0;
- input * 23;
- };
-
- var someNumber = mysticalMath.value( 9 );
- someNumber.postln;
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var mysticalMath =
+ {
+ arg input = 0;
+ input * 23;
+ };
+
+ var someNumber = mysticalMath.value( 9 );
+ someNumber.postln;
+ nil;
+)
+]]></programlisting>
</para>
<para>
It could have been shortened even more like this:
- [pre]
- (
- var mysticalMath =
- {
- arg input = 0;
- input * 23;
- };
-
- mysticalMath.value( 9 ).postln;
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var mysticalMath =
+ {
+ arg input = 0;
+ input * 23;
+ };
+
+ mysticalMath.value( 9 ).postln;
+ nil;
+)
+]]></programlisting>
</para>
<para>
Experiment with the shortened versions of the program, ensuring that you know why they work.
@@ -380,44 +382,44 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Variables_and_Functions-">
<title>Variable Scope</title>
<para>
- A variable is only valid within its "scope." A variable's scope is determined by where it is declared. It will always last between either ( and ) or { and }, and applies to all statements within that block of code. Variable names can be re-declared in some contexts, which can be confusing.
+ A variable is only valid within its "scope." A variable's scope is determined by where it is declared. It will always last between either <literal>(</literal> and <literal>)</literal> or <literal>{</literal> and <literal>}</literal>, and applies to all statements within that block of code. Variable names can be re-declared in some contexts, which can be confusing.
</para>
<para>
Consider the scope of the variables in this example:
- [pre]
- (
- var zero = 0;
- var function =
- {
- var zero = 8;
- var sixteen = 16;
- zero.postln; // always prints 8
- };
-
- function.value;
- zero.postln; // always prints 0
- sixteen.postln; // always causes an error
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var zero = 0;
+ var function =
+ {
+ var zero = 8;
+ var sixteen = 16;
+ zero.postln; // always prints 8
+ };
+
+ function.value;
+ zero.postln; // always prints 0
+ sixteen.postln; // always causes an error
+)
+]]></programlisting>
Because <code>function</code> declares its own copy of <code>zero</code>, it is modified independently of the variable <code>zero</code> declared before the Function. Every time <code>function</code> is executed, it re-declares its own <code>zero</code>, and the interpreter keeps it separate from any other variables with the same name. When <code>function</code> has finished executing, the interpreter destroys its variables. Variables declared inside any Function are only ever accessible from within that Function. This is why, when we try to execute <code>sixteen.postln;</code>, the interpreter encounters an error: <code>sixteen</code> exists only within <code>function</code>, and is not accessible outside the Function. By the way, in order to excute this example, you will need to remove the error-causing reference to <code>sixteen</code>.
</para>
<para>
Now consider the scope of the variables in this example:
- [pre]
- (
- var zero = 0;
- var function =
- {
- var sixteen = 16;
- zero = 8;
- zero.postln; // always prints 8
- sixteen.postln;
- };
-
- function.value;
- zero.postln; // always prints 8
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var zero = 0;
+ var function =
+ {
+ var sixteen = 16;
+ zero = 8;
+ zero.postln; // always prints 8
+ sixteen.postln;
+ };
+
+ function.value;
+ zero.postln; // always prints 8
+)
+]]></programlisting>
Why does the last line always print <code>8</code>? It's because <code>zero</code> was set to 8 within <code>function</code>. More importantly, <code>function</code> did not declare its own copy of <code>zero</code>, so it simply accesses the one declared in the next "highest" block of code, which exists between ( and ) in this example.
</para>
<para>
@@ -425,21 +427,21 @@
</para>
<para>
Astute readers will notice that it is possible to re-declare the single-letter variable names, allowing you to control their scope. Consider the following program:
- [pre]
- (
- var a = 0;
- b =
- {
- var c = 16;
- a = 8;
- a.postln;
- c.postln;
- };
-
- b.value;
- a.postln;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var a = 0;
+ b =
+ {
+ var c = 16;
+ a = 8;
+ a.postln;
+ c.postln;
+ };
+
+ b.value;
+ a.postln;
+)
+]]></programlisting>
This example requires careful examination. What is the scope of <code>a</code>, <code>b</code>, and <code>c</code>? The answers may be surprising.
<itemizedlist>
<listitem><para><code>a</code> is declared just after the ( character, so the interpreter destroys it upon reaching the ) character.</para></listitem>
@@ -451,31 +453,31 @@
</section> <!-- Ends "Variables and Functions" Section --> <!-- SC-Basic_Programming-Variables_and_Functions- -->
<section id="sect-Musicians_Guide-SC-Basic_Programming-Object_Oriented">
- <title>Object-Oriented SuperCollider</title>
+ <title>Object-Oriented <application>SuperCollider</application></title>
<para>
- SuperCollider is difficult to describe precisely, because its syntax allows great flexibility. There are many different ways to accomplish the same task. Each one is subtly different, and gives you a different set of possibilities, but there is often no "best solution." One of the advantages to this is that it easily allows three "programming paradigms," although one is used much more often than the others.
+ <application>SuperCollider</application> is difficult to describe precisely, because its syntax allows great flexibility. There are many different ways to accomplish the same task. Each one is subtly different, and gives you a different set of possibilities, but there is often no "best solution." One of the advantages to this is that it easily allows three "programming paradigms," although one is used much more often than the others.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Object_Oriented-Imperative_Programming">
<title>Imperative Programming</title>
<para>
Imperative programming is easy to understand: it is simply a list of commands, like this:
- [pre]
- (
- var a, b, c;
+<programlisting><![CDATA[
+(
+ var a, b, c;
- a = 12;
- b = 25;
- c = a + b;
- a.postln;
- )
- [/pre]
+ a = 12;
+ b = 25;
+ c = a + b;
+ a.postln;
+)
+]]></programlisting>
Declare the variables, set the variables, do a calculation, and print the result of the calculation. This is a simple example, and a simple model, but it is very difficult to escape completely. After all, humans think of large problems in terms of algorithms (the instructions needed to do something). Computers solve large problems, so being able to program them with a series of instructions makes sense.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Object_Oriented-Functional_Programming">
<title>Functional Programming</title>
<para>
- Functional programming is also easy to understand, but it can be a little bit more difficult to think about complex tasks. Functional programs use Functions to complete all of their work. This is not strictly possible in SuperCollider: it is more imperative than functional, but the creative use of Functions can easily solve some problems that are difficult to write with an imperative approach.
+ Functional programming is also easy to understand, but it can be a little bit more difficult to think about complex tasks. Functional programs use Functions to complete all of their work. This is not strictly possible in <application>SuperCollider</application>: it is more imperative than functional, but the creative use of Functions can easily solve some problems that are difficult to write with an imperative approach.
</para>
<para>
The following example is an extension of the "Imperative" example. Pretend that the following Functions exist, and do the following tasks:
@@ -483,14 +485,14 @@
<listitem><para>getinput : allows the user to enter a number, and returns that number</para></listitem>
<listitem><para>add : adds together the numbers given as arguments, returning the sum</para></listitem>
</itemizedlist>
- [pre]
- (
- postln( add( getinput, getinput ) );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ postln( add( getinput, getinput ) );
+)
+]]></programlisting>
</para>
<para>
- SuperCollider will always execute the inner-most Functions first. This is how the interpreter executes the single-line program above:
+ <application>SuperCollider</application> will always execute the inner-most Functions first. This is how the interpreter executes the single-line program above:
<orderedlist>
<listitem><para>Execute the left call of <code>getinput</code></para></listitem>
<listitem><para>Execute the right call of <code>getinput</code></para></listitem>
@@ -499,36 +501,36 @@
</orderedlist>
</para>
<para>
- Both imperative and functional programming have advantages and disadvantages. SuperCollider will allow you to use either approach, or a mix of both, when solving problems.
+ Both imperative and functional programming have advantages and disadvantages. <application>SuperCollider</application> will allow you to use either approach, or a mix of both, when solving problems.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Object_Oriented-Object-Oriented_Programming">
<title>Object-Oriented Programming</title>
<para>
- Object-oriented programming is more difficult to think about than imperative or functional. When using this paradigm (mode of thought), almost everything in SuperCollider is thought of as an abstract Object. In this way, it allows programmers to make compelling comparisons to the real world, where all tangible things are objects, and where it is not hard to conceive of most intangible things as objects, too. With object-oriented programming, computer science takes a break from mathematics, and is influenced by philosophy.
+ Object-oriented programming is more difficult to think about than imperative or functional. When using this paradigm (mode of thought), almost everything in <application>SuperCollider</application> is thought of as an abstract Object. In this way, it allows programmers to make compelling comparisons to the real world, where all tangible things are objects, and where it is not hard to conceive of most intangible things as objects, too. With object-oriented programming, computer science takes a break from mathematics, and is influenced by philosophy.
</para>
<para>
Class names always begin with an uppercase letter.
</para>
<para>
- Anything can be represented as an Object - like a bicycle, for instance. Let's pretend that we have an Object called a Bicycle. We don't yet have a particular bicycle - just the abstract '''class''' containing everything that is true about all bicycles. If a Bicycle class exists in SuperCollider, you generate a specific instance like this: <code>var bike = Bicycle.new;</code> All SuperCollider Objects can be '''instantiated''' in this way: you get a specific Bicycle from the generic class, and you can then modify and work with your own Object as you choose. The specific properties associated with a particular instance of a class are called '''instance variables'''.
+ Anything can be represented as an Object - like a bicycle, for instance. Let's pretend that we have an Object called a Bicycle. We don't yet have a particular bicycle - just the abstract '''class''' containing everything that is true about all bicycles. If a Bicycle class exists in <application>SuperCollider</application>, you generate a specific instance like this: <code>var bike = Bicycle.new;</code> All <application>SuperCollider</application> Objects can be '''instantiated''' in this way: you get a specific Bicycle from the generic class, and you can then modify and work with your own Object as you choose. The specific properties associated with a particular instance of a class are called '''instance variables'''.
</para>
<para>
- There are certain things that Bicycles are designed to do: turn the wheels, turn the handlebar, raise and lower the seat, and so on. You can cause these things to happen by providing a certain input to a real-world Bicycle: if you want to turn the wheels, you might push the pedals. In SuperCollider, you cause things to happen by '''sending a message''' to the Object that tells it what you want: if you have a Bicycle, you might turn the wheels like this: <code>bike.turnTheWheels;</code> When you do this, you are actually executing the <code>turnTheWheels</code> Function, which is defined by the abstract Bicycle class. Because it doesn't make sense to turn the wheels of all bicycles in existence, you don't call the '''method''' (a synonym for "Function") from the Bicycle class itself, but from the particular instance whose wheels you want to turn. The proper way to access instance variables is by using instance methods.
+ There are certain things that Bicycles are designed to do: turn the wheels, turn the handlebar, raise and lower the seat, and so on. You can cause these things to happen by providing a certain input to a real-world Bicycle: if you want to turn the wheels, you might push the pedals. In <application>SuperCollider</application>, you cause things to happen by '''sending a message''' to the Object that tells it what you want: if you have a Bicycle, you might turn the wheels like this: <code>bike.turnTheWheels;</code> When you do this, you are actually executing the <code>turnTheWheels</code> Function, which is defined by the abstract Bicycle class. Because it doesn't make sense to turn the wheels of all bicycles in existence, you don't call the '''method''' (a synonym for "Function") from the Bicycle class itself, but from the particular instance whose wheels you want to turn. The proper way to access instance variables is by using instance methods.
</para>
<para>
- If this kind of programming is new to you, it might seem extremely difficult. It can be intimidating at first, but it is actually not too difficult to understand once you start to use it. In fact, you have already been using it! Remember the <code>postln</code> command that was described earlier as a special kind of Function? It's actually a Function defined by SuperCollider's abstract class <code>Object</code>, which defines a set of messages that can be passed to ''any'' SuperCollider Object. Because most things in SuperCollider are Objects, we can send them the <code>postln</code> message, and they will understand that it means to print themselves in the "SuperCollider output" pane.
+ If this kind of programming is new to you, it might seem extremely difficult. It can be intimidating at first, but it is actually not too difficult to understand once you start to use it. In fact, you have already been using it! Remember the <code>postln</code> command that was described earlier as a special kind of Function? It's actually a Function defined by <application>SuperCollider</application>'s abstract class <code>Object</code>, which defines a set of messages that can be passed to ''any'' <application>SuperCollider</application> Object. Because most things in <application>SuperCollider</application> are Objects, we can send them the <code>postln</code> message, and they will understand that it means to print themselves in the "<application>SuperCollider</application> output" pane.
</para>
<para>
<!-- Begin Confusing??? (TODO) -->
- Why is it that all Objects respond to the <code>postln</code> message? SuperCollider classes are allowed to belong to other SuperCollider classes, of which they are a part. Consider the Bicycle class again. It is a kind of vehicle, and philosophers might say that "things that are members of the bicycle class are also members of the vehicle class." That is, real-world bicycles share certain characteristics with other real-world objects that are classified as "vehicles." The bicycle class is a "sub-class" of the vehicle class, and it '''inherits''' certain properties from the vehicles class. SuperCollider allows this behaviour too, and calls it '''inheritance'''. In SuperCollider, since all classes define Objects, they are all automatically considered to be a sub-class of the class called <code>Object</code>. All classes therefore inherit certain characteristics from the <code>Object</code> class, like knowing how to respond to the <code>postln</code> message.
+ Why is it that all Objects respond to the <code>postln</code> message? <application>SuperCollider</application> classes are allowed to belong to other <application>SuperCollider</application> classes, of which they are a part. Consider the Bicycle class again. It is a kind of vehicle, and philosophers might say that "things that are members of the bicycle class are also members of the vehicle class." That is, real-world bicycles share certain characteristics with other real-world objects that are classified as "vehicles." The bicycle class is a "sub-class" of the vehicle class, and it '''inherits''' certain properties from the vehicles class. <application>SuperCollider</application> allows this behaviour too, and calls it '''inheritance'''. In <application>SuperCollider</application>, since all classes define Objects, they are all automatically considered to be a sub-class of the class called <code>Object</code>. All classes therefore inherit certain characterist
ics from the <code>Object</code> class, like knowing how to respond to the <code>postln</code> message.
<!-- End Confusing??? -->
</para>
<para>
equivalent notation: <literal>5.postln</literal> versus <literal>postln( 5 )</literal>
</para>
<para>
- You still don't know how to write new Classes and Objects in SuperCollider, but knowing how to use them is more than enough for now. By the time you need to write your own Classes, you will probably prefer to use the official SuperCollider help files, anyway.
+ You still don't know how to write new Classes and Objects in <application>SuperCollider</application>, but knowing how to use them is more than enough for now. By the time you need to write your own Classes, you will probably prefer to use the official <application>SuperCollider</application> help files, anyway.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Object_Oriented-Choosing_a_Paradigm">
@@ -537,7 +539,7 @@
At this point you may begin worrying about which programming paradigm you should choose, and when. The answer is unhelpful: "Whichever seems best for the task."
</para>
<para>
- Let's expand on this. If you are primarily a programmer, then you probably already know how to choose the best paradigm and algorithm for the task. If you are a musician, then you probably just want your program to produce the output that you want (in this case, a particular set of sounds). Part of the beauty of SuperCollider's flexibility is that it allows you to produce the same output in different ways. As a musician this means that, as long as your program works as you want it to work, it doesn't matter how you write it. Experience will teach you more and less effective ways of doing things, but there is no need for rules.
+ Let's expand on this. If you are primarily a programmer, then you probably already know how to choose the best paradigm and algorithm for the task. If you are a musician, then you probably just want your program to produce the output that you want (in this case, a particular set of sounds). Part of the beauty of <application>SuperCollider</application>'s flexibility is that it allows you to produce the same output in different ways. As a musician this means that, as long as your program works as you want it to work, it doesn't matter how you write it. Experience will teach you more and less effective ways of doing things, but there is no need for rules.
</para>
<para>
Even so, here are some guidelines that will help you to start thinking about music programs:
@@ -556,7 +558,7 @@
</itemizedlist>
</para>
</section>
- </section> <!-- Ends "Object-Oriented SuperCollider" Section --> <!-- SC-Basic_Programming-Object_Oriented- -->
+ </section> <!-- Ends "Object-Oriented <application>SuperCollider</application>" Section --> <!-- SC-Basic_Programming-Object_Oriented- -->
<section id="sect-Musicians_Guide-SC-Basic_Programming-Sound_Making_Functions">
<title>Sound-Making Functions</title>
@@ -564,8 +566,8 @@
It's finally time to start thinking about Functions that produce sound!
</para>
<para>
- This example is discussed below in the following sections. Remember, when running SuperCollider code in GEdit, you can stop the sound by pressing 'Esc' on your keyboard.
- [pre]{ SinOsc.ar( 440, 0, 0.2 ); }.play;[/pre]
+ This example is discussed below in the following sections. Remember, when running <application>SuperCollider</application> code in <application>GEdit</application>, you can stop the sound by pressing <keycombo><keycap>Esc</keycap></keycombo>
+ <programlisting><![CDATA[{ SinOsc.ar( 440, 0, 0.2 ); }.play;]]></programlisting>
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Sound_Making_Functions-UGens">
<title>UGens</title>
@@ -579,10 +581,10 @@
The example at the beginning of this chapter, <code>SinOsc.ar( 440, 0, 0.2 );</code> produces an "instance" of the <code>SinOsc</code> Class, which continuously outputs a signal, based on the parameters given in parentheses. This instance produces an "audio rate" signal, which means that it is of sufficient quality to eventually become sound.
</para>
<para>
- A slightly modified version of that code will give us a "control rate" signal: <code>SinOsc.kr( 440, 0, 0.2 );</code> There is only one small difference between the two examples - for us - but for SuperCollider, the difference is huge. A control rate signal will not be of sufficient quality to become sound; it is used to control other UGens that do become sound.
+ A slightly modified version of that code will give us a "control rate" signal: <code>SinOsc.kr( 440, 0, 0.2 );</code> There is only one small difference between the two examples - for us - but for <application>SuperCollider</application>, the difference is huge. A control rate signal will not be of sufficient quality to become sound; it is used to control other UGens that do become sound.
</para>
<para>
- Unlike other Classes, UGen Classes should not be instantiated with the <code>new</code> message. They should always be instantiated as either audio-rate (by passing the <code>ar</code> message), or control-rate (by passing the <code>kr</code> message). Control-rate signals are calculated much less often than audio-rate signals, which allows the SuperCollider interpreter and server to save processing power where it wouldn't be noticed.
+ Unlike other Classes, UGen Classes should not be instantiated with the <code>new</code> message. They should always be instantiated as either audio-rate (by passing the <code>ar</code> message), or control-rate (by passing the <code>kr</code> message). Control-rate signals are calculated much less often than audio-rate signals, which allows the <application>SuperCollider</application> interpreter and server to save processing power where it wouldn't be noticed.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Sound_Making_Functions-The_play_Function">
@@ -592,8 +594,8 @@
</para>
<para>
The following two examples produce the same output:
- [pre]{ SinOsc.ar( 440, 0, 0.2 ); }.play;[/pre]
- [pre]play( { SinOsc.ar( 440, 0, 0.2 ); } );[/pre]
+ <programlisting><![CDATA[{ SinOsc.ar( 440, 0, 0.2 ); }.play;]]></programlisting>
+ <programlisting><![CDATA[play( { SinOsc.ar( 440, 0, 0.2 ); } );]]></programlisting>
The first example is written from an object-oriented perspective. Functions know how to play their return value, when passed the <code>play</code> message. This is true of all Functions whose return value is an audio-rate UGen. The second example is written from a functional perspective. The Function called <code>play</code> will play its input, which must be a Function whose return value is an audio-rate UGen. Whether you should write <code>play</code> in the functional or object-oriented way depends on which makes more sense to you.
</para>
<para>
@@ -619,14 +621,14 @@
</para>
<para>
You now know enough to spend hours with the sine oscillator UGen. Try combining audio- and control-rate UGens, and try to figure out what happens when each of the arguments is adjusted. Be careful that your audio interface's volume isn't set too high! Experiment with this one:
- [pre]
- (
- var myFrequency = SinOsc.kr( freq:1, mul:200, add:400 );
- var sound = { SinOsc.ar( myFrequency, 0, 0.2 ); };
-
- play( sound );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myFrequency = SinOsc.kr( freq:1, mul:200, add:400 );
+ var sound = { SinOsc.ar( myFrequency, 0, 0.2 ); };
+
+ play( sound );
+)
+]]></programlisting>
<!-- WHY DOESN'T THAT WORK?!?!?!?!?!? (TODO) -->
</para>
</section>
@@ -640,77 +642,81 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Multichannel_Audio-Stereo_Array">
<title>Stereo Array</title>
<para>
- The easiest way to output multichannel audio in SuperCollider is to use a kind of "Collection" (defined later) called an "Array." SuperCollider will theoretically handle any number of audio output channels, but by default is usually only configured for two-channel stereo audio. Since humans have only two ears, this is sufficient for most tasks! A multichannel array is notated like this: <code>[ LeftChannel.ar( x ), RightChannel.ar( y ) ]</code>
+ The easiest way to output multichannel audio in <application>SuperCollider</application> is to use a kind of "Collection" (defined later) called an "Array." <application>SuperCollider</application> will theoretically handle any number of audio output channels, but by default is usually only configured for two-channel stereo audio. Since humans have only two ears, this is sufficient for most tasks! A multichannel array is notated like this: <code>[ LeftChannel.ar( x ), RightChannel.ar( y ) ]</code>
</para>
<para>
Here is our simple sine oscillator expanded to produce stereo audio:
- [pre]{ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 440, 0, 0.2 ) ]; }.play;[/pre]
+ <programlisting><![CDATA[{ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 440, 0, 0.2 ) ]; }.play;]]></programlisting>
Not much has changed, except that the audio we hear is now being emitted from both the left and right channels. Change the frequency of one of the sine oscillators to <code>450</code> and the difference will become much more apparent.
</para>
<para>
Multichannel arrays can also be combined with each other, like this:
- [pre]
- {
- var one = [ x, y, z ];
- var two = [ a, b, c ];
- [ one, two ];
- }
- [/pre]
+<programlisting><![CDATA[
+{
+ var one = [ x, y, z ];
+ var two = [ a, b, c ];
+ [ one, two ];
+}
+]]></programlisting>
If <code>a</code>, <code>b</code>, <code>c</code>, <code>x</code>, <code>y</code>, and <code>z</code> were all audio-rate UGens, this Function could be <code>play</code>'ed. It would produce stereo audio, and each channel would have three independent UGens.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Multichannel_Audio-Multichannel_Expansion">
<title>Multichannel Expansion</title>
<para>
- You can automatically create multiple UGens by providing an Array as one of the parameters. The SuperCollider interpreter will automatically create multichannel UGens as a result.
+ You can automatically create multiple UGens by providing an Array as one of the parameters. The <application>SuperCollider</application> interpreter will automatically create multichannel UGens as a result.
</para>
<para>
The following two examples produce equivalent output:
- [pre]{ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 440, 0, 0.2 ) ]; }.play;[/pre]
- [pre]{ SinOsc.ar( [440, 440], 0, 0.2 ); }.play;[/pre]
+ <programlisting><![CDATA[{ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 440, 0, 0.2 ) ]; }.play;]]></programlisting>
+ <programlisting><![CDATA[{ SinOsc.ar( [440, 440], 0, 0.2 ); }.play;]]></programlisting>
The second example can be easier to read, because it is obvious that only the frequency is changing - or in this case, that nothing is changing. This technique is more useful in a situation like the following:
- [pre]{ SinOsc.ar( [[440, 445, 450, 455, 460, 465],
- [440, 445, 450, 455, 460, 465]],
- 0,
- 0.2 ); }.play;[/pre]
+<programlisting><![CDATA[
+{ SinOsc.ar( [[440, 445, 450, 455, 460, 465],
+ [440, 445, 450, 455, 460, 465]],
+ 0,
+ 0.2 ); }.play;
+]]></programlisting>
That's not exactly easy to read, but it's easier to figure out than the most obvious alternative:
- [pre]{
- [[ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 445, 0, 0.2 ), SinOsc.ar( 450, 0, 0.2 ), SinOsc.ar( 455, 0, 0.2 ), SinOsc.ar( 460, 0, 0.2 ), SinOsc.ar( 465, 0, 0.2 ) ],
- [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 445, 0, 0.2 ), SinOsc.ar( 450, 0, 0.2 ), SinOsc.ar( 455, 0, 0.2 ), SinOsc.ar( 460, 0, 0.2 ), SinOsc.ar( 465, 0, 0.2 ) ]];
- }.play;[/pre]
+<programlisting><![CDATA[
+{
+ [[ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 445, 0, 0.2 ), SinOsc.ar( 450, 0, 0.2 ), SinOsc.ar( 455, 0, 0.2 ), SinOsc.ar( 460, 0, 0.2 ), SinOsc.ar( 465, 0, 0.2 ) ],
+ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 445, 0, 0.2 ), SinOsc.ar( 450, 0, 0.2 ), SinOsc.ar( 455, 0, 0.2 ), SinOsc.ar( 460, 0, 0.2 ), SinOsc.ar( 465, 0, 0.2 ) ]];
+}.play;
+]]></programlisting>
More importantly, multichannel expansion gives us another tool to avoid repetition. Repetition is the enemy of correctness - it's so much more difficult to find a mistake in the second example than in the first!
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Multichannel_Audio-Method_One">
<title>Method One</title>
<para>
- Believe it or not, you now know enough to understand a slightly-modified version of the first part of "Method One," a SuperCollider program written and heavily commented specifically for use with this Guide. You should <code>play</code> this example, and experiment with changing the frequencies, volumes, and so on. The fully-commented version provides a full explanation of how the Function works.
- [pre]
- {
- // sets up the frequencies of both channels
- var frequencyL = SinOsc.kr( freq:10, mul:200, add:400 ); // oscillating
- var frequencyR = SinOsc.kr( freq:1, mul:50, add:150 ); // oscillating
- var frequencyL_drone = SinOsc.kr( freq:0.03, mul:20, add:100 ); // drone
- var frequencyR_drone = SinOsc.kr( freq:0.01, mul:20, add:210 ); // drone
-
- // changes the volume of the oscillating part in the left channel
- var volumeL = SinOsc.kr( freq:0.5, mul:0.02, add:0.03 );
-
- // left channel
- var left = [ SinOsc.ar( freq:frequencyL, mul:volumeL ), // this is the oscillating part
- SinOsc.ar( freq:[frequencyL_drone,2*frequencyL_drone], mul:0.02 ), // the rest make up the drone
- SinOsc.ar( freq:[5*frequencyL_drone,7*frequencyL_drone], mul:0.005 ),
- SinOsc.ar( freq:[13*frequencyL_drone,28*frequencyL_drone], mul:0.001 ) ];
-
- // right channel
- var right = [ SinOsc.ar( freq:frequencyR, mul:0.1 ), // this is the oscillating part
- SinOsc.ar( freq:[frequencyR_drone,2*frequencyR_drone], mul:0.02 ), // the rest make up the drone
- SinOsc.ar( freq:4*frequencyR_drone, mul:0.005 ),
- SinOsc.ar( freq:[64*frequencyR_drone,128*frequencyR_drone], mul:0.01 ) ]; // high frequencies!
-
- [ left, right ];
- }
- [/pre]
+ Believe it or not, you now know enough to understand a slightly-modified version of the first part of "Method One," a <application>SuperCollider</application> program written and heavily commented specifically for use with this Guide. You should <code>play</code> this example, and experiment with changing the frequencies, volumes, and so on. The fully-commented version provides a full explanation of how the Function works.
+<programlisting><![CDATA[
+{
+ // sets up the frequencies of both channels
+ var frequencyL = SinOsc.kr( freq:10, mul:200, add:400 ); // oscillating
+ var frequencyR = SinOsc.kr( freq:1, mul:50, add:150 ); // oscillating
+ var frequencyL_drone = SinOsc.kr( freq:0.03, mul:20, add:100 ); // drone
+ var frequencyR_drone = SinOsc.kr( freq:0.01, mul:20, add:210 ); // drone
+
+ // changes the volume of the oscillating part in the left channel
+ var volumeL = SinOsc.kr( freq:0.5, mul:0.02, add:0.03 );
+
+ // left channel
+ var left = [ SinOsc.ar( freq:frequencyL, mul:volumeL ), // this is the oscillating part
+ SinOsc.ar( freq:[frequencyL_drone,2*frequencyL_drone], mul:0.02 ), // the rest make up the drone
+ SinOsc.ar( freq:[5*frequencyL_drone,7*frequencyL_drone], mul:0.005 ),
+ SinOsc.ar( freq:[13*frequencyL_drone,28*frequencyL_drone], mul:0.001 ) ];
+
+ // right channel
+ var right = [ SinOsc.ar( freq:frequencyR, mul:0.1 ), // this is the oscillating part
+ SinOsc.ar( freq:[frequencyR_drone,2*frequencyR_drone], mul:0.02 ), // the rest make up the drone
+ SinOsc.ar( freq:4*frequencyR_drone, mul:0.005 ),
+ SinOsc.ar( freq:[64*frequencyR_drone,128*frequencyR_drone], mul:0.01 ) ]; // high frequencies!
+
+ [ left, right ];
+}
+]]></programlisting>
</para>
</section>
</section> <!-- Ends "Multichannel Audio" Section --> <!-- SC-Basic_Programming-Multichannel_Audio- -->
@@ -718,7 +724,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections">
<title>Collections</title>
<para>
- A "collection" is just that - a collection of Objects. Collections are simply a means of organizing a large amount of data, without having to assign a variable name for each portion of data. Compared to other programming languages, SuperCollider provides a relatively large number of Collections in the standard library.
+ A "collection" is just that - a collection of Objects. Collections are simply a means of organizing a large amount of data, without having to assign a variable name for each portion of data. Compared to other programming languages, <application>SuperCollider</application> provides a relatively large number of Collections in the standard library.
</para>
<para>
We have already seen an example of a Collection as multichannel audio arrays. An Array is a kind of Collection - in object-oriented terminology, the Array Class is a '''sub-class''' of the Collection Class, and inherits its behaviours. Conversely, the Collection Class is the '''super-class''' of the Array Class. The Collection Class itself is not to be used; it is designed to provide common features so that it is easier to write Classes for collections.
@@ -729,7 +735,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-Array">
<title>Array</title>
<para>
- Arrays have been traditionally been very popular with programmers. In SuperCollider, they are capable of storing a large number of Objects, and they provide advanced behaviours that are normally not associated with Arrays. They are not as indespensible as they used to be. Most programming languages now provide (or can easily be extended to add) Lists, Trees, and other kinds of data storage structures, which offer more capabilities, and are easier to use and to think about. Users new to programming might find the various kinds of Lists to be more helpful.
+ Arrays have been traditionally been very popular with programmers. In <application>SuperCollider</application>, they are capable of storing a large number of Objects, and they provide advanced behaviours that are normally not associated with Arrays. They are not as indespensible as they used to be. Most programming languages now provide (or can easily be extended to add) Lists, Trees, and other kinds of data storage structures, which offer more capabilities, and are easier to use and to think about. Users new to programming might find the various kinds of Lists to be more helpful.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-Array-Building">
<title>Building an Array</title>
@@ -738,32 +744,32 @@
</para>
<para>
This example declares an Array, adds some elements, then prints them out.
- [pre]
- (
- var tA = Array.new( 2 ); // "tA" stands for "testArray"
-
- tA = tA.add( 5 );
- tA = tA.add( 3 );
- tA = tA.add( 17 );
-
- tA.postln;
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tA = Array.new( 2 ); // "tA" stands for "testArray"
+
+ tA = tA.add( 5 );
+ tA = tA.add( 3 );
+ tA = tA.add( 17 );
+
+ tA.postln;
+ nil;
+)
+]]></programlisting>
Notice that Array is a Class, and it must be instantiated before use. Here, the variable <code>tA</code> is assigned an Array with enough space for two objects. Notice that the elements are printed out in the order that you add them to the Array. They are not sorted or shuffled (unless you send a message like <code>scramble</code>). But why did I write <code>tA = tA.add( 17 );</code> instead of <code>tA.add( 17 );</code>? Shouldn't the second method be sufficient for adding an Object to an Array, thereby making the re-assignment unnecessary? It does, but let's see what happens when we take it away:
- [pre]
- (
- var tA = Array.new( 2 ); // "tA" stands for "testArray"
-
- tA.add( 5 );
- tA.add( 3 );
- tA.add( 17 );
-
- tA.postln;
- nil;
- )
- [/pre]
- The <code>17</code> is missing - it doesn't get added into the Array! This is because the Array was only declared with two slots, and you can't add three Objects into two slots. So why did this work the first time? SuperCollider was programmed to help us fit additional items into an Array. If an Array has reached its capacity, SuperCollider will automatically make a new, larger Array for us, and returns that from the <code>add</code> method. Therefore, any time you add an element to an Array, you should always re-assign the result, so that you don't have to worry about whether you exceeded the Array's capacity.
+<programlisting><![CDATA[
+(
+ var tA = Array.new( 2 ); // "tA" stands for "testArray"
+
+ tA.add( 5 );
+ tA.add( 3 );
+ tA.add( 17 );
+
+ tA.postln;
+ nil;
+)
+]]></programlisting>
+ The <code>17</code> is missing - it doesn't get added into the Array! This is because the Array was only declared with two slots, and you can't add three Objects into two slots. So why did this work the first time? <application>SuperCollider</application> was programmed to help us fit additional items into an Array. If an Array has reached its capacity, <application>SuperCollider</application> will automatically make a new, larger Array for us, and returns that from the <code>add</code> method. Therefore, any time you add an element to an Array, you should always re-assign the result, so that you don't have to worry about whether you exceeded the Array's capacity.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-Array-Accessing">
@@ -773,44 +779,44 @@
</para>
<para>
The following examples produce equivalent output. The first uses the object-oriented style, and the second uses the traditional style.
- [pre]
- (
- var tA = Array.new( 3 );
-
- tA = tA.add( 5 );
- tA = tA.add( 3 );
- tA = tA.add( 17 );
-
- tA.at( 0 ).postln; // outputs 5
- tA.at( 1 ).postln; // outputs 3
- tA.at( 2 ).postln; // outputs 17
-
- tA.put( 0, 24 ); // assigns 24 to element 0
-
- tA.at( 0 ).postln; // outputs 24
-
- nil;
- )
- [/pre]
- [pre]
- (
- var tA = Array.new( 3 );
-
- tA = tA.add( 5 );
- tA = tA.add( 3 );
- tA = tA.add( 17 );
-
- tA[0].postln; // outputs 5
- tA[1].postln; // outputs 3
- tA[2].postln; // outputs 17
-
- tA[0] = 24 ; // assigns 24 to element 0
-
- tA[0].postln; // outputs 24
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tA = Array.new( 3 );
+
+ tA = tA.add( 5 );
+ tA = tA.add( 3 );
+ tA = tA.add( 17 );
+
+ tA.at( 0 ).postln; // outputs 5
+ tA.at( 1 ).postln; // outputs 3
+ tA.at( 2 ).postln; // outputs 17
+
+ tA.put( 0, 24 ); // assigns 24 to element 0
+
+ tA.at( 0 ).postln; // outputs 24
+
+ nil;
+)
+]]></programlisting>
+<programlisting><![CDATA[
+(
+ var tA = Array.new( 3 );
+
+ tA = tA.add( 5 );
+ tA = tA.add( 3 );
+ tA = tA.add( 17 );
+
+ tA[0].postln; // outputs 5
+ tA[1].postln; // outputs 3
+ tA[2].postln; // outputs 17
+
+ tA[0] = 24 ; // assigns 24 to element 0
+
+ tA[0].postln; // outputs 24
+
+ nil;
+)
+]]></programlisting>
Different people prefer different styles of accessing Arrays.
</para>
</section>
@@ -818,7 +824,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-List">
<title>List</title>
<para>
- An List is a Collection with an infinite maximum size. It is the programmer's responsibility to maintain a meaningful order, and to remember the meaning of the data. Data in a List is called "elements," each of which is assigned a specific "index number." Index numbers begin at 0. Any mix of Objects can be stored in a List, including a List. Lists and Arrays are very similar, but SuperCollider manages some of the dirty work for you, when you use the List Class.
+ An List is a Collection with an infinite maximum size. It is the programmer's responsibility to maintain a meaningful order, and to remember the meaning of the data. Data in a List is called "elements," each of which is assigned a specific "index number." Index numbers begin at 0. Any mix of Objects can be stored in a List, including a List. Lists and Arrays are very similar, but <application>SuperCollider</application> manages some of the dirty work for you, when you use the List Class.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-List-Building">
<title>Building a List</title>
@@ -871,161 +877,161 @@
The following examples show different ways to use List's.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL.add( 42 );
- tL.add( 820 );
-
- postln( tL.pop ); // outputs 820
-
- tL.add( 7 );
- tL.add( 19 );
- tL.add( 23 );
-
- postln( tL.pop ); // outputs 23
- postln( tL.pop ); // outputs 19
- postln( tL.pop ); // outputs 7
- postln( tL.pop ); // outputs 42
-
- postln( tL.pop ); // List is empty, so we get "nil"
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL.add( 42 );
+ tL.add( 820 );
+
+ postln( tL.pop ); // outputs 820
+
+ tL.add( 7 );
+ tL.add( 19 );
+ tL.add( 23 );
+
+ postln( tL.pop ); // outputs 23
+ postln( tL.pop ); // outputs 19
+ postln( tL.pop ); // outputs 7
+ postln( tL.pop ); // outputs 42
+
+ postln( tL.pop ); // List is empty, so we get "nil"
+
+ nil;
+)
+]]></programlisting>
This code adds numbers to the end of a List, then removes them from the end of the List.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL.addFirst( 42 );
- tL.addFirst( 820 );
-
- postln( tL.pop ); // outputs 42
-
- tL.addFirst( 7 );
- tL.addFirst ( 19 );
- tL.addFirst ( 23 );
-
- postln( tL.pop ); // outputs 820
- postln( tL.pop ); // outputs 7
- postln( tL.pop ); // outputs 19
- postln( tL.pop ); // outputs 23
-
- postln( tL.pop ); // list is empty, so we get "nil"
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL.addFirst( 42 );
+ tL.addFirst( 820 );
+
+ postln( tL.pop ); // outputs 42
+
+ tL.addFirst( 7 );
+ tL.addFirst ( 19 );
+ tL.addFirst ( 23 );
+
+ postln( tL.pop ); // outputs 820
+ postln( tL.pop ); // outputs 7
+ postln( tL.pop ); // outputs 19
+ postln( tL.pop ); // outputs 23
+
+ postln( tL.pop ); // list is empty, so we get "nil"
+
+ nil;
+)
+]]></programlisting>
This modification of the first example adds numbers to the beginning of a List, then removes them from the end of the List. This is one way to ensure that the List elements are removed in the same order that they are added.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL.add( 42 );
- tL.add( 820 );
-
- postln( tL.removeAt( 0 ) ); // outputs 42
-
- tL.add( 7 );
- tL.add( 19 );
- tL.add( 23 );
-
- postln( tL.removeAt( 0 ) ); // outputs 820
- postln( tL.removeAt( 0 ) ); // outputs 7
- postln( tL.removeAt( 0 ) ); // outputs 19
- postln( tL.removeAt( 0 ) ); // outputs 23
-
- // postln( tL.removeAt( 0 ) ); // would cause an error
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL.add( 42 );
+ tL.add( 820 );
+
+ postln( tL.removeAt( 0 ) ); // outputs 42
+
+ tL.add( 7 );
+ tL.add( 19 );
+ tL.add( 23 );
+
+ postln( tL.removeAt( 0 ) ); // outputs 820
+ postln( tL.removeAt( 0 ) ); // outputs 7
+ postln( tL.removeAt( 0 ) ); // outputs 19
+ postln( tL.removeAt( 0 ) ); // outputs 23
+
+// postln( tL.removeAt( 0 ) ); // causes an error!
+
+ nil;
+)
+]]></programlisting>
This modification of the first example adds numbers to the end of a List, then removes from the beginning of the List. This is another way to ensure that the List elements are removed in the same order that they're added. Note that, when the List is empty, using the "removeAt()" Function causes an error, because you try to access a List index which doesn't exist.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL = [42,820,7,19,23];
-
- tL.at( 0 ).postln; // outputs 42
- tL.at( 1 ).postln; // outputs 820
- tL.at( 2 ).postln; // outputs 7
- tL.at( 3 ).postln; // outputs 19
- tL.at( 4 ).postln; // outputs 23
- tL.at( 5 ).postln; // outputs nil
- tL.at( 6 ).postln; // outputs nil
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL = [42,820,7,19,23];
+
+ tL.at( 0 ).postln; // outputs 42
+ tL.at( 1 ).postln; // outputs 820
+ tL.at( 2 ).postln; // outputs 7
+ tL.at( 3 ).postln; // outputs 19
+ tL.at( 4 ).postln; // outputs 23
+ tL.at( 5 ).postln; // outputs nil
+ tL.at( 6 ).postln; // outputs nil
+
+ nil;
+)
+]]></programlisting>
This example shows another way to add elements to an empty List, which also works for Arrays. Then it shows what happens when you try to access elements beyond the end of a List with the "at()"Function.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL = [42,820,7,19,23];
-
- tL.clipAt( 0 ).postln; // outputs 42
- tL.clipAt( 1 ).postln; // outputs 820
- tL.clipAt( 2 ).postln; // outputs 7
- tL.clipAt( 3 ).postln; // outputs 19
- tL.clipAt( 4 ).postln; // outputs 23
- tL.clipAt( 5 ).postln; // outputs 23
- tL.clipAt( 6 ).postln; // outputs 23
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL = [42,820,7,19,23];
+
+ tL.clipAt( 0 ).postln; // outputs 42
+ tL.clipAt( 1 ).postln; // outputs 820
+ tL.clipAt( 2 ).postln; // outputs 7
+ tL.clipAt( 3 ).postln; // outputs 19
+ tL.clipAt( 4 ).postln; // outputs 23
+ tL.clipAt( 5 ).postln; // outputs 23
+ tL.clipAt( 6 ).postln; // outputs 23
+
+ nil;
+)
+]]></programlisting>
This example shows what happens when you try to access elements beyond the end of a List with the "clipAt()" Function. For index numbers beyond the end of the List, the interpreter will simply return the last element.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL = [42,820,7,19,23];
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL = [42,820,7,19,23];
- tL.foldAt( 0 ).postln; // outputs 42
- tL.foldAt( 1 ).postln; // outputs 820
- tL.foldAt( 2 ).postln; // outputs 7
- tL.foldAt( 3 ).postln; // outputs 19
- tL.foldAt( 4 ).postln; // outputs 23
- tL.foldAt( 5 ).postln; // outputs 19
- tL.foldAt( 6 ).postln; // outputs 7
-
- nil;
- )
- [/pre]
+ tL.foldAt( 0 ).postln; // outputs 42
+ tL.foldAt( 1 ).postln; // outputs 820
+ tL.foldAt( 2 ).postln; // outputs 7
+ tL.foldAt( 3 ).postln; // outputs 19
+ tL.foldAt( 4 ).postln; // outputs 23
+ tL.foldAt( 5 ).postln; // outputs 19
+ tL.foldAt( 6 ).postln; // outputs 7
+
+ nil;
+)
+]]></programlisting>
This example shows what happens when you try to aceess elements beyond the end of a List with the "foldAt()" Function. For index numbers beyond the end of the List, the interpreter will start moving back through the List, towards the first element, "folding" through the List.
</para>
<para>
- [pre]
- (
- var tL = List.new;
-
- tL = [42,820,7,19,23];
-
- tL.wrapAt( 0 ).postln; // outputs 42
- tL.wrapAt( 1 ).postln; // outputs 820
- tL.wrapAt( 2 ).postln; // outputs 7
- tL.wrapAt( 3 ).postln; // outputs 19
- tL.wrapAt( 4 ).postln; // outputs 23
- tL.wrapAt( 5 ).postln; // outputs 42
- tL.wrapAt( 6 ).postln; // outputs 820
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+
+ tL = [42,820,7,19,23];
+
+ tL.wrapAt( 0 ).postln; // outputs 42
+ tL.wrapAt( 1 ).postln; // outputs 820
+ tL.wrapAt( 2 ).postln; // outputs 7
+ tL.wrapAt( 3 ).postln; // outputs 19
+ tL.wrapAt( 4 ).postln; // outputs 23
+ tL.wrapAt( 5 ).postln; // outputs 42
+ tL.wrapAt( 6 ).postln; // outputs 820
+
+ nil;
+)
+]]></programlisting>
This example shows what happens when you try to access elements beyond the end of a List with the "wrapAt()" Function. For index numbers beyond the end of the List, the interpreter will start again at the beginning of the List, "wrapping" around to the beginning.
</para>
</section>
@@ -1033,10 +1039,10 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-LinkedList">
<title>LinkedList</title>
<para>
- Linked lists are very common structures for data management in computer science. They are more efficient than arrays for many tasks, particularly when it's impossible to know how many elements will be required in an array until the program is run. SuperCollider's List Class is implemented with arrays, and it offers nearly the same functionality as the LinkedList class.
+ Linked lists are very common structures for data management in computer science. They are more efficient than arrays for many tasks, particularly when it's impossible to know how many elements will be required in an array until the program is run. <application>SuperCollider</application>'s List Class is implemented with arrays, and it offers nearly the same functionality as the LinkedList class.
</para>
<para>
- A true linked list is accessed most efficiently from the start (called the "head" of the list) or the end (called the "tail"). Each element is linked to the one before it, the one after it, or both. SuperCollider's LinkedList Class has elements which are linked both to the preceding and following elements, so it is called a "doubly linked list."
+ A true linked list is accessed most efficiently from the start (called the "head" of the list) or the end (called the "tail"). Each element is linked to the one before it, the one after it, or both. <application>SuperCollider</application>'s LinkedList Class has elements which are linked both to the preceding and following elements, so it is called a "doubly linked list."
</para>
<para>
Knowing when to use a LinkedList over a List is a question of efficiency, and for small collections of information, it isn't going to make a big difference - you might as well use a basic List. When you plan to store hundreds or thousands of elements, choosing the right Class becomes more important, and can save a lot of processor time. Here is how to know which Class you should use:
@@ -1076,34 +1082,34 @@
<title>Example</title>
<para>
This example uses a LinkedList as a queue, adding numbers to the tail, and removing and printing from the head.
- [pre]
- (
- var tL = LinkedList.new;
-
- tL.add( 42 );
- tL.add( 89 );
-
- tL.popFirst.postln; // prints 42
-
- tL.add( 256 );
-
- tL.popFirst.postln; // prints 89
-
- tL.add( 900 );
-
- tL.popFirst.postln; // prints 256
- tL.popFirst.postln; // prints 900
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = LinkedList.new;
+
+ tL.add( 42 );
+ tL.add( 89 );
+
+ tL.popFirst.postln; // prints 42
+
+ tL.add( 256 );
+
+ tL.popFirst.postln; // prints 89
+
+ tL.add( 900 );
+
+ tL.popFirst.postln; // prints 256
+ tL.popFirst.postln; // prints 900
+
+ nil;
+)
+]]></programlisting>
</para>
</section>
</section> <!-- Ends "LinkedList" Section -->
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-Other_Collections">
<title>Other Collections</title>
<para>
- As mentioned previously, the SuperCollider language provides for many more kinds of data structures. The following Collections are useful, but much more complex than those listed above. For usage instructions, refer to the SuperCollider documentation.
+ As mentioned previously, the <application>SuperCollider</application> language provides for many more kinds of data structures. The following Collections are useful, but much more complex than those listed above. For usage instructions, refer to the <application>SuperCollider</application> documentation.
<itemizedlist>
<listitem><para>Dictionary: stores and allows retrieval of data by arbitrary Objects (for example, by symbols, rather than by index numbers).</para></listitem>
<listitem><para>Library: a type of Dictionary. Objects inserted can be used by any Object in the program, like books in a real-world library can be used by anybody who walks in.</para></listitem>
@@ -1117,27 +1123,43 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating">
<title>Repeated Execution</title>
<para>
- Repeating boring tasks is one of the main uses of computers, which don't mind doing the same thing over and over again. More importantly, writing code once and using it many times is much more intelligent than writing the same code many times. Repetition of the same code is often problematic, and repetition with subtle differences is even worse. Errors in this kind of code are difficult to find in the first place, and more difficult to solve effectively. Thankfully, as with most other things, SuperCollider offers a wide variety of ways to repeat code without re-writing it.
+ Repeating boring tasks is one of the main uses of computers, which don't mind doing the same thing over and over again. More importantly, writing code once and using it many times is much more intelligent than writing the same code many times. Repetition of the same code is often problematic, and repetition with subtle differences is even worse. Errors in this kind of code are difficult to find in the first place, and more difficult to solve effectively. Thankfully, as with most other things, <application>SuperCollider</application> offers a wide variety of ways to repeat code without re-writing it.
</para>
<para>
- The code structure used to create repetition is normally called a '''loop'''. "Do" loops are SuperCollider's most versatile and useful repetition structure, and there are a few different ways to think about and write it. The "while" loop is a standard of most programming languages.
+ The code structure used to create repetition is normally called a '''loop'''. "Do" loops are <application>SuperCollider</application>'s most versatile and useful repetition structure, and there are a few different ways to think about and write it. The "while" loop is a standard of most programming languages.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-Simple_Do">
<title>"Do This to Everything in This Collection"</title>
<para>
- One way to write a "do" loop is basically the same as telling the interpreter to "do this Function to every element in this Collection." The syntax looks like this,
- [pre]do( aCollection, aFunction );[/pre]
- or this,
- [pre]aCollection.do( aFunction );[/pre]
- This causes <code>aFunction</code> to be executed once for each element in <code>aCollection</code>, which can be any kind of Collection. Each time <code>aFunction</code> is run, it is given two arguments, in this order: an element of <code>aCollection</code>, and the elements index number. For Collection's that don't have index numbers, it returns what the element's index number would have been. The loop always begins at the start of the Collection, and progresses with each element in order to the end. The second argument, really, is the integers from zero to one less than the number of elements in the Collection, increasing by one each time the loop executes <code>aFunction</code>.
+ One way to write a "do" loop is basically the same as telling the interpreter to "do this Function to every element in this Collection." The syntax looks like this:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>do</function></funcdef>
+ <paramdef><parameter>aCollection</parameter></paramdef>
+ <paramdef>aFunction<funcparams>number, number</funcparams></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ ... or like this:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function><replaceable>aCollection</replaceable>.do</function></funcdef>
+ <paramdef>aFunction<funcparams>number, number</funcparams></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ This causes <function>aFunction</function> to be executed once for each element in <replaceable>aCollection</replaceable>, which can be any kind of Collection. Each time <function>aFunction</function> is run, it is given two arguments, in this order: an element of <replaceable>aCollection</replaceable>, and the elements index number. For Collection's that don't have index numbers, it returns what the element's index number would have been. The loop always begins at the start of the Collection, and progresses with each element in order to the end. The second argument, really, is the integers from zero to one less than the number of elements in the Collection, increasing by one each time the loop executes <function>aFunction</function>.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-Number_Do">
<title>"Do This, This Many Times"</title>
<para>
- Another way to write a "do" loop takes advantage of SuperCollider's flexibility, and is really the same as one of the methods above. It's basically equivalent to telling the interpreter to "run this Function this many times." The syntax looks like this,
- [pre]aNumber.do( aFunction );[/pre]
- This causes <code>aFunction</code> to be executed <code>aNumber</code> times. The interpreter still provdies two arguments to <code>aFunction</code>, but they are the same: it is the integers from zero to one less than <code>aNumber</code>. You might also think of it as the number of times that <code>aFunction</code> has been executed ''prior'' to this particular execution.
+ Another way to write a "do" loop takes advantage of <application>SuperCollider</application>'s flexibility, and is really the same as one of the methods above. It's basically equivalent to telling the interpreter to "run this Function this many times." The syntax looks like this,
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function><replaceable>aNumber</replaceable>.do</function></funcdef>
+ <paramdef>aFunction<funcparams>number</funcparams></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ This causes <function>aFunction</function> to be execute <replaceable>aNumber</replaceable> times. The interpreter still provdies two arguments to <function>aFunction</function>, but they are the same: it is the integers from zero to one less than <replaceable>aNumber</replaceable>. You might also think of it as the number of times that <function>aFunction</function> has been executed prior to this particular execution.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-Do_Examples">
@@ -1146,96 +1168,101 @@
These examples illustrate different ways to use "do" loops for trivial tasks.
</para>
<para>
- [pre]
- (
- var tL = List.new;
- tL = [27, 46, 102, 81, 34, 0, 39, 26, 203, 62];
-
- do( tL, { arg item, rep; [rep, item].postln; }; );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+ tL = [27, 46, 102, 81, 34, 0, 39, 26, 203, 62];
+
+ do( tL, { arg item, rep; [rep, item].postln; }; );
+
+ nil;
+)
+]]></programlisting>
This example is of the first syntax shown. For each element in <code>tL</code>, the interpreter executes the Function once, giving it ''first'' the corresponding element of the Collection, and ''then'' the iteration counter, which happens to be equal to the element's List index number.
</para>
<para>
- [pre]
- (
- var tL = List.new;
- var myFunc =
- {
- arg item;
- item.postln;
- };
-
- tL = [27, 46, 102, 81, 34, 0, 39, 26, 203, 62];
-
- tL.do( myFunc; );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var tL = List.new;
+ var myFunc =
+ {
+ arg item;
+ item.postln;
+ };
+
+ tL = [27, 46, 102, 81, 34, 0, 39, 26, 203, 62];
+
+ tL.do( myFunc; );
+
+ nil;
+)
+]]></programlisting>
This example does several things differently, but maintains the same basic functionality as the previous example. In this case, the Function only uses the first argument that the interpreter provides, and completely ignores the iteration counter. The syntax here also puts the Collection outside the parentheses, which perhaps makes it more clear that <code>tL</code> is not part of the Function.
</para>
<para>
- [pre]
- (
- 10.do( { "repeat".postln; }; );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ 10.do( { "repeat".postln; }; );
+
+ nil;
+)
+]]></programlisting>
This example simply prints the string "repeat" ten times. If the Function accepted one argument, it would receive the integers zero through nine. If it accepted two arguments, both of the arguments would be equal.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-While">
<title>"Do This While"</title>
<para>
- "While" loops execute continuously while their "test condition" is evaluated to be "true". Upon reaching the loop, the SuperCollider interpreter executes the test condition. If it is "fale", the interpreter does not execute the loop, and continues with the code after the loop. If it is "true", the interpreter executes the code in the loop once, then re-executes the test condition. If the test condition is "true", the loop is executed, the test condition re-executed, and so on. Until the test condition returns "false", the interpreter will never leave the loop.
+ "While" loops execute continuously while their "test condition" is evaluated to be "true". Upon reaching the loop, the <application>SuperCollider</application> interpreter executes the test condition. If it is "fale", the interpreter does not execute the loop, and continues with the code after the loop. If it is "true", the interpreter executes the code in the loop once, then re-executes the test condition. If the test condition is "true", the loop is executed, the test condition re-executed, and so on. Until the test condition returns "false", the interpreter will never leave the loop.
</para>
<para>
- Here is the format of a "while" loop in SuperCollider:
- [pre]
- while( testFunc, bodyFunc );
- [/pre]
- or
- [pre]
- testFunc.while( bodyFunc );
- [/pre]
- The test condition, called <code>testFunc</code>, is a Function which returns a boolean value - either "true" or "false". The loop's body, called <code>bodyFunc</code>, is a Function which can do anything. The loop body function is not provided any arguments by the interpreter. You will have to use comparison operators and boolean expressions when writing the Function for the test condition. For information on how these work in SuperCollider, see <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Operators" /> and <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Expressions" />.
+ Here is the format of a "while" loop in <application>SuperCollider</application>:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>while</function></funcdef>
+ <paramdef>boolean <replaceable>testFunction</replaceable><funcparams>number</funcparams></paramdef>
+ <paramdef><replaceable>bodyFunction</replaceable><funcparams>number</funcparams></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ or like this:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><replaceable>testFunction</replaceable>.<function>while</function></funcdef>
+ <paramdef><replaceable>bodyFunction</replaceable><funcparams>number</funcparams></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ The test condition, called <code>testFunc</code>, is a Function which returns a boolean value - either "true" or "false". The loop's body, called <code>bodyFunc</code>, is a Function which can do anything. The loop body function is not provided any arguments by the interpreter. You will have to use comparison operators and boolean expressions when writing the Function for the test condition. For information on how these work in <application>SuperCollider</application>, see <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Operators" /> and <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Expressions" />.
</para>
<para>
The following three code blocks are equivalent:
- [pre]
- (
- 10.do( { "repeat".postln; }; );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ 10.do( { "repeat".postln; }; );
+)
+]]></programlisting>
and
- [pre]
- (
- var counter = 0;
- while( { counter < 10; }, { "repeat".postln; counter = counter + 1; } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var counter = 0;
+ while( { counter < 10; }, { "repeat".postln; counter = counter + 1; } );
+)
+]]></programlisting>
and
- [pre]
- (
- var counter = 0;
- { counter < 10; }.while( { "repeat".postln; counter = counter + 1; } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var counter = 0;
+ { counter < 10; }.while( { "repeat".postln; counter = counter + 1; } );
+)
+]]></programlisting>
You can see how it's easier to write this particular activity as a "do" loop. It's often the case that a "do" loop better reflects what you want to do, but not always.
</para>
<para>
Contemplate a situation where you are waiting for the user to input some information, which you're going to use to calculate the rest of the composition. The following example isn't real code. It's intended to simplify a complex situation, so you can see where a "while" loop makes more sense than a "do" loop.
- [pre]
- play( some background music );
-
- while( { is the user still inputting information? }, { keep playing music } );
-
- stop( some background music );
- [/pre]
+<programlisting><![CDATA[
+play( some background music );
+while( { is the user still inputting information? }, { keep playing music } );
+stop( some background music );
+]]></programlisting>
The background music is begun, and then the interpreter would enter the loop. For as long as the user is still inputting information, the interpreter will then "keep playing music." When the user is not still inputting information, the interpreter will move on to the next command, which stops the music. An equivalent "do" loop would be very difficult to write, if not impossible. This is because we won't know when the user has finished inputting their information until ''after'' they've finished, so we can't plan in advance for how long to play background music.
</para>
<para>
@@ -1245,7 +1272,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-">
<title>Other Loops</title>
<para>
- The default language provides two other loop structures, both of which are designed to iterate over a series of integer values: "for" loops and "forBy" loops. Their use is more limited than "do" loops. They are explained in the SuperCollider documentation.
+ The default language provides two other loop structures, both of which are designed to iterate over a series of integer values: "for" loops and "forBy" loops. Their use is more limited than "do" loops. They are explained in the <application>SuperCollider</application> documentation.
</para>
</section>
</section> <!-- Ends "Repeated Execution" Section --> <!-- SC-Basic_Programming-Repeating- -->
@@ -1253,7 +1280,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution">
<title>Conditional Execution</title>
<para>
- Conditional execution tells the SuperCollider interpreter to execute code on the condition that something is true. SuperCollider offers three conditional execution structures, "if", "switch", and "case" statements. Each of these structures is controlled by one or a series of "boolean expressions" (sometimes called "conditional expressions"), which are composed of "boolean operators".
+ Conditional execution tells the <application>SuperCollider</application> interpreter to execute code on the condition that something is true. <application>SuperCollider</application> offers three conditional execution structures, "if", "switch", and "case" statements. Each of these structures is controlled by one or a series of "boolean expressions" (sometimes called "conditional expressions"), which are composed of "boolean operators".
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Operators">
<title>Boolean Operators</title>
@@ -1311,76 +1338,64 @@
<title>Simple Expressions</title>
<para>
Here are a few simple boolean expressions. Of course, variables can be used in place of constant numbers:
- [pre]
- 5 < 60; // evaluates to "false"
- [/pre]
- [pre]
- 42 != 42; // evaluates to "false"
- [/pre]
- [pre]
- 42 == 42; // evaluates to "true"
- [/pre]
- [pre]
- 0.isPositive; // evaluates to "true"
- [/pre]
- [pre]
- isNegative( -256 ); // evaluates to "true"
- [/pre]
+<programlisting><![CDATA[
+5 < 60; // evaluates to "false"
+42 != 42; // evaluates to "false"
+42 == 42; // evaluates to "true"
+0.isPositive; // evaluates to "true"
+isNegative( -256 ); // evaluates to "true"
+]]></programlisting>
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Assignment_and_Equality_Mistake">
<title>Assignment/Equality Mistake</title>
<para>
Beware the following pitfall, common to a large number of programming languages:
- [pre]
- a == 42; // evaluates to "true" or "false", depending on the value in "a"
- [/pre]
- [pre]
- a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
- [/pre]
+<programlisting><![CDATA[
+a == 42; // evaluates to "true" or "false", depending on the value in "a"
+a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
+]]></programlisting>
One possible work-around is to write the number first.
- [pre]
- 42 == a; // evaluates to "true" or "false", depending on the value in "a"
- [/pre]
- [pre]
- 42 = a; // causes an error, because you can't assign a value to a constant number
- [/pre]
- This way, if you accidentally leave out one of the "=" signs, the interpreter will stop execution and produce an error, rather than continuing with an unexpected assignment.
+<programlisting><![CDATA[
+42 == a; // evaluates to "true" or "false", depending on the value in "a"
+42 = a; // causes an error, because you can't assign a value to a constant number
+]]></programlisting>
+ This way, if you accidentally leave out one of the <literal>=</literal> signs, the interpreter will stop execution and produce an error, rather than continuing with an unexpected assignment.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Equality_versus_Identity">
<title>Equality versus Identity</title>
<para>
The identity-equivalence operators are not usually needed.
- [pre]
- (
- var a = [12,24,48];
- var b = [12,24,48];
-
- a == b; // evaluates to "true"
- a === b; // evaluates to "false"
- )
- [/pre]
- The "==" operator evaluates to "true" because "a" and "b" represent equivalent Objects - they are ''equal''. The "===" operator evaluates to "false" because "a" and "b" represent different instances of the Objects - they are not ''identical''.
- [pre]
- (
- var a = [12,24,48];
- var b = a;
-
- a == b; // evaluates to "true"
- a === b; // evaluates to "true"
- )
- [/pre]
- In this case, the "==" operator still evaluates to "true". The "===" operator also evaluates to "true", because "a" and "b" both represent the same Object. When the interpreter evaluates <code>var b = a;</code> in the example above, it actually assigns "b" the same value that "a" stores, not a copy of it.
+<programlisting><![CDATA[
+(
+ var a = [12,24,48];
+ var b = [12,24,48];
+
+ a == b; // evaluates to "true"
+ a === b; // evaluates to "false"
+)
+]]></programlisting>
+ The <code>==</code> operator evaluates to <literal>true</literal> because <literal>a</literal> and <literal>b</literal> represent equivalent Objects - they are equal. The <code>===</code> operator evaluates to <literal>false</literal> because <literal>a</literal> and <literal>b</literal> represent different instances of the Objects - they are not identical.
+<programlisting><![CDATA[
+(
+ var a = [12,24,48];
+ var b = a;
+
+ a == b; // evaluates to "true"
+ a === b; // evaluates to "true"
+)
+]]></programlisting>
+ In this case, the <code>==</code> operator still evaluates to <literal>true</literal>. The <code>===</code> operator also evaluates to <literal>true</literal>, because <literal>a</literal> and <literal>b</literal> both represent the same Object. When the interpreter evaluates <code>var b = a;</code> in the example above, it actually assigns <literal>b</literal> the same value that <literal>a</literal> stores, not a copy of it.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Logical_And_and_Or">
- <title>Logical And and Or</title>
+ <title>Logical <literal>And</literal> and <literal>Or</literal></title>
<para>
The logical And and Or operators must receive two boolean arguments. Logical And returns "true" if both of its arguments are "true". Logical Or returns "true" if one of its arguments are "true".
</para>
<para>
- The following table illustrates how the SuperCollider interpreter will evaluate each of the following situations.
+ The following table illustrates how the <application>SuperCollider</application> interpreter will evaluate each of the following situations.
{|
! If the left sub-expression evaluates to... !! ... and the right sub-expression evaluates to... !! ... then logical And would evaluate to... !! ... and logical Or would evaluate to...
|-
@@ -1398,19 +1413,19 @@
</para>
<para>
This can be exploited to help avoid errors like division-by-zero.
- [pre]
- (
- var x = 5.rand; // assigns a pseudo-random number between 0 and 5
-
- ( x != 0 ) && ( { x = 17 / x; } ); // doesn't divide by x if it would cause division-by-zero
-
- x; // the interpreter automatically prints this value after execution
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var x = 5.rand; // assigns a pseudo-random number between 0 and 5
+
+ ( x != 0 ) && ( { x = 17 / x; } ); // doesn't divide by x if it would cause division-by-zero
+
+ x; // the interpreter automatically prints this value after execution
+)
+]]></programlisting>
If the left-side expression of the logical And operator is "false", the interpreter doesn't evaluate the right-side expression; it simply moves on to the next expression. If the left-side expression is "true" (meaning that x is not zero), then the right-side expression is evaluated. The right-side expression happens to be a Function which assigns "x" the result of dividing 17 by its previous value. The result of the logical And operation is simply discarded in this case - it doesn't really matter to us. This isn't the most straight-forward code, and there are other ways to avoid division-by-zero. If you use this, it's probably best to include a brief explanation of what the code does, as a commment.
</para>
<para>
- If you run this code many times, you will see that it gives many different results - one of which is zero, which proves that the code works as intended. If SuperCollider divides by zero, the result is "inf", representing infinity. Try modifying the code so that it will divide by zero, and see what happens.
+ If you run this code many times, you will see that it gives many different results - one of which is zero, which proves that the code works as intended. If <application>SuperCollider</application> divides by zero, the result is "inf", representing infinity. Try modifying the code so that it will divide by zero, and see what happens.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Order_of_Precedence">
@@ -1420,27 +1435,25 @@
</para>
<para>
Even simple expression can benefit from parentheses. These produce the same results:
- [pre]
- (
- var a = 5 == 5 && 17 != 5;
- var b = ( 5 == 5 ) && ( 17 != 5 ); // parentheses help to clarify
-
- a == b; // evaluates to "true"
- )
- [/pre]
- [pre]
- (
- var a = 5.isPositive && isNegative( 6 ) || 12 + 5 * 42 - 1 > 18 ;
- var b = ( 5.isPositive && isNegative( 6 ) ) || ( ((12 + 5) * 42 - 1) > 18 ); // parentheses help to clarify
-
- a && b; // evaluates to "true"
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var a = 5 == 5 && 17 != 5;
+ var b = ( 5 == 5 ) && ( 17 != 5 ); // parentheses help to clarify
+
+ a == b; // evaluates to "true"
+)
+]]></programlisting>
+<programlisting><![CDATA[
+(
+ var a = 5.isPositive && isNegative( 6 ) || 12 + 5 * 42 - 1 > 18 ;
+ var b = ( 5.isPositive && isNegative( 6 ) ) || ( ((12 + 5) * 42 - 1) > 18 ); // parentheses help to clarify
+
+ a && b; // evaluates to "true"
+)
+]]></programlisting>
And perhaps even more surprisingly...
- [pre]
- ( 12 + 5 * 42 - 1 ) != ( (12 + 5) * 42 - 1 );
- [/pre]
- ... evaluates to "false"! They're equal - the interpreter doesn't follow the standard mathematical order of precedence rules! SuperCollider evaluates from left to right, so it's important to clarify to the interpreter what you mean. Where would you put parentheses so that SuperCollider evaluates the expression as per the standard mathematical order of precedence rules, with multiplication before addition and subtraction?
+ <programlisting><![CDATA[( 12 + 5 * 42 - 1 ) != ( (12 + 5) * 42 - 1 );]]></programlisting>
+ ... evaluates to "false"! They're equal - the interpreter doesn't follow the standard mathematical order of precedence rules! <application>SuperCollider</application> evaluates from left to right, so it's important to clarify to the interpreter what you mean. Where would you put parentheses so that <application>SuperCollider</application> evaluates the expression as per the standard mathematical order of precedence rules, with multiplication before addition and subtraction?
</para>
</section>
</section> <!-- Ends "Boolean Expressions" Section -->
@@ -1451,73 +1464,69 @@
</para>
<para>
Here are the two ways to write an "if" structure:
- [pre]
- if ( booleanExpression, trueFunction, falseFunction );
- [/pre]
+ <programlisting><![CDATA[if ( booleanExpression, trueFunction, falseFunction );]]></programlisting>
and
- [pre]
- booleanExpression.if( trueFunction, falseFunction );
- [/pre]
+ <programlisting><![CDATA[booleanExpression.if( trueFunction, falseFunction );]]></programlisting>
It's possible to exclude the <code>falseFunction</code>, which is like telling the interpreter, "If the boolean expression is true, then execute this Function. Otherwise, don't execute it."
</para>
<para>
- [pre]
- (
- var test = [true,false].choose; // pseudo-randomly chooses one of the elements in the List
-
- if ( ( true == test ), { "It's true!".postln; }, { "It's false!".postln; } );
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var test = [true,false].choose; // pseudo-randomly chooses one of the elements in the List
+
+ if ( ( true == test ), { "It's true!".postln; }, { "It's false!".postln; } );
+ nil;
+)
+]]></programlisting>
This example prints out a nice message, saying whether <code>test</code> is "true" or "false". Because <code>test</code> is already a boolean value, we don't need to include it in an expression. The "if" statement could have been shortened like this: <code>if ( test, { "It's true!".postln; }, { "It's false!".postln; } );</code>
</para>
<para>
Suppose we only wanted to be alerted if <code>test</code> is "true".
- [pre]
- (
- var test = [true,false].choose; // pseudo-randomly chooses one of the elements in the List
-
- test.if( { "It's true!".postln; } );
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var test = [true,false].choose; // pseudo-randomly chooses one of the elements in the List
+
+ test.if( { "It's true!".postln; } );
+ nil;
+)
+]]></programlisting>
In this example, the alternate "if" syntax is used, where the boolean expression is placed before the parentheses.
</para>
<para>
"If" structures can also be "nested," which is like telling the interpreter, "If this is true, do this; otherwise if this is true, do this; otherwise if this is true, do this." In this relatively simple example of nesting, the interpreter evaluates each "if" structure only if the previous one was "false".
- [pre]
- (
- var test = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
-
- if( 1 == test, { "It's one!".postln; },
- if( 2 == test, { "It's two!".postln; },
- if( 3 == test, { "It's three!".postln; } ) ) );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var test = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
+
+ if( 1 == test, { "It's one!".postln; },
+ if( 2 == test, { "It's two!".postln; },
+ if( 3 == test, { "It's three!".postln; } ) ) );
+
+ nil;
+)
+]]></programlisting>
</para>
<para>
This is a more complex example of nesting:
- [pre]
- (
- var testA = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
- var testB = [1,2,3].choose;
-
- if( 1 == testA, { ( 1 == testB ).if( { "It's one and one!".postln; },
- ( 2 == testB ).if( { "It's one and two!".postln; },
- ( 3 == testB ).if( { "It's one and three!".postln; } ) ) ); },
- if( 2 == testA, { ( 1 == testB ).if( { "It's two and one!".postln; },
- ( 2 == testB ).if( { "It's two and two!".postln; },
- ( 3 == testB ).if( { "It's two and three!".postln; } ) ) ); },
- if( 3 == testA, { ( 1 == testB ).if( { "It's three and one!".postln; },
- ( 2 == testB ).if( { "It's three and two!".postln; },
- ( 3 == testB ).if( { "It's three and three!".postln; } ) ) ); } ) ) );
-
- nil;
- )
- [/pre]
- As you can see, this type of nesting is not easy to figure out - from the standpoint of the original programmer or somebody else who wishes to use your code. In writing this example, it took me several attempts before getting the parentheses and braces right. Usually, if you have a long list of possibilities to test (like the nine in this example), it is better to use a "case" or "switch" structure. Not only does this help to make the code easier to understand, but the SuperCollider interpreter can apply optimizations that make the code run marginally faster.
+<programlisting><![CDATA[
+(
+ var testA = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
+ var testB = [1,2,3].choose;
+
+ if( 1 == testA, { ( 1 == testB ).if( { "It's one and one!".postln; },
+ ( 2 == testB ).if( { "It's one and two!".postln; },
+ ( 3 == testB ).if( { "It's one and three!".postln; } ) ) ); },
+ if( 2 == testA, { ( 1 == testB ).if( { "It's two and one!".postln; },
+ ( 2 == testB ).if( { "It's two and two!".postln; },
+ ( 3 == testB ).if( { "It's two and three!".postln; } ) ) ); },
+ if( 3 == testA, { ( 1 == testB ).if( { "It's three and one!".postln; },
+ ( 2 == testB ).if( { "It's three and two!".postln; },
+ ( 3 == testB ).if( { "It's three and three!".postln; } ) ) ); } ) ) );
+
+ nil;
+)
+]]></programlisting>
+ As you can see, this type of nesting is not easy to figure out - from the standpoint of the original programmer or somebody else who wishes to use your code. In writing this example, it took me several attempts before getting the parentheses and braces right. Usually, if you have a long list of possibilities to test (like the nine in this example), it is better to use a "case" or "switch" structure. Not only does this help to make the code easier to understand, but the <application>SuperCollider</application> interpreter can apply optimizations that make the code run marginally faster.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Switch_Statements">
@@ -1527,80 +1536,80 @@
</para>
<para>
Here is the syntax of a "switch" statement:
- [pre]
- case( compareThis,
- toThis1, { doThis; },
- toThis2, { doThis; },
- toThis3, { doThis; }
- );
- [/pre]
+<programlisting><![CDATA[
+case( compareThis,
+ toThis1, { doThis; },
+ toThis2, { doThis; },
+ toThis3, { doThis; }
+);
+]]></programlisting>
You can include any number of cases. Notice that there is no comma after the last case, and that I've put the concluding ");" on a separate line with the same indentation as the word "case", so that it's easy to see.
</para>
<para>
The following example shows a simple switch.
- [pre]
- (
- var grade = 11.rand + 1; // pseudo-randomly chooses 0 to 11, then adds 1 to give 1 to 12
-
- grade =
- switch( grade,
- 1, { "D-" },
- 2, { "D" },
- 3, { "D+" },
- 4, { "C-" },
- 5, { "C" },
- 6, { "C+" },
- 7, { "B-" },
- 8, { "B" },
- 9, { "B+" },
- 10, { "A-" },
- 11, { "A" },
- 12, { "A+" }
- );
-
- ("Your grade is" + grade).postln;
- nil;
- )
- [pre]
+<programlisting><![CDATA[
+(
+ var grade = 11.rand + 1; // pseudo-randomly chooses 0 to 11, then adds 1 to give 1 to 12
+
+ grade =
+ switch( grade,
+ 1, { "D-" },
+ 2, { "D" },
+ 3, { "D+" },
+ 4, { "C-" },
+ 5, { "C" },
+ 6, { "C+" },
+ 7, { "B-" },
+ 8, { "B" },
+ 9, { "B+" },
+ 10, { "A-" },
+ 11, { "A" },
+ 12, { "A+" }
+ );
+
+ ("Your grade is" + grade).postln;
+ nil;
+)
+]]></programlisting>
The code picks a pseudo-random number between 1 and 12, then uses a "switch" structure to convert that number into a letter-grade, assigning it to the same <code>grade</code> variable. Then, it adds the "Your grade is" string to the value of <code>grade</code> (with a space between), and prints that result.
</para>
<para>
This example avoids the complex nested "if" structure from above.
- [pre]
- (
- var testA = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
- var testB = [1,2,3].choose;
-
- switch( [testA,testB],
- [1,1], { "It's one and one!".postln; },
- [1,2], { "It's one and two!".postln; },
- [1,3], { "It's one and three!".postln; },
- [2,1], { "It's two and one!".postln; },
- [2,2], { "It's two and two!".postln; },
- [2,3], { "It's two and thre!".postln; },
- [3,1], { "It's three and one!".postln; },
- [3,2], { "It's three and two!".postln; },
- [3,3], { "It's three and three!".postln; }
- );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var testA = [1,2,3].choose; // pseudo-randomly chooses one of the elements in the List
+ var testB = [1,2,3].choose;
+
+ switch( [testA,testB],
+ [1,1], { "It's one and one!".postln; },
+ [1,2], { "It's one and two!".postln; },
+ [1,3], { "It's one and three!".postln; },
+ [2,1], { "It's two and one!".postln; },
+ [2,2], { "It's two and two!".postln; },
+ [2,3], { "It's two and thre!".postln; },
+ [3,1], { "It's three and one!".postln; },
+ [3,2], { "It's three and two!".postln; },
+ [3,3], { "It's three and three!".postln; }
+ );
+
+ nil;
+)
+]]></programlisting>
This is an elegant way to inspect two otherwise-separate variables. Remember that the first argument to "switch" (in this case, it's <code>[testA,tesB]</code>) is compared to the first argument of possibe result with the equality operator: "==".
</para>
<para>
- When evaluating which switch to use, the SuperCollider interpreter will always apply the ''last'' one that evaluates to "true".
- [pre]
- (
- switch( 5,
- 5, { "one".postln; },
- 5, { "two".postln; },
- 5, { "three".postln; }
- );
-
- nil;
- )
- [/pre]
+ When evaluating which switch to use, the <application>SuperCollider</application> interpreter will always apply the ''last'' one that evaluates to "true".
+<programlisting><![CDATA[
+(
+ switch( 5,
+ 5, { "one".postln; },
+ 5, { "two".postln; },
+ 5, { "three".postln; }
+ );
+
+ nil;
+)
+]]></programlisting>
All of these cases are true, but this will always result in "three" being printed.
</para>
</section>
@@ -1611,82 +1620,82 @@
</para>
<para>
Here is the syntax of a "case" structure:
- [pre]
- case
- booleanFunction resultFunction
- booleanFunction resultFunction
- booleanFunction resultFunction
- booleanFunction resultFunction
- ;
- [/pre]
+<programlisting><![CDATA[
+case
+ <replaceable>booleanFunction</replaceable> <replaceable>resultFunction</replaceable>
+ <replaceable>booleanFunction</replaceable> <replaceable>resultFunction</replaceable>
+ <replaceable>booleanFunction</replaceable> <replaceable>resultFunction</replaceable>
+ <replaceable>booleanFunction</replaceable> <replaceable>resultFunction</replaceable>
+;
+]]></programlisting>
</para>
<para>
Contemplate the following pseudo-code example, which represents a possible musical sitation, and a good use of the "case" structure.
- [pre]
- (
- var coolFunction =
- {
- case
- { is there no music playing?
- AND people are in the room } { play music }
- { has the same song been playing for too long?
- OR is the song boring? } { change the song }
- { has everybody left the room? } { turn off the music }
- { has a song been requested? } { change to that song }
- { is the music too loud? } { lower the music's volume }
- { is the music too quiet? } { raise the music's volume }
- { is the music too fast? } { lower the music's tempo }
- { is the music too slow? } { raise the music's tempo }
- { is everything okay? } { wait for 10 seconds }
- ;
- };
-
- ( 5 == 5 ).while( coolFunction ); // executes coolFunction contiuously
- )
- [/pre]
- It might seem like this example doesn't relate to a real SuperCollider programming situation, but in fact it might. If you could program Function's which determined all of those questions and all of the answers, this sort of "case" structure would be very helpful in a situation where a computer running SuperCollider were left in a room by itself, and expected to play music whenever anybody entered the room. Since five is always equal to five, the interpreter will run <code>coolFunction</code> forever. If the music needs adjustment in some way, the Function will adjust the music. If everything is okay, then the interpreter will wait for 10 seconds, and then the loop will cause the Function to be re-evaluated. Because many different criteria are evaluated in the "case" structure, this represents an efficient use of the structure.
+<programlisting><![CDATA[
+(
+ var coolFunction =
+ {
+ case
+ { is there no music playing?
+ AND people are in the room } { play music }
+ { has the same song been playing for too long?
+ OR is the song boring? } { change the song }
+ { has everybody left the room? } { turn off the music }
+ { has a song been requested? } { change to that song }
+ { is the music too loud? } { lower the music's volume }
+ { is the music too quiet? } { raise the music's volume }
+ { is the music too fast? } { lower the music's tempo }
+ { is the music too slow? } { raise the music's tempo }
+ { is everything okay? } { wait for 10 seconds }
+ ;
+ };
+
+ ( 5 == 5 ).while( coolFunction ); // executes coolFunction contiuously
+)
+]]></programlisting>
+ It might seem like this example doesn't relate to a real <application>SuperCollider</application> programming situation, but in fact it might. If you could program Function's which determined all of those questions and all of the answers, this sort of "case" structure would be very helpful in a situation where a computer running <application>SuperCollider</application> were left in a room by itself, and expected to play music whenever anybody entered the room. Since five is always equal to five, the interpreter will run <code>coolFunction</code> forever. If the music needs adjustment in some way, the Function will adjust the music. If everything is okay, then the interpreter will wait for 10 seconds, and then the loop will cause the Function to be re-evaluated. Because many different criteria are evaluated in the "case" structure, this represents an efficient use of the structure.
</para>
<para>
"Case" structures can be used to do the same thing as "switch" structures, but it's usually less elegant solution. Also, it doesn't allow the interpreter to use an speed optimization that it would have used in an equivalent "switch" structure.
- [pre]
- (
- var grade = 11.rand + 1; // pseudo-randomly chooses 0 to 11, then adds 1 to give 1 to 12
-
- grade =
- case
- { 1 == grade; } { "D-" }
- { 2 == grade; } { "D" }
- { 3 == grade; } { "D+" }
- { 4 == grade; } { "C-" }
- { 5 == grade; } { "C" }
- { 6 == grade; } { "C+" }
- { 7 == grade; } { "B-" }
- { 8 == grade; } { "B" }
- { 9 == grade; } { "B+" }
- { 10 == grade; } { "A-" }
- { 11 == grade; } { "A" }
- { 12 == grade; } { "A+" }
- ;
-
- ("Your grade is" + grade).postln;
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var grade = 11.rand + 1; // pseudo-randomly chooses 0 to 11, then adds 1 to give 1 to 12
+
+ grade =
+ case
+ { 1 == grade; } { "D-" }
+ { 2 == grade; } { "D" }
+ { 3 == grade; } { "D+" }
+ { 4 == grade; } { "C-" }
+ { 5 == grade; } { "C" }
+ { 6 == grade; } { "C+" }
+ { 7 == grade; } { "B-" }
+ { 8 == grade; } { "B" }
+ { 9 == grade; } { "B+" }
+ { 10 == grade; } { "A-" }
+ { 11 == grade; } { "A" }
+ { 12 == grade; } { "A+" }
+ ;
+
+ ("Your grade is" + grade).postln;
+ nil;
+)
+]]></programlisting>
This example is equivalent to one of the "switch" structure examples. This is not a good use of the "case" structure, because it requires a lot of code repetition.
</para>
<para>
Unlike a "switch" structure, a "case" structure will always follow the ''first'' case that evaluates to "true".
- [pre]
- (
- case
- { 5 == 5; } { "one".postln; }
- { 5 == 5; } { "two".postln; }
- { 5 == 5; } { "three".postln; }
- ;
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ case
+ { 5 == 5; } { "one".postln; }
+ { 5 == 5; } { "two".postln; }
+ { 5 == 5; } { "three".postln; }
+ ;
+
+ nil;
+)
+]]></programlisting>
This example will always result in "one" being printed.
</para>
</section>
@@ -1695,7 +1704,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Combining_and_Mix">
<title>Combining Audio; the Mix Class</title>
<para>
- One of the requirements of multi-channel audio is the ability to combine a large number of UGen's into a small number of channels - normally just two. The SuperCollider interpreter allows you to accomplish this in a number of ways, which are explained here.
+ One of the requirements of multi-channel audio is the ability to combine a large number of UGen's into a small number of channels - normally just two. The <application>SuperCollider</application> interpreter allows you to accomplish this in a number of ways, which are explained here.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Combining_and_Mix-Mix_Class">
<title>The "Mix" Class</title>
@@ -1704,50 +1713,56 @@
</para>
<para>
Here are the two possible syntaxes for the "Mix" Class:
- [pre]
- Mix.new( ArrayOfUGens );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Mix.new</function></funcdef>
+ <paramdef><parameter>ArrayOfUGens</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
and
- [pre]
- Mix( ArrayOfUGens );
- [/pre]
- The second form is simply a short-hand version of the first. The "Mix" Class doesn't really create "Mix" Objects either - it's just a Function that combines many UGen's into one.
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Mix</function></funcdef>
+ <paramdef><parameter>ArrayOfUGens</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ The second form is simply a short-hand version of the first. The <classname>Mix</classname> Class doesn't really create "Mix" Objects either - it's just a Function that combines many UGen's into one.
</para>
<para>
Here's an example of the "Mix" Class in action:
- [pre]
- {
- Mix( [SinOsc.ar(220, 0, 0.1),
- SinOsc.ar(440, 0, 0.1),
- SinOsc.ar(660, 0, 0.1),
- SinOsc.ar(880, 0, 0.1),
- SinOsc.ar(850, 0, 0.1),
- SinOsc.ar(870, 0, 0.1),
- SinOsc.ar(880, 0, 0.1),
- SinOsc.ar(885, 0, 0.1),
- SinOsc.ar(890, 0, 0.1),
- SinOsc.ar(1000, 0, 0.1)] );
- }.play;
- [/pre]
+<programlisting><![CDATA[
+{
+ Mix( [SinOsc.ar(220, 0, 0.1),
+ SinOsc.ar(440, 0, 0.1),
+ SinOsc.ar(660, 0, 0.1),
+ SinOsc.ar(880, 0, 0.1),
+ SinOsc.ar(850, 0, 0.1),
+ SinOsc.ar(870, 0, 0.1),
+ SinOsc.ar(880, 0, 0.1),
+ SinOsc.ar(885, 0, 0.1),
+ SinOsc.ar(890, 0, 0.1),
+ SinOsc.ar(1000, 0, 0.1)] );
+}.play;
+]]></programlisting>
Notice how all of these SinOsc's are heard through the left channel only. The "Mix" Class mixes all the UGen's together into one. You could use a bus to send the audio to both the left and right channels. What happens if we don't use the Mix Class? Try removing the Function, and find out. You only hear some of the SinOsc's. Which ones? The first two, representing the left and right channels. If your audio interface has more than two channels, you may be able to hear more than those first two channels.
</para>
<para>
There is another Function offered by the Mix Class, and it is a kind of loop. The Function is called <code>Fill</code>, and it takes two arguments: the number of times to run a Function, and the Function to run. The Function is provided with one argument (like in a "do" loop), which is the number of times the Function has ''already'' been run.
- [pre]
- (
- var n = 8;
- var sineFunc =
- {
- arg iteration;
-
- var freq = 440 + iteration;
- SinOsc.ar( freq:freq, mul:1/n );
- };
-
- { Mix.fill( n, sineFunc ); }.play;
- )
- [/pre]
- As you can see, the "fill" Function itself is quite simple: you provide the number of UGen's to create, and a Function that creates UGen's. It's the <code>sineFunc</code> Function that is a little confusing. The argument is called "iteration", because it holds how many times the Function has already been run - how many iterations have happened already. It uses this value to help calculate the frequency (stored in a variable called "freq"), and then creates a SinOsc UGen. The "mul" argument helps to automatically control the volume level. Since the total volume should be no more than 1.0, the "sineFunc" Function calculates UGen's' volume by dividing 1, the maximum level, by the number of UGen's that will be created. The slowly pulsating volume is part of the acoustic result of this many frequencies being so close together - it is not a hidden effect by SuperCollider.
+<programlisting><![CDATA[
+(
+ var n = 8;
+ var sineFunc =
+ {
+ arg iteration;
+
+ var freq = 440 + iteration;
+ SinOsc.ar( freq:freq, mul:1/n );
+ };
+
+ { Mix.fill( n, sineFunc ); }.play;
+)
+]]></programlisting>
+ As you can see, the "fill" Function itself is quite simple: you provide the number of UGen's to create, and a Function that creates UGen's. It's the <code>sineFunc</code> Function that is a little confusing. The argument is called "iteration", because it holds how many times the Function has already been run - how many iterations have happened already. It uses this value to help calculate the frequency (stored in a variable called "freq"), and then creates a SinOsc UGen. The "mul" argument helps to automatically control the volume level. Since the total volume should be no more than 1.0, the "sineFunc" Function calculates UGen's' volume by dividing 1, the maximum level, by the number of UGen's that will be created. The slowly pulsating volume is part of the acoustic result of this many frequencies being so close together - it is not a hidden effect by <application>SuperCollider</application>.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Combining_and_Mix-Arrays_of_Arrays">
@@ -1756,26 +1771,26 @@
There is another way to combine many UGen's into two channels for stereo output: rather than sending the Array's to the Mix class, combine them into a two-element Array.
</para>
<para>
- [pre]
- {
- [
- [ SinOsc.ar(440, 0, 0.1), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.1 ) ],
- [ SinOsc.ar(440, 0, 0.1), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.1 ) ]
- ];
- }.play;
- [/pre]
+<programlisting><![CDATA[
+{
+ [
+ [ SinOsc.ar(440, 0, 0.1), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.1 ) ],
+ [ SinOsc.ar(440, 0, 0.1), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.1 ) ]
+ ];
+}.play;
+]]></programlisting>
Here, a two-element Array is the result of a Function, which gets sent the "play" message. Each of the elements is an equivalent, three-element Array where each element is a UGen.
</para>
<para>
This representation also offers another benefit: each UGen can have a different "mul" value, which will be preserved.
- [pre]
- {
- [
- [ SinOsc.ar(440, 0, 0.2), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.05 ) ],
- [ SinOsc.ar(440, 0, 0.2), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.05 ) ]
- ];
- }.play;
- [/pre]
+<programlisting><![CDATA[
+{
+ [
+ [ SinOsc.ar(440, 0, 0.2), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.05 ) ],
+ [ SinOsc.ar(440, 0, 0.2), SinOsc.ar( 880, 0, 0.1 ), SinOsc.ar( 1660, 0, 0.05 ) ]
+ ];
+}.play;
+]]></programlisting>
This sounds much less harsh than the first example. Try it with the Mix Class. Even with the different "mul" values, it sounds the same as the first example! This helps Mix to ensure that the total level doesn't exceed 1.0, but it has the disadvantage that careful level-balancing on your part will be erased.
</para>
</section>
@@ -1785,14 +1800,14 @@
This method of combinine UGen's into two channels uses the addition operator: +
</para>
<para>
- [pre]
- {
- [
- ( SinOsc.ar(440, 0, 0.1) + SinOsc.ar( 880, 0, 0.1 ) + SinOsc.ar( 1660, 0, 0.1 ) ),
- ( SinOsc.ar(440, 0, 0.1) + SinOsc.ar( 880, 0, 0.1 ) + SinOsc.ar( 1660, 0, 0.1 ) )
- ];
- }.play;
- [/pre]
+<programlisting><![CDATA[
+{
+ [
+ ( SinOsc.ar(440, 0, 0.1) + SinOsc.ar( 880, 0, 0.1 ) + SinOsc.ar( 1660, 0, 0.1 ) ),
+ ( SinOsc.ar(440, 0, 0.1) + SinOsc.ar( 880, 0, 0.1 ) + SinOsc.ar( 1660, 0, 0.1 ) )
+ ];
+}.play;
+]]></programlisting>
Notice that, like with the Mix Class, independent "mul" levels are not preserved.
</para>
</section>
@@ -1802,17 +1817,17 @@
<title>SynthDef and Synth</title>
<para>
The preceding sections of this "Basic Programming" guide have only created sound with Function's. The truth is that Function's are very useful for creating sound, but they represent a simplification of the actual commands and Functions that must be run by the interpreter in order to create sound.
- [pre]
- // When you write this...
- (
- { SinOsc.ar( freq:440, mul:0.2 ); }.play;
- )
+<programlisting><![CDATA[
+// When you write this...
+(
+ { SinOsc.ar( freq:440, mul:0.2 ); }.play;
+)
- // The interpreter actually does this...
- (
- SynthDef.new( "temp__963", { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).play;
- )
- [/pre]
+// The interpreter actually does this...
+(
+ SynthDef.new( "temp__963", { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).play;
+)
+]]></programlisting>
Yikes! Don't despair - it's easy to understand - it just looks scary!
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Out_UGen">
@@ -1822,13 +1837,9 @@
</para>
<para>
The following examples have the same effect:
- [pre]
- { SinOsc.ar( freq:500, mul:0.2 ); }.play;
- [/pre]
+ <programlisting><![CDATA[{ SinOsc.ar( freq:500, mul:0.2 ); }.play;]]></programlisting>
and
- [pre]
- { Out.ar( 0, SinOsc.ar( freq:500, mul:0.2 ) ); }.play;
- [/pre]
+ <programlisting><![CDATA[{ Out.ar( 0, SinOsc.ar( freq:500, mul:0.2 ) ); }.play;]]></programlisting>
The first argument to "Out.ar" is the bus number for where you want to place the second argument, which is either a UGen or a multi-channel Array of UGen's. If the second argument is an Array, then the first element is sent to the first argument's bus number, the second argument is sent to one bus number higher, the third to two bus numbers higher, and so on. This issues is explained fully in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Busses" />, but here is what you need to know for now, working with stereo (two-channel) audio:
<itemizedlist>
<listitem><para>If the second argument is a two-element Array, use bus number 0.</para></listitem>
@@ -1843,7 +1854,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-SynthDef">
<title>SynthDef</title>
<para>
- A SynthDef is what we use to tell the server how to create sound. In order to truly understand what SynthDef accomplishes, we need to recall the disconnect between the interpreter and the server. In reality, the interpreter has no idea how to make sound or work with audio hardware. The server, likewise, has no understanding at all of the SuperCollider language. The interpreter takes the code that we write, and does one of a number of things, depending on the nature of the code:
+ A SynthDef is what we use to tell the server how to create sound. In order to truly understand what SynthDef accomplishes, we need to recall the disconnect between the interpreter and the server. In reality, the interpreter has no idea how to make sound or work with audio hardware. The server, likewise, has no understanding at all of the <application>SuperCollider</application> language. The interpreter takes the code that we write, and does one of a number of things, depending on the nature of the code:
<itemizedlist>
<listitem><para>executes it completely,</para></listitem>
<listitem><para>executes it partially, makes choices, and then does something else</para></listitem>
@@ -1859,49 +1870,45 @@
</para>
<para>
There are two steps to creating a useful SynthDef: making an interpreter Object, and sending the actual synthesis information to the server. There are two ways to write this, as follows:
- [pre]
- someVariable = SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen );
- someVariable.send( nameOfServer );
- [/pre]
+<programlisting><![CDATA[
+someVariable = SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen );
+someVariable.send( nameOfServer );
+]]></programlisting>
and
- [pre]
- SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen ).send( nameOfServer );
- [/pre]
+ <programlisting><![CDATA[SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen ).send( nameOfServer );]]></programlisting>
The <code>FunctionContainingOutUGen</code> is simply that - a Function that, when executed, returns an "Out" UGen (meaning that the "Out" UGen must be the last expression in the Function). The <code>nameOfSynthDef</code> should be a symbol (as described in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Symbols" />), but can also be a string. The <code>nameOfServer</code> is a variable that represents the server to which you want to send the SynthDef's information; unless you know that you need to use a different variable for this, it's probably just the letter "s", which the interpreter automatically assigns to the default server.
</para>
<para>
Here is a demonstration of both methods:
- [pre]
- (
- var playMe =
- {
- Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) );
- };
-
- var playMeSynthDef = SynthDef.new( \playMe, playMe );
-
- playMeSynthDef.send( s );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var playMe =
+ {
+ Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) );
+ };
+
+ var playMeSynthDef = SynthDef.new( \playMe, playMe );
+
+ playMeSynthDef.send( s );
+
+ nil;
+)
+]]></programlisting>
and
- [pre]
- (
- var playMe =
- {
- Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) );
- };
-
- SynthDef.new( \playMe, playMe ).send( s );
-
- nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var playMe =
+ {
+ Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) );
+ };
+
+ SynthDef.new( \playMe, playMe ).send( s );
+
+ nil;
+)
+]]></programlisting>
The only advantage to assigning something to a variable is the ability to refer to it later. If you use the first method, then you can send the SynthDef to more than one server. Since it's rare that you will want to use more than one server, it's usually better to use the second style. In fact, if you won't be using the "playMe" Function again, you don't need to assign it to a variable!
- [pre]
- SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).send( s );
- [/pre]
+ <programlisting><![CDATA[SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).send( s );]]></programlisting>
This is all that's really needed to create and send a synthesis definition to the server. It looks long and frightening, but now at least you understand what all of the parts do.
</para>
</section>
@@ -1917,7 +1924,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Symbols">
<title>Symbols</title>
<para>
- As stated in the section about variables, a symbol is simply something which represents something else. When used in the context of a SynthDef, a symbol is a string of characters that refers to a SynthDef that we've already sent to the server. What wasn't mentioned in the section about variables is that, in addition to the symbols that can be used as variable names, the SuperCollider language provides a distinct data-type (like numbers or strings) for symbols. Many programming languages don't provide a "symbol" data-type, so many programmers do not use them extensively, but they are very handy for situations like this. As local variable names are symbols representing data stored by the interpreter, here we are using the symbol data-type to refer to data stored on the server.
+ As stated in the section about variables, a symbol is simply something which represents something else. When used in the context of a SynthDef, a symbol is a string of characters that refers to a SynthDef that we've already sent to the server. What wasn't mentioned in the section about variables is that, in addition to the symbols that can be used as variable names, the <application>SuperCollider</application> language provides a distinct data-type (like numbers or strings) for symbols. Many programming languages don't provide a "symbol" data-type, so many programmers do not use them extensively, but they are very handy for situations like this. As local variable names are symbols representing data stored by the interpreter, here we are using the symbol data-type to refer to data stored on the server.
</para>
<para>
Symbols are a better way to name SynthDef's than strings. Not only do symbols take up less memory, they aren't actually the interpreter doesn't actually think of them as Objects, and neither should you. Symbols are universally unique; only one instance of a symbol with the same characters can exist. On the other hand, an infinite number of strings with the same characters can exist. When we use a symbol, we are defining it universally. When we use a string, the server pretends that all strings with the same characters are the same philosophical object, even though they aren't. This isn't a technical problem, but it can be difficult to think about, and is cognitively dissonant.
@@ -1938,29 +1945,28 @@
</para>
<para>
The following example contains some valid symbols, and some invalid symbols.
- [pre]
- \stopSign \\ this is a symbol
- \stop sign \\ this is a symbol called 'stop' followed by the unrelated word 'sign'
- 'stopSign' \\ this is a symbol
- 'stop sign' \\ this is a symbol
- 'stop
- sign' \\ these lines are not a symbol, and will cause an error
- [/pre]
+<programlisting><![CDATA[
+\stopSign \\ this is a symbol
+\stop sign \\ this is a symbol called 'stop' followed by the unrelated word 'sign'
+'stopSign' \\ this is a symbol
+'stop sign' \\ this is a symbol
+'stop
+sign' \\ these lines are not a symbol, and will cause an error
+]]></programlisting>
</para>
<para>
The following example illustrates the differences between strings and symbols.
- [pre]
- var a = "stop sign" \\ a string
- var b = "stop sign" \\ a string with the same letters as the first string
- a == b; \\ returns "true" because the strings are equivalent
- a === b; \\ returns "false" because the strings are separate copies with the same characters
- </para>
- <para>
- var c = 'stop sign' \\ a symbol
- var d = 'stop sign' \\ the same symbol
- c == d; \\ returns "true" because the symbols are equivalent
- c === d; \\ returns "true" because the symbols are identical
- [/pre]
+<programlisting><![CDATA[
+var a = "stop sign" \\ a string
+var b = "stop sign" \\ a string with the same letters as the first string
+a == b; \\ returns "true" because the strings are equivalent
+a === b; \\ returns "false" because the strings are separate copies with the same characters
+
+var c = 'stop sign' \\ a symbol
+var d = 'stop sign' \\ the same symbol
+c == d; \\ returns "true" because the symbols are equivalent
+c === d; \\ returns "true" because the symbols are identical
+]]></programlisting>
</para>
</section>
</section> <!-- Ends "Symbols" Section -->
@@ -1971,30 +1977,29 @@
</para>
<para>
This is the syntax used to create a new synth, after its definition has been sent to the server.
- [pre]
- Synth.new( nameOfSynthDef );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Synth.new</function></funcdef>
+ <paramdef><parameter>nameOfSynthDef</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
The name will be a symbol or a string - whatever you supplied when you ran the <code>SynthDef.new()</code> Function.
</para>
<para>
Because we're creating a new Synth Object, we should assign it to a variable, for later reference.
- [pre]
- SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).send( s );
- var mySynth = Synth.new( \playMe );
- [/pre]
+<programlisting><![CDATA[
+SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).send( s );
+var mySynth = Synth.new( \playMe );
+]]></programlisting>
</para>
<para>
Recall that the interpreter automatically uses the Synth and SynthDef Classes when we send the "play" message to a Function. We can actually capture and use the Synth Object created from "play-ing" a Function, too. This example is almost the same as the previous one.
- [pre]
- var mySynth = { SinOsc.ar( freq:443, mul:0.2 ); }.play;
- [/pre]
+ <programlisting><![CDATA[var mySynth = { SinOsc.ar( freq:443, mul:0.2 ); }.play;]]></programlisting>
The difference is subtle: after the second example, we have no control over what name the interpreter gives to the SynthDef that it sends to the server, so we can't re-use the SynthDef. On the other hand, because we assign the name <code>\sillyTutorialSD</code> to the SynthDef in the first example, we know what it's called, and we can re-use it. Theoretically, we can make an infinite number of synths from this single definition. Realistically, it's limited by the amount of memory the server can use; for most modern computers, this number is so high that we don't ever need to worry about it.
</para>
<para>
As usual, the interpreter provides us with an optional short-cut:
- [pre]
- var mySynth = SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).play;
- [/pre]
+ <programlisting><![CDATA[var mySynth = SynthDef.new( \playMe, { Out.ar( 0, SinOsc.ar( freq:440, mul:0.2 ) ); } ).play;]]></programlisting>
This automatically sends the synthesis information to the server, creates a synth, and plays it. What minor functionality is lost when we use this shortcut?
</para>
</section>
@@ -2002,34 +2007,34 @@
<title>Shortcomings of a SynthDef</title>
<para>
Consider the following program:
- [pre]
- (
- var myRandFunc =
- {
- var frequency = 440.rand + 440; // produces an integer between 440 and 880
- SinOsc.ar( freq:frequency, mul:0.025 );
- };
-
- 10.do( { myRandFunc.play; } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ var frequency = 440.rand + 440; // produces an integer between 440 and 880
+ SinOsc.ar( freq:frequency, mul:0.025 );
+ };
+
+ 10.do( { myRandFunc.play; } );
+)
+]]></programlisting>
Execute the program a few times. The result will be different each time: ten different SinOsc's with ten different frequencies.
</para>
<para>
What if we convert the program to use a SynthDef and multiple Synth's instead? This program will probably cause an error the first time - this is exaplained below.
- [pre]
- (
- var myRandFunc =
- {
- var frequency = 440.rand + 440; // produces an integer between 440 and 880
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
-
- 10.do( { Synth.new( \myRandFunc ); } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ var frequency = 440.rand + 440; // produces an integer between 440 and 880
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+
+ 10.do( { Synth.new( \myRandFunc ); } );
+)
+]]></programlisting>
Execute the program a few times. The result is still different each time, but it's the ''same'' ten SinOsc's, all with the same frequency. This is the nature of a SynthDef: once it's sent to the server, you can create a synth from the same instructions without re-sending them.
</para>
<para>
@@ -2043,19 +2048,19 @@
</para>
<para>
The way to do this is with control-rate UGen's. The following example uses a control-rate SinOsc to set the frequency of an audio-rate SinOsc.
- [pre]
- (
- var myRandFunc =
- {
- var frequency = SinOsc.kr( freq:0.5, add:660, mul:220 ); // oscillates between 440 and 880, hitting each extreme every 2 seconds
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.2 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
-
- Synth.new( \myRandFunc );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ var frequency = SinOsc.kr( freq:0.5, add:660, mul:220 ); // oscillates between 440 and 880, hitting each extreme every 2 seconds
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.2 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+
+ Synth.new( \myRandFunc );
+)
+]]></programlisting>
When you use a UGen as a control-rate UGen, you have to think about its arguments quite differently than when using it as an audio-rate UGen. This table shows how the same argument gives a different result for an audio-rate vs. control-rate UGen used for pitch:
{|
! parameter !! audio-rate UGen !! control-rate UGen for pitch
@@ -2070,19 +2075,19 @@
</para>
<para>
There is a handy UGen designed specifically for replacing pseudo-randomness in Functions. The following example restores the "ten different pitches" to the example from the last section.
- [pre]
- (
- var myRandFunc =
- {
- var frequency = Rand( 440, 880 ); // produces an integer between 440 and 880
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
-
- 10.do( { Synth.new( \myRandFunc ); } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ var frequency = Rand( 440, 880 ); // produces an integer between 440 and 880
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+
+ 10.do( { Synth.new( \myRandFunc ); } );
+)
+]]></programlisting>
If you run this multiple times, you will again hear ten different pitches. Depending on audio hardware, previous musical experience, and other factors, some people may have difficulty hearing that the pitches are different. Try reducing the number of synths created in the loop.
</para>
</section>
@@ -2093,45 +2098,43 @@
</para>
<para>
With only a subtle change to our Function, we can add the possibility of passing arguments on synth creation:
- [pre]
- var myRandFunc =
- {
- arg frequency = Rand( 440, 880 ); // default value between 440 and 880
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
- [/pre]
+<programlisting><![CDATA[
+var myRandFunc =
+{
+ arg frequency = Rand( 440, 880 ); // default value between 440 and 880
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+};
+]]></programlisting>
I've decided to use the Rand UGen anyway, so that supplying a frequency is optional. This adds functionality while making the added complexity optional:
- [pre]
- (
- var myRandFunc =
- {
- arg frequency = 440;
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
-
- 10.do( { Synth.new( \myRandFunc ); } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ arg frequency = 440;
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+
+ 10.do( { Synth.new( \myRandFunc ); } );
+)
+]]></programlisting>
If you use the SynthDef in the old way, as in the example, you'll get the expected result: ten Synth's, all with the same frequency. But, if you add a "rand" Function call into the loop, you can get ten different frequencies!
- [pre]
- (
- var myRandFunc =
- {
- arg frequency = 440;
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
-
- 10.do( { Synth.new( \myRandFunc, [\frequency,(440.rand + 440)] ); } );
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var myRandFunc =
+ {
+ arg frequency = 440;
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+
+ 10.do( { Synth.new( \myRandFunc, [\frequency,(440.rand + 440)] ); } );
+)
+]]></programlisting>
Notice how we supply arguments: an Array with elements alternating between a string-quoted parameter name, and the value of the argument itself. If we "parameterized" all three main fields of the SinOsc, we could supply them like this:
- [pre]
- Synth.new( \mySinOsc, [\freq,440,\add,0,\mul,0.2] );
- [/pre]
+ <programlisting><![CDATA[Synth.new( \mySinOsc, [\freq,440,\add,0,\mul,0.2] );]]></programlisting>
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Set_and_Free">
@@ -2141,34 +2144,32 @@
</para>
<para>
To change the arguments used by a synth, send it the "set" message, with a list of arguments:
- [pre]
- variableHoldingSynth.set( [\argument1,value,\argument2,value,...] );
- [/pre]
+ <programlisting><replaceable>variableHoldingSynth</replaceable>.set( [<replaceable>\argument1</replaceable>,<replaceable>value</replaceable>,<replaceable>\argument2</replaceable>,<replaceable>value</replaceable>,...] );</programlisting>
This helps to save even more time and memory: rather than destroying and creating synths all the time, you can simply change pre-existing ones.
</para>
<para>
This modification of the ten-pseudo-random-tones example includes an extra line that lets you change the tones without destroying and re-creating the synths.
- [pre]
- // run this first
- h = List.new;
-
- // run this second
- (
- var myRandFunc =
- {
- arg frequency = 440;
- Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
- };
-
- SynthDef.new( \myRandFunc, myRandFunc ).send( s );
- )
-
- // run this third
- 10.do( { h.add( Synth.new( \myRandFunc, [\frequency,(440.rand + 440)] ) ); } );
-
- // run this fourth, as many times as you please
- h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
- [/pre]
+<programlisting><![CDATA[
+// run this first
+h = List.new;
+
+// run this second
+(
+ var myRandFunc =
+ {
+ arg frequency = 440;
+ Out.ar( 0, SinOsc.ar( freq:frequency, mul:0.025 ) );
+ };
+
+ SynthDef.new( \myRandFunc, myRandFunc ).send( s );
+)
+
+// run this third
+10.do( { h.add( Synth.new( \myRandFunc, [\frequency,(440.rand + 440)] ) ); } );
+
+// run this fourth, as many times as you please
+h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
+]]></programlisting>
The reason that you have to run each of those segments separately is two-fold: we need to store the List of Synth's in a single-letter variable because, for this simple demonstration, this is the most efficient way; second, for the asynchronous behaviour of the server that was previously noted as causing an error.
</para>
<para>
@@ -2176,24 +2177,18 @@
</para>
<para>
Take special note that the arguments in this case are not identical to those given with the "new" message. Compare the two forms below:
- [pre]
- SynthDef.new( \SynthName, [\parameter1,value,\parameter2,value] );
- [/pre]
+ <programlisting>SynthDef.new( <replaceable>\SynthName</replaceable>, [<replaceable>\parameter1</replaceable>,<replaceable>value</replaceable>,<replaceable>\parameter2</replaceable>,<replaceable>value</replaceable>] );</programlisting>
and
- [pre]
- existingSynth.set( \parameter1, value, \parmeter2, value );
- [/pre]
+ <programlisting><replaceable>existingSynth</replaceable>.set( <replaceable>\parameter1</replaceable>, <replaceable>value</replaceable>, <replaceable>\parmeter2</replaceable>, <replaceable>value</replaceable> );</programlisting>
</para>
<para>
To get rid of one synth without stopping all sound, send its corresponding Synth the "free" message:
- [pre]
- variableHoldingSynth.free;
- [/pre]
+ <programlisting><replaceable>variableHoldingSynth</replaceable>.free;</programlisting>
This stops the synth and frees the associated memory - on the server. Your Synth Object still exists in the interpreter, but you can't use it any more. A Synth Object represents a synth on the server; since you got rid of the synth on the server, the Synth Object represents something that doesn't exist. If you attempt to send the "free" message again, you'll get an error. For this reason, it's a good idea to get rid of the Synth Object at the same time:
- [pre]
- variableHoldingSynth.free;
- variableHoldingSynth = nil;
- [/pre]
+<programlisting><![CDATA[
+<replaceable>variableHoldingSynth</replaceable>.free;
+<replaceable>variableHoldingSynth</replaceable> = nil;
+]]></programlisting>
If you accidentally send "free" to an already-freed Synth, the interpreter will cause an error, and program execution will stop. If you accidentally send "free" to a variable set to "nil", nothing will happen. Proactively avoiding mistakes like this is good programming practice.
</para>
</section>
@@ -2202,7 +2197,7 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Busses">
<title>Busses</title>
<para>
- SuperCollider busses work just like busses in other audio creation contexts, which work similarly to busses used to transport humans. Busses are used to send audio from one place to another, and in SuperCollider they can also be used to send control-rate signals. Each SuperCollider bus is given an index number, which are integers starting at 0. Audio-rate busses and control-rate busses are independent, and are given an independent set of index numbers. Any number of unique signals can be routed into a bus, and any number of receivers can take signals from a bus - but the signal will be the sum of all the input signals. In other words, if you want to send two different sets of signals, you need two different busses with different index numbers.
+ <application>SuperCollider</application> busses work just like busses in other audio creation contexts, which work similarly to busses used to transport humans. Busses are used to send audio from one place to another, and in <application>SuperCollider</application> they can also be used to send control-rate signals. Each <application>SuperCollider</application> bus is given an index number, which are integers starting at 0. Audio-rate busses and control-rate busses are independent, and are given an independent set of index numbers. Any number of unique signals can be routed into a bus, and any number of receivers can take signals from a bus - but the signal will be the sum of all the input signals. In other words, if you want to send two different sets of signals, you need two different busses with different index numbers.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Busses-Audio_Rate_Bus_Numbers">
<title>Audio-Rate Bus Numbers</title>
@@ -2228,25 +2223,41 @@
The "Out" UGen is discussed in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Out_UGen" />. What it does is take a signal and route it to the specified bus number. The "In" UGen performs a similar action: take a signal from a bus number, and make it available for use.
</para>
<para>
- This is the syntax to use for "Out":
- [pre]
- Out.ar( busNumber, audioRateUGen );
- [/pre]
+ This is the syntax to use for the <classname>Out</classname> UGen:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Out.ar</function></funcdef>
+ <paramdef><parameter>busNumber</parameter></paramdef>
+ <paramdef><parameter>audioRateUGen</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
or
- [pre]
- Out.kr( busNumber, controlRateUGen );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Out.kr</function></funcdef>
+ <paramdef><parameter>busNumber</parameter></paramdef>
+ <paramdef><parameter>controlRateUGen</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
The UGen enclosed here should not be enclosed in a Function. If the UGen provides multi-channel output, "Out" will automatically route the lowest channel to the specified bus number, the next channel to the next highest bus number, and so on. This way, you can achieve stereo output with one "Out" UGen.
</para>
<para>
- This is the syntax to use for "In":
- [pre]
- In.ar( busNumber, numberOfChannels );
- [/pre]
+ This is the syntax to use for the <classname>In</classname> UGen:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>In.ar</function></funcdef>
+ <paramdef><parameter>busNumber</parameter></paramdef>
+ <paramdef><parameter>numberOfChannels</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
or
- [pre]
- In.kr( busNumber, numberOfChannels );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>In.kr</function></funcdef>
+ <paramdef><parameter>busNumber</parameter></paramdef>
+ <paramdef><parameter>numberOfChannels</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
Whereas "Out" automatically outputs the right number of channels based on how many you provide, "In" requires that you specify how many channels you want it to fetch for you.
</para>
<para>
@@ -2262,15 +2273,24 @@
The primary advantage of using Bus Objects is that you don't have to keep track of bus numbers, whether they're being used, and how mnany channels are being routed. For simple input and output of audio-rate signals, you're better off simply remembering the bus numbers
</para>
<para>
- The "new" message creates a new Bus. Here is the syntax:
- [pre]
- var myBusVariable = Bus.audio( serverName, numberOfChannels );
- [/pre]
+ The <literal>new</literal> message creates a new Bus object. This is the syntax:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Bus.audio</function></funcdef>
+ <paramdef><parameter>serverName</parameter></paramdef>
+ <paramdef><parameter>numberOfChannels</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
or
- [pre]
- var myBusVariable = Bus.control( serverName, numberOfChannels );
- [/pre]
- The interpreter takes "numberOfChannels" busses on the "serverName" server, and groups them together for multi-channel use in one Bus Object, which it returns to you. The "numberOfChannels" argument is optional; if you leave it out, the Bus Object will have only one bus, for single-channel signals.
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Bus.control</function></funcdef>
+ <paramdef><parameter>serverName</parameter></paramdef>
+ <paramdef><parameter>numberOfChannels</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ The interpreter takes "numberOfChannels" busses on the "serverName" server, and groups them together for multi-channel use in one Bus Object, which it returns to you. The "numberOfChannels" argument is optional; if you leave it out, the Bus Object will have only one bus, for single-channel signals. You should always assign the object to a variable, or else you have no way to use the bus later:
+ <programlisting><![CDATA[var myBus = Bus.audio( s, 2 );]]></programlisting>
</para>
<para>
The interpreter also keeps track of which bus numbers are used for which Bus Objects, so the signals will never get confused. Of course, you can still route signals through those bus numbers without using the Bus Object, but the Bus Class helps us to keep things straight.
@@ -2291,10 +2311,10 @@
</para>
<para>
When you are done with a Bus, you can release the channels for use by other Bus Objects:
- [pre]
- myBusVariable.free;
- myBusVariable = nil;
- [/pre]
+<programlisting><![CDATA[
+<replaceable>myBusVariable</replaceable>.free;
+<replaceable>myBusVariable</replaceable> = nil;
+]]></programlisting>
Like when sending the "free" message to a Synth Object, you should set the variable name of a "free'd" Bus to "nil". This will prevent you from accidentally sending audio there after the Bus is released.
</para>
</section>
@@ -2302,42 +2322,42 @@
<title>Using Busses: Control-Rate Example</title>
<para>
The best way to understand how and when to use a bus is to see them in action.
- [pre]
- ( // execute first: prepare the server
- var busAudioSynth =
- {
- arg bus, freqOffset = 0;
-
- Out.ar( 0, SinOsc.ar( freq:( In.kr(bus) + freqOffset ), mul:0.1 ) );
- };
-
- var busControlSynth =
- {
- arg bus, freq = 400;
-
- Out.kr( bus, SinOsc.kr( freq:1, mul:( freq/40 ), add:freq ) );
- };
-
- SynthDef( \tutorialAudioBus, busAudioSynth ).send( s );
- SynthDef( \tutorialControlBus, busControlSynth ).send( s );
-
- b = Bus.control( s );
- )
-
- ( // execute second: create synths
- x = Synth.new( \tutorialControlBus, [\bus, b] ); // control synth
- y = Synth.after( x, \tutorialAudioBus, [\bus, b] ); // low audio synth
- z = Synth.after( x, \tutorialAudioBus, [\bus, b, \freqOffset, 200] ); // high audio synth
- )
-
- ( // commands to free each Object
- x.free; x = nil; // control synth
- y.free; y = nil; // low audio synth
- z.free; z = nil; // high audio synth
- b.free; b = nil; // control bus
- )
- [/pre]
- This example contains three stages: prepare the server, create the synths, destroy the synths. These three stages will become familiar as you program in SuperCollider, whether or not you use busses frequently. The example is fairly complicated, so the code is explained here:
+<programlisting><![CDATA[
+( // execute first: prepare the server
+ var busAudioSynth =
+ {
+ arg bus, freqOffset = 0;
+
+ Out.ar( 0, SinOsc.ar( freq:( In.kr(bus) + freqOffset ), mul:0.1 ) );
+ };
+
+ var busControlSynth =
+ {
+ arg bus, freq = 400;
+
+ Out.kr( bus, SinOsc.kr( freq:1, mul:( freq/40 ), add:freq ) );
+ };
+
+ SynthDef( \tutorialAudioBus, busAudioSynth ).send( s );
+ SynthDef( \tutorialControlBus, busControlSynth ).send( s );
+
+ b = Bus.control( s );
+)
+
+( // execute second: create synths
+ x = Synth.new( \tutorialControlBus, [\bus, b] ); // control synth
+ y = Synth.after( x, \tutorialAudioBus, [\bus, b] ); // low audio synth
+ z = Synth.after( x, \tutorialAudioBus, [\bus, b, \freqOffset, 200] ); // high audio synth
+)
+
+( // commands to free each Object
+ x.free; x = nil; // control synth
+ y.free; y = nil; // low audio synth
+ z.free; z = nil; // high audio synth
+ b.free; b = nil; // control bus
+)
+]]></programlisting>
+ This example contains three stages: prepare the server, create the synths, destroy the synths. These three stages will become familiar as you program in <application>SuperCollider</application>, whether or not you use busses frequently. The example is fairly complicated, so the code is explained here:
<itemizedlist>
<listitem><para>"busAudioSynth" Function: Accepts two arguments, and creates an audio-rate <code>SinOsc</code>, routed to the left output channel. The frequency is determined by a control-rate bus given as an argument, and optionally with an offset that can be supplied as an argument.</para></listitem>
<listitem><para>"busControlSynth" Function: Accepts two arguments, and creates a control-rate <code>SinOsc</code>, routed to the bus given as an argument. Can also be given a frequency; the value produced by the synth is intended to be used to control pitch. The centre pitch of the oscillation is "freq", and the range of oscillation is one-twentieth the size of "freq" (one-fourtieth both higher and lower than "freq").</para></listitem>
@@ -2375,21 +2395,19 @@
<title>Special Note about Control-Rate Busses</title>
<para>
Control-rate Bus'ses are a great way to enhance the flexibility of your program. The best part is that, in order to use a control-rate Bus, the UGen doesn't even need to have been written to accomodate it.
- [pre]
- { SinOsc.ar( freq:In.kr( controlRateBus, 1 ), mul:0.2 ); }.play;
- [/pre]
+ <programlisting><![CDATA[{ SinOsc.ar( freq:In.kr( controlRateBus, 1 ), mul:0.2 ); }.play;]]></programlisting>
Now you've managed to spice up an otherwise-boring synth!
</para>
<para>
Also, control-rate Bus'ses don't need to be constantly changing. Unlike an audio-rate Bus, a control-rate Bus will hold the last-inputted value until another value is provided. You can the value of a control-rate Bus with the "set" message (and a single argument, which is the value). You can also get the current value, whether created by "set" or a UGen, by using the "get" message, and sending a Function with one argument.
- [pre]
- (
- var bus = Bus.control( s );
- bus.set( 12 );
- bus.get( { arg val; val.postln; } );
- bus.free; bus = nil;
- )
- [/pre]
+<programlisting><![CDATA[
+(
+ var bus = Bus.control( s );
+ bus.set( 12 );
+ bus.get( { arg val; val.postln; } );
+ bus.free; bus = nil;
+)
+]]></programlisting>
When running this example, you'll notice that the "12" doesn't get posted until ''after'' the program finishes with "nil". This is because of the '''latency''' between when the interpreter asks the server to do something, and when the server does it. The amount of time it takes for the server to complete a command is usually very small, but as you can see, it can make an important difference to your program. This latency is also the reason that you can't call "SynthDef.new( ... )" and "Synth.new( ... )" at the exact same time.
</para>
<para>
@@ -2399,91 +2417,92 @@
</section> <!-- Ends "Using Busses: Control-Rate Example" Section -->
<section id="sect-Musicians_Guide-SC-Basic_Programming-Busses-Audio_Rate_Bus_Example">
<title>Using Busses: Audio-Rate Example</title>
- <para>
- [pre]
- (
- var tutorialDecayPink =
- {
- arg outBus = 0, effectBus,
- direct = 0.5; // controls proportion of "direct" / "processed" sound
- var source;
-
- // Decaying pulses of PinkNoise.
- source = Decay2.ar( in:Impulse.ar( freq:1, phase:0.25 ),
- attackTime:0.01,
- decayTime:0.2,
- mul:PinkNoise.ar
- );
-
- Out.ar( outBus, (source*direct) ); // main output
- Out.ar( effectBus, (source*(1-direct)) ); // effects output
- };
-
- var tutorialDecaySine =
- {
- arg outBus = 0, effectBus,
- direct = 0.5; // controls proportion of "direct" / "processed" sound
- var source;
-
- // Decaying pulses of a modulating Sine wave.
- source = Decay2.ar( in:Impulse.ar( freq:0.3, phase: 0.25),
- attackTime:0.3,
- decayTime:1,
- mul:SinOsc.ar( freq:SinOsc.kr( freq:0.2, mul:110, add:440) )
- );
-
- Out.ar(outBus, (source*direct) ); // main output
- Out.ar(effectBus, (source*(1-direct)) ); // effects output
- };
-
- var tutorialReverb =
- {
- arg outBus = 0, inBus; // default outBus is audio interface
- var input;
-
- input = In.ar( inBus, 1 );
-
- 16.do( { input = AllpassC.ar( in:input,
- maxdelaytime:0.04,
- delaytime:{ Rand(0.001,0.04) }.dup,
- decaytime:3
- )
- }
- );
-
- Out.ar( outBus, input );
- };
-
- // send synthesis information to the server
- SynthDef( \tutorialReverb, tutorialReverb ).send( s );
- SynthDef( \tutorialDecayPink, tutorialDecayPink ).send( s );
- SynthDef( \tutorialDecaySine, tutorialDecaySine ).send( s );
-
- // reserve an effects Bus
- b = Bus.audio( s );
- )
-
- (
- x = Synth.new( \tutorialReverb, [\inBus, b] );
- y = Synth.before( x, \tutorialDecayPink, [\effectBus, b] );
- z = Synth.before( x, \tutorialDecaySine, [\effectBus, b, \outBus, 1] );
- )
-
- // Change the balance of "wet" to "dry"
- y.set( \direct, 1 ); // only direct PinkNoise
- z.set( \direct, 1 ); // only direct Sine wave
- y.set( \direct, 0 ); // only reverberated PinkNoise
- z.set( \direct, 0 ); // only reverberated Sine wave
- y.set( \direct, 0.5 ); // original PinkNoise
- z.set( \direct, 0.5 ); // original Sine wave
-
- ( // commands to free each Object
- x.free; x = nil;
- y.free; y = nil;
- z.free; z = nil;
- b.free; b = nil;
- )
- [/pre]
+ <!-- <xi:include parse="text" href="examples/Busses-Audio_Rate.sc" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <para>
+<programlisting><![CDATA[
+(
+ var tutorialDecayPink =
+ {
+ arg outBus = 0, effectBus,
+ direct = 0.5; // controls proportion of "direct" / "processed" sound
+ var source;
+
+ // Decaying pulses of PinkNoise.
+ source = Decay2.ar( in:Impulse.ar( freq:1, phase:0.25 ),
+ attackTime:0.01,
+ decayTime:0.2,
+ mul:PinkNoise.ar
+ );
+
+ Out.ar( outBus, (source*direct) ); // main output
+ Out.ar( effectBus, (source*(1-direct)) ); // effects output
+ };
+
+ var tutorialDecaySine =
+ {
+ arg outBus = 0, effectBus,
+ direct = 0.5; // controls proportion of "direct" / "processed" sound
+ var source;
+
+ // Decaying pulses of a modulating Sine wave.
+ source = Decay2.ar( in:Impulse.ar( freq:0.3, phase: 0.25),
+ attackTime:0.3,
+ decayTime:1,
+ mul:SinOsc.ar( freq:SinOsc.kr( freq:0.2, mul:110, add:440) )
+ );
+
+ Out.ar(outBus, (source*direct) ); // main output
+ Out.ar(effectBus, (source*(1-direct)) ); // effects output
+ };
+
+ var tutorialReverb =
+ {
+ arg outBus = 0, inBus; // default outBus is audio interface
+ var input;
+
+ input = In.ar( inBus, 1 );
+
+ 16.do( { input = AllpassC.ar( in:input,
+ maxdelaytime:0.04,
+ delaytime:{ Rand(0.001,0.04) }.dup,
+ decaytime:3
+ )
+ }
+ );
+
+ Out.ar( outBus, input );
+ };
+
+ // send synthesis information to the server
+ SynthDef( \tutorialReverb, tutorialReverb ).send( s );
+ SynthDef( \tutorialDecayPink, tutorialDecayPink ).send( s );
+ SynthDef( \tutorialDecaySine, tutorialDecaySine ).send( s );
+
+ // reserve an effects Bus
+ b = Bus.audio( s );
+)
+
+(
+ x = Synth.new( \tutorialReverb, [\inBus, b] );
+ y = Synth.before( x, \tutorialDecayPink, [\effectBus, b] );
+ z = Synth.before( x, \tutorialDecaySine, [\effectBus, b, \outBus, 1] );
+)
+
+// Change the balance of "wet" to "dry"
+y.set( \direct, 1 ); // only direct PinkNoise
+z.set( \direct, 1 ); // only direct Sine wave
+y.set( \direct, 0 ); // only reverberated PinkNoise
+z.set( \direct, 0 ); // only reverberated Sine wave
+y.set( \direct, 0.5 ); // original PinkNoise
+z.set( \direct, 0.5 ); // original Sine wave
+
+( // commands to free each Object
+ x.free; x = nil;
+ y.free; y = nil;
+ z.free; z = nil;
+ b.free; b = nil;
+)
+]]></programlisting>
</para>
<para>
I'm not going to explain this example as extensively as the previous one. It's definitely the most complex example so far. It's better if you figure out what the parts do by playing with them yourself. The bus works by routing audio from the <code>\tutorialDecayPink</code> and <code>\tutorialDecaySine</code> synths into the <code>\tutorialReverb</code> synth. The first two synths can be controlled to put all, none, or some of their signal into the bus (so that it goes through the <code>\tutorialReverb</code> synth), or straight out the audio interface (bypassing the <code>\tutorialReverb</code> synth). Notice that the ''same'' effects processor is operating on two different input sources.
@@ -2503,58 +2522,66 @@
</para>
<para>
Consider the following example:
- [pre]
- { SinOsc.ar( freq:SinOsc.kr( freq:1, add:500, mul:10 ), mul:0.2 ); }.play;
- [/pre]
+ <programlisting><![CDATA[{ SinOsc.ar( freq:SinOsc.kr( freq:1, add:500, mul:10 ), mul:0.2 ); }.play;]]></programlisting>
What happens if the server calculates the audio-rate UGen first? It wouldn't have a frequency. This is another one of those things which the interpreter takes care of automatically when we run Function rather than create a Synth. Since it's often preferable to use a synth instead of a Function, we need some way to control the order of execution. The interpreter and the server are only so good at guessing what we need, after all.
</para>
<para>
- There are two methods in the Synth Class that we can use to inform the server about our desired order of execution: "before" and "after". They represent a small extension to the "new" method, and they work like this:
- [pre]
- Synth.before( variableHoldingSynth, nameOfSynthDef, ListOfArguments );
- [/pre]
+ There are two methods in the <classname>Synth</classname> Class that we can use to inform the server about our desired order of execution: "before" and "after". They represent a small extension to the "new" method, and they work like this:
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Synth.before</function></funcdef>
+ <paramdef><parameter>variableHoldingSynth</parameter></paramdef>
+ <paramdef><parameter>nameOfSynthDef</parameter></paramdef>
+ <paramdef><parameter>ListOfArguments</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
and
- [pre]
- Synth.after( variableHoldingSynth, nameOfSynthDef, ListOfArguments );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>Synth.after</function></funcdef>
+ <paramdef><parameter>variableHoldingSynth</parameter></paramdef>
+ <paramdef><parameter>nameOfSynthDef</parameter></paramdef>
+ <paramdef><parameter>ListOfArguments</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
And it works just as it looks, too: the server creates a new synth, adds it before or after the synth represented by "variableHoldingSynth" (depending on which Function you use), and uses "nameOfSynthDef" and "ListOfArguments" just as in the "add" method.
This example, from <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Busses-Control_Rate_Bus_Example" />, uses the "after" Function to ensure that the control-rate synth is calculated before the audio-rate synths that depend on it.
- [pre]
- ( // execute first: prepare the server
- var busAudioSynth =
- {
- arg bus, freqOffset = 0;
-
- Out.ar( 0, SinOsc.ar( freq:( In.kr(bus) + freqOffset ), mul:0.1 ) );
- };
-
- var busControlSynth =
- {
- arg bus, freq = 400;
-
- Out.kr( bus, SinOsc.kr( freq:1, mul:( freq/40 ), add:freq ) );
- };
-
- SynthDef( \tutorialAudioBus, busAudioSynth ).send( s );
- SynthDef( \tutorialControlBus, busControlSynth ).send( s );
-
- b = Bus.control( s );
- )
-
- ( // execute second: create synths
- x = Synth.new( \tutorialControlBus, [\bus, b] ); // control synth
- y = Synth.after( x, \tutorialAudioBus, [\bus, b] ); // low audio synth
- z = Synth.after( x, \tutorialAudioBus, [\bus, b, \freqOffset, 200] ); // high audio synth
- )
-
- ( // commands to free each Object
- x.free; x = nil; // control synth
- y.free; y = nil; // low audio synth
- z.free; z = nil; // high audio synth
- b.free; b = nil; // control bus
- )
- [/pre]
+<programlisting><![CDATA[
+( // execute first: prepare the server
+ var busAudioSynth =
+ {
+ arg bus, freqOffset = 0;
+
+ Out.ar( 0, SinOsc.ar( freq:( In.kr(bus) + freqOffset ), mul:0.1 ) );
+ };
+
+ var busControlSynth =
+ {
+ arg bus, freq = 400;
+
+ Out.kr( bus, SinOsc.kr( freq:1, mul:( freq/40 ), add:freq ) );
+ };
+
+ SynthDef( \tutorialAudioBus, busAudioSynth ).send( s );
+ SynthDef( \tutorialControlBus, busControlSynth ).send( s );
+
+ b = Bus.control( s );
+)
+
+( // execute second: create synths
+ x = Synth.new( \tutorialControlBus, [\bus, b] ); // control synth
+ y = Synth.after( x, \tutorialAudioBus, [\bus, b] ); // low audio synth
+ z = Synth.after( x, \tutorialAudioBus, [\bus, b, \freqOffset, 200] ); // high audio synth
+)
+
+( // commands to free each Object
+ x.free; x = nil; // control synth
+ y.free; y = nil; // low audio synth
+ z.free; z = nil; // high audio synth
+ b.free; b = nil; // control bus
+)
+]]></programlisting>
In this case, the control-rate synth is created before the audio-rate synths - probably the easier way to think about it. Even so, it's possible to add them in the opposite order with a little extra thought.
</para>
<para>
@@ -2564,19 +2591,25 @@
<section id="sect-Musicians_Guide-C-Basic_Programming-Ordering_and_Other_Features-Changing_the_Order">
<title>Changing the Order</title>
<para>
- SuperCollider offers equally easy-to-use methods to change the order of execution.
+ <application>SuperCollider</application> offers equally easy-to-use methods to change the order of execution.
</para>
<para>
To move a synth's execution after another:
- [pre]
- variableHoldingSynth.moveAfter( variableHoldingAnotherSynth );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><replaceable>variableHoldingSynth</replaceable><function>moveAfter</function></funcdef>
+ <paramdef><parameter>variableHoldingAnotherSynth</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
</para>
<para>
To move a synth's execution before another:
- [pre]
- variableHoldingSynth.moverBefore( variableHoldingAnotherSynth );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><replaceable>variableHoldingSynth</replaceable><function>moveBefore</function></funcdef>
+ <paramdef><parameter>variableHoldingAnotherSynth</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
</para>
</section>
<section id="sect-Musicians_Guide-C-Basic_Programming-Ordering_and_Other_Features-Replace_a_Running_Synth">
@@ -2586,9 +2619,7 @@
</para>
<para>
This is the syntax:
- [pre]
- variableHoldingNewSynth = Synth.replace( variableHoldingSynthToReplace, nameOfSynthDef, ListOfArguments );
- [/pre]
+ <programlisting><![CDATA[variableHoldingNewSynth = Synth.replace( variableHoldingSynthToReplace, nameOfSynthDef, ListOfArguments );]]></programlisting>
The "variableHoldingNewSynth" will often be the same as the "variableHoldingSynthToReplace," but not always. When you use this Function, the synth being replaced is freed from the server (equivalent to running "free"), so that variable should always be assigned something.
</para>
</section>
@@ -2599,15 +2630,11 @@
</para>
<para>
To pause a synth:
- [pre]
- variableHoldingSynth.run( false );
- [/pre]
+ <programlisting><replaceable>variableHoldingSynth</replaceable>.run( false );</programlisting>
</para>
<para>
To re-start a synth:
- [pre]
- variableHoldingSynth.run( true );
- [/pre]
+ <programlisting><replaceable>variableHoldingSynth</replaceable>.run( true );</programlisting>
</para>
</section>
</section> <!-- Ends "Ordering and Other Synth Features" Section --> <!-- SC-Basic_Programming-Ordering_and_Other_Features- -->
@@ -2634,16 +2661,14 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Scheduling-Default_Clocks">
<title>Default Clocks</title>
<para>
- The SuperCollider interpreter provides two default clocks, and one default pseudo-clock.
+ The <application>SuperCollider</application> interpreter provides two default clocks, and one default pseudo-clock.
</para>
<para>
The <code>SystemClock</code> always operates in seconds, and it can be used to schedule musical events, but usually this isn't necessary.
</para>
<para>
The <code>TempoClock.default</code> runs at 60 beats-per-minute by default (equal to one beat per second). Since it's accessible from anywhere within a program, any tempo changes will have an effect on the scheduling of the entire program - so be careful! If you don't want something to be effected by tempo changes, you can create a new TempoClock just for that part of the program. If you will be using this clock frequently, you can assign it to a variable like this:
- [pre]
- var t = TempoClock.default;
- [/pre]
+ <programlisting><![CDATA[var t = TempoClock.default;]]></programlisting>
</para>
<para>
The <code>thisThread.clock</code> is not really a clock in itself, but refers to the clock which is responsible for scheduling the part of the program where the command is written. It can be a little bit tricky working with this clock, since it may be either the SystemClock or a TempoClock.
@@ -2653,11 +2678,11 @@
<title>Finding the Current Time</title>
<para>
Using the "beats" method on a clock will return that clock's current time. Try running each of the following:
- [pre]
- SystemClock.beats;
- TempoClock.default.beats;
- thisThread.clock.beats;
- [/pre]
+<programlisting><![CDATA[
+SystemClock.beats;
+TempoClock.default.beats;
+thisThread.clock.beats;
+]]></programlisting>
</para>
<para>
This can be useful for scheduling events in an absolute way, or for a number of other things.
@@ -2670,17 +2695,17 @@
</para>
<para>
To schedule things on a clock, use the "sched" Function:
- [pre]
- nameOfClock.sched( beatsFromNow, FunctionToExecute );
- [/pre]
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><replaceable>nameOfClock</replaceable><function>sched</function></funcdef>
+ <paramdef><parameter>beatsFromNow</parameter></paramdef>
+ <paramdef><parameter>FunctionToExecute</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
The interpreter will let you schedule just about anything, but there's no point in scheduling something other than a Function: scheduling a five won't have any effect - try it!
- [pre]
- SystemClock.sched( 5, 5 );
- [/pre]
- It looks like nothing happens. The 5 does happen, but... well... it doesn't do anything. Scheduling a Function ''will'' do something:
- [pre]
- SystemClock.sched( 5, { 5.postln; } );
- [/pre]
+ <programlisting><![CDATA[SystemClock.sched( 5, 5 );]]></programlisting>
+ It looks like nothing happens. The <literal>5</literal> does happen, but... well... it doesn't do anything. Scheduling a Function ''will'' do something:
+ <programlisting><![CDATA[SystemClock.sched( 5, { 5.postln; } );]]></programlisting>
When you run this, there are two things to notice:
<itemizedlist>
<listitem><para>The interpreter prints out "SystemClock" first. This is to let you know that it did the scheduling as requested.</para></listitem>
@@ -2695,16 +2720,12 @@
</para>
<para>
This will print "5" every five seconds, until you press [Esc] to stop execution.
- [pre]
- SystemClock.sched( 5, { 5.postln; } );
- [/pre]
+ <programlisting><![CDATA[SystemClock.sched( 5, { 5.postln; } );]]></programlisting>
</para>
<para>
- To avoid this, you can end your Function with "nil", which has been done sometimes through this guide.
- [pre]
- SystemClock.sched( 5, { 5.postln; nil; } );
- [/pre]
- This will print "5" in five seconds, and then stop.
+ To avoid this, you can end your Function with <literal>nil</literal>, which has been done sometimes through this guide.
+ <programlisting><![CDATA[SystemClock.sched( 5, { 5.postln; nil; } );]]></programlisting>
+ This will print <literal>5</literal> in five seconds, and then stop.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Scheduling-TempoClock_Class">
@@ -2713,42 +2734,34 @@
Here is a brief explanation of some Functions available with the TempoClock Class. Throughout this section, the variable "t" is used to represent any particular TempoClock.
</para>
<para>
- [pre]
- var t = TempoClock.new( tempo, beats );
- [/pre]
+ <programlisting><![CDATA[var t = TempoClock.new( tempo, beats );]]></programlisting>
This creates a new TempoClock. The arguments are optional, and have the following meanings:
- * tempo: tempo of the clock, given in beats per second. To input a value in beats-per-minute, divide it by 60. Defaults to 60 beats per minute, or one per second.
- * beats: starts the clock at this time. Default is zero.
+ <itemizedlist>
+ <listitem><para>tempo: tempo of the clock, given in beats per second. To input a value in beats-per-minute, divide it by 60. Defaults to 60 beats per minute, or one per second.</para></listitem>
+ <listitem><para>beats: starts the clock at this time. Default is zero.</para></listitem>
+ </itemizedlist>
</para>
<para>
- [pre]
- t.stop;
- t = nil;
- [/pre]
+<programlisting><![CDATA[
+t.stop;
+t = nil;
+]]></programlisting>
Equivalent to the "free" method for a Synth of Bus Object. This stops the clock, discards all scheduled events, and releases the resources used to run the clock. Setting the variable to "nil" afterwards is optional, but recommended, to avoid later programming mistakes.
</para>
<para>
- [pre]
- t.clear;
- [/pre]
+ <programlisting><replaceable>t</replaceable>.clear;</programlisting>
Discards all scheduled events, but keeps the clock running.
</para>
<para>
- [pre]
- t.tempo;
- [/pre]
+ <programlisting><replaceable>t</replaceable>.tempo;</programlisting>
Returns the current tempo in beats-per-second.
</para>
<para>
- [pre]
- t.tempo_( newTempo );
- [/pre]
+ <programlisting><replaceable>t</replaceable>.tempo_( <replaceable>newTempo</replaceable> );</programlisting>
Allows you to change the clock's tempo. The new tempo should be in beats-per-second. To input a tempo in beats-per-minute, divide the value by 60.
</para>
<para>
- [pre]
- t.play( Function );
- [/pre]
+ <programlisting><replaceable>t</replaceable>.play( <replaceable>aFunction</replaceable> );</programlisting>
Schedules the Function to begin execution on the next beat.
</para>
<para>
@@ -2760,18 +2773,18 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Getting_Help">
<title>How to Get Help</title>
<para>
- Knowing how to get help in SuperCollider is going to play a large part in determining whether you have a productive or frustrating relationship with the language and its components. There are a large number of ways to get help, but here are some of the most helpful.
+ Knowing how to get help in <application>SuperCollider</application> is going to play a large part in determining whether you have a productive or frustrating relationship with the language and its components. There are a large number of ways to get help, but here are some of the most helpful.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Getting_Help-Official_Help_Files">
- <title>Use the SuperCollider Help Files</title>
+ <title>Use the <application>SuperCollider</application> Help Files</title>
<para>
- SuperCollider comes with an extensive collection of help files, which contain the answers to most of your problems. The difficulty will be in finding the solution - it's not always located where you think it is, because it often isn't the solution you think it will be.
+ <application>SuperCollider</application> comes with an extensive collection of help files, which contain the answers to most of your problems. The difficulty will be in finding the solution - it's not always located where you think it is, because it often isn't the solution you think it will be.
</para>
<para>
On Fedora Linux systems, the main help file is located at [file:///usr/share/SuperCollider/Help/Help.html this URL], and it can be viewed in any web browser. It may also be helpful to browse the directory structure of the help files, located at [file:///usr/share/SuperCollider/Help this URL], which can also be viewed in your web browser.
</para>
<para>
- If you're looking for further explanations of material in this tutorial, you could start by reviewing the [file:///usr/share/SuperCollider/Help/Tutorials/Getting-Started/Getting%20Started%20With%20SC.html Getting Started With SuperCollider] tutorial, on which this document is based. The sections in that tutorial roughly correspond to the sections in this guide.
+ If you're looking for further explanations of material in this tutorial, you could start by reviewing the [file:///usr/share/SuperCollider/Help/Tutorials/Getting-Started/Getting%20Started%20With%20SC.html Getting Started With <application>SuperCollider</application>] tutorial, on which this document is based. The sections in that tutorial roughly correspond to the sections in this guide.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Getting_Help-IRC">
@@ -2787,9 +2800,9 @@
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Getting_Help-SuperCollider_Website">
- <title>The SuperCollider Website</title>
+ <title>The <application>SuperCollider</application> Website</title>
<para>
- The <citetitle>SuperCollider Website</citetitle> at SourceForge (<ulink url="http://supercollider.sourceforge.net/" />) offers links to many resources.
+ The <citetitle><application>SuperCollider</application> Website</citetitle> at SourceForge (<ulink url="http://supercollider.sourceforge.net/" />) offers links to many resources.
</para>
</section>
</section> <!-- Ends "How to Get Help" Section --> <!-- SC-Basic_Programming-Getting_Help- -->
@@ -2797,13 +2810,13 @@
<section id="sect-Musicians_Guide-SC-Basic_Programming-Legal_Attribution">
<title>Legal Attribution</title>
<para>
- This portion of the Fedora Musicians' Guide, called "Basic Programming with SuperCollider," is a derivative work of the, <citetitle>Getting Started With SuperCollider</citetitle> tutorial. The original work was created by Scott Wilson, James Harkins, and the SuperCollider development team. It is available on the internet from <ulink url="http://supercollider.svn.sourceforge.net/viewvc/supercollider/trunk/common/build/Help/Tutorials/Getting-Started/Getting%20Started%20With%20SC.html" />.
+ This portion of the Fedora Musicians' Guide, called "Basic Programming with <application>SuperCollider</application>," is a derivative work of the, <citetitle>Getting Started With <application>SuperCollider</application></citetitle> tutorial. The original work was created by Scott Wilson, James Harkins, and the <application>SuperCollider</application> development team. It is available on the internet from <ulink url="http://supercollider.svn.sourceforge.net/viewvc/supercollider/trunk/common/build/Help/Tutorials/Getting-Started/Getting%20Started%20With%20SC.html" />.
</para>
<para>
- The original document, like all SuperCollider documentation, is licenced under the Creative Commons' <citetitle>Attribution Share-Alike 3.0 Unported Licence</citetitle>, accessible on the internet at <ulink url="http://creativecommons.org/licenses/by-sa/3.0/" />.
+ The original document, like all <application>SuperCollider</application> documentation, is licenced under the Creative Commons' <citetitle>Attribution Share-Alike 3.0 Unported Licence</citetitle>, accessible on the internet at <ulink url="http://creativecommons.org/licenses/by-sa/3.0/" />.
</para>
<para>
- This usage should in no way be construed as an endorsement of the Fedora Project, the Musicians' Guide, or any other party by the SuperCollider development team.
+ This usage should in no way be construed as an endorsement of the Fedora Project, the Musicians' Guide, or any other party by the <application>SuperCollider</application> development team.
</para>
</section> <!-- Ends "Legal Attribution" Section --> <!-- SC-Basic_Programming-Legal_Attribution- -->
-</section> <!-- End "Basic Programming with SuperCollider -->
\ No newline at end of file
+</section> <!-- End "Basic Programming with <application>SuperCollider</application> -->
\ No newline at end of file
diff --git a/en-US/SuperCollider/SuperCollider-Composing.xml b/en-US/SuperCollider/SuperCollider-Composing.xml
index d1bd1c6..5669b5c 100644
--- a/en-US/SuperCollider/SuperCollider-Composing.xml
+++ b/en-US/SuperCollider/SuperCollider-Composing.xml
@@ -53,23 +53,31 @@
<step><para>I started with something simple: a single SinOsc: <code>{ SinOsc.ar(); }.play;</code></para></step>
<step><para>This is not exciting: it just stays the same forever, and it only uses one channel! So, I added another SinOsc to the right channel, using the [ , ] array notation. The result is <code>{ [ SinOsc.ar(), SinOsc.ar() ] }.play;</code></para></step>
<step><para>Now it sounds balanced, at least, like it's coming from the middle. But it's still boring, so I added a frequency-changing SinOsc to the right channel, resulting in <code>{ [ SinOsc.ar(), SinOsc.ar(SinOsc.kr(1,50,300)) ] }.play;</code></para></step>
- <step><para>Since that's difficult to read, and since I know that I'm just going to keep adding things, I expand the code a little bit to make it more legible. This gives me [pre]{
- var left = SinOsc.ar();
- var right = SinOsc.ar( SinOsc.kr( 1, 50, 300 ) );
-
- [ left, right ]
-
- }.play;[/pre]I define a variable holding everything I want in the left channel, then the same for the right. I still use the [ , ] array notation to create a stereo array. Remember that SuperCollider functions return the last value stated, so it might look like the stereo array is ignored, but because this array is what is returned by the function contained between { and }, it is this array that gets played by the following ".play;"</para></step>
- <step><para>I also added a frequency controller to the left SinOsc, and realized that it's getting a bit difficult to read again, especially if I wanted to add another parameter to the SinOsc.ar objects. So I placed the SinOsc.kr's into their own variables: frequencyL and frequencyR. This results in [pre]{
- var frequencyL = SinOsc.kr( freq:10, mul:200, add:400 );
- var frequencyR = SinOsc.kr( freq:1, mul:50, add:150 );
-
- var left = SinOsc.ar( frequencyL );
- var right = SinOsc.ar( frequencyR );
-
- [ left, right ]
-
- }.play;[/pre]</para></step>
+ <step><para>Since that's difficult to read, and since I know that I'm just going to keep adding things, I expand the code a little bit to make it more legible. This gives me
+<programlisting><![CDATA[
+{
+ var left = SinOsc.ar();
+ var right = SinOsc.ar( SinOsc.kr( 1, 50, 300 ) );
+
+ [ left, right ]
+
+}.play;
+]]></programlisting>
+ I define a variable holding everything I want in the left channel, then the same for the right. I still use the [ , ] array notation to create a stereo array. Remember that SuperCollider functions return the last value stated, so it might look like the stereo array is ignored, but because this array is what is returned by the function contained between { and }, it is this array that gets played by the following ".play;"</para></step>
+ <step><para>I also added a frequency controller to the left SinOsc, and realized that it's getting a bit difficult to read again, especially if I wanted to add another parameter to the SinOsc.ar objects. So I placed the SinOsc.kr's into their own variables: frequencyL and frequencyR. This results in
+<programlisting><![CDATA[
+{
+ var frequencyL = SinOsc.kr( freq:10, mul:200, add:400 );
+ var frequencyR = SinOsc.kr( freq:1, mul:50, add:150 );
+
+ var left = SinOsc.ar( frequencyL );
+ var right = SinOsc.ar( frequencyR );
+
+ [ left, right ]
+
+}.play;
+]]></programlisting>
+ </para></step>
<step><para>Now I can experiment with the frequency-changing SinOsc's, to make sure that I get things just right. When I realize what the parameters do, I make a note for myself (see "FSC-method-1-.sc"), so that it will be easy to adjust it later. I also explicitly call the parameters. This isn't necessary, but it also helps to avoid future confusion. Most programmers would not explicitly call the parameters, but we're musicians, not programmers.</para></step>
<step><para>The left channel has something like a "melody," so I decided to add a drone-like SinOsc to it. This is easy, of course, because any SinOsc left alone is automatically a drone! But, where should it be added? Into the "left" variable, of course. We'll create an array using [ , ] array notation. There are two things that I would do at this point to help with future readability:</para>
<substeps>
@@ -120,106 +128,132 @@
<title>Creating Ten Pseudo-Random Tones</title>
<procedure>
<step><para>We'll start again with something simple, that we know how to do.
- [pre]{
- SinOsc.ar();
- }.play;[/pre]</para></step>
+<programlisting><![CDATA[
+{
+ SinOsc.ar();
+}.play;
+]]></programlisting>
+ </para></step>
<step><para>We already know that we want this to produce stereo output, and we already know that we're going to be using enough SinOsc's that we'll need to reduce "mul." Keeping in mind that there will be ten pitches, and two SinOsc's for each of them, set both of those things now, keeping just one pitch for now.</para></step>
<step><para>The first challenge is to implement pseudo-randomness. We'll use the number.rand function to generate a pseudo-random number (integer, actually), but if run as <code>50.rand</code>, we will get a result between 0 and 50. As a frequency, this is not useful: most audio equipment cannot produce pitches below 20 Hz, and many people have problems hearing very low frequencies. This means that we'll need to add a value to .rand's output (like <code>100 + 50.rand</code>, which will yield an integer between 100 and 150). I decided to go with a value between 200 Hz and 800 Hz instead, largely because I felt like it. Try setting the freq with the .rand call.</para></step>
<step><para>I hope you didn't end up with two different frequencies! If you did, you'll need to use a variable to temporarily store the pseduo-random frequency, so that both sides can use it.</para></step>
- <step><para>Now we need to make ten of these, so copy-and-paste until there are ten different stereo pitches at once.[pre]{
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
- }.play;[/pre]</para></step>
- <step><para>It doesn't work: you'll also have to rename your frequency-setting variable each time.[pre]{
- var frequency1 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]
- var frequency2 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ]
- var frequency3 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ]
- var frequency4 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ]
- var frequency5 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ]
- var frequency6 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ]
- var frequency7 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ]
- var frequency8 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ]
- var frequency9 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ]
- var frequency0 = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ]
- }.play;[/pre]</para></step>
- <step><para>It still doesn't work! The error given in the "SuperCollider output" window is not easy to understand, but it means "You have to put all of your variable declarations before everything else."[pre]{
- var frequency1 = 200 + 600.rand;
- var frequency2 = 200 + 600.rand;
- var frequency3 = 200 + 600.rand;
- var frequency4 = 200 + 600.rand;
- var frequency5 = 200 + 600.rand;
- var frequency6 = 200 + 600.rand;
- var frequency7 = 200 + 600.rand;
- var frequency8 = 200 + 600.rand;
- var frequency9 = 200 + 600.rand;
- var frequency0 = 200 + 600.rand;
-
- [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ]
- [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ]
- }.play;[/pre]</para></step>
+ <step><para>Now we need to make ten of these, so copy-and-paste until there are ten different stereo pitches at once.
+<programlisting><![CDATA[
+{
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ]
+}.play;
+]]></programlisting>
+ </para></step>
+ <step><para>It doesn't work: you'll also have to rename your frequency-setting variable each time.
+<programlisting><![CDATA[
+{
+ var frequency1 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]
+ var frequency2 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ]
+ var frequency3 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ]
+ var frequency4 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ]
+ var frequency5 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ]
+ var frequency6 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ]
+ var frequency7 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ]
+ var frequency8 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ]
+ var frequency9 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ]
+ var frequency0 = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ]
+}.play;
+]]></programlisting>
+ </para></step>
+ <step><para>It still doesn't work! The error given in the "SuperCollider output" window is not easy to understand, but it means "You have to put all of your variable declarations before everything else."
+<programlisting><![CDATA[
+{
+ var frequency1 = 200 + 600.rand;
+ var frequency2 = 200 + 600.rand;
+ var frequency3 = 200 + 600.rand;
+ var frequency4 = 200 + 600.rand;
+ var frequency5 = 200 + 600.rand;
+ var frequency6 = 200 + 600.rand;
+ var frequency7 = 200 + 600.rand;
+ var frequency8 = 200 + 600.rand;
+ var frequency9 = 200 + 600.rand;
+ var frequency0 = 200 + 600.rand;
+
+ [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ]
+ [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ]
+}.play;
+]]></programlisting>
+ </para></step>
<step><para>It still doesn't work! SuperCollider is confused because I was been lazy and didn't include enough semicolons. The error we get is, "Index not an Integer," which is a clue as to what SuperCollider is trying to do (but it's irrelevant). The real problem is that SuperCollider interprets our ten stereo arrays as all being part of the same statement. We don't want them to be the same statement, however, because we want ten ''different'' stereo arrays to be played. Fix this problem by putting a semicolon at the end of each stereo array. You don't ''need'' to include one at the end of the last statement, because SuperCollider assumes the end of the statement when it encounters a } (end-of-function marker) after it. Since we're still building our code, we might move these around or add something aftwards, so it's better to include a semicolon at the end of each stereo array.</para></step>
<step><para>Now the file plays successfully, but with a disappointing result. If you can't already see the problem, try to think of it before continuing to read.</para></step>
<step><para>Only one SinOsc array gets played, and it's the last one. This is because the last statement is returned by the function that ends at } and it is that result which gets sent to the following .play</para></step>
- <step><para>To fix this, and ensure that all of the stereo arrays are played, you should remove the .play from the end of the function, and add a .play to each stereo array statement. You end up with [pre]{
- var frequency1 = 200 + 600.rand;
- var frequency2 = 200 + 600.rand;
- var frequency3 = 200 + 600.rand;
- var frequency4 = 200 + 600.rand;
- var frequency5 = 200 + 600.rand;
- var frequency6 = 200 + 600.rand;
- var frequency7 = 200 + 600.rand;
- var frequency8 = 200 + 600.rand;
- var frequency9 = 200 + 600.rand;
- var frequency0 = 200 + 600.rand;
-
- [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ].play;
- [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ].play;
- }[/pre]</para></step>
- <step><para>When you execute this, no sound is produced, but SuperCollider outputs "a Function." Can you think of why this happens? It's because you wrote a function, but never told SuperCollider to evaluate it! At the end of execution, SuperCollider just throws away the function, because it's never used. This is the same thing that happened to the first nine stereo arrays - they were created, but you never said to do anything with them, so they were just thrown out. We need to execute the function. Because it doesn't produce a UGen, we can't use "play," so we have to use "value" instead. You can choose to do either of these:[pre]{ ... }.value;[/pre] or [pre]var myFunction = { ... }; myFunction.value;[/pre]</para></step>
+ <step><para>To fix this, and ensure that all of the stereo arrays are played, you should remove the .play from the end of the function, and add a .play to each stereo array statement. You end up with
+<programlisting><![CDATA[
+{
+ var frequency1 = 200 + 600.rand;
+ var frequency2 = 200 + 600.rand;
+ var frequency3 = 200 + 600.rand;
+ var frequency4 = 200 + 600.rand;
+ var frequency5 = 200 + 600.rand;
+ var frequency6 = 200 + 600.rand;
+ var frequency7 = 200 + 600.rand;
+ var frequency8 = 200 + 600.rand;
+ var frequency9 = 200 + 600.rand;
+ var frequency0 = 200 + 600.rand;
+
+ [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ].play;
+ [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ].play;
+}
+]]></programlisting>
+ </para></step>
+ <step><para>When you execute this, no sound is produced, but SuperCollider outputs "a Function." Can you think of why this happens? It's because you wrote a function, but never told SuperCollider to evaluate it! At the end of execution, SuperCollider just throws away the function, because it's never used. This is the same thing that happened to the first nine stereo arrays - they were created, but you never said to do anything with them, so they were just thrown out. We need to execute the function. Because it doesn't produce a UGen, we can't use "play," so we have to use "value" instead. You can choose to do either of these:
+ <programlisting><![CDATA[{ ... }.value;]]></programlisting>
+ or
+<programlisting><![CDATA[
+var myFunction = { ... };
+myFunction.value;
+]]></programlisting>
+ </para></step>
<step><para>This gives us yet another error, as if we can't play the stereo arrays! In fact, we can't - and we didn't do it in the first part, either. We play'ed the result of returning a stereo array from a function. The subtle difference isn't important yet - we're just trying to make this work! Use { and } to build a function for .play to .play</para></step>
<step><para>Now make the correction nine more times.</para></step>
<step><para>When you play execute the resulting code, you probably get something that sounds quite "space-age." Execute it a few times, to see the kind of results you get.</para></step>
@@ -231,66 +265,75 @@
<procedure>
<step><para>The next step is to get these started consecutively, with 5-second pauses after each addition. For this we will use a TempoClock, and since this is the only thing that we're doing, we'll just use the default one called TempoClock.default. I don't feel like typing that, however, so we're going to define an alias variable: <code>var t_c = TempoClock.default;</code> You could put that in the main function, but I suggest putting it before the main function. This way, if we want to write another function later, then it can also access t_c.</para></step>
<step><para>The default TempoClock has a default tempo of one beat per second (1 Hz). This will be good enough for us. If you wanted to change the tempo, remember that you can enter a metronome setting (which is "beats per minute") by dividing the metronome setting by 60. So a metronome's 120 beats per minute would be given to a new TempoClock as <code>TempoClock.new( 120/60 )</code>. Even though you could do that ahead of time and just write "2," inputting it as "120/60" makes it clearer what tempo you intend to set.</para></step>
- <step><para>You can schedule something on a TempoClock by using <code>t_c.sched( x, f );</code>, where "f" is a function to execute, and "x" is when it should be done, measured as the number of beats from now. So we can schedule our SinOsc like this: [pre]t_c.sched( 1, {{[ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]}.play;} );[/pre]</para></step>
+ <step><para>You can schedule something on a TempoClock by using <code>t_c.sched( x, f );</code>, where "f" is a function to execute, and "x" is when it should be done, measured as the number of beats from now. So we can schedule our SinOsc like this:
+ <programlisting><![CDATA[t_c.sched( 1, {{[ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ]}.play;} );]]></programlisting></para></step>
<step><para>Schedule the rest, in intervals of five beats (which is five seconds). They will all be scheduled virtually instantaneously (that is, the computer will notice the slight delay between when each one is scheduled, but humans will not). I started at one beat from now, to insert a slight pause before the sound begins.</para></step>
- <step><para>If you've done this correctly, then we should get a build-up of ten pitches. But they never stop! This is going to take some more ingenuity to solve, because we can't just make a stereo array, play it, then throw it away. We need to hold onto the stereo array, so that we can stop it. The first step here is to store the stereo arrays in variables, and subsequently schedule them. You will end up with something like this:[pre]var sinosc1 = { [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ] };
- // the other nine...
-
- t_c.sched( 1, { sinosc1.play; } );
- // the other nine...[/pre]</para></step>
+ <step><para>If you've done this correctly, then we should get a build-up of ten pitches. But they never stop! This is going to take some more ingenuity to solve, because we can't just make a stereo array, play it, then throw it away. We need to hold onto the stereo array, so that we can stop it. The first step here is to store the stereo arrays in variables, and subsequently schedule them. You will end up with something like this:
+<programlisting><![CDATA[
+var sinosc1 = { [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ] };
+// the other nine...
+
+ t_c.sched( 1, { sinosc1.play; } );
+// the other nine...
+]]></programlisting>
+ </para></step>
<step><para>It should still work, but we after all that cutting-and-pasting, we still haven't managed to turn off the SinOsc's. We need to "free" the object that was returned when we used the "play" function. We need to declare yet more variables: <code>var so1, so2, so3, so4, so5, so6, so7, so8, so9, so0;</code> should appear anywhere before the scheduler.</para></step>
<step><para>Now adjust all the scheduling commands so they look like this: <code>t_c.sched( 1, { so1 = sinosc1.play; } );</code></para></step>
<step><para>Now you can add ten of these, after the existing scheduling commands: <code>t_c.sched( 51, { so1.free; } );</code>. Be sure to schedule each one for 51 beats, so that they all turn off simultaneously, 5 beats after the last pitch is added.</para></step>
- <step><para>It should work successfully. If it doesn't, then compare what you have to this, which does work:[pre]var t_c = TempoClock.default;
+ <step><para>It should work successfully. If it doesn't, then compare what you have to this, which does work:
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
- {
- var frequency1 = 200 + 600.rand;
- var frequency2 = 200 + 600.rand;
- var frequency3 = 200 + 600.rand;
- var frequency4 = 200 + 600.rand;
- var frequency5 = 200 + 600.rand;
- var frequency6 = 200 + 600.rand;
- var frequency7 = 200 + 600.rand;
- var frequency8 = 200 + 600.rand;
- var frequency9 = 200 + 600.rand;
- var frequency0 = 200 + 600.rand;
-
- var sinosc1 = { [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ] };
- var sinosc2 = { [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ] };
- var sinosc3 = { [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ] };
- var sinosc4 = { [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ] };
- var sinosc5 = { [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ] };
- var sinosc6 = { [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ] };
- var sinosc7 = { [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ] };
- var sinosc8 = { [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ] };
- var sinosc9 = { [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ] };
- var sinosc0 = { [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ] };
-
- var so1, so2, so3, so4, so5, so6, so7, so8, so9, so0;
-
- t_c.sched( 1, { so1 = sinosc1.play; } );
- t_c.sched( 6, { so2 = sinosc2.play; } );
- t_c.sched( 11, { so3 = sinosc3.play; } );
- t_c.sched( 16, { so4 = sinosc4.play; } );
- t_c.sched( 21, { so5 = sinosc5.play; } );
- t_c.sched( 26, { so6 = sinosc6.play; } );
- t_c.sched( 31, { so7 = sinosc7.play; } );
- t_c.sched( 36, { so8 = sinosc8.play; } );
- t_c.sched( 41, { so9 = sinosc9.play; } );
- t_c.sched( 46, { so0 = sinosc0.play; } );
-
- t_c.sched( 51, { so1.free; } );
- t_c.sched( 51, { so2.free; } );
- t_c.sched( 51, { so3.free; } );
- t_c.sched( 51, { so4.free; } );
- t_c.sched( 51, { so5.free; } );
- t_c.sched( 51, { so6.free; } );
- t_c.sched( 51, { so7.free; } );
- t_c.sched( 51, { so8.free; } );
- t_c.sched( 51, { so9.free; } );
- t_c.sched( 51, { so0.free; } );
-
- }.value;[/pre]</para></step>
+{
+ var frequency1 = 200 + 600.rand;
+ var frequency2 = 200 + 600.rand;
+ var frequency3 = 200 + 600.rand;
+ var frequency4 = 200 + 600.rand;
+ var frequency5 = 200 + 600.rand;
+ var frequency6 = 200 + 600.rand;
+ var frequency7 = 200 + 600.rand;
+ var frequency8 = 200 + 600.rand;
+ var frequency9 = 200 + 600.rand;
+ var frequency0 = 200 + 600.rand;
+
+ var sinosc1 = { [ SinOsc.ar( freq:frequency1, mul:0.01 ), SinOsc.ar( freq:frequency1, mul:0.01 ) ] };
+ var sinosc2 = { [ SinOsc.ar( freq:frequency2, mul:0.01 ), SinOsc.ar( freq:frequency2, mul:0.01 ) ] };
+ var sinosc3 = { [ SinOsc.ar( freq:frequency3, mul:0.01 ), SinOsc.ar( freq:frequency3, mul:0.01 ) ] };
+ var sinosc4 = { [ SinOsc.ar( freq:frequency4, mul:0.01 ), SinOsc.ar( freq:frequency4, mul:0.01 ) ] };
+ var sinosc5 = { [ SinOsc.ar( freq:frequency5, mul:0.01 ), SinOsc.ar( freq:frequency5, mul:0.01 ) ] };
+ var sinosc6 = { [ SinOsc.ar( freq:frequency6, mul:0.01 ), SinOsc.ar( freq:frequency6, mul:0.01 ) ] };
+ var sinosc7 = { [ SinOsc.ar( freq:frequency7, mul:0.01 ), SinOsc.ar( freq:frequency7, mul:0.01 ) ] };
+ var sinosc8 = { [ SinOsc.ar( freq:frequency8, mul:0.01 ), SinOsc.ar( freq:frequency8, mul:0.01 ) ] };
+ var sinosc9 = { [ SinOsc.ar( freq:frequency9, mul:0.01 ), SinOsc.ar( freq:frequency9, mul:0.01 ) ] };
+ var sinosc0 = { [ SinOsc.ar( freq:frequency0, mul:0.01 ), SinOsc.ar( freq:frequency0, mul:0.01 ) ] };
+
+ var so1, so2, so3, so4, so5, so6, so7, so8, so9, so0;
+
+ t_c.sched( 1, { so1 = sinosc1.play; } );
+ t_c.sched( 6, { so2 = sinosc2.play; } );
+ t_c.sched( 11, { so3 = sinosc3.play; } );
+ t_c.sched( 16, { so4 = sinosc4.play; } );
+ t_c.sched( 21, { so5 = sinosc5.play; } );
+ t_c.sched( 26, { so6 = sinosc6.play; } );
+ t_c.sched( 31, { so7 = sinosc7.play; } );
+ t_c.sched( 36, { so8 = sinosc8.play; } );
+ t_c.sched( 41, { so9 = sinosc9.play; } );
+ t_c.sched( 46, { so0 = sinosc0.play; } );
+
+ t_c.sched( 51, { so1.free; } );
+ t_c.sched( 51, { so2.free; } );
+ t_c.sched( 51, { so3.free; } );
+ t_c.sched( 51, { so4.free; } );
+ t_c.sched( 51, { so5.free; } );
+ t_c.sched( 51, { so6.free; } );
+ t_c.sched( 51, { so7.free; } );
+ t_c.sched( 51, { so8.free; } );
+ t_c.sched( 51, { so9.free; } );
+ t_c.sched( 51, { so0.free; } );
+
+}.value;
+]]></programlisting>
+ </para></step>
</procedure>
</section>
@@ -332,36 +375,38 @@
<step><para>Now let's reduce the repetitiveness of the scheduling. First, replace so1, so2, etc. with a ten-element array. Test it to ensure that the code still works.</para></step>
<step><para>Getting the next two loops working is a little bit more complicated. We know how to run the exact same code in a loop, but we don't know how to change it subtly (by supplying different index numbers for the array, for example). Thankfully, SuperCollider provides a way to keep track of how many times the function in a loop has already been run. The first argument given to a function in a loop is the number of times that the function has ''already'' been executed. The first time it is run, the function receives a 0; if we're using a <code>10.do( ... );</code> loop, then the last time the function is run, it receives a 9 because the function has already been executed 9 times. Since our ten-element array is indexed from 0 to 9, this works perfectly for us.</para></step>
<step><para>The code to free is shorter: <code>10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );</code> This can look confusing, especially written in one line, like it is. If it helps, you might want to write it like this instead:
- [pre]
- 10.do
- ({ arg index;
- t_c.sched( 51, { so[index].free; } );
- });
- [/pre]Now it looks more like a typical function.</para></step>
- <step><para>The next step is to simplify the original scheduling calls in a similar way, but it's slightly more complicated because we have to schedule a different number of measures for each call. With a little math, this is also not a problem - it's just a simple linear equation:[pre]number_of_measures = 5 * array_index + 1[/pre]Try to write this loop by yourself, before going to the next step.</para></step>
- <step><para>If you missed it, my solution is
- [pre]
- 10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( sinosc[index].play; ); } ); } );
- [/pre] which includes some extra parentheses to ensure that the math is computed in the right order.</para></step>
+<programlisting><![CDATA[
+10.do
+({ arg index;
+ t_c.sched( 51, { so[index].free; } );
+});
+]]></programlisting>
+ Now it looks more like a typical function.</para></step>
+ <step><para>The next step is to simplify the original scheduling calls in a similar way, but it's slightly more complicated because we have to schedule a different number of measures for each call. With a little math, this is also not a problem - it's just a simple linear equation: <literal>number_of_measures = 5 * array_index + 1</literal> Try to write this loop by yourself, before going to the next step.</para></step>
+ <step><para>
+ If you missed it, my solution is
+ <programlisting><![CDATA[10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( sinosc[index].play; ); } ); } );]]></programlisting>
+ which includes some extra parentheses to ensure that the math is computed in the right order.</para></step>
<step><para>The code is already much shorter, easier to understand, and easier to expand or change. There is one further optimzation that we can easily make: get rid of the sinosc array. This simply involves replacing <code>sinosc[index]</code> with what all of its elements are: <code>{func.value;}</code></para></step>
<step><para>The resulting program is a little different from what ended up in FSC_method_1.sc, but produces the same output. What I have is this:
- [pre]
- var t_c = TempoClock.default;
-
- {
- var so = Array.new( 10 );
-
- var func =
- {
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
- };
-
- 10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
- 10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
-
- }.value;
- [/pre]</para></step>
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
+
+{
+ var so = Array.new( 10 );
+
+ var func =
+ {
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
+ };
+
+ 10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
+ 10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
+
+}.value;
+]]></programlisting>
+ </para></step>
<step><para>Finally, assign this Function to a variable (called "secondPart", perhaps), and remove the "value" Function-call. If we leave that in, the Function will execute before the rest of the program begins!</para></step>
</procedure>
</section>
@@ -376,75 +421,75 @@
</para>
<para>
Here's what I have from the previous step:
- [pre]
- var t_c = TempoClock.default;
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
- var secondPart =
- {
- var so = Array.new( 10 );
-
- var func =
- {
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
- };
-
- 10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
- 10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
-
- };
- [/pre]
+var secondPart =
+{
+ var so = Array.new( 10 );
+
+ var func =
+ {
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
+ };
+
+ 10.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
+ 10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
+
+};
+]]></programlisting>
This Function is the perfect solution if you want ten pseudo-random pitches between 200 Hz and 800 Hz, and a five-second pause between each one. If you want nine or eleven pitches, if you want them to eb between 60 Hz and 80Hz, if you want a six-second pause between each - you would have to modify the Function. If you don't remember how it works, or if you give it to a friend, you're going to have to figure out how it works before you modify it. This is not an ideal solution.
</para>
<para>
Let's solve these problems one at a time, starting with allowing a different number of SinOsc synths to be created. We know that we'll have to create an argument, and that it will have to be used wherever we need the number of SinOsc's. Also, to preserve functionality, we'll make a default assignment of 10. Try to accomplish this yourself, making sure to test your Function so that you know it works. Here's what I did:
- [pre]
- var t_c = TempoClock.default;
-
- var secondPart =
- {
- arg number_of_SinOscs = 10;
-
- var so = Array.new( number_of_SinOscs );
-
- var func =
- {
- var frequency = 200 + 600.rand;
- [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
- };
-
- number_of_SinOscs.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
- number_of_SinOscs.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
-
- };
- [/pre]
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
+
+var secondPart =
+{
+ arg number_of_SinOscs = 10;
+
+ var so = Array.new( number_of_SinOscs );
+
+ var func =
+ {
+ var frequency = 200 + 600.rand;
+ [ SinOsc.ar( freq:frequency, mul:0.01 ), SinOsc.ar( freq:frequency, mul:0.01 ) ];
+ };
+
+ number_of_SinOscs.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
+ number_of_SinOscs.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
+
+};
+]]></programlisting>
The "do" loop doesn't need a constant number; it's fine with a variable. What happens when you pass a bad argument, like a string? This would be an easy way to sabotage your program, and in almost any other programming context it would concern us, but this is just audio programming. If somebody is going to try to create "cheese" SinOsc's, it's their own fault for mis-using the Function.
</para>
<para>
Now let's modify the Function so that we can adjust the range of frequencies that the Function will generate. We know that we'll need two more arguments, and that they'll have to be used in the equation to calculate the frequency. But we'll also need to do a bit of arithmetic, because of the way the "rand" Function works (actually we don't - see the "rand" Function's help file). Also, to preserve functionality, we'll make default assignments of 200 and 800. Try to accomplish this yourself, making sure that you test the Function so you know it works. Here's what I did:
- [pre]
- var t_c = TempoClock.default;
-
- var secondPart =
- {
- arg number_of_SinOscs = 10,
- pitch_low = 200,
- pitch_high = 800;
-
- var so = Array.new( number_of_SinOscs );
-
- var func =
- {
- var freq = pitch_low + (pitch_high - pitch_low).rand;
- [ SinOsc.ar( freq:freq, mul:0.01),
- SinOsc.ar( freq:freq, mul:0.01) ];
- };
-
- number_of_SinOscs.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
- number_of_SinOscs.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
-
- };
- [/pre]
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
+
+var secondPart =
+{
+ arg number_of_SinOscs = 10,
+ pitch_low = 200,
+ pitch_high = 800;
+
+ var so = Array.new( number_of_SinOscs );
+
+ var func =
+ {
+ var freq = pitch_low + (pitch_high - pitch_low).rand;
+ [ SinOsc.ar( freq:freq, mul:0.01),
+ SinOsc.ar( freq:freq, mul:0.01) ];
+ };
+
+ number_of_SinOscs.do( { arg index; t_c.sched( ((5*index)+1), { so = so.add( {func.value;}.play; ); } ); } );
+ number_of_SinOscs.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );
+
+};
+]]></programlisting>
Notice that I changed the name of the variables, and the indentation in the "func" sub-Function, to make it easier to read. This isn't a particularly difficult change.
</para>
<para>
@@ -452,57 +497,55 @@
</para>
<para>
The change to the "do" loop which schedules the SinOsc's to play is almost trivial. My new argument is called "pause_length", (meaning "the length of the pause, in seconds, between adding each SinOsc"), so I get this modification:
- [pre]
number_of_SinOscs.do(
- {
- arg time;
- secondPart_clock.sched( (1+(time*5)), { sounds = sounds.add( func.play ); } );
- });
- [/pre]
+<programlisting><![CDATA[
+{
+ arg time;
+ secondPart_clock.sched( (1+(time*5)), { sounds = sounds.add( func.play ); } );
+});
+]]></programlisting>
Again, I changed the indentation, and the names of the variables in this sub-Function. Recall that the "1+" portion is designed to add a one-second pause to the start of the Function's execution. The problem comes in the next "do" loop, where we have to know how the number of beats from now will be five seconds after the last SinOsc is added. We'll have to calculate it, so I added a variable to store the value after it's calculated. This also allows us to return it, as a convenience to the Function that called this one, so that it knows how long until this Function is finished. Try adding this yourself, then testing the Function to ensure that it works. I got this:
- [pre]
- var t_c = TempoClock.default;
-
- var secondPart =
- {
- arg number_of_SinOscs = 10,
- pitch_low = 200,
- pitch_high = 800,
- pause_length = 5;
-
- var so = Array.new( number_of_SinOscs );
-
- var when_to_stop = ( 1 + ( pause_length * number_of_SinOscs ) );
-
- var func =
- {
- var freq = pitch_low + (pitch_high - pitch_low).rand;
- [ SinOsc.ar( freq:freq, mul:0.01),
- SinOsc.ar( freq:freq, mul:0.01) ];
- };
-
- number_of_SinOscs.do(
- {
- arg time;
- t_c.sched( (1+(time*5)), { so = so.add( func.play ); } );
- });
-
- t_c.sched( when_to_stop,
- {
- number_of_SinOscs.do( { arg index; so[index].free; } );
- nil;
- });
-
- when_to_stop;
- };
- [/pre]
+<programlisting><![CDATA[
+var t_c = TempoClock.default;
+
+var secondPart =
+{
+ arg number_of_SinOscs = 10,
+ pitch_low = 200,
+ pitch_high = 800,
+ pause_length = 5;
+
+ var so = Array.new( number_of_SinOscs );
+
+ var when_to_stop = ( 1 + ( pause_length * number_of_SinOscs ) );
+
+ var func =
+ {
+ var freq = pitch_low + (pitch_high - pitch_low).rand;
+ [ SinOsc.ar( freq:freq, mul:0.01),
+ SinOsc.ar( freq:freq, mul:0.01) ];
+ };
+
+ number_of_SinOscs.do(
+ {
+ arg time;
+ t_c.sched( (1+(time*5)), { so = so.add( func.play ); } );
+ });
+
+ t_c.sched( when_to_stop,
+ {
+ number_of_SinOscs.do( { arg index; so[index].free; } );
+ nil;
+ });
+
+ when_to_stop;
+};
+]]></programlisting>
I decided to "invert" the "free-ing" of the SinOsc's. Rather than scheduling number_of_SinOscs Function-calls at some point in the future, I decided to schedule one thing: a "do" loop that does the work. The indentation looks strange, but sometimes there's not much you can do about that. The "when_to_stop" variable must be the last thing in the Function, so that the interpreter returns it to the Function's caller.
</para>
<para>
In order to retain the "bare minimum" robustness to be used elsewhere, we can't rely on the "TempoClock.default" clock having the tempo we expect, and we certainly can't rely on it being declared as "t_c". The solution is quite easy: create a new TempoClock within the Function.
- [pre]
- var t_c = TempoClock.new; // default tempo is one beat per second
- [/pre]
+ <programlisting><![CDATA[var t_c = TempoClock.new; // default tempo is one beat per second]]></programlisting>
We could hypothetically use the "SystemClock", since we're measuring time strictly in seconds. But, using a TempoClock is preferred for two reasons:
<orderedlist>
<listitem><para>It has the word "tempo" in its name, and it's designed for scheduling musical events; the "SystemClock" is for system events.</para></listitem>
@@ -562,13 +605,13 @@
</substeps>
</step>
<step><para>Try to schedule the events for yourself, then test your program to make sure that it works as you intended. Here's what I wrote:
- [pre]
- t_c.sched( 1, { sound = Synth.new( \FirstPart ); } );
- t_c.sched( 61, { sound.free; } );
- t_c.sched( 61, { secondPart.value; nil; } );
- t_c.sched( 113, { sound = Synth.new( \FirstPart ); } );
- t_c.sched( 143, { sound.free; } );
- [/pre]
+<programlisting><![CDATA[
+t_c.sched( 1, { sound = Synth.new( \FirstPart ); } );
+t_c.sched( 61, { sound.free; } );
+t_c.sched( 61, { secondPart.value; nil; } );
+t_c.sched( 113, { sound = Synth.new( \FirstPart ); } );
+t_c.sched( 143, { sound.free; } );
+]]></programlisting>
Why is the "nil" required after "secondPart"? Because that function returns a number. As you know, any scheduled function which returns a number will re-schedule itself to run that many beats after the previous execution began. Since "secondPart" returns the number of seconds it takes to finish, it will always be re-started as soon as it finishes. Including "nil" disallows this repetition.
</para></step>
</procedure>
diff --git a/en-US/SuperCollider/SuperCollider.xml b/en-US/SuperCollider/SuperCollider.xml
index 0eb9905..78c792a 100644
--- a/en-US/SuperCollider/SuperCollider.xml
+++ b/en-US/SuperCollider/SuperCollider.xml
@@ -17,6 +17,7 @@
<section id="sect-Musicians_Guide-SC-Technical_Convetions">
<title>Technical Conventions for This Chapter</title>
+ <!-- TODO : decide whether you need this (CRA) -->
<para>
Because this chapter of the Musicians' Guide is more like a textbook or technical manual than a regular user manual, I have adopted several conventions commonly used in those contexts:
<orderedlist>
@@ -123,7 +124,7 @@
<para>
To install the minimum recommended installation for SuperCollider:
<orderedlist>
- <listitem><para>In a terminal, run [pre]su -c 'yum install supercollider supercollider-gedit'[/pre]</para></listitem>
+ <listitem><para>In a terminal, run <command>su -c 'yum install supercollider supercollider-gedit'</command></para></listitem>
<listitem><para>Review the proposed installation carefully. The list may be quite long, and require a large download.</para></listitem>
</orderedlist>
</para>
@@ -157,15 +158,20 @@
<step><para>A 'SuperCollider' menu should appear, and a window at the bottom which says, "SuperCollider output".</para></step>
<step><para>If you cannot see the window at the bottom, then select 'View > Bottom Pane' from the menu, so that it shows up. It is sometimes important to see the information that SuperCollider provides in this window.</para></step>
<step><para>After enabling SuperCollider mode, the window should display a series of notices. Near the end should be something like this:
- [pre]RESULT = 0
- Welcome to SuperCollider, for help type ctrl-c ctrl-h (Emacs) or :SChelp (vim) or ctrl-U (sced/gedit)[/pre]
+<programlisting><![CDATA[
+RESULT = 0
+Welcome to SuperCollider, for help type ctrl-c ctrl-h (Emacs) or :SChelp (vim) or ctrl-U (sced/gedit)
+]]></programlisting>
If this window gives a non-zero value for "RESULT," then an error has probably occurred, and you should scroll up to see what it is, and try to fix it. If you receive the following warning: "The GUI scheme 'swing' is not installed" then you will not be able to run any SuperCollider prorams that use a GUI (graphical user interface). The GUI components are not used anywhere in this Guide, and they are highly optional.</para></step>
<step><para>You will probably also want to start a server at this point, so from the menu select 'SuperCollider > Start Server'.</para></step>
<step><para>After the server starts, you should see messages from "JackDriver". If a JACK server is not already started, then SuperCollider will start one automatically.</para></step>
<step><para>If the SuperCollider server started successfully, you should see a message similar to this:
- [pre]SuperCollider 3 server ready..
- JackDriver: max output latency 46.4 ms
- notification is on[/pre]</para></step>
+<programlisting><![CDATA[
+SuperCollider 3 server ready..
+JackDriver: max output latency 46.4 ms
+notification is on
+]]></programlisting>
+ </para></step>
</procedure>
</section>
<section id="sect-Musicians_Guide-SC-Using_GEdit-Executing_Code">
diff --git a/en-US/SuperCollider/examples/Busses-Audio_Rate.sc b/en-US/SuperCollider/examples/Busses-Audio_Rate.sc
new file mode 100644
index 0000000..725dae5
--- /dev/null
+++ b/en-US/SuperCollider/examples/Busses-Audio_Rate.sc
@@ -0,0 +1,82 @@
+(
+ var tutorialDecayPink =
+ {
+ arg outBus = 0, effectBus,
+ direct = 0.5; // controls proportion of "direct" / "processed" sound
+ var source;
+
+ // Decaying pulses of PinkNoise.
+ source = Decay2.ar( in:Impulse.ar( freq:1, phase:0.25 ),
+ attackTime:0.01,
+ decayTime:0.2,
+ mul:PinkNoise.ar
+ );
+
+ Out.ar( outBus, (source*direct) ); // main output
+ Out.ar( effectBus, (source*(1-direct)) ); // effects output
+ };
+
+ var tutorialDecaySine =
+ {
+ arg outBus = 0, effectBus,
+ direct = 0.5; // controls proportion of "direct" / "processed" sound
+ var source;
+
+ // Decaying pulses of a modulating Sine wave.
+ source = Decay2.ar( in:Impulse.ar( freq:0.3, phase: 0.25),
+ attackTime:0.3,
+ decayTime:1,
+ mul:SinOsc.ar( freq:SinOsc.kr( freq:0.2, mul:110, add:440) )
+ );
+
+ Out.ar(outBus, (source*direct) ); // main output
+ Out.ar(effectBus, (source*(1-direct)) ); // effects output
+ };
+
+ var tutorialReverb =
+ {
+ arg outBus = 0, inBus; // default outBus is audio interface
+ var input;
+
+ input = In.ar( inBus, 1 );
+
+ 16.do( { input = AllpassC.ar( in:input,
+ maxdelaytime:0.04,
+ delaytime:{ Rand(0.001,0.04) }.dup,
+ decaytime:3
+ )
+ }
+ );
+
+ Out.ar( outBus, input );
+ };
+
+ // send synthesis information to the server
+ SynthDef( \tutorialReverb, tutorialReverb ).send( s );
+ SynthDef( \tutorialDecayPink, tutorialDecayPink ).send( s );
+ SynthDef( \tutorialDecaySine, tutorialDecaySine ).send( s );
+
+ // reserve an effects Bus
+ b = Bus.audio( s );
+)
+
+(
+ x = Synth.new( \tutorialReverb, [\inBus, b] );
+ y = Synth.before( x, \tutorialDecayPink, [\effectBus, b] );
+ z = Synth.before( x, \tutorialDecaySine, [\effectBus, b, \outBus, 1] );
+)
+
+// Change the balance of "wet" to "dry"
+y.set( \direct, 1 ); // only direct PinkNoise
+z.set( \direct, 1 ); // only direct Sine wave
+y.set( \direct, 0 ); // only reverberated PinkNoise
+z.set( \direct, 0 ); // only reverberated Sine wave
+y.set( \direct, 0.5 ); // original PinkNoise
+z.set( \direct, 0.5 ); // original Sine wave
+
+( // commands to free each Object
+ x.free; x = nil;
+ y.free; y = nil;
+ z.free; z = nil;
+ b.free; b = nil;
+)
\ No newline at end of file
diff --git a/en-US/images/FMG-Ardour-Connections.png b/en-US/images/FMG-Ardour-Connections.png
new file mode 100644
index 0000000..464ebd7
Binary files /dev/null and b/en-US/images/FMG-Ardour-Connections.png differ
More information about the docs-commits
mailing list