CSRW_DOC.TXT Master doco file for Robin Whittle's Csound activities 11 September 1995 Robin Whittle firstpr@ozemail.com.au rwhittle@ozonline.com.au http://www.ozemail.com.au/~firstpr For Csound users and C programmers. This file documents the features of my current release of CSOUND.EXE and the source code which produced it. This source code can be easily added to Csound sources for compilation on machines other than MSDOS. Following that is a list of all the relevant doco and .ZIP files. Then there are some copyright notices. After that I describe my priorities for extending Csound. Then there is a "wish list" or things I want to do. There are no example files in this release. I have only been doing test files and programming recently. Paris warned me about the "dark side" - so if you don't see any .org or .exe files appear in the next month or so, then you will know that I have been seduced by forces other than music. Your comments, bug reports and carefully considered suggestions about new unit generators are welcome! - Robin Whittle For general info on Csound check out: The MIT site: ftp://cecelia.media.mit.edu/pub/Csound The Bath ftp site: ftp://ftp.maths.bath.ac.uk/pub/dream The Leeds WWW site: http://www.leeds.ac.uk/music/Man/c_front.html (This has details and archives of the Csound mailing list.) ----------------- | | | FEATURES | | | ----------------- CSOUND.EXE for MSDOS -------------------- This CSOUND.EXE (in CSRW_EXE.ZIP) is compiled with the DJGPP 1.12 compiler, and contains a number of enhancements. My work is based on John Fitch's release of Csound code on 17 April 1995. I will attempt to keep up with bug fixes and well documented improvements from this and other sources. This CSOUND.EXE has the following characteristics: 1 - It needs a 386, 486 or Pentium with a maths coprocessor. So a 386 DX or SX is OK if you have a 387 plugged in. Any Intel 486 DX will do - a 486 SX has no maths coprocessor. 2 - It does not do graphics. I probably can get this working, but it will be a lot of work I think. Use one of John Fitch's CSOUND.EXEs if you need to display graphs. 3 - It has several bugs removed from the table and tablei ugens. 4 - It has a whole swag of new ugens as documented below. 5 - It runs under MSDOS, a Win3.1 DOS box, and I expect, a WIN95 DOS box. I am not planning a Windows graphics version at present. 6 - I am only working with the main CSOUND program - not the utilities. I am not maintaining or distribute the the source for them. Features of this CSOUND.EXE --------------------------- This carries the same MIT version (3.29) as John Fitch's source from which I worked. I don't know anything about these version numbers. It also carries John's version 12. To this I have added my version number 1.00 - for the 11 September 95 release. This CSOUND.EXE can handle instrument numbers up to 1200 and function table numbers up to 1000. There are some limits on the length of the orchestra file. I have not investigated this yet. Environment variables to set ---------------------------- This CSOUND.EXE has a built in DOS extender which is part of DJGPP - it is called GO32. This provides the 32 bit linear address space the program works in, and handles the interface to MSDOS. It uses the 386/486/586 memory management system to map physical memory wherever the program needs it. It also needs to run under a DPMI server such as HIMEM.SYS or in a DOS box in Windows 3.1 or Windows 95. GO32 then uses the DMPI system to access memory it needs. If your CSOUND.EXE uses more memory than is available from RAM, then GO32 will create a swap file on hard disk. This will only occur if your .orc and .sco files use lots of memory due to tables or delays. If you want to tell GO32 where to put the swap file, put a line like the following in your autoexec.bat: SET GO32TMP=F:/tmp Note the forward slash - GO32 expects this - not a MSDOS backslash Csound has some default directories which are also defined as environment variables. It is best to make these sub-directories, rather than the root directory of a disk (like f:\). In my autoexec.bat I have: SET SFDIR=f:\0snd SET SSDIR=f:\0snd SET SADIR=f:\0snd I use some batch files to edit files, run Csound and play the sound files. I use an environment variable PROJ to store the name of the active files. When I do this under Windows, I find that I cannot define PROJ, or redefine it to a longer name - due to some pesky problem with environment space. The solution is to define PROJ to something quite long in the autoexec.bat: SET PROJ=AVERYLONGNAME New features available as source code for any Csound implementation ------------------------------------------------------------------- These are contained in new and modified files in CSRW_SRC.ZIP. All these features are built into the CSOUND.EXE in CSRW_EXE.ZIP. A full listing of documentation files follows this list of features. UGENS2 Bugs in table read code fixed. New versions of table and ------ tablei enable the table number to be controlled by a k rate variable. See TABREAD.TXT. Modified code is in UGENS2.C and UGENS2.H. These bug fixes, clearer documentation and k rate control are intended to be a lasting part of Csound if people like them. UGRW1 Table write ugens - for writing directly into function tables ----- at i k or a rates - with i or k rate control of the table number. (See TABREAD.TXT for krate control details.) Ugens for manipulating data in tables: tablegpw, tableleng, tablemix and tablecopy. Ugens for reading and writing to table locations sequentially from a rate variables. One of the uses of this is to read a rate data into a table (or several a rates into several tables), and use _any_ k rate code to process the data, before converting it back to a rate. This means that when you really want to, you can use all of Csounds ugens and operations on a rate code. It is somewhat slow, but faster than running with ksmps = 1 and using upsamp and downsamp. Global patching of i, k and a rate signals based on numbers generated at i or k rate. This is really a fudge until the language supports arrays. This is called the "zak" system. However it is extremely useful. There is a numbered set of "zk" k rate patch points and another set of "za" a rate patch points. A variety of ugens read, write and mix to these - with k rate control over which patch point is used. This enables the code in each instrument to decide where to get and send a and k rate signals when working with other instruments. Simple ugens to read the time elapsed since the start of the piece or the initialisation of the instrument. Two ugens for printing k rate variables as numbers on the screen. The second of these allows four variables to be printed in the midst of a text string - by printf(). It also allows any byte to be printed and makes it easy to insert escape codes into the text for cursor control. These, or something like them are intended to become a lasting part of Csound if people like them. The "zak" system is very useful for patching things, but not as good as a rewrite of Csound to support arrays - so it is only intended to last *until* that happens. See UGRW1.TXT. New code in UGRW1.C and UGRW1.H. UGRW2 kport - a low pass filter for k rate variables like port, but ----- now with a k rate frequency control. Filters for k rate variables: ktone, katone, kreson & kareson limit and ilimit ugens for setting k (or i) rate upper and lower limits on (i,) k or a rate variables. See UGRW2.TXT. CMATH A 31 bit random number generator replaces the previous 15 bit ----- one. A seed ugen is provided to set it. This global random number generator is used for all of the new set of noise (random number) ugens introduced early in 1995 by Paris Smarargdis - the zlinrand family. To complete the family, there is now an xunirand ugen for uniform distribution of random numbers between 0 and the value given to the ugen. See CS_RAND.TXT. Also a slight change has been made to entry.c to make the inorm parameter of kpow and apow optional like README.csound says it is. ------------------ | | | .ZIP FILES | | | ------------------ CSRW_EXE.ZIP Just the CSOUND.EXE program. Be sure to get CSRW_DOC.ZIP as well. CSRW_DOC.ZIP All the doco you need, except for the Csound manual. Includes the README.csound which documents new ugens added to April 95. Also contains the new and modified source code. See full list below. CSRW_SRC.ZIP This is the complete set of source code I used for making the CSOUND.EXE program with DJGPP. It contains only a makefile for DJGPP (which should be fine for any GNU C compiler). It contains the original versions of files I have modified. It is only the code for the CSOUND program itself - not the utilities. However all the code is there - not just files needed for an MSDOS compilation. All new and modified code is extensively documented - including details of how to patch it into another set of source files. The contents of CSRW_SRC.ZIP are further documented in the FILES.TXT file which is included in it. (The above three files consititute everything you need from me directly.) CSJF_SRC.ZIP John Fitch's source release of 17 April (actually all the files are 14 April or earlier) - complete with sources for all the utilities. This is what my work is based on. See notes in CSDJGPP3.TXT on tweaking this source to work with DJGPP. See the description of below of README.CSO for a list of the ugens and fgens which are in this release. John probably does not support this source - see his site for his latest work. CSJF_EXE.ZIP .EXE files for the 486 (or 386) - co-processor required. CSOUND.EXE and the utilities: CSOUND EXE 360,687 14-04-95 7:35p HETRO EXE 85,307 14-04-95 8:15p LPCANAL EXE 143,423 14-04-95 8:15p PVANAL EXE 152,183 14-04-95 8:15p CSCORE LIB 15,360 14-04-95 8:15p SCOT EXE 51,123 14-04-95 8:15p SCSORT EXE 43,404 14-04-95 8:15p EXTRACT EXE 49,687 14-04-95 8:15p SNDINFO EXE 69,167 14-04-95 8:16p SCALE EXE 82,171 14-04-95 8:15p MIXER EXE 84,647 14-04-95 8:16p MKGRAPH EXE 102,771 14-04-95 8:16p Since I am not providing source or .EXEs of the utilities, you may want to get this file. The CSOUND.EXE will draw graphs - using an 800 x 600 SVGA mode if it can find one. My CSOUND.EXE can't do this. These (I think) were compiled with Zortech C. John is now using Watcom for his later .EXE releases. He probably does not want to support these older files. CS_MAN.ZIP Contains and MSDOS text file of Barry Varcoe's Csound manual - see below. ------------------ | | | DOCO FILES | | | ------------------ (First the two basic Csound doco files you definitely need. I have turned these into standard MSDOS text files. Otherwise they are original.) CS_MAN.TXT MSDOS text file derived from the original Csound manual by Barry Vercoe. This is was a Macintosh Word file and is available at the MIT site. This file is the only one listed here which is not in CSRW_DOC.ZIP. CS_MAN.ZIP .ZIP of the above. README.CSO MSDOS text file. A copy of John Fitch's README.csound from April 95. This documents the new ugens added to that time. These ugens and function generators include a granular synthesizer, a new set of filters, a new variable delay, a multitap delay, a new reverb, an envelope follower, various noise generators, a power function generator and two gen routines, GEN20 and GEN21. There are also two ungens for convolution. grain butterhp butterlp butterbp butterbr vdelay multitap reverb2 follow xlinrand xtrirand xexprand xbexprnd xcauchy xpcauchy xpoisson xgauss xweibull xbeta kpow apow GEN20 - f tables of 9 types of window: Hamming, Hanning, Bartlett ( triangle), Blackman ( 3 - term), Blackman - Harris ( 4 - term), Gaussian, Kaiser, Rectangle and Sinc. GEN21 - f tables of different random distributions: Uniform, Linear, Triangular, Exponential, Biexponential, Gaussian, Cauchy, Positive Cauchy, Beta, Weibull and Poisson. (The above were written by Paris Smarargdis.) From Greg Sullivan, a convolution ugen and an an analysis utility program to go with it: convolve cvanal - Impulse Response Fourier Analysis for convolve operator. UGRW1.TXT Full doco of the new ugens mentioned above for UGRW1.C. Also a discussion of how good it would be to have arrays in Csound, and why I wrote the "zak" system in the interim. UGRW2.TXT Describes kport and the new k rate controlable filters: ktone, katone, kreson & kareson CS_RAND.TXT Describes the changes to the random noise functions in CMATH.C. FILES.TXT Describes the files in CSRW_SRC.ZIP. CSDJGPP3.TXT Describes how I obtained DJGPP, fired it up, got the Csound source in April and tweaked to to produce a CSOUND.EXE. Basic reading for anyone interested in using DJGPP to invent their own variants of Csound. CSRW_HIS.TXT History file of my Csound work. CSRW_DOC.TXT This file. ------------------------- | | | COPYRIGHT NOTICES | | | ------------------------- CSOUND was originally written by Barry Vercoe at MIT Media Lab. Other people have made contributions, and some of them have their copyright notices in the source code. I started with the source from John Fitch. Here are the relevant copyright notices. Barry's is from the Csound manual 1992. John's is from his README.csound (README.CSO) file of April 1995. -------------------------------------------------------------------- Copyright 1986, 1992 by the Massachusetts Institute of Technology. All rights reserved. Developed by Barry L. Vercoe at the Experimental Music Studio, Media Laboratory, M.I.T., Cambridge, Massachusetts, with partial support from the System Development Foundation and from National Science Foundation Grant # IRI-8704665. Permission to use, copy, or modify these programs and their documentation for educational and research purposes only and without fee is hereby granted, provided that this copyright and permission notice appear on all copies and supporting documentation. For any other uses of this software, in original or modified form, including but not limited to distribution in whole or in part, specific prior permission from M.I.T. must be obtained. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. -------------------------------------------------------------------- John Fitch School of Mathematical Sciences University of Bath Bath BA2 7AY England Tel: +44-1225-826820 FAX: +44-1225-826492 E-mail: jpff@maths.bath.ac.uk or J.P.Fitch@bath.ac.uk (also Codemist Ltd, Tel/FAX: +44-1225-837430) The mixer, graphing and SoundBlaster support are probably my copyright, and I hereby give permission to use, copy, or modify this code for any purpose whatsoever. I would like my name to remain in there, but I do not insist. -------------------------------------------------------------------- Modifications and new code provided by Robin Whittle are provided without warranty etc. etc. They are copyright 1995 Robin Whittle. Use of this code for non-commercial software products is permitted, provided the source code is made freely available according to the principles of the Free Sofware Foundation, with this copyright notice attached - and those of Barry Vercoe and John Fitch. --------------------------------------------------------------------- --------------------- | | | MY PRIORITIES | | | --------------------- When a publicly available program is altered and extended by someone other than the original author, there is cause for concern about trouble arising from incompatible versions of the same program being in circulation - leading to: 1 - .SCO and .ORC files which work with one Csound and not another. 2 - The original author getting asked to help with bugs or difficulties unrelated to his own work. 3 - The new version developing enough momentum and differences to draw a significant number of people from the original - so blunting the momentum of the program, and making it harder for anyone to maintain a version with the best possible features of the two paths of development. In my case, I have split off from John Fitch's MSDOS Csound lineage and chosen his April 95 source release as the basis for my own. So now we have my Csound, John Fitch's and whatever is going on with Barry and others at MIT. It seems (according to a recent post by Paris) that Barry Vercoe and others are working on a Mac version with ugens in files rather than built into a single executable program. Paris reports that this is not an ANSI C compatible approach. He also reports that it is very impressive. I cannot think of an approach with ANSI C of having ugens in files - unless there was significant rewriting of the ugens and extra code which would inevitably slow the program down. I chose John Fitch's April release as my starting point because: 1 - It worked. (I made a piece of music I really like with it!) 2 - John's subsequent release in August contained undocumented changes to dozens of files. Most (but apparently not all) of this was to make a Windows version. However the Windows version is very awkward to use, so I am not interested in a Windows version unless a more sophisitcated interface is developed. For now, I am quite happy with MSDOS or a DOS box under Win3.1 or Windows 95. The altered files had tabs expanded to spaces and so it was going to take an awfully long time to figure out which changes were not related to the Windows mods. I asked for some guidance in which files had been changed for other reasons and to date have not had a reply. Life is too short to be trying to keep up with poorly documented mods to a complex program. My reasons for altering and extending Csound: 1 - I wanted the table read bugs fixed and wanted all the features which I have now added. Virtually all of these will help me make music. The rest are just there for completeness - for instance I may never use some of the init time versions of these ugens, but since I was working on them I figured I should make all useful versions of them. 2 - I want to be able to use this as a reliable tool for making music. There are a few flaky things about it and ultimately I want to comment (and bug fix) as much of the program as I can. The table read bugs were only uncovered as I commented the code in preparation to doing table write - but the bugs had certainly been causing some people trouble and would have upset my music. 3 - I am really excited about Csound. My background is in modifying musical instruments and Csound is like a wonderful instrument that can be cleanly modified to a very high degree - with the cost of time rather than hardware. Csound is an immensely flexible tool. There is enormous variation between people in their musical tastes. It is not surprising that any flexible instrument will be used in differing and incompatible ways. One of the wildest, weirdest musical instruments (I think the weirdest invented in the Western World) is the pedal steel guitar. With ten strings, no soundboard, a magnetic pickup, it looks more like an ironing board than a guitar. It is played with finger picks, and a foot pedal for volume control. Up to a dozen foot pedals and knee levers stretch and slacken the strings in complex ways, and the pitch of the strings is controlled by a "steel" a lead filled chrome plated tube held in the left hand and pressed to the strings. There are no frets. Pedal steel guitars have a number of possible standard tunings and pedal configurations. Some have two sets of strings and pedals so two completely different arrangements can be used. I read that most players start with a standard tuning - Nashville E9. Many of the keen ones get frustrated at what they can't do with the standard approach (there are a daunting array of things you _can_ do with the standard setup). So they think of another arrangement, redesigning and retuning their machine - engaging a technician to custom modify the levers and cams to their exact requirements - which are likely to be different from anyone elses. This may go through several cycles as they refine their instrument design. Pedal steel playing requires extraordinary physical skill - with precision movement and delicacy. These players have to keep their chops up and are constantly practicing. However they can only play properly on their own instruments. Csound is my pedal steel guitar! (I bought and sold a student model pedal steel guitar - the optionitis and physical skills were beyond me). I will attempt to make Csound into what I want it to be, including external programs to process another file type into an orchestra and score. I don't know how many people will want to approach things my way, but I will try to assist those who can benefit from my work. I have benefited from other people's Csound work. So in working on Csound I will attempt to: 1 - Work on the margins of the program - the unit generators - rather than in the core of the language. This means that my code can easily be installed in someone else's Csound source. 2 - Try to keep my version up to date with improvements made to other versions. This will only happen if: a - Other people's changes are worth incorporating - in my opinion, primarily for my purposes. b - The new code is well documented. (most of Csound is extremely poorly documented.) c - The changes are relatively modular - rather than dozens of changes all over the place. (The exception would be if someone did a really good Windows version - which would require many changes.) 3 - Document my changes, my code and the operation of the new unit generators fully - so that I and other people will have minimal trouble using and maintaining the code. If a fabulous new version of Csound comes along, my changes should be pretty easy to add to it. Since I have no idea when there will be a significant upgrade, and since I doubt that anyone else's ideal Csound would be ideal for me, I will get on with making my own. I also hope that the new features I add will stimulate thought about what might go into an upgraded version of Csound - or into another language. Of course I hope the changes will help other people make music too - I would be keen to hear the results! ----------------- | | | WISH LIST | | | ----------------- Modify RDORC.C to get rid of the pesky bug in which spaces are ignored when reading orchestra code. This does not seem to be a useful feature and can cause confusion when a comma is left out and two separate variable numbers or names are truncated into one. Investigate reports of Csound reading strange values when more than 6 or 7 decimal places are used. Write a pre-processor so that a single file can be worked on, and from it orchestra and score files will be generated to drive Csound. Amongst other things I want to have variables (like # define) which work in both the score and the orchestra. I also want instruments to be automatically numbered (with potentially multiple numbers) so they will execute in the order they appear in the score. There is a lot more to this plan. Finish the layout updates to my Word for Windows 2.0 version of the Csound Manual - based on Barry's Mac Word version. Layout of manuals is very important, and while I have made improvements, it is not finished enough to release. Maybe add in the new ugens, and my new ugens to the end - or perhaps the main part of the manual. Refine my binaural model instrument - making its X, Y and Z input parameters be driven from zk variables and the audio input from a za variable. Then rewrite it as a unit generator to speed up processing. Then write a simplified version which sounds nearly as good but is even faster - use this for "draft" mode. Maybe get hold of some head/pinnae transform impulse responses and make a ugen which did a really fine job of binarual placement, using actual transforms from recordings and full three dimensional placement. Get a Zefiro digital audio input/output board, and a DAT, so I can do recordings and direct digital out. Also use the board with supplied software to do backups of hard disk to DAT. This board comes with full source code for the drivers - so I should be able to write a Csound driver for it. It can do input and output at the same time, so maybe Csound could be used to do some very simple real-time audio processing. There are two boards - the simple one is US$350. The fancy one has a DAC on it, and a 24 bit DSP for sample rate conversion etc. Contact Greg . Get the graphic display happening, and make a ugen to display table contents during performance. Provide ugens for reading and writing two dimensional tables - with or without interpolation. Provide a ugen for writing a table out to a files. Provide a way of spitting out short files of the sound made so far - so that in a long Csound "cooking" session, you can hear the progress without stopping the process. Mayby use a LAN to send the file to another machine which can play it indepenedantly. This may work fine on a single machine with Csound in a Windows DOS box. Look at ways of generating a MIDI file from within Csound - so the compositional structures I create with instruments can write to the MIDI file - to drive MIDI synthesisers and analog equipment via a MIDI to control voltage converter. Of course there is lots of music to make and instruments to create - I don't want to dwell on the "dark side". <<<<