     
@setfilename surmulot.info
@settitle Surmulot manual

@direntry
* Surmulot: (surmulot).       Open system for music composition.   
@end direntry


@ifinfo
This file documents Surmulot.

@example
Copyright (C) 2008 Stéphane Rollandin
@end example

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo
@c

@c
@setchapternewpage odd

@titlepage
@title SURMULOT manual (a draft)

@author by Stéphane Rollandin
@end titlepage

@contents

@node Top, Overview, (dir), (dir)
@unnumbered Surmulot documentation

This manual is a work in progress... feedback is welcome

Stéphane Rollandin (Stef)
<hepta@@zogotounga.net>

last updated @today{}

@menu
* Overview::                    What is Surmulot ?
* Installation::                Getting and installing Surmulot

* Entry points::                Where do we start ? 
* Fast recipes::                How to (simply) ... ?
* The Surmulot menu::           Emacs global menu for Surmulot 
* Widgets::                     Graphical editors for Csound-x
* Widgets reference::           Specific widgets documentation
* MIDI::                        The many faces of MIDI data
* Saving your work::            Snapshotting the system state. 
* Upgrading::                   Keeping the system up to date.

* Concept index::               General concepts
* Command index::               Commands responding to M-x
* Variable index::              Customization variables and hooks
* Function index::              Public internal Emacs Lisp functions
@end menu



@c ==================================================================
@node Overview, Installation, Top, Top
@section Overview

Surmulot is an integrated environment for music composition. It has
many entry points, making it the liking of a large toolbox, or a laboratory.

You can use it to produce melodies, and possibly sound. Which, together,
may be music. You can also create graphical user interfaces for
interactive compositions.

