This manual is work in progress... feedback is welcome
Stéphane Rollandin (Stef) <hepta@zogotounga.net>
last updated 2 May 2008
Please refer to http://www.zogotounga.net/surmulot/surmulot.html
... surmulot is also the french name for the common rat, Ratus Norvegicus.
This currently covers only Surmulot for Windows.
Get the latest version of surmulot at: http://www.zogotounga.net/surmulot/surmulot.html
Since the Keykit licence does not allow direct distribution of Keykit, if you want it you will have to download Keykit there: http://nosuch.com/keykit
This should give you a self-extracting archive; launch it and set the destination directory to the "keykit" subdirectory of surmulot. That's it.
Csound-x is an Emacs package for Csound composition.
see (Csound-x)Top.
Surmulot provides interactive widgets extending Csound-x with graphical editors for musical data such as musical phrases and envelopes.
see Widgets.
Surmulot also makes it possible to generate, edit and play MIDI data from Emacs, using Timidity as soft synthesizer.
see MIDI.
ľO homepage: http://www.zogotounga.net/comp/squeak/sqgeo.htm
Surmulot allows Emacs to be integrated as the default text and files
editor for ľO. It makes it also possible for Squeak to access the
system shell via Emacs instead of using OSProcess.
Objects and data can be exchanged between ľO and Emacs.
Emacs snippets:
(squeak-eval "Project current") (muo-get "'a,b,c' kmusic asBox") (setq envelope-editor (surmulot-make-widget "MuO EnvelopeEditor")) (funcall (surmulot-widget-interface envelope-editor) "Widget music asFTable: 1024")
Surmulot widgets are Squeak morphs, mostly ľO editors, made available for Emacs via a TCP/IP connection.
When Emacs requests a widget, it starts the ľO image as a subprocess
and ask it to become a specific widget. The image then changes its name, close
its source files and resize itself; the requested morph is opened in
full size and can be accessed through the Smalltalk global variable Widget.
Use the global "Widget" menu to create a new widget from emacs. The customizable variable `surmulot-widget-specs' lists all available widget types.
A widget can be stored in a CSD file, as a <WIDGET>...</WIDGET> area.
Stored widgets can be recreated from a CSD buffer via the "Stored widgets" submenu.
Once a widget is opened and connected, an associated submenu appears
which allows for closing, cloning or storing the widget.
The widget can send its data to Emacs, usually via menu items.
One common operation is the insertion of text from the widget; this happens in the current Emacs buffer. For example, the envelope editor can insert its envelope description in either linseg of ftgen format for csound buffers, or in Common Music or Nyquist formats for appropriate buffers.
On the emacs side, a comint buffer named "*Squeak on port xxxx* *" allows interaction with the widget Squeak image, where xxxx is the local port number used for communication. Any Smalltalk command is valid; note that the widget can be accessed via global variable Widget. This is not always the full morph displayed by the Squeak image: Widget may be one of its submorphs. The full morph can be retreived by sending "Widget biggerSurmulotWidget".
The comint buffer can be brought up with the "interact" item of the
widget submenu.
Use the "collapse" menu item to hide the widget and access the Display of the underlying Squeak image. You can directly debug or modify the widget then file out the current changeset to get a patch for the main ľO image.
Note that is is better to directly work within the ľO image because it has access to its source and change files. In the widget image you will only have decompiled code, and no class comments.
This sections explain how to work with the different types of widgets
Editors
The envelope editors defines breakpoints.
The shape of the envelope between two breakpoints is actually a property of the first breakpoint, its interpolation property. If the second breakpoint does not have its own interpolation, then it simply transmits the current interpolation to the next segment.
A breakpoint with interpolation property appears filled in orange color.
To put it simply, this means you only have to set the interpolation for the first breakpoint to change the shape of the overall envelope.
Example:
right-click on the first breakpoints (at bottom left corner)
and select "interpolation > basic > startingFlat"; see how the envelope
changes.
now right-click on the third breakpoints and choose "goingFlat";
this override the previous interpolation and changes the shape for the
last part of the envelope.
One or two breakpoints can be selected. The selection is the set of breakpoints included between the selected ones, or the selected one itself if there is only one.
A selected breakpoint appears as a red circle.
Several operations can be performed on the selection, such as
repeating, reversing or flipping. See the "selection" submenu.
Breakpoints can be dragged with the mouse if they have an handle.
A breakpoint with handle appears as a thick circle.
When handles are grouped, all breakpoints with handles move together. If there is one (and only one) point currently selected, then moving the group actually scale and rotate it with regards to the selected point.
When a breakpoint has a handle, you can delete it: use the "delete
break point" menu item.
The envelope can be exported as a string, where breakpoints are described in specific formats. See the "emacs" submenu for a list of format available. The string will be inserted at point in the current buffer.
If some breakpoints have a non-linear interpolation, the envelope is broken down in linear segments upon exportation.
You can see what this means by doing "envelope -> break envelope" from
the contextual menu. The "tolerance" parameter can be changed to tune
the precision of the conversion: the lower it is, the more precise
the operation is.
Use "emacs -> edit as a function" to convert the current envelope into a function and edit it with a function editor.
This allows arbitrary mathematical operations to be applied to the envelope. The function can later be converted back into an envelope if desired. see Function editor.
The phrase editor is a comprehensive tool for editing MIDI-like
data. Type ? for a summary of commands bound to specific keys.
You can either input MIDI data interactively via a virtual keyboard (menu item "open keyboard") or via the cursor (see below), or else read a MIDI file (menu item "emacs -> read MIDI file").
If a CSD buffer includes one or several <MPhrases> areas then you can
edit these areas via the "MPhrases" submenu at the top of the "CSD"
menu. This will open a musical phrase editor.
The displayed area is modified by dragging it the mouse. Dragging with [SHIFT] pressed scales the area with respect to its lower left corner.
Keys + and - (or menu items "zoom in" & "zoom out") also scale the
displayed area.
Typing c create a cursor. You can move it around and insert or delete notes with it. See the many commands available by pressing ?.
Once the cursor is enabled, typing m creates a mark at its current position. The mark and the cursor define the region, which includes every notes between them.
Notes in the region can be selected or deselected, delayed, removed,
etc. Again, refer to the keybindings for available commands (type ?).
Notes can be selected/deselected individually or collectively with the
region. The selection can be moved and transposed, or directly edited
(type e).
Any note can have a handle. Through the handle one can change the note parameters, either using the contextual menu or with the mouse: the left part of the handle controls the volume which can be changed by dragging up or down; the right part controls the duration, and can be dragged left or right; the central part allows the handle to be grabbed by a mouse click and moved elsewhere.
When handles are grouped, moving a handle moves the whole group.
...
...
Once edition is completed, you can choose to export the musical phrase in different ways via the "emacs" submenu: it can be written as a MIDI file, inserted in the current buffer in Keykit syntax or embedded in a <MPhrase> area within a CSD buffer.
see (Csound-x)Handling MIDI data.
<MPhrase> areas can later be edited directly, using the "MPhrases" submenu of the main "CSD" menu.
... this widget is not ready yet ...
The function editor is a workspace for mathematical operations
relative to one-dimensional functions, such as envelopes or sound waves.
The editor starts blank. From the contextual menu, "add function from
library" provides a submenu of predefined functions. Choose any one to
add it
A function can also be added by directly inputing its equation. Use the "add function" item to open an input area. The function equation must be entered there with "x" as a variable and in Smalltalk format.
For example
x sqrt 1 + x x abs log ((((x + 0.5) * 500) * (((10 * x) fractionPart) sin)) sin)
Note that Smalltalk has no concept of mathematical operator precedence !
For example
1 + 2 * xis actually
3 * xso take care to write
1 + (2 * x)
The editor can display several functions. Each function has its own submenu in the main contextual menu. From there, the "set color" item lets you choose the display color.
The displayed area is modified by dragging the mouse. Dragging with [SHIFT] pressed scales the area with respect to its lower left corner.
Keys + and - (or menu items "zoom in" & "zoom out") also scale the
displayed area.
Most functions from the library have parameters. For example add two functions: from the "basic functions" submenu, take "sine" and "sineWithPoint". If your editor was blank they should appear as "f1" and "f2" in the contextual menu.
The first item in both "f1" and "f2" menus is actually a menu
itself. For "f1", it lets you set the value for the parameters "freq"
and "amp", that is the frequency and amplitude of the sine wave. For
"f2", it gives access to the single parameter "point" which is the
position for the first extremum of the sine wave. Change the values
for these parameters and see how the functions change.
When adding a function by inputing its equation, you can reference the already displayed functions by using their name as a method for "self", the function editor itself.
Practically if you have the two functions "f1" and "f2" from the previous chapter, you can input
self f1 + self f2
which displays the function x -> f1(x) + f2(x)
The operator "<=" allows the composition of functions; try
self f1 <= self f2
to display the function x -> f1(f2(x))
For technical details about what functions really are in Squeak,
see http://www.zogotounga.net/comp/squeak/functionaltalk.htm
From a function submenu, the item "edit as envelope" crops the currently displayed section of the function and convert it into an envelope by breaking it into linear segment. The function editor becomes an envelope editor. see Envelope editor.
Beware that this is a destructive operation: you will not be able to come back to the function editor. You may clone the widget before conversion though (see Widgets).
Use the "tolerance" item in the bottom of the contextual menu for setting the variation threshold used when breaking the function. The smaller it is, the more precise is the conversion.
This widget is a book: it contains several pages which you can navigate with the upper buttons: "<<", "<", ">", and ">>". Use "+" and "-" to add or remove a page.
Each page is a workspace for setting up diagrams representing csound orchestras.
For documentation, please open the ľO image (see The surmulot menu) and from the
"ľO objects" menu select "live documentation -> examples -> reference
-> Csound Blocks Examples".
Use the top "widget" menu to get the different objects needed for a diagram: connectors, blocks and text areas.
From each of these object a contextual menu allows edition and
exportation.
From an instrument header contextual menu, "emacs insert instrument code" plainly insert the code right into the current buffer; while "emacs replace instrument code" only apply if the current buffer is a CSD or a csound orchestra edited in the appropriate major mode. The instrument code then replace the existing code.
From an orchestra header contextual menu, "emacs insert orchestra code" and "emacs replace orchestra in CSD" behave similarly, for CSD buffers only.
There is also "emacs insert generated code" from any opcode block.