\section{Haskore Support for CSound} \label{csound-sect} \begin{verbatim} > module CSound (module Performance, module CSound) > where > > import Performance > import IO > import List (find, nub) \end{verbatim} [Note: if this module is loaded into Hugs98, the following error message may result: \begin{verbatim} Reading file "CSound.lhs": ERROR "CSound.lhs" (line 707): *** Cannot derive Eq OrcExp after 40 iterations. *** This may indicate that the problem is undecidable. However, *** you may still try to increase the cutoff limit using the -c *** option and then try again. (The current setting is -c40) \end{verbatim} This is apparently due to the size of the {\tt OrcExp} data type. For correct operation, start Hugs with a larger cutoff limit, such as {\tt -c1000}.] CSound is a software synthesizer that allows its user to create a virtually unlimited number of sounds and instruments. It is extremely portable because it is written entirely in C. Its strength lies mainly in the fact that all computations are performed in software, so it is not reliant on sophisticated musical hardware. The output of a CSound computation is a file representing the signal which can be played by an independent application, so there is no hard upper limit on computation time. This is important because many sophisticated signals take much longer to compute than to play. The purpose of this module is to create an interface between Haskore and CSound in order to give the Haskore user access to all the powerful features of a software sound synthesizer. CSound takes as input two plain text files: a {\em score} (.sco) file and an {\em orchestra} (.orc) file. The score file is similar to a Midi file, and the orchestra file defines one or more {\em instruments} that are referenced from the score file (the orchestra file can thus be thought of as the software equivalent of Midi hardware). The CSound program takes these two files as input, and produces a {\em sound file} as output, usually in {\tt .wav} format. Sound files are generally much larger than Midi files, since they describe the actual sound to be generated, represented as a sequence of values (typically 44,100 of them for each second of music), which are converted directly into voltages that drive the audio speakers. Sound files can be played by any standard media player found on conventional PC's. Each of these files is described in detail in the following sections. \subsection{The Score File} \label{score-file-sect} We will represent a score file as a sequence of {\em score statements}: \begin{verbatim} > type Score = [ScoreStmt] \end{verbatim} The {\tt ScoreStmt} data type is designed to simulate CSound's three kinds of score statements: \begin{enumerate} \item A {\em tempo} statement, which sets the tempo. In the absence of a tempo statement, the tempo defaults to 60 beats per minute. \item A {\em note event}, which defines the start time, pitch, duration (in beats), volume (in decibels), and instrument to play a note (and is thus more like a Haskore {\tt Event} than a Midi event, thus making the conversion to CSound easier than to Midi, as we shall see later). Each note event also contains a number of optional arguments called {\em p-fields}, which determine other properties of the note, and whose interpretation depends on the instrument that plays the note. This will be discussed further in a later section. \item {\em Function table} definitions. A function table is used by instruments to produce audio signals. For example, sequencing through a table containing a perfect sine wave will produce a very pure tone, while a table containing an elaborate polynomial will produce a complex sound with many overtones. The tables can also be used to produce control signals that modify other signals. Perhaps the simplest example of this is a tremolo or vibrato effect, but more complex sound effects, and FM (frequency modulation) synthesis in general, is possible. \end{enumerate} \begin{verbatim} > data ScoreStmt = CSTempo Bpm > | CSNote Inst StartTime Duration Pch Vlm [Pfield] > | CSTable Tbl CreatTime TblSize Normalize GenRoutine > deriving Show > > type Bpm = Int > type Inst = Int > type StartTime = Float > type Duration = Float > type Pch = Float > type Vlm = Float > type Pfield = Float > type Tbl = Int > type CreatTime = Float > type TblSize = Int > type Normalize = Bool \end{verbatim} This is all rather straightforward, except for function table generation, which requires further explanation. \subsubsection{Function Tables} \label{function-table-sect} Each function table must have a unique integer ID ({\tt Tbl}), creation time (usually 0), size (which must be a power of 2), and a {\tt Normalize} flag. Most tables in CSound are normalized, i.e.\ rescaled to a maximum absolute value of 1. The normalization process can be skipped by setting the {\tt Normalize} flag to {\tt False}. Such a table may be desirable to generate a control or modifying signal, but is not very useful for audio signal generation. Tables are simply arrays of floating point values. The values stored in the table are calculated by one of CSound's predefined {\em generating routines}, represented by the type {\tt GenRoutine}: \begin{verbatim} > data GenRoutine = GenRoutine GenNum [GenArg] > | SoundFile SFName SkipTime ChanNum > deriving Show > > type SFName = String > type SkipTime = Float > type ChanNum = Float > type GenNum = Int > type GenArg = Float \end{verbatim} {\tt GenRoutine n args} refers to CSound's generating routine $n$ (an integer), called with floating point arguments {\tt args}. There is only one generating routine (called GEN01) in CSound that takes an argument type other than floating point, and thus we represent this using the special constructor {\tt SoundFile}, whose functionality will be described shortly. Knowing which of CSound's generating routines to use and with what arguments can be a daunting task. The newest version of CSound (version 4.01) provides 23 different generating routines, and each one of them assigns special meanings to its arguments. To avoid having to reference routines using integer ids, the following functions are defined for the most often-used generating routines. A brief discussion of each routine is also included. For a full description of these and other routines, refer to the CSound manual or consult the following webpage: {\tt http://www.leeds.ac.uk/music/Man/Csound/Function/GENS.html}. The user familiar with CSound is free to write helper functions like the ones below to capture other generating routines. \paragraph*{GEN01.} Transfers data from a soundfile into a function table. Recall that the size of the function table in CSound must be a power of two. If the soundfile is larger than the table size, reading stops when the table is full; if it is smaller, then the table is padded with zeros. One exception is allowed: if the file is of type AIFF and the table size is set to zero, the size of the function table is allocated dynamically as the number of points in the soundfile. The table is then unusable by normal oscillators, but can be used by a special {\tt SampOsc} constructor (discussed in Section \ref{orchestra-file-sect}). The first argument passed to the GEN01 subroutine is a string containing the name of the source file. The second argument is skip time, which is the number of seconds into the file that the reading begins. Finally there is an argument for the channel number, with 0 meaning read all channels. GEN01 is represented in Haskore as {\tt SoundFile SFName SkipTime ChanNum}, as discussed earlier. To make the use of {\tt SoundFile} consistent with the use of other functions to be described shortly, we define a simple equivalent: \begin{verbatim} > soundFile :: SFName -> SkipTime -> ChanNum -> GenRoutine > soundFile = SoundFile \end{verbatim} \paragraph*{GEN02.} Transfers data from its argument fields directly into the function table. We represent its functionality as follows: \begin{verbatim} > tableValues :: [GenArg] -> GenRoutine > tableValues gas = GenRoutine 2 gas \end{verbatim} \paragraph*{GEN03.} Fills the table by evaluating a polynomial over a specified interval and with given coefficients. For example, calling GEN03 with an interval of $(-1,1)$ and coefficients 5, 4, 3, 2, 0, 1 will generate values of the function $5+4x+3x^2+2x^3+x^5$ over the interval $-1$ to $1$. The number of values generated is equal to the size of the table. Let's express this by the following function: \begin{verbatim} > polynomial :: Interval -> Coefficients -> GenRoutine > polynomial (x1,x2) cfs = GenRoutine 3 (x1:x2:cfs) > > type Interval = (Float, Float) > type Coefficients = [Float] \end{verbatim} \paragraph*{GEN05.} Constructs a table from segments of exponential curves. The first argument is the starting point. The meaning of the subsequent arguments alternates between the length of a segment in samples, and the endpoint of the segment. The endpoint of one segment is the starting point of the next. The sum of all the segment lengths normally equals the size of the table: if it is less the table is padded with zeros, if it is more, only the first {\tt TblSize} locations will be stored in the table. \begin{verbatim} > exponential1 :: StartPt -> [(SegLength, EndPt)] -> GenRoutine > exponential1 sp xs = GenRoutine 5 (sp : flattenTuples2 xs) > > type StartPt = Float > type SegLength = Float > type EndPt = Float \end{verbatim} {\tt flattenTuples2} flattens a list of pairs into a list. Similarly, {\tt flattenTuples3} flattens a list of 3-tuples into a list, and so on. \begin{verbatim} > flattenTuples2 :: [(a,a)] -> [a] > flattenTuples3 :: [(a,a,a)] -> [a] > flattenTuples4 :: [(a,a,a,a)] -> [a] > > flattenTuples2 [] = [] > flattenTuples2 ((x,y) : xs) = x : y : flattenTuples2 xs > > flattenTuples3 [] = [] > flattenTuples3 ((x,y,z) : xs) = x : y : z : flattenTuples3 xs > > flattenTuples4 [] = [] > flattenTuples4 ((x, y, z, w) : xs) = x : y : z : w : flattenTuples4 xs \end{verbatim} \paragraph*{GEN25.} Similar to GEN05 in that it produces segments of exponential curves, but instead of representing the lengths of segments and their endpoints, its arguments represent $(x,y)$ coordinates in the table, and the subroutine produces curves between successive locations. The $x$-coordinates must be in increasing order. \begin{verbatim} > exponential2 :: [Point] -> GenRoutine > exponential2 pts = GenRoutine 25 (flattenTuples2 pts) > > type Point = (Float,Float) \end{verbatim} \paragraph*{GEN06.} Generates a table from segments of cubic polynomial functions, spanning three points at a time. We define a function {\tt cubic} with two arguments: a starting position and a list of segment length (in number of samples) and segment endpoint pairs. The endpoint of one segment is the starting point of the next. The meaning of the segment endpoint alternates between a local minimum/maximum and point of inflexion. Whether a point is a maximum or a minimum is determined by its relation to the next point of inflexion. Also note that for two successive minima or maxima, the inflexion points will be jagged, whereas for alternating maxima and minima, they will be smooth. The slope of the two segments is independent at the point of inflection and will likely vary. The starting point is a local minimum or maximum (if the following point is greater than the starting point, then the starting point is a minimum, otherwise it is a maximum). The first pair of numbers will in essence indicate the position of the first inflexion point in $(x,y)$ coordinates. The folowing pair will determine the next local minimum/maximum, followed by the second point of inflexion, etc. \begin{verbatim} > cubic :: StartPt -> [(SegLength, EndPt)] -> GenRoutine > cubic sp pts = GenRoutine 6 (sp : flattenTuples2 pts) \end{verbatim} \paragraph*{GEN07.} Similar to GEN05, except that it generates straight lines instead of exponential curve segments. All other issues discussed about GEN05 also apply to GEN07. We represent it as: \begin{verbatim} > lineSeg1 :: StartPt -> [(SegLength, EndPt)] -> GenRoutine > lineSeg1 sp pts = GenRoutine 7 (sp : flattenTuples2 pts) \end{verbatim} \paragraph*{GEN27.} As with GEN05 and GEN25, produces straight line segments between points whose locations are given as $(x,y)$ coordinates, rather than a list of segment length, endpoint pairs. \begin{verbatim} > lineSeg2 :: [Point] -> GenRoutine > lineSeg2 pts = GenRoutine 27 (flattenTuples2 pts) \end{verbatim} \paragraph*{GEN08.} Produces a smooth piecewise cubic spline curve through the specified points. Neighboring segments have the same slope at the common points, and it is that of a parabola through that point and its two neighbors. The slope is zero at the ends. \begin{verbatim} > cubicSpline :: StartPt -> [(SegLength, EndPt)] -> GenRoutine > cubicSpline sp pts = GenRoutine 8 (sp : flattenTuples2 pts) \end{verbatim} \paragraph*{GEN10.} Produces a composite sinusoid. It takes a list of relative strengths of harmonic partials 1, 2, 3, etc. Partials not required should be given strength of zero. \begin{verbatim} > compSine1 :: [PStrength] -> GenRoutine > compSine1 pss = GenRoutine 10 pss > > type PStrength = Float \end{verbatim} \paragraph*{GEN09.} Also produces a composite sinusoid, but requires three arguments to specify each contributing partial. The arguments specify the partial number, which doesn't have to be an integer (i.e.\ inharmonic partials are allowed), the relative partial strength, and the initial phase offset of each partial, expressed in degrees. \begin{verbatim} > compSine2 :: [(PNum, PStrength, PhaseOffset)] -> GenRoutine > compSine2 args = GenRoutine 9 (flattenTuples3 args) > > type PNum = Float > type PhaseOffset = Float \end{verbatim} \paragraph*{GEN19.} Provides all of the functionality of GEN09, but in addition a DC offset must be specified for each partial. The DC offset is a vertical displacement, so that a value of 2 will lift a 2-strength partial from range $[-2,2]$ to range $[0,4]$ before further scaling. \begin{verbatim} > compSine3 :: [(PNum, PStrength, PhaseOffset, DCOffset)] -> GenRoutine > compSine3 args = GenRoutine 19 (flattenTuples4 args) > > type DCOffset = Float \end{verbatim} \paragraph*{GEN11.} Produces an additive set of harmonic cosine partials, similar to GEN10. We will represent it by a function that takes three arguments: the number of harmonics present, the lowest harmonic present, and a multiplier in an exponential series of harmonics amplitudes (if the $x$'th harmonic has strength coefficient of $A$, then the $(x+n)$'th harmonic will have a strength of $A*(r^n)$, where $r$ is the multiplier). \begin{verbatim} > cosineHarms :: NHarms -> LowestHarm -> Mult -> GenRoutine > cosineHarms n l m = GenRoutine 11 [float n, float l, m] > > type NHarms = Int > type LowestHarm = Int > type Mult = Float \end{verbatim} \paragraph*{GEN21.} Produces tables having selected random distributions. \begin{verbatim} > randomTable :: RandDist -> GenRoutine > randomTable rd = GenRoutine 21 [float rd] > > type RandDist = Int > > uniform, linear, triangular, expon, > biexpon, gaussian, cauchy, posCauchy :: Int > uniform = 1 > linear = 2 > triangular = 3 > expon = 4 > biexpon = 5 > gaussian = 6 > cauchy = 7 > posCauchy = 8 \end{verbatim} \paragraph*{Common Tables} For convenience, here are some common function tables, which take as argument the identifier integer: \begin{verbatim} > simpleSine, square, sawtooth, triangle, whiteNoise :: Tbl -> ScoreStmt > > simpleSine n = CSTable n 0 8192 True > (compSine1 [1]) > square n = CSTable n 0 1024 True > (lineSeg1 1 [(256, 1), (0, -1), (512, -1), (0, 1), (256, 1)]) > sawtooth n = CSTable n 0 1024 True > (lineSeg1 0 [(512, 1), (0, -1), (512, 0)]) > triangle n = CSTable n 0 1024 True > (lineSeg1 0 [(256, 1), (512, -1), (256, 0)]) > whiteNoise n = CSTable n 0 1024 True > (randomTable uniform) \end{verbatim} The following function for a composite sine has an extra argument, a list of harmonic partial strengths: \begin{verbatim} > compSine :: Tbl -> [PStrength] -> ScoreStmt > compSine n s = CSTable 6 0 8192 True (compSine1 s) \end{verbatim} \subsubsection{Naming Instruments and Tables} In CSound, each table and instrument has a unique identifying integer associated with it. Haskore, on the other hand, uses strings to name instruments. What we need is a way to convert Haskore instrument names to identifier integers that CSound can use. Similar to Haskore's player maps, we define a notion of a {\em CSound name map} for this purpose. \begin{verbatim} > type NameMap = [(Name, Int)] > type Name = String \end{verbatim} A name map can be provided directly in the form {\tt [("name1", int1), ("name2", int2), ...]}, or the programmer can define auxiliary functions to make map construction easier. For example: \begin{verbatim} > makeNameMap :: [Name] -> NameMap > makeNameMap nms = zip nms [1..] \end{verbatim} The following function will add a name to an existing name map. If the name is already in the map, an error results. \begin{verbatim} > addToMap :: NameMap -> Name -> Int -> NameMap > addToMap nmap nm i = > case (getId nmap nm) of > Nothing -> (nm,i) : nmap > Just _ -> error (" addToMap: the name " ++ nm ++ > " is already in the name map") > > getId :: NameMap -> Name -> Maybe Int > getId nmap nm = > case (find (\(n,_) -> n==nm) nmap) of > Nothing -> Nothing > Just (n,i) -> Just i \end{verbatim} Note the use of the function {\tt find} imported from the {\tt List} library. \subsubsection{Converting Haskore Music to a CSound Score File} To convert a {\tt Music} value into a CSound score file, we need to: \begin{enumerate} \item Convert the {\tt Music} value to a {\tt Performance}. \item Convert the {\tt Performance} value to a {\tt Score}. \item Write the {\tt Score} value to a CSound score file. \end{enumerate} We already know how to do the first step. Steps two and three will be achieved by the following two functions: \begin{verbatim} perfToScore :: NameMap -> Performance -> Score writeScore :: Score -> IO () \end{verbatim} The three steps can be put together in whatever way the user wishes, but the most general way would be this: \begin{verbatim} > musicToCSound :: NameMap -> PMap -> Tables -> Context -> Music -> IO () > musicToCSound nmap pmap tables cont m = > writeScore (tables ++ perfToScore nmap (perform pmap cont m)) > > type Tables = Score \end{verbatim} The {\tt Tables} argument is a user-defined set of function tables, represented as a sequence of {\tt ScoreStmt}s (specifically, {\tt CSTable} constructors). (See Section \ref{function-tables-sect}.) \paragraph*{From Performance to Score} The translation between performance {\tt Events} and score {\tt CSNotes} is straightforward, the only tricky parts being: \begin{itemize} \item The unit of time in a {\tt Performance} is the second, whereas in a {\tt Score} it is the beat. However, the default CSound tempo is 60 beats per minute, or one beat per second, as was already mentioned, and we use this default for our {\em Score} files. Thus the two are equivalent, and no translation is necessary. \item In a {\tt Performance}, pitch is represented as an {\tt AbsPitch} value, an integer denoting the absolute position of the pitch in semitones (MIDI uses the same representation). CSound, however, uses different pitch representations, one of them being {\em octave point pitch class}, or ``pch.'' Using pch, a pitch is represented by a decimal number whose integer part represents the octave, and decimal part represents the semitone within the octave (thus 0.00 is the lowest C, 0.11 the lowest B, 8.00 is middle C, etc.). The function {\tt absToPch} defined below performs the required conversion for us. \end{itemize} \begin{verbatim} > perfToScore :: NameMap -> Performance -> Score > perfToScore _ [] = [] > perfToScore nmap (Event t i p d v pfs : evs) = > case (getId nmap i) of > Nothing -> error ("perfToScore: instrument " ++ i ++ " is unknown") > Just num -> CSNote num t d (absToPch p) v pfs : perfToScore nmap evs > > absToPch :: AbsPitch -> Pch > absToPch ap = float (ap `quot` 12) + (float (ap `mod` 12) / 100.0) \end{verbatim} \paragraph*{From Score to Score File} Now that we have a value of type {\tt Score}, we must write it into a plain text ASCII file with an extension {\tt .sco} in a way that CSound will recognize. This is done by the following function: \begin{verbatim} > writeScore :: Score -> IO () > writeScore s = do putStr "\nName your score file " > putStr "(.sco extension will be added): " > name <- getLine > h <- openFile (name ++ ".sco") WriteMode > printScore h s > hClose h \end{verbatim} This function asks the user for the name of the score file, opens that file for writing, writes the score into the file using the function {\tt printScore}, and then closes the file. The score file is a plain text file containing one statement per line. Each statement consists of an opcode, which is a single letter that determines the action to be taken, and a number of arguments. The opcodes we will use are ``e'' for end of score, ``t'' to set tempo, ``f'' to create a function table, and ``i'' for note events. \begin{verbatim} > printScore :: Handle -> Score -> IO () > printScore h [] = hPutStr h "e\n" -- end of score > printScore h (s : ss) = do printStatement h s > printScore h ss \end{verbatim} In the following we will come across several instances where we will need to write a list of floating point numbers into the file, one number at a time, separated by spaces. To do this, we will need to convert the list to a string. This is done by the following function: \begin{verbatim} > listToString :: [Float] -> String > listToString [] = "" > listToString (n : ns) = " " ++ show n ++ listToString ns \end{verbatim} Finally, the {\tt printStatement} function: \begin{verbatim} > printStatement :: Handle -> ScoreStmt -> IO () > printStatement h (CSTempo t) = > hPutStr h ("t 0 " ++ show t ++ "\n") > printStatement h (CSNote i st d p v pfs) = > hPutStr h > ("i " ++ show i ++ " " ++ show st ++ " " ++ show d ++ " " ++ > show p ++ " " ++ show v ++ listToString pfs ++ "\n") > printStatement h (CSTable t ct s n gr) = > hPutStr h > ("f " ++ show t ++ " " ++ show ct ++ " " ++ show s ++ > (if n then " " else " -") ++ showGenRoutine gr ++ "\n") > where showGenRoutine (SoundFile nm st cn) = > "1 " ++ nm ++ " " ++ show st ++ " 0 " ++ show cn > showGenRoutine (GenRoutine gn gas) = > show gn ++ listToString gas \end{verbatim} \subsection{The Orchestra File} \label{orchestra-file-sect} The orchestra file consists of two parts: a {\em header}, and one or more {\em instrument blocks}. The header sets global parameters controlling sampling rate, control rate, and number of output channels. The instrument blocks define instruments, each identified by a unique integer ID, and containing statements modifying or generating various audio signals. Each note statement in a score file passes all its arguments---including the p-fields---to its corresponding instrument in the orchestra file. While some properties vary from note to note, and should therefore be designed as p-fields, many can be defined within the instrument; the choice is up to the user. The orchestra file is represented as: \begin{verbatim} > type Orchestra = (Header, [InstBlock]) \end{verbatim} The orchestra header sets the audio rate, control rate, and number of output channels: \begin{verbatim} > type Header = (AudRate, CtrlRate, Chnls) > > type AudRate = Int -- samples per second > type CtrlRate = Int -- samples per second > type Chnls = Int -- mono=1, stereo=2, surround=4 \end{verbatim} Digital computers represent continuous analog audio waveforms as a sequence of discrete samples. The audio rate ({\tt AudRate}) is the number of these samples calculated each second. Theoretically, the maximum frequency that can be represented is equal to one-half the audio rate. Audio CDs contain 44,100 samples per second of music, giving them a maximum sound frequency of 22,050 Hz, which is as high as most human ears are able to hear. Computing 44,100 values each second can be a demanding task for a CPU, even by today's standards. However, some signals used as inputs to other signal generating routines don't require such a high resolution, and can thus be generated at a lower rate. A good example of this is an amplitude envelope, which changes relatively slowly, and thus can be generated at a rate much lower than the audio rate. This rate is called the {\em control rate} ({\tt CtrlRate}), and is set in the orchestra file header. The audio rate is usually a multiple of the control rate, but this is not a requirement. Each instrument block contains a unique identifying integer, as well as an {\em orchestra expression} that defines the audio signal characterizing that instrument: \begin{verbatim} > type InstBlock = (Inst, OrcExp) \end{verbatim} Recall that {\tt Inst} is a type synonym for an {\tt Int}. This value may be obtained from a string name and a name map using the function {\tt getId :: NameMap -> Name -> Maybe Int} discussed earlier. \subsubsection{Orchestra Expressions} The data type {\tt OrcExp} is the largest deviation that we will make from the actual CSound design. In CSound, instruments are defined using a sequence of statements that, in a piecemeal manner, define the various oscillators, summers, constants, etc.\ that make up an instrument. These pieces can be given names, and these names can be referenced from other statements. But despite this rather imperative, statement-oriented approach, it is acually completely functional. In other words, every CSound instrument can be rewritten as a single expression. It is this ``expression language'' that we capture in {\tt OrcExp}. A pleasant attribute of the result is that CSound's ad hoc naming mechanism is replaced with Haskell's conventional way of naming things. The entire {\tt OrcExp} data type declaration is shown in Figure \ref{OrcExp-fig}. In what follows, we describe each of the various constructors in turn. \begin{figure} {\scriptsize\vspace{-.7in} \begin{verbatim} > data OrcExp = Const Float > | Pfield Int > > | Plus OrcExp OrcExp > | Minus OrcExp OrcExp > | Times OrcExp OrcExp > | Divide OrcExp OrcExp > | Power OrcExp OrcExp > | Modulo OrcExp OrcExp > > | Int OrcExp > | Frac OrcExp > | Neg OrcExp > | Abs OrcExp > | Sqrt OrcExp > | Sin OrcExp > | Cos OrcExp > | Exp OrcExp > | Log OrcExp > > | AmpToDb OrcExp > | DbToAmp OrcExp > | PchToHz OrcExp > | HzToPch OrcExp > > | GreaterThan OrcExp OrcExp OrcExp OrcExp > | LessThan OrcExp OrcExp OrcExp OrcExp > | GreaterOrEqTo OrcExp OrcExp OrcExp OrcExp > | LessOrEqTo OrcExp OrcExp OrcExp OrcExp > | Equals OrcExp OrcExp OrcExp OrcExp > | NotEquals OrcExp OrcExp OrcExp OrcExp > > | MonoOut OrcExp > | LeftOut OrcExp > | RightOut OrcExp > | StereoOut OrcExp OrcExp > | FrontLeftOut OrcExp > | FrontRightOut OrcExp > | RearRightOut OrcExp > | RearLeftOut OrcExp > | QuadOut OrcExp OrcExp OrcExp OrcExp > > | Line EvalRate Start Durn Finish > | Expon EvalRate Start Durn Finish > | LineSeg EvalRate Start Durn Finish [(Durn, Finish)] > | ExponSeg EvalRate Start Durn Finish [(Durn, Finish)] > | Env EvalRate Sig RTime Durn DTime RShape SAttn DAttn Steep > | Phasor EvalRate Freq InitPhase > | TblLookup EvalRate Index Table IndexMode > | TblLookupI EvalRate Index Table IndexMode > | Osc EvalRate Amp Freq Table > | OscI EvalRate Amp Freq Table > | FMOsc Amp Freq CarFreq ModFreq ModIndex Table > | FMOscI Amp Freq CarFreq ModFreq ModIndex Table > | SampOsc Amp Freq Table > | Random EvalRate Amp > | RandomHold EvalRate Amp HoldHz > | RandomI EvalRate Amp HoldHz > | GenBuzz Amp Freq NumHarms LoHarm Multiplier Table > | Buzz Amp Freq NumHarms Table > | Pluck Amp Freq Table DecayMethod DecArg1 DecArg2 > | Delay MaxDel AudioSig > | DelTap TapTime DelLine > | DelTapI TapTime DelLine > | DelayW AudioSig > | Comb AudioSig RevTime LoopTime > | AlPass AudioSig RevTime LoopTime > | Reverb AudioSig RevTime > deriving (Show, Eq) \end{verbatim}} \caption{The OrcExp Data Type} \label{OrcExp-fig} \end{figure} \paragraph*{Constants} {\tt Const x} represents the floating-point constant {\tt x}. \paragraph*{P-field Arguments} {\tt Pfield n} refers to the $n$th p-field argument. Recall that all note characteristics, including pitch, volume, and duration, are passed into the orchestra file as p-fields. For example, to access the pitch, one would write {\tt Pfield 4}. To make the access of these most common p-fields easier, we define the following constants: \begin{verbatim} > noteDur, notePit, noteVol :: OrcExp > noteDur = Pfield 3 > notePit = Pfield 4 > noteVol = Pfield 5 \end{verbatim} It is also useful to define the following standard names, which are identical to those used in CSound: \begin{verbatim} > p1,p2,p3,p4,p5,p6,p7,p8,p9 :: OrcExp > p1 = Pfield 6 > p2 = Pfield 7 > p3 = Pfield 8 > p4 = Pfield 9 > p5 = Pfield 10 > p6 = Pfield 11 > p7 = Pfield 12 > p8 = Pfield 13 > p9 = Pfield 14 \end{verbatim} \paragraph*{Arithmetic and Transcendental Functions} Arithmetic expressions are represented by the constructors {\tt Plus}, {\tt Minus}, {\tt Times}, {\tt Divide}, {\tt Power}, and {\tt Modulo}, each taking two {\tt OrcExps} as arguments. In addition, there are a number of unary arithmatic functions: {\tt Int x} and {\tt Frac x} represent the integer and fractional parts, respectively, of {\tt x}. {\tt Abs x}, {\tt Neg x}, {\tt Sqrt x}, {\tt Sin x}, and {\tt Cos x} represent the absolute value, negation, square root, sine and cosine (in radians) of {\tt x}, respectively. {\tt Exp x} represents $e$ raised to the power {\tt x}, and {\tt Log x} is the natural logarithm of {\tt x}. To facilitate the use of these arithmetic functions, we can make {\tt OrcExp} an instance of certain numeric type classes, thus providing more conventional names for the various operations. \begin{verbatim} > instance Num OrcExp where > (+) = Plus > (-) = Minus > (*) = Times > negate = Neg > abs = Abs > fromInteger i = Const (fromInteger i) > -- omitted: signum > instance Fractional OrcExp where > (/) = Divide > fromRational x = Const (fromRational x) > instance Floating OrcExp where > exp = Exp > log = Log > sqrt = Sqrt > (**) = Power > sin = Sin > cos = Cos > pi = Const pi > tan x = Sin x / Cos x > -- omitted: asin, acos, atan :: a -> a > -- sinh, cosh, tanh :: a -> a > -- asinh, acosh, atanh :: a -> a \end{verbatim} For example, {\tt Plus (Pfield 3) (Power (Sin (Pfield 6)) (Const 2))} can now be written simply as {\tt noteDur + sin p6 ** 2}. \paragraph*{Pitch and Volume Coercions} The next set of constructors represent functions that convert between different CSound pitch and volume representations. Recall that the {\tt CSNote} constructor uses decibels for volume and ``pch'' notation for pitch. If these values are to be used as inputs into a signal generating or modifying routine, they must first be converted into units of raw amplitude and hertz, respectively. This is accomplished by the functions represented by {\tt DbToAmp} and {\tt PchToHz}, and their inverses are {\tt AmpToDb} and {\tt HzToPch}. Thus note that {\tt PchToHz (notePit + 0.01)} raises the pitch by one semitone, whereas {\tt PchToHz notePit + 0.01} raises the pitch by 0.01 Hz. \paragraph*{Comparison Operators} {\tt OrcExp} also includes comparison constructors {\tt GreaterThan}, {\tt LessThan}, {\tt GreaterOrEqTo}, {\tt LessOrEqTo}, {\tt Equals}, and {\tt NotEquals}. Each takes four {\tt OrcExp} arguments: the values of the first two are compared, and if the result is true, the expression evaluates to the third argument; otherwise, it takes on the value of the fourth.\footnote{This design emulates that of CSound. A more conventional design would have comparison operators that return a Boolean value, and a conditional expression to choose between two values based on a Boolean. One could then add Boolean operators such as ``and'', ``or'', etc. It seems possible to do this in Haskore, but its translation into CSound would be more difficult, and thus we take the more conservative approach for now.} \paragraph*{Output Operators} The next group of constructors represent CSound's {\em output statements}. The constructors are {\tt MonoOut}, {\tt LeftOut}, {\tt RightOut}, {\tt StereoOut}, {\tt FrontLeftOut}, {\tt FrontRightOut}, {\tt RearRightOut}, {\tt RearLeftOut}, and {\tt QuadOut}. {\tt StereoOut} takes two {\tt OrcExp} arguments, {\tt QuadOut} takes four, and the rest take one. The top-level of an instrument's {\tt OrcExp} (i.e., the one in the {\tt InstBlock} value) will normally be an application of one of these. Furthermore, the constructor used must be in agreement with the number of output channels specified in the orchestra header---for example, using {\tt LeftOut} when the header declares the resulting sound file to be mono will result in an error. \paragraph*{Signal Generation and Modification} The most sophisticated {\tt OrcExp} constructors are those that emulate CSound's signal generation and modification functions. There are quite a few of them, and they are all described here, although the reader is encouraged to read the CSound manual for further details. Before defining each constructor, however, there are two general issues to discuss: First, signals in CSound can be generated at three rates: the note rate (i.e., with every note event), the control rate, and the audio rate (we discussed the latter two earlier). Many of the signal generating routines can produce signals at more than one rate, so the rate must be specified as an argument. The following simple data structure serves this purpose: \begin{verbatim} > data EvalRate = NR -- note rate > | CR -- control rate > | AR -- audio rate > deriving (Show, Eq) \end{verbatim} Second, note in Figure \ref{OrcExp-fig} that this collection of constructors uses quite a few other type names. In all cases, however, these are simply type synonyms for {\tt OrcExp}, and are used only for clarity. These type synonyms are listed here in one fell swoop: \begin{verbatim} > type Start = OrcExp > type Durn = OrcExp > type Finish = OrcExp > type Sig = OrcExp > type RTime = OrcExp > type DTime = OrcExp > type RShape = OrcExp > type SAttn = OrcExp > type DAttn = OrcExp > type Steep = OrcExp > type Freq = OrcExp > type InitPhase = OrcExp > type Index = OrcExp > type Table = OrcExp > type IndexMode = OrcExp > type Amp = OrcExp > type CarFreq = OrcExp > type ModFreq = OrcExp > type ModIndex = OrcExp > type HoldHz = OrcExp > type NumHarms = OrcExp > type LoHarm = OrcExp > type Multiplier = OrcExp > type DecayMethod = OrcExp > type DecArg1 = OrcExp > type DecArg2 = OrcExp > type MaxDel = OrcExp > type AudioSig = OrcExp > type TapTime = OrcExp > type DelLine = OrcExp > type RevTime = OrcExp > type LoopTime = OrcExp \end{verbatim} We can now discuss each constructor in turn: \begin{enumerate} \item {\tt Line evalrate start durn finish} produces values along a straight line from {\tt start} to {\tt finish}. The values can be generated either at control or audio rate, and the line covers a period of time equal to {\tt durn} seconds. \item {\tt Expon} is similar to {\tt Line}, but {\tt Expon evalrate start durn finish} produces an exponential curve instead of a straight line. \item If a more elaborate signal is required, one can use the constructors {\tt LineSeg} or {\tt ExponSeg}, which take arguments of type {\tt EvalRate}, {\tt Start}, {\tt Durn}, and {\tt Finish}, as above, and also {\tt [(Durn, Finish)]}. The first four arguments work as before, but only for the first of a number of segments. The subsequent segment lengths and endpoints are given in the fifth argument. A signal containing both straight line and exponential segments can be obtained by adding a {\tt LineSeg} signal and {\tt ExponSeg} signal together in an appropriate way. \item {\tt Env evalrate sig rtime durn dtime rshape sattn dattn steep} modifies the signal {\tt sig} by applying an envelope to it.\footnote{Although this function is widely-used in CSound, the same effect can be accomplished by creating a signal that is a combination of straight line and exponential curve segments, and multiplying it by the signal to be modified.} {\tt rtime} and {\tt dtime} are the rise time and decay time, respectively (in seconds), and {\tt durn} is the overall duration. {\tt rshape} is the identifier integer of a function table storing the rise shape. {\tt sattn} is the pseudo-steady state attenuation factor. A value between 0 and 1 will cause the signal to exopnentially decay over the steady period, a value greater than 1 will cause the signal to exponentially rise, and a value of 1 is a true steady state maintained at the last rise value. {\tt steep}, whose value is usually between $-0.9$ and $+0.9$, influences the steepness of the exponential trajectory. {\tt dattn} is the attenuation factor by which the closing steady state value is reduced exponentially over the decay period, with value usually around 0.01. \item {\tt Phasor evalrate freq initphase} generates a signal moving from 0 to 1 at a given frequency and starting at the given initial phase offset. When used properly as the index to a table lookup unit, {\tt Phasor} can simulate the behavior of an oscillator. \item Table lookup constructors {\tt TblLookup} and {\tt TblLookupI} both take {\tt EvalRate}, {\tt Index}, {\tt Table}, and {\tt IndexMode} arguments. The {\tt IndexMode} is either 0 or 1, differentiating between raw index and normalized index (zero to one); for convenience we define: \begin{verbatim} > rawIndex, normalIndex :: OrcExp > rawIndex = 0.0 > normalIndex = 1.0 \end{verbatim} Both {\tt TblLookup} and {\tt TblLookupI} return values stored in the specified table at the given index. The difference is that {\tt TblLookupI} uses the fractional part of the index to interpolate between adjacent table entries, which generates a smoother signal at a small cost in execution time. As mentioned, the output of a {\tt Phasor} can be used as input to a table lookup to simulate an oscillator whose frequencey is controlled by the note pitch. This can be accomplished easily by the following piece of Haskore code: \begin{verbatim} osc = let index = Phasor AR (PchToHz notePit) 0.0 in TblLookupI AR index table normalIndex \end{verbatim} where {\tt table} is some given function table ID. If {\tt osc} is given as argument to an output operator such as {\tt MonoOut}, then this {\tt OrcExp} coupled with an instrument ID number (say, 1) produces a complete instrument block: \begin{verbatim} i1 = (1, MonoOut osc) \end{verbatim} Adding a suitable {\tt Header} would then give us a complete, though somewhat sparse, {\tt Orchestra} value. \item Instead of the above design we could use one of the built-in CSound oscillators, {\tt Osc} and {\tt OscI}, which differ in the same way as {\tt TblLookup} and {\tt TblLookupI}. Each oscillator constructor takes arguments of type {\tt EvalRate}, {\tt Amp} (in raw amplitude), {\tt Freq} (in Hertz), and {\tt Table}. The result is a signal that oscillates through the function table at the given frequency. Thus the following value is equivalent to {\tt osc} above: \begin{verbatim} osc' = OscI AR 1 (PchToHz notePit) table \end{verbatim} \item It is often desirable to use the output of one oscillator to modulate the frequency of another, a process known as {\em frequency modulation}. {\tt FMOsc amp freq carfreq modfreq modindex table} is a signal whose effective modulating frequency is {\tt freq*modfreq}, and whose carrier frequency is {\tt freq*carfreq}. {\tt modindex} is the {\em index of modulation}, usually a value between 0 and 4, which determines the timbre of the resulting signal. {\tt FMOscI} behaves similarly. Note that there is no {\tt EvalRate} argument, since these functions work at audio rate only. The given function table normally contains a sine wave. This oscillator setup is known as the {\em chowning FM} setup. \item {\tt SampOsc amp freq table} oscillates through a table containing an AIFF sampled sound segment. This is the only time a table can have a length that is not a power of two, as mentioned earlier. Like {\tt FMOsc}, {\tt SampOsc} can only generate values at the audio rate. \item {\tt Random evalrate amp} produces a random number series between {\tt -amp} and {\tt +amp} at either control or audio rate. {\tt RandomHold evalrate amp holdhz} does the same but will hold each number for {\tt holdhz} cycles before generating a new one. {\tt RandomI evalrate amp holdhz} will in addition provide straight line interpolation between successive numbers. All the remaining constructors only operate at audio rate, and thus do not have {\tt EvalRate} arguments. \item {\tt GenBuzz amp freq numharms loharm multiplier table} generates a signal that is an additive set of harmonically related cosine partials. {\tt freq} is the fundamental frequency, {\tt numharms} is the number of harmonics, and {\tt loharm} is the lowest harmonic present. The amplitude coefficients of the harmonics are given by the exponential series {\tt a}, {\tt a * multiplier}, {\tt a * multiplier**2}, $\ldots$ , {\tt a * multiplier**(numharms-1)}. The value {\tt a} is chosen so that the sum of the amplitudes is {\tt amp}. {\tt table} is a function table containing a cosine wave. \item {\tt Buzz} is a special case of {\tt GenBuzz} in which {\tt loharm = 1.0} and {\tt Multiplier = 1.0}. {\tt table} is a function table containing a sine wave. Note that the above two constructors have an analog in the generating routine GEN11 and the related function {\tt cosineHarms} (see Section \ref{function-table-sect}). {\tt cosineHarms} stores into a table the same waveform that would be generated by {\tt Buzz} or {\tt GenBuzz}. However, although {\tt cosineHarms} is more efficient, it has fixed arguments and thus lacks the flexibility of {\tt Buzz} and {\tt GenBuzz} in being able to vary the argument values with time. \item {\tt Pluck amp freq table decaymethod decarg1 decarg2} is an audio signal that simulates a plucked string or drum sound, constructed using the Karplus-Strong algorithm. The signal has amplitude {\tt amp} and frequency {\tt freq}. It is produced by iterating through an internal buffer that initially contains a copy of {\tt table} and is smoothed on every pass to simulate the natural decay of a plucked string. If 0.0 is used for {\tt table}, then the initial buffer is filled with a random sequence. There are six possible decay modes: \begin{enumerate} \item {\em simple smoothing}, which ignores the two arguments; \item {\em stretched smoothing}, which stretches the smoothing time by a factor of {\tt decarg1}, ignoring {\tt decarg2}; \item {\em simple drum}, where {\tt decarg1} is a ``roughness factor'' (0 for pitch, 1 for white noise; a value of 0.5 gives an optimal snare drum sound); \item {\em stretched drum}, which contains both roughness ({\tt decarg1}) and stretch ({\tt decarg2}) factors; \item {\em weighted smoothing}, in which {\tt decarg1} gives the weight of the current sample and {\tt decarg2} the weight of the previous one ({\tt decarg1+decarg2} must be $\leq1$); and \item {\em recursive filter smoothing}, which ignores both arguments. \end{enumerate} Here again are some helpful constants: \begin{verbatim} > simpleSmooth, stretchSmooth, simpleDrum, stretchDrum, > weightedSmooth, filterSmooth :: OrcExp > simpleSmooth = 1.0 > stretchSmooth = 2.0 > simpleDrum = 3.0 > stretchDrum = 4.0 > weightedSmooth = 5.0 > filterSmooth = 6.0 \end{verbatim} \item {\tt Delay deltime audiosig} establishes a digital delay line, where {\tt audiosig} is the source, and {\tt deltime} is the delay time in seconds. The delay line can also be {\em tapped} by {\tt DelayTap deltime delline} and {\tt DelayTapI deltime delline}, where {\tt deltime} is the tap delay, and {\tt delline} must be a delay line created by the {\tt Delay} constructor above. Again, {\tt DelayTapI} uses interpolation, and may take up to twice as long as {\tt DelayTap} to run, but produces higher precision results and thus a cleaner signal. (Note: the constructor {\tt DelayW} is used in the translation described later to mark the end of a sequence of delay taps, and is not intended for use by the user.) \item Reverberation can be added to a signal using {\tt Comb audiosig revtime looptime}, {\tt AlPass audiosig revtime looptime}, and {\tt Reverb audiosig revtime}. {\tt revtime} is the time in seconds it takes a signal to decay to 1/1000th of its original amplitude, and {\tt looptime} is the echo density. {\tt Comb} produces a ``colored'' reverb, {\tt AlPass} a ``flat'' reverb, and {\tt Reverb} a ``natural room'' reverb. \end{enumerate} \subsubsection{Converting Orchestra Values to Orchestra Files} We must now convert the {\tt OrcExp} values into a form which can be written into a CSound {\tt .sco} file. As mentioned earlier, each signal generation or modification statement in CSound assigns its result a string name. This name is used whenever another statement takes the signal as an argument. Names of signals generated at note rate must begin with the letter ``i'', control rate with letter ``k'', and audio rate with letter ``a''. The output statements do not generate a signal so they do not have a result name. \begin{figure} {\scriptsize\vspace{-.9in} \begin{verbatim} > mkList :: OrcExp -> [(EvalRate, OrcExp)] > mkList (Const _) = [] > mkList (Pfield _) = [] > mkList (x1 `Plus` x2) = mkListAll [x1,x2] > mkList (x1 `Minus` x2) = mkListAll [x1,x2] > mkList (x1 `Times` x2) = mkListAll [x1,x2] > mkList (x1 `Divide` x2) = mkListAll [x1,x2] > mkList (x1 `Power` x2) = mkListAll [x1,x2] > mkList (x1 `Modulo` x2) = mkListAll [x1,x2] > mkList (Int x) = mkList x > mkList (Frac x) = mkList x > mkList (Abs x) = mkList x > mkList (Neg x) = mkList x > mkList (Sqrt x) = mkList x > mkList (Sin x) = mkList x > mkList (Cos x) = mkList x > mkList (Exp x) = mkList x > mkList (Log x) = mkList x > mkList (AmpToDb x) = mkList x > mkList (DbToAmp x) = mkList x > mkList (PchToHz x) = mkList x > mkList (HzToPch x) = mkList x > mkList (GreaterThan x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (LessThan x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (GreaterOrEqTo x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (LessOrEqTo x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (Equals x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (NotEquals x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (QuadOut x1 x2 x3 x4) = mkListAll [x1,x2,x3,x4] > mkList (StereoOut x1 x2) = mkListAll [x1,x2] > mkList (MonoOut x) = mkList x > mkList (LeftOut x) = mkList x > mkList (RightOut x) = mkList x > mkList (FrontLeftOut x) = mkList x > mkList (FrontRightOut x) = mkList x > mkList (RearRightOut x) = mkList x > mkList (RearLeftOut x) = mkList x > mkList oe@(Line er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(Expon er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(LineSeg er x1 x2 x3 xs) > = (er,oe) : mkListAll (x1:x2:x3: flattenTuples2 xs) > mkList oe@(ExponSeg er x1 x2 x3 xs) > = (er,oe) : mkListAll (x1:x2:x3: flattenTuples2 xs) > mkList oe@(Env er x1 x2 x3 x4 x5 x6 x7 x8) > = (er,oe) : mkListAll [x1,x2,x3,x4,x5,x6,x7,x8] > mkList oe@(Phasor er x1 x2) = (er,oe) : mkListAll [x1,x2] > mkList oe@(TblLookup er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(TblLookupI er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(Osc er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(OscI er x1 x2 x3) = (er,oe) : mkListAll [x1,x2,x3] > mkList oe@(Random er x) = (er,oe) : mkList x > mkList oe@(RandomHold er x1 x2) = (er,oe) : mkListAll [x1,x2] > mkList oe@(RandomI er x1 x2) = (er,oe) : mkListAll [x1,x2] > mkList oe@(FMOsc x1 x2 x3 x4 x5 x6)= (AR,oe) : mkListAll [x1,x2,x3,x4,x5,x6] > mkList oe@(FMOscI x1 x2 x3 x4 x5 x6) > = (AR,oe) : mkListAll [x1,x2,x3,x4,x5,x6] > mkList oe@(SampOsc x1 x2 x3) = (AR,oe) : mkListAll [x1,x2,x3] > mkList oe@(GenBuzz x1 x2 x3 x4 x5 x6) > = (AR,oe) : mkListAll [x1,x2,x3,x4,x5,x6] > mkList oe@(Buzz x1 x2 x3 x4) = (AR,oe) : mkListAll [x1,x2,x3,x4] > mkList oe@(Pluck x1 x2 x3 x4 x5 x6)= (AR,oe) : mkListAll [x1,x2,x3,x4,x5,x6] > mkList oe@(Delay x1 x2) = (AR,oe) : mkListAll [x1,x2] > mkList oe@(DelTap x1 x2) = (AR,oe) : mkList x2 > mkList oe@(DelTapI x1 x2) = (AR,oe) : mkList x2 > mkList oe@(DelayW x) = error "DelayW not for you!" > mkList oe@(Comb x1 x2 x3) = (AR,oe) : mkListAll [x1,x2,x3] > mkList oe@(AlPass x1 x2 x3) = (AR,oe) : mkListAll [x1,x2,x3] > mkList oe@(Reverb x1 x2) = (AR,oe) : mkListAll [x1,x2] \end{verbatim}} \caption{The {\tt mkList} Function} \label{mkList-fig} \end{figure} The function {\tt mkList} is shown in Figure \ref{mkList-fig}, and creates an entry in the list for every signal generating, modifying, or outputting constructor. It uses the following auxiliary functions: \begin{verbatim} > mkListAll :: [OrcExp] -> [(EvalRate, OrcExp)] > mkListAll = foldr (++) [] . map mkList > > addNames :: [(EvalRate,OrcExp)] -> [(Name,OrcExp)] > addNames ls = zipWith counter ls [1..] > where counter (er,x) n = > let var = case er of > AR -> 'a' : show n > CR -> 'k' : show n > NR -> 'i' : show n > in (var,x) \end{verbatim} Putting all of the above together, here is a function that converts an {\tt OrcExp} into a list of proper name / {\tt OrcExp} pairs. Each one of these will eventually result in one statement in the CSound orchestra file. (The result of {\tt mkList} is reversed to ensure that a definition exists before it is used; and this must be done {\em before} {\tt nub} is applied (which removes duplicates), for the same reason.) \begin{verbatim} > processOrcExp :: OrcExp -> [(Name, OrcExp)] > processOrcExp = addNames . nub . procDelay . reverse . mkList \end{verbatim} The function {\tt procDelay} is used to process delay lines, which require special treatment because a delay line followed by a number of taps must be ended in Csound with a {\tt DelayW} command. \begin{verbatim} > procDelay :: [(EvalRate, OrcExp)] -> [(EvalRate, OrcExp)] > procDelay [] = [] > procDelay (x@(AR, d@(Delay _ _)) : xs) = [x] ++ procTaps d xs ++ procDelay xs > procDelay (x : xs) = x : procDelay xs > > procTaps :: OrcExp -> [(EvalRate, OrcExp)] -> [(EvalRate, OrcExp)] > procTaps d@(Delay t sig) [] = [(AR, DelayW sig)] > procTaps d (x@(AR,DelTap t dl) : xs) = > if d == dl then (mkList t ++ [x] ++ procTaps d xs) > else procTaps d xs > procTaps d (x@(AR,DelTapI t dl): xs) = > if d == dl then (mkList t ++ [x] ++ procTaps d xs) > else procTaps d xs > procTaps d (x : xs) = procTaps d xs \end{verbatim} The functions that follow are used to write the orchestra file. {\tt writeOrchestra} is similar to {\tt writeScore}: it asks the user for a file name, opens the file, writes the given orchestra value to the file, and then closes the file. \begin{verbatim} > writeOrchestra :: Orchestra -> IO () > writeOrchestra orch = do putStr "\nName your orchestra file " > putStr "(.orc extension will be added): " > name <- getLine > h <- openFile (name ++ ".orc") WriteMode > writeOrc h orch > hClose h \end{verbatim} {\tt writeOrc} splits the task of writing the orchestra into two parts: writing the header and writing the instrument blocks \begin{verbatim} > writeOrc :: Handle -> Orchestra -> IO () > writeOrc h (hdr,ibs) = do writeHeader h hdr > writeIBlocks h ibs \end{verbatim} Writing the header is relatively simple, and is accomplished by the following function: \begin{verbatim} > writeHeader :: Handle -> Header -> IO () > writeHeader h (a,k,nc) = > hPutStrLn h ( "sr = " ++ show a ++ > "\nkr = " ++ show k ++ > "\nksmps = " ++ show (float a / float k) ++ > "\nnchnls = " ++ show nc) \end{verbatim} {\tt writeIBlocks} writes each instrument block using the function {\tt writeIBlock}: \begin{verbatim} > writeIBlocks :: Handle -> [InstBlock] -> IO () > writeIBlocks h = mapM_ (writeIBlock h) \end{verbatim} {\tt writeIBlock} writes a single instrument block. \begin{verbatim} > writeIBlock :: Handle -> InstBlock -> IO () > writeIBlock h (num,ox) = > do hPutStrLn h ("\ninstr " ++ show num) > writeOrcExps h (processOrcExp ox ++ [("",ox)]) > hPutStrLn h "endin" \end{verbatim} Recall that after processing, the {\tt OrcExp} becomes a list of {\tt (Name, OrcExp)} pairs. The last few functions write each of these named {\tt OrcExp}s as a statement in the orchestra file. Whenever a signal generation/modification constructor is encountered in an argument list of another constructor, the argument's string name is used instead, as found in the list of {\tt (Name, OrcExp)} pairs. \begin{figure} {\scriptsize\vspace{-.7in} \begin{verbatim} > writeOrcExps :: Handle -> [(Name,OrcExp)] -> IO () > writeOrcExps h noes = mapM_ writeOrcExp noes > where > writeOrcExp :: (Name,OrcExp) -> IO () > writeOrcExp (nm, MonoOut x) = hPutStr h "out " >> writeArgs [x] > writeOrcExp (nm, LeftOut x) = hPutStr h "outs1 " >> writeArgs [x] > writeOrcExp (nm, RightOut x) = hPutStr h "outs2 " >> writeArgs [x] > writeOrcExp (nm, StereoOut x1 x2) = hPutStr h "outs " >> writeArgs [x1,x2] > writeOrcExp (nm, FrontLeftOut x) = hPutStr h "outq1 " >> writeArgs [x] > writeOrcExp (nm, FrontRightOut x) = hPutStr h "outq2 " >> writeArgs [x] > writeOrcExp (nm, RearRightOut x) = hPutStr h "outq3 " >> writeArgs [x] > writeOrcExp (nm, RearLeftOut x) = hPutStr h "outq4 " >> writeArgs [x] > writeOrcExp (nm, QuadOut x1 x2 x3 x4) = hPutStr h "outq " >> writeArgs [x1,x2,x3,x4] > writeOrcExp (nm, Line er x1 x2 x3) = > hPutStr h (nm ++ " line ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, Expon er x1 x2 x3) = > hPutStr h (nm ++ " expon ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, LineSeg er x1 x2 x3 xlist) = > hPutStr h (nm ++ " linseg ") >> writeArgs ([x1,x2,x3] ++ flattenTuples2 xlist) > writeOrcExp (nm, ExponSeg er x1 x2 x3 xlist) = > hPutStr h (nm ++ " expseg ") >> writeArgs ([x1,x2,x3] ++ flattenTuples2 xlist) > writeOrcExp (nm, Env er x1 x2 x3 x4 x5 x6 x7 x8) = > hPutStr h (nm ++ " envlpx ") >> writeArgs [x1,x2,x3,x4,x5,x6,x7,x8] > writeOrcExp (nm, Phasor er x1 x2) = > hPutStr h (nm ++ " phasor ") >> writeArgs [x1,x2] > writeOrcExp (nm, TblLookup er x1 x2 x3) = > hPutStr h (nm ++ " table ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, TblLookupI er x1 x2 x3) = > hPutStr h (nm ++ " tablei ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, Osc er x1 x2 x3) = > hPutStr h (nm ++ " oscil ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, OscI er x1 x2 x3) = > hPutStr h (nm ++ " oscili ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, FMOsc x1 x2 x3 x4 x5 x6) = > hPutStr h (nm ++ " foscil ") >> writeArgs [x1,x2,x3,x4,x5,x6] > writeOrcExp (nm, FMOscI x1 x2 x3 x4 x5 x6) = > hPutStr h (nm ++ " foscili ") >> writeArgs [x1,x2,x3,x4,x5,x6] > writeOrcExp (nm, SampOsc x1 x2 x3) = > hPutStr h (nm ++ " loscil ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, Random er x) = > hPutStr h (nm ++ " rand ") >> writeArgs [x] > writeOrcExp (nm, RandomHold er x1 x2) = > hPutStr h (nm ++ " randh ") >> writeArgs [x1,x2] > writeOrcExp (nm, RandomI er x1 x2) = > hPutStr h (nm ++ " randi ") >> writeArgs [x1,x2] > writeOrcExp (nm, GenBuzz x1 x2 x3 x4 x5 x6) = > hPutStr h (nm ++ " gbuzz ") >> writeArgs [x1,x2,x3,x4,x5,x6] > writeOrcExp (nm, Buzz x1 x2 x3 x4) = > hPutStr h (nm ++ " buzz ") >> writeArgs [x1,x2,x3,x4] > writeOrcExp (nm, Pluck x1 x2 x3 x4 x5 x6) = > hPutStr h (nm ++ " pluck ") >> writeArgs [x1,x2,x2,x3,x4,x5,x6] > writeOrcExp (nm, Delay x1 x2) = hPutStr h (nm ++ " delayr ") >> writeArgs [x1] > writeOrcExp (nm, DelayW x) = hPutStr h (" delayw ") >> writeArgs [x] > writeOrcExp (nm, DelTap x1 x2) = hPutStr h (nm ++ " deltap ") >> writeArgs [x1] > writeOrcExp (nm, DelTapI x1 x2) = hPutStr h (nm ++ " deltapi ") >> writeArgs [x1] > writeOrcExp (nm, Comb x1 x2 x3) = hPutStr h (nm ++ " comb ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, AlPass x1 x2 x3) = hPutStr h (nm ++ " alpass ") >> writeArgs [x1,x2,x3] > writeOrcExp (nm, Reverb x1 x2) = hPutStr h (nm ++ " reverb ") >> writeArgs [x1,x2] > writeOrcExp _ = error "writeOrcExp: unknown constructor\n" > > writeArgs :: [OrcExp] -> IO () > writeArgs [x] = hPutStrLn h (showExp noes x) > writeArgs (x:xs) = hPutStr h (showExp noes x ++ ", ") >> writeArgs xs \end{verbatim}} \caption{The Function {\tt writeOrcExp}} \label{writeOrcExp-fig} \end{figure} \begin{figure} \begin{verbatim} > showExp :: [(Name, OrcExp)] -> OrcExp -> String > showExp _ (Const x) = show x > showExp _ (Pfield p) = "p" ++ show p > showExp xs (x1 `Plus` x2) = showBin xs " + " x1 x2 > showExp xs (x1 `Minus` x2) = showBin xs " - " x1 x2 > showExp xs (x1 `Times` x2) = showBin xs " * " x1 x2 > showExp xs (x1 `Divide` x2) = showBin xs " / " x1 x2 > showExp xs (x1 `Power` x2) = showBin xs " ^ " x1 x2 > showExp xs (x1 `Modulo` x2) = showBin xs " % " x1 x2 > showExp xs (Int x) = "int(" ++ showExp xs x ++ ")" > showExp xs (Frac x) = "frac(" ++ showExp xs x ++ ")" > showExp xs (Abs x) = "abs(" ++ showExp xs x ++ ")" > showExp xs (Neg x) = "-(" ++ showExp xs x ++ ")" > showExp xs (Sqrt x) = "sqrt(" ++ showExp xs x ++ ")" > showExp xs (Sin x) = "sin(" ++ showExp xs x ++ ")" > showExp xs (Cos x) = "cos(" ++ showExp xs x ++ ")" > showExp xs (Exp x) = "exp(" ++ showExp xs x ++ ")" > showExp xs (Log x) = "log(" ++ showExp xs x ++ ")" > showExp xs (AmpToDb x) = "dbamp(" ++ showExp xs x ++ ")" > showExp xs (DbToAmp x) = "ampdb(" ++ showExp xs x ++ ")" > showExp xs (PchToHz x) = "cpspch(" ++ showExp xs x ++ ")" > showExp xs (HzToPch x) = "pchoct (octcps(" ++ showExp xs x ++ "))" > showExp xs (GreaterThan x1 x2 x3 x4) = showComp xs " > " x1 x2 x3 x4 > showExp xs (LessThan x1 x2 x3 x4) = showComp xs " < " x1 x2 x3 x4 > showExp xs (GreaterOrEqTo x1 x2 x3 x4) = showComp xs " >= " x1 x2 x3 x4 > showExp xs (LessOrEqTo x1 x2 x3 x4) = showComp xs " <= " x1 x2 x3 x4 > showExp xs (Equals x1 x2 x3 x4) = showComp xs " == " x1 x2 x3 x4 > showExp xs (NotEquals x1 x2 x3 x4) = showComp xs " != " x1 x2 x3 x4 > showExp xs ox = case find (\(nm,oexp) -> ox==oexp) xs of > Just (nm,_) -> nm > Nothing -> error ("showExp: constructor not found\n") > > showBin xs s x1 x2 = > "(" ++ showExp xs x1 ++ s ++ showExp xs x2 ++ ")" > showComp xs s x1 x2 x3 x4 = > "(" ++ showExp xs x1 ++ s ++ showExp xs x2 ++ " ? " ++ > showExp xs x3 ++ " : " ++ showExp xs x4 ++ ")" \end{verbatim} \caption{The Function {\tt showExp}} \label{showExp-fig} \end{figure} \subsection{An Orchestra Example} Figure \ref{csound-orc-file-fig} shows a typical CSound orchestra file. Figure \ref{orc-def-fig} shows how this same functionality would be achieved in Haskore using an {\tt Orchestra} value. Finally, Figure \ref{orc-file-result-fig} shows the result of applying {\tt writeOrchestra} to {\tt orc1} shown in Figure \ref{orc-def-fig}. Figures \ref{csound-orc-file-fig} and \ref{orc-file-result-fig} should be compared: you will note that except for name changes, they are the same, as they should be. \begin{figure} \begin{verbatim} sr = 48000 kr = 24000 ksmps = 2 nchnls = 2 instr 4 inote = cpspch(p5) k1 envlpx ampdb(p4), .001, p3, .05, 6, -.1, .01 k2 envlpx ampdb(p4), .0005, .1, .1, 6, -.05, .01 k3 envlpx ampdb(p4), .001, p3, p3, 6, -.3, .01 a1 oscili k1, inote, 1 a2 oscili k1, inote * 1.004, 1 a3 oscili k2, inote * 16, 1 a4 oscili k3, inote, 5 a5 oscili k3, inote * 1.004, 5 outs (a2 + a3 + a4) * .75, (a1 + a3 + a5) * .75 endin \end{verbatim} \caption{Sample CSound Orchestra File} \label{csound-orc-file-fig} \end{figure} \begin{figure} \begin{verbatim} > orc1 :: Orchestra > orc1 = > let hdr = (48000, 24000, 2) > inote = PchToHz p5 > k1 = Env CR (DbToAmp p4) 0.001 p3 0.05 6 (-0.1) 0.01 0 > k2 = Env CR (DbToAmp p4) 0.0005 0.1 0.1 6 (-0.05) 0.01 0 > k3 = Env CR (DbToAmp p4) 0.001 p3 p3 6 (-0.3) 0.01 0 > a1 = OscI AR k1 inote 1 > a2 = OscI AR k1 (inote*1.004) 1 > a3 = OscI AR k2 (inote*16) 1 > a4 = OscI AR k3 inote 5 > a5 = OscI AR k3 (inote*1.004) 5 > out = StereoOut ((a2+a3+a4) * 0.75) ((a1+a3+a5) * 0.75) > ib = (4,out) > in (hdr,[ib]) > t1 = processOrcExp (snd (head (snd orc1))) \end{verbatim} \caption{Haskore Orchestra Definition} \label{orc-def-fig} \end{figure} \begin{figure} \begin{verbatim} sr = 48000 kr = 24000 ksmps = 2.0 nchnls = 2 instr 4 k1 envlpx ampdb(p4), 0.001, p3, p3, 6.0, -0.3, 0.01, 0.0 a2 osci k1, (cpspch(p5) * 1.004), 5.0 k3 envlpx ampdb(p4), 0.0005, 0.1, 0.1, 6.0, -0.05, 0.01, 0.0 a4 osci k3, (cpspch(p5) * 16.0), 1.0 k5 envlpx ampdb(p4), 0.001, p3, 0.05, 6.0, -0.1, 0.01, 0.0 a6 osci k5, cpspch(p5), 1.0 a7 osci k1, cpspch(p5), 5.0 a8 osci k5, (cpspch(p5) * 1.004), 1.0 outs (((a8 + a4) + a7) * 0.75), (((a6 + a4) + a2) * 0.75) endin \end{verbatim} \caption{Result of {\tt writeOrchestra orc1}} \label{orc-file-result-fig} \end{figure} --------------------------------------------------------------------