Table Of Content

QuteCsound, a Csound Frontend Andrés CABRERA Sonic Arts Research Centre Queen’s University Belfast UK [email protected] Abstract QuteCsound is a front-end application for Csound written using the Qt toolkit. It has been developed since 2008, and is now part of the Csound distribution for Windows and OS X. It is a code editor forCsound,andprovidesmanyfeaturesforreal-time controloftheCsoundengine,throughgraphicalcon- trol interfaces and live score processing. Keywords Csound, Front-end, Qt, Widgets, Interface builder Figure 1: The main QuteCsound window 1 Introduction QuteCsoundwasbornoutofthedesiretohavea cross-platformfront-endforCsound[Boulanger, 2000]likeMacCsound[Ingalls, 2005]whichonly runs on OS X. It is based on the idea of hav- Figure 2: The transport bar ing real-time control of Csound through graphical widgets, and making Csound accessible for QuteCsound Front page1 and the QuteCsound novice users. It is however designed to be also sourcesandbinariescanbefoundonitsSource- a powerful editor for advanced users and also forge page2. offline (non-realtime) work. The most recent version is 0.5.0. It has been tested on Linux, 2 GUI Mac OS X, Windows and Solaris. QuteCsound The main application window is shown in figure has been translated to Spanish, French, Italian, 1. The main component is a text editor with German and Portuguese. syntax highlighting. Documents can be opened One of the main goals was also to make a as separate tabs in this area. There is a large new interface for Csound which would be com- icon bar with the main actions, which contains fortable for a musician whose background is not the usual open/save and cut/copy/paste action in programming. Existing cross-platform inter- icons, a section with transport controls (see fig- faces for Csound were either too basic or some- ure 2), and a section for handling visibility of what impractical. The Csound Manual [Cabr- the rest of the application windows and panels. era, 2010] is very comprehensive, but few front- ends take full advantage of its resources like op- Aroundtheeditormanydockablewidgetscan code listing in XML format. be positioned freely. These dockable widgets QuteCsound uses the Csound API [ffitch, are: 2005], which enables tight integration and con- Widget Panel In the widget panel, control trol of Csound. widgets like sliders and knobs can be cre- It is licensed under the GPLv3 and LGPLv2 ated. The design and manipulation of the for compatibility with the Csound licence to ease distribution alongside Csound. More in- 1http://qutecsound.sourceforge.net formation on QuteCsound can be found in the 2http://www.sourceforge.net/projects/qutecsound widgets is all graphical, and requires no textual programming. See 2.1 below. Manual Panel The html version of the Csound Manual can be displayed in this panel. The reference for an opcode under the editor cursor can be called with the de- fault short-cut Shift+F1. Console Panel The output from Csound for the current document is displayed in this panel. Inspector Panel Shows a dynamically gener- ated hierarchical list of important sections from the current file. It shows instrument Figure 3: Widget Panel detail definitionsandlabels,definitionofUserde- fined opcodes, f-table definitions, and score An example of how the widget panel can be sections. used is shown in figure 3. When the current document tab is changed, These are the available data widgets: all the panels which depend on the document Slider Ordinary sliders which become horizon- like the widget panel and the inspector panel, talorverticaldependingontherelationbe- change to show the current data. tween width and height. There are three additional windows in the GUI: Knob Simple rotary knobs. Configuration dialog Allows setting options Labels and Displays Text widgets that dis- forCsoundexecution,Environmentandin- play immutable text (labels), or text that terface options. can be changed only from Csound, not using the mouse4. Utilities dialog Simplifies usage of the Csound utilities -applications which pre- Text Editor A text entry widget. process files for certain opcodes- can be Number widgets The ScrollNumber and called and controlled through this dialog SpinBox widgets offer number value inputs window. and outputs with mouse and keyboard Live Event Panels These windows which control. vary in number according to the current Menus The menu widget allows creating a document contain a spreadsheet-like in- Drop-down or Combo Box for selection terface for manipulating Csound score from a list. events which can be sent, manipulated and looped while Csound is running. They can Controller The controller widget can be a also be processed using the simple python slider, a meter or an XY controller. It can qutesheet API (see section 2.3). also be used as a “LED” display. 2.1 Widgets Button Buttons can be data widgets (sending The widget panel allows creation of versatile different values depending on whether they graphical control interfaces. Data widgets pro- are pressed or not) or score event genera- vide bi-directional interchange of values with tors. They can also hold images. Csound through the API. The values can be CheckBox A simple checkbox which can take updated synchronously or asynchronously de- a value of 1 or 0. pending on the QuteCsound configuration and theusageofinvalue/outvalue orchnget/chnset3 There are three other widgets which are used to opcodes in the csd file. display information from Csound: 3The invalue/outvalue opcodes call a registered call- 4While this separation is not really necessary or use- back when they are used, while chnget/chnset only ful, it follows the MacCsound format choices, and was change internal values which must be polled kept for compatibility purposes only There are some handy organization functions for selected widgets like align and distribute to aid in creating better looking widget panels. The widgets are saved as text in the csd file, but this text is always hidden from the user5. Each widget is currently represented by a single line of text, which looks something like this: ioSlider {23, 244} {414, 32} -1.000000 1.000000 -1.000000 amount This follows the original MacCsound format strictly, whichenablesQuteCsoundtoopenand generate files which are interchangeable with Figure 4: The Widget Preferences dialog MacCsound. It is somewhat human-readable and editable, but impossible to extend without Graphs The Graph Widget displays Csound breaking compatibility. A lot of internal work F-tables, as they are created by Csound, has already been done to move past the MacC- and also displays data from the dispfft and sound widget format to an XML based format display opcodes, which allow monitoring whichwillalloweasierextensibilityandparsing, anysignaloritsspectrum. ThereisaCom- and new widget types. boBoxwhichallowsselectionofthecurrent tables. The table shown can also be se- 2.2 Live events panel lected through a Csound API channel. Each document can have any number of Live Event Panels. A live event panel is a place Scopes The Scope widget shows visual repre- where Csound score events can be placed for sentations of Csound output buffer. It can interactive usage during a Csound run. It is actasatraditionalOscilloscopeorasaLis- shown in figure 5. The live event panel can dis- sajou, or Poincare display. play the information in the traditional Csound Consoles The Console widget shows the score format or as a spreadsheet with editable Csound console output as a widget in the cells. It offers a group of common processing widget panel. functions which can be applied quickly to a group of cells like addition, multiplication, and Widgets can be created by right-clicking on generationfunctionslikefilllinearlyorexponen- the widget panel, and selecting a type of widget tially or random number generation. There is from a list. They can be moved and resized also support for some of the basic Csound Score by entering the ‘Edit Mode’ with the keyboard preprocessorfeaturesliketempocontrolandthe short-cut Ctrl+E. carry operator ‘.’. All widgets have a configuration dialog which Score events can be copied/pasted to/from can be shown by right clicking on them and se- text view and sheet view seamlessly. lecting ‘Properties’ or by double clicking when Live Event Panels are also stored as text in in edit mode. The Properties dialog for a text the main csd file, and are hidden from the user widget is shown on figure 4. Properties like size in the main text editor. and position can be set in these dialogs. The channel name through which the widget trans- 2.3 The QuteSheet Python API mits (if it can according to its type) can also be AsimplepythonAPIhasbeendevisedtoenable set here. transformation of data from the Live Events To receive data from the widgets, they must Panel using Python. The cells (both the se- be assigned to a control variable (k-rate) using lected and the complete set) are passed to the the invalue opcode like this: python script as arrays in any particular orga- kval invalue "channel" nization (by rows, by columns, by individual cells), and can be returned with a single func- Conversely, to send data to a widget, the out- tionspecifyingthenewdataandwhereitshould value opcode can be used. 5This behavior will probably change in the future to outvalue "chan", kval allow text modification of the widgets Figure 5: The Live Events Panel be placed in the sheet. The python scripts can be stored in a directory which is scanned every time the right-click menu in the event sheet is triggered, effectively allowing “live coding” of score transformations while the Csound audio engine is running. 2.4 Code Graph Figure 6: The Code Graph Output QuteCsoundcanparsethecurrentlyactivedoc- umenttogenerateadotlanguagefile,whichcan read/write library, which is very well main- berenderedusinggraphviz6 . Althoughcompli- tained, stable and efficient. cated files produce diagrams that are too com- AllaudioandMIDII/OishandledbyCsound plex, this feature is useful for beginners to see itself, except the Record function, which copies how the variables and opcodes are connected in the Csound output buffer after every control a visual way. The output of this action can be block to a ring buffer and writes it to disk from seen in figure 6. another thread. This means that QuteCsound supports output to Jack, Coreaudio and Win- 3 Architecture MME as well as generic interfaces like Portau- dio. QuteCsound requires Qt 4[Nokia, 2010], Csound can be run either as a com- Csound and libsndfile[de Castro Lopo, 2010] to pletely independent process in a separate build. Terminal application, on the same appli- Qt is a mature cross-platform graphical tool- cation thread (usually undesirable) or on kit, which is used in several well known free- a separate thread using the API through software audio projects like QJackCtl. It also the CsoundPerformanceThread7 C++ interface has cross-platform libraries for non GUI stuff from interfaces/csPerfThread.hpp in the like networking, XML parsing, printing and Csound sources. threadingwhichhassavedtimeandavoidedthe Data update is requested by Csound syn- need for additional dependencies. It also has chronously through its callback functions (set extensive facilities for internationalization and using the csoundSetInputValueCallback and translation. It is distributed in separate dy- csoundSetOutputValueCallback functions) namic libraries which can be distributed with when the invalue/outvalue opcodes are used. the executable. Data for Csound is polled in that callback, but Libsndfile is a well established audiofile data for the widgets is queued, to be processed 6Graphviz is a package for generating flowchart style 7this class handles some of the threading issues as- graphics using the dot language. More information can sociated with passing events to Csound and with start- be found on www.graphviz.org ing/pausing/stopping the engine at a slower rate. The values can also be up- And of course fix some of the bugs along the dated asynchronously with the chnset/chnget way. opcodes. The values are then updated from a 6 Acknowledgements timer triggered thread in QuteCsound, forcing locking of values. Many thanks to the Csound developers, spe- An interesting feature of MacCsound which cially John ffitch and Victor Lazzarini for their has been emulated in QuteCsound is that wid- assistance with usage of the API during the de- gets with the same channel name update each velopment of QuteCsound, and their quick re- other even when Csound is not running. This is sponse to issues and particular needs. Also, useful to avoid Csound code for common things many thanks go to the users who have con- like showing the numeric value of a slider wid- tributed many ideas, translations, bug reports get, and it also gives a (false but expected and and testing. Thanks to people like Joachim rewarding) sense of an “always running” en- Heintz, Andy Fillebrown and Fran¸cois Pinot, gine. In practical terms, this implies that when for their contribution to development and pack- Csound is running, widgets must first take val- aging. uesgeneratedfromCsound,andthenpropagate References their values to other widgets. RichardBoulanger,editor. 2000. The Csound 3.1 Documentation integration Book: Perspectives in Software Synthesis, TheCsounddocumentationishighlyintegrated Sound Design, Signal Processing and Pro- in QuteCsound. It can be easily called from gramming. MIT Press. the Help menu, or to find the reference for the Andres Cabrera, editor. 2010. The Csound opcode under the editor cursor. The documen- 5.12 Manual. tation also contains an XML file of all the opcode definitions organized by category. This file Erik de Castro Lopo. 2010. is used for syntax highlight, but also for show- Libsndfile. http://www.mega- ing opcode syntax in the status bar, populating nerd.com/libsndfile/api.html. an opcode selector organized by categories and John ffitch. 2005. On the design of csound building the code graph code (to know the in- 5. In Proceedings of the 2005 Linux Audio put/output variable names and types). Conference, ZKM, Karlsruhe, Germany. 4 Examples Menu Matt Ingalls. 2005. Maccsound. The Examples menu in QuteCsound includes http://www.csounds.com/matt/MacCsound/. a large set of introductory examples and tu- Nokia. 2010. Qt – cross-platform application torials, reference examples for the widgets and and ui framework. http://qt.nokia.com/. a group of ‘classic’ Csound compositions like Boulanger’s Trapped in Convert, and Csound realizations of important historical pieces like Chowning’s Stria and Stockhausen’s Studie II. The examples menu also contains a set of realtime synths, some useful files for things like I/O monitoring and file processing, and a ‘Fa- vorites’ menu which shows the csd files from a user specified directory. 5 The future Plans for the future include completion of the new widget format, and development of new widgets like a table widget. It would be nice to have a synchronization option to make loops sync to a master loop. A lot of work has been done to enable the exporting of stand alone applications, so this will hopefully be finished soon.