How Surmulot came to existence is related in this page:
@uref{http://www.zogotounga.net/surmulot/surmulot.html}

@sp 1

Surmulot can be divided in two big parts: the textual front-end, which
is Emacs, and the interactive graphical environment, which is MuO.

Both parts are actually full-featured programming environments, with
their own langages: Emacs Lisp, and Squeak Smalltalk.

They have very different world views: Emacs works with files, which it
can edit in very powerful ways, and processes (it can monitor the
execution of Csound, for example). On the other hand, Squeak works with
objects living all together in a big image, which is the MuO
world. When you quit Surmulot, all data pertaining to Emacs will be
saved on files or be forgotten, while the image where live all MuO objects will simply be
frozen, ready to get back to life exactly as it was when you left
it. Multiple versions of this image can be stored, parallel worlds so
to say.


@sp 1

MuO objects can be highly interactive. Squeak graphical user
interface, called Morphic, is very dynamic. Complex data structures
can be edited and explored in quite original ways. This complements
Emacs ability to see meaningful structures in text and code; in Emacs
text itself is very dynamic.

The overall system is thus very rich. You can easily be overwhelmed by
the possibilities it opens. So it is important to understand
that there is not one single way to achieve something with Surmulot;
you can start with a simple usage and give yourself time to discover
what is available and which parts of it may be interesting to you. 

At first you may simply
edit Csound files in Emacs, or else use an envelope editor in Squeak. Then
you may see how an envelope can be edited graphically in Squeak from
within Emacs, and the envelope editor actually be embedded in the
Csound document. Eventually you may want to learn some Emacs Lisp or
some Smalltalk, or both, and have the whole system gradually become a library for your own
programs. 

Everything is open and can be modified on the fly; all code
is right there, easy to browse and change. But you do not have to
write a single line of code to use Surmulot. It's all up to you, and I
believe how you will discover the system to be a very personal
matter. Please do not try to get it all at once immediately. Take
time, find your own way. Surmulot is intended to be a place where you
can wander. It does not have a definite purpose or usage. It is a toolbox for working with musical ideas, a laboratory for setting-up
musical experiments.

@sp 1

Documentation is scattered in several places, and several levels.

On the Emacs side we have high-level Info documentation. See @pxref{(Csound-x)Top}. and @pxref{(Surmulot)Top}. 

Low-level documentation is provided by the self-documentating features
of Emacs, namely the documentation strings of functions and
variables. Please see @pxref{(emacs)Lisp Doc}.

On the Squeak side, high-level documentation is available as a set of
BookMorphs. Low-level documentation is in class and methods comments,
and SUnit test cases. 

On the web, see @uref{http://www.zogotounga.net/comp/eindex.html}.

@sp 3

@image{images/surmulot}
@sp 2


Surmulot is also the french name for the common rat, Ratus Norvegicus.




@c ==================================================================
@node Installation, Entry points, Overview, Top
@section Getting and installing Surmulot

@sp 1

@unnumberedsubsec on Windows systems

Get the latest version of Surmulot at:
@uref{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:
@uref{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.  

@sp 1

@unnumberedsubsec on Linux systems

Install Emacs, csound, timidity and sox in your system (on Ubuntu,
this is easily done via apt-get)

Get the latest version of surmulot at:
@uref{http://www.zogotounga.net/surmulot/surmulot.html}

Untar the archive anywhere and use any of its entry point scripts. It
should work out of the box.

@sp 1

@unnumberedsubsec customization

On both systems, you may then fine-tune many aspects of Surmulot. More
about this later... for now see @pxref{(Csound-x)Top} and see muO documentation.


@c ==================================================================
@node Entry points, Fast recipes, Installation, Top
@section Entry points to the system

@sp 1
@unnumberedsubsec Surmulot as a Csound-x extension

Here the entry point is Emacs and its Csound-x package for Csound composition.                 

@pxref{(Csound-x)Top}.

Surmulot provides interactive widgets extending Csound-x with 
graphical editors for musical data such as musical phrases and
envelopes, or interactive controls (like OSC-driven sliders).

@pxref{Widgets}.

Surmulot also makes it possible to generate, edit and play MIDI data
from Emacs, using Timidity as soft synthesizer. 

@pxref{MIDI}.

@sp 1

@unnumberedsubsec Surmulot as a MuO extension

Here the entry point is MuO, a Squeak application for music composition.

MuO homepage:
@uref{http://www.zogotounga.net/comp/squeak/sqgeo.htm}

Surmulot allows Emacs to be integrated as the default text and files
editor for MuO. It makes it also possible for Squeak to access the
system shell via Emacs instead of using OSProcess.

It also gives MuO access to the full power of Csound-x.

@sp 1
@unnumberedsubsec Surmulot as an environment above Csound-x and MuO

Surmulot can also be considered as an unified programming environment in
which applications can use both Csound-x and MuO as libraries.

@c ==================================================================
@node Fast recipes, The Surmulot menu, Entry points, Top
@section How to (simply) ... ?

Here are a few examples of use of Surmulot, in the form of
basic tasks (basic from a composer point of view only since their
actual underlying implementation can be quite complex).

Each example can be evaluated straight away if you're reading
this in Emacs; it is followed by a few explanations and pointers
to set you on the way to further exploration.


@sp 1

@unnumberedsubsec How to (simply) hear some notes

@example
(muo-do "'a,e,f' kmusic fractal play")
@end example

Here we have MuO compute and play a musical phrase, using its default MIDI
synthesizer for playing. 

@sp 1
@unnumberedsubsec How to (simply) generate a sound file

@example
(muo-do "'a,e,f' kmusic fractal asWAVFile edit")
@end example

Same example as above, only the musical phrase is being converted to a
WAV file which is then opened with Surmulot sound editor. the
conversion is done by MuO default MIDI synthesizer for WAV rendering (it is not necessarily the same as the default synth for playing). 

@sp 1
@unnumberedsubsec How to (simply) create an envelope

@example
(setq envelope-editor (surmulot-make-widget "EnvelopeEditor new"))
@end example

Tweak the envelope graphically to your liking (@pxref{Envelope
editor}.), then get it in a suitable format from the editor with something like

@example
(surmulot-widget-do envelope-editor "Widget music asFTable: 1024")
@end example

@pxref{Widgets}.


@sp 1
@unnumberedsubsec How to (simply) start a csound composition

Start from scratch with

@example
(csound-csd-new)
@end example

or directly code a composition in Emacs Lisp like this:

@example
(setq my-composition
  (csound-composition
    :instr 1 '(out (bamboo p4 0.01))
    :i-stream
    (i-be 1 0 1 0)
    (loop for amplitude in '(20000 30000 14000 25000)
          for duration in '(1 2 3 1)
          do (+i :p4 amplitude :p3 duration))))
@end example

You can then either play it with

@example
(csl-play-composition my-composition)
@end example

or use it as a draft and further edit it with

@example
(csl-edit-composition my-composition)
@end example

@pxref{(Csound-x)Csound Elisp}.

@c @sp 1
@c @unnumberedsubsec How to (simply) choose a soundfont

@c @sp 1
@c @unnumberedsubsec How to (simply) play drum patterns

@sp 1
@unnumberedsubsec How to (simply) find the usage of a csound opcode

Get the documentation with

@example
(csound-opcode-doc "linseg")
@end example

@pxref{(Csound-x)Integrated documentation}.


Find all its occurences in the orchestra library with

@example
(csound-search-exact-word "linseg")
@end example

@pxref{(Csound-x)Libraries and repositories}.


@c ==================================================================
@node The Surmulot menu, Widgets, Fast recipes, Top
@section Emacs global menu for Surmulot

If you read this documentation with Info in Emacs, the global Surmulot
menu is the top left one, labelled "<Surmulot>".

From this menu you have direct access to Surmulot documentation and
settings.


@c ==================================================================
@node Widgets, Widgets reference, The Surmulot menu, Top
@section Widgets
@cindex graphical interfaces

Surmulot widgets are Squeak morphs, mostly MuO editors, made available for
Emacs via a TCP/IP connection.

When Emacs requests a widget, it starts the MuO image as a subprocess
and asks it to become a specific widget. The image then changes its name, close
its source files and resizes itself; the requested morph is opened in
full size and can be accessed through the Smalltalk global variable Widget.


@sp 1

@unnumberedsubsec The Widget menu

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. 

@sp 1

@unnumberedsubsec Interaction

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.

@sp 1

@unnumberedsubsec Debugging and advanced usage (for Squeak developers)

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 MuO image.

Note that is is better to directly work within the MuO 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.

@c @sp 1

@c @unnumberedsubsec Functions and commands related to Surmulot widgets

@c TEXI DOCSTRING MAGIC: muo-edit-csd-as-widget


@c TEXI DOCSTRING MAGIC: surmulot-OSC-controls

@c TEXI DOCSTRING MAGIC: surmulot-widgets-list


@c ==================================================================
@node Widgets reference, MIDI, Widgets, Top
@section Widgets reference

This section explains how to work with the different types of widgets

@menu
Editors

* Envelope editor::
* Musical phrase editor::
* Score editor::
* Function editor::
* Csound Blocks::

@end menu

@c ------------------------------------------------------------------
@node Envelope editor, Musical phrase editor, Widgets reference, Widgets reference
@section Envelope editor
@cindex envelope editor

@image{images/EnvelopeEditor}
@sp 2

The envelope editors defines breakpoints, and how they shape an envelope.


@sp 1
@unnumberedsubsec Interpolations

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.

@sp 1
@unnumberedsubsec Selection

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.

@sp 1
@unnumberedsubsec Handles

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.

@sp 1
@unnumberedsubsec Exportation

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.

@sp 1
@unnumberedsubsec Edition as a function

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. @pxref{Function editor}.


@c ------------------------------------------------------------------
@node Musical phrase editor, Score editor, Envelope editor, Widgets reference
@section Musical phrase editor
@cindex musical phrase editor

@image{images/MusicalPhraseEditor}
@sp 2

The phrase editor is a comprehensive tool for editing MIDI-like
data. Type ? for a summary of commands bound to specific keys.

@sp 1
@unnumberedsubsec Importing MIDI data

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.

@sp 1
@unnumberedsubsec Displayed area

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.

@sp 1
@unnumberedsubsec Cursor and region

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 ?).


@sp 1
@unnumberedsubsec Selection

Notes can be selected/deselected individually or collectively with the
region. The selection can be moved and transposed, or directly edited
(type e).


@sp 1
@unnumberedsubsec Handles

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.
  

@sp 1
@unnumberedsubsec Rhytmic canvas

The editor time grid unit is the second. By default the grid is
composed of plain decimal subdivisions, but it can be a much more
complex rhytmic canvas made of any number of repeated rhytmic cells.

This is not yet documented, sorry.


@sp 1
@unnumberedsubsec Scales

While the default pitch grid is an ordinary 12tet scale, any other
scale can be used instead. The editor can read the Scala format for
scales; see menu item 'grid->select a scale'.

@sp 1
@unnumberedsubsec Exportation

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.

@pxref{(Csound-x)Handling MIDI data}.

<MPhrase> areas can later be edited directly, using the "MPhrases"
submenu of the main "CSD" menu. 


@c ------------------------------------------------------------------
@node Score editor, Function editor, Musical phrase editor, Widgets reference
@section Score editor

@c @image{images/CsoundCompositionEditor}
@c @sp 2

The Csound score editor (or Csound composition editor) is very similar
to the musical phrase editor (@pxref{Musical phrase editor}). 

It is always linked to a specific CSD file, which is why you can not
create a new one from the "Widgets" menu. Instead, use the "Edit
score in widget" from the "CSD -> Surmulot" submenu.

@sp 1

The main difference between the musical phrase editor and the
score editor comes from the arbitrary format of score i-statements. Apart from
the first three there is no meaning associated to the p-fields. For
example there is no generic way to know which p-field is responsible for
the pitch or the volume of the csound note described by the
i-statement; and we must take into account the fact that some notes
do not have either pitch or volume, plus the fact that some
i-statements do not describe a note at all.

To enable editing in a meaningful way, each Csound orchestra has to be associated to a description of its score
format. The score editor allows this format to be entered
interactively via context menu items; the score format can also be encoded directly as specific
comments in a CSD file, in which case the editor will read it automatically. Both approaches are described below.

@sp 1
@unnumberedsubsec Score format

@sp 1
@unnumberedsubsec Score format


@c ------------------------------------------------------------------
@node Function editor, Csound Blocks, Score editor, Widgets reference
@section Function editor
@cindex function editor

@image{images/NFunctionEditor}
@sp 2
The function editor is a workspace for mathematical operations
relative to one-dimensional functions, such as envelopes or sound
waves.

Functions can be edited, combined and exported to different formats. 


@sp 1
@unnumberedsubsec Function library

The editor starts blank. From the contextual menu, "add function from
library" provides a submenu of predefined functions. Choose any one to
add it

@sp 1
@unnumberedsubsec Function input

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

@example
x sqrt
1 + x
x abs log
((((x + 0.5) * 500) * (((10 * x) fractionPart) sin)) sin)
@end example

Note that Smalltalk has no concept of mathematical operator
precedence !

For example 
@example
1 + 2 * x
@end example
is actually
@example
3 * x
@end example
so take care to write
@example
1 + (2 * x)
@end example


@sp 1
@unnumberedsubsec Display

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.


@sp 1
@unnumberedsubsec Parameters

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.



@sp 1
@unnumberedsubsec Functions composition

When adding a function by inputing its equation, you can reference the
already displayed functions using their name.

For example if you have the two functions "f1" and "f2" from the
previous chapter, you can input  

@example
f1 + f2
@end example

which displays the function x -> f1(x) + f2(x)

The operator "<=" allows the composition of functions; try

@example
f1 <= f2
@end example

to display the function x -> f1(f2(x))

@sp 1
For technical details about what functions really are in Squeak,
see @uref{http://www.zogotounga.net/comp/squeak/functionaltalk.htm}


@c @sp 1
@c @unnumberedsubsec Exportation

@sp 1
@unnumberedsubsec Edition as an envelope

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. @pxref{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 (@pxref{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. 


@c ------------------------------------------------------------------
@node Csound Blocks, , Function editor, Widgets reference
@section Csound Blocks

@image{images/CsoundBlocks}
@sp 2

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 MuO image (@pxref{The Surmulot menu}) and from the
"muO objects" menu select "live documentation -> examples -> reference
-> Csound Blocks Examples".


@sp 1
@unnumberedsubsec Manipulation

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.

@sp 1
@unnumberedsubsec 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.



@c ==================================================================
@node MIDI, Saving your work, Widgets reference, Top
@section The many faces of MIDI data


@unnumberedsubsec Keykit format

@sp 1

@unnumberedsubsec MusicalPhrase

@sp 1

@unnumberedsubsec MIDI to score conversions

@sp 1

@unnumberedsubsec Timidity interaction

@sp 1



@c ==================================================================
@node Saving your work, Upgrading, MIDI, Top
@section Saving and restoring the current state of the system


@c ==================================================================
@node Upgrading, Concept index, Saving your work, Top
@section Getting and installing Surmulot




@c ==================================================================
@c ==================================================================

@node Concept index, Command index, Upgrading, Top
@printindex cp

@c ..................................................................
@node Command index, Variable index, Concept index, Top
@unnumbered Command Index

@noindent
Commands available via @kbd{M-x} prefix.

@printindex pg

@c ..................................................................
@node Variable index, Function index, Command index, Top
@unnumbered Variable Index

@noindent
Surmulot variables and hooks

@printindex vr

@node Function index, (dir), Variable index, Top
@unnumbered Function Index

@noindent
Surmulot public functions

@printindex fn

@bye


@comment Local variables:
@comment version-control: t
@comment End:
