==How to handle the various GLAME frontends==
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 also that the sections entitled “Copying” and “GNU General Public License” are included exactly as in the original, and 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 Free Software Foundation.
Moi Mr. Newcomer, hi Mrs. Impatient!
Welcome to GLAME, the GNU/Linux Audio Mechanics. This is the Quick Start Guide for all those who loathe reading lengthy documentation. So I won't fuzz with details but try to get you going on basic tasks as fast as possible.
GLAME comes in two flavours, the graphical interface glame and the console frontend called cglame. You'll have to be able to grok Scheme in order to deal with cglame. It's extremely cool and powerful but it's probably not what you are looking for when reading a quick start guide. So let's talk about the graphical interface in the following, and send those Schemers off to poke through the proper documentation.
So you recorded this charming little chanson called Angelina, but she ditched you the other day and now dates Ron instead? No need to keep waiting until another Angelina passes your way. GLAME will help you changing your Angelina tune into a hymn on Heather in an instant. (Admit it, you've been after Heather for ages!)
Fire up glame, ignore the crappy splash screen, and what you'll see is the so-called Swapfile GUI. Don't waste your time pondering about the name, it's simply a view of all audio tracks that GLAME knows about. Tracks are kept in a hierarchy of projects and further groups of tracks. To make your sweet angelina.wav known to GLAME, first select New Project from the Project menu. A new entry appears; name it No More Angelina. Then click the right mouse button on the new entry, and a pop-up menu does what its name suggests: it pops up right in front of you. Choose the entry called Import, and select your angelina.wav. It's a stereo file, of course. Therefore the Swapfile GUI now shows two entries within your Angelina project, one for each track. Now you're all set to wipe poor Angelina if not from your life, then at least from your art.
Once again, click on the No More Angelina entry in the Swapfile GUI, press the right mouse button, and select Edit from the pop-up menu. What appears now is the so-called Waveedit GUI, a window containing a graphical view of the audio tracks in your project. (Of course you are tempted now to wipe Angelina from one track only. Well, you could do that by selecting Edit on a single track rather than the whole project. You could even edit one track in multiple windows at the same time. But this is not the road we want to go down now. This Angelina-bitch ditched you, remember? Let's wipe her from your song completely.)
The Waveedit GUI is mostly driven from a pop-up menu attached to the right mouse button. Have a guess what Play All might do? Well, try it out. If you can't hear a single note, check your mixer settings with an external mixer program, and if all seems to be right, go back to the Settings menu in the Swapfile GUI and check your Audio I/O preferences. Working now? Good. Want to know how zoom in and out work? Ah, no, you figured that out yourself. Now you have to identify the places in the song where your voice trembles Angelina. To make it easier for you, during playback a vertical line will mark the region currently playing. Of course you don't have to keep playing the song as a whole over and over. There is Play Selection after all. What's a selection? That's a highlighted region in the editing window. Press the left mouse button, drag the mouse, release the mouse button again, and you'll get the trick. A lot of things can be done with selections from the pop-up menu. They can for example be played, zoomed into, cut, copied, and deleted. The latter is just what we need now. Select each of the passages enchanting Angelina, delete them, and there she goes.
So what about Heather? We'll be with her in an instant, but we have to learn a bit about recording first.
Back we are at the Swapfile GUI. Let's add a new project, and name it Oh Heather. That's where you're going to record into. Well, not quite. You can't record into a project, of course, you can only record into tracks. So you need to pull a track out of thin air, two of them actually, as you're going to record stereo. The right mouse button again acts as your magic wand. It will present you a menu item Add stereo wave, and that's exactly what you need now. Add the two empty tracks, select your Heather project, and open the Waveedit GUI on it, using the Edit entry in the pop-up menu.
The editing window doesn't look too interesting at the moment but that's what you'd expect from an empty file. It'll change soon, so go launch your favourite mixer application, and prepare your system as well as yourself for recording. Once both of you feel in shape, come back to the editing window. Record at marker is the preferred item in the pop-up menu now. A panel will appear containing the four buttons Record, Pause, Stop, and Cancel. Hitting the first one will start the recording. Finding out about the meaning of the others is left as an exercise to the reader. Don't think too hard about it, though, as now is the time to give a c-sharp Heather in your best tremolo ever. You should've figured out to hit the Stop button by the time you're done.
The rest is easy. In the Heather editing window, mark a selection only containing you singing the name but none of the noise before and after. Pop-up the menu with the right mouse button and hit Copy. Then move over to the Angelina editing window, which should still be open. A click with the left mouse button will mark a position in the song, and selecting Paste from the pop-up menu will insert your Heather at this position. Where to insert the section is entirely up to your artistic talent.
Not fancy enough to woo Heather, you feel? Read on.
To brush up a selection from the Waveedit GUI, you can apply a single filter on it. Apply Filter from the pop-up menu gets you going. But you can do even better. Select Apply Custom and watch the Filternetwork Editor come up. Here, you can not only apply a single filter, but a whole collection of filters that interact with each other.
Think of the filter network as a factory of waves. It starts out on one or more sources of sound waves, mangles the sound, and finally sends it off to one or several consumers. There is already a source in the network, called swapfile_in, and a consumer called swapfile_out. Don't mess with them, as they were already set up by the Waveedit GUI to work on the selection you marked. It is your task now to build the individual steps in the factory itself. That is, what should be done to your sound, and in which order. To this end, you can insert filters into the network. They are your machines. Just hit the right mouse button, and select one of the entries. A small icon will appear depicting your new filter. Each filter has its inputs to the left, and its outputs to the right. To connect two filters, you draw a line from the output of the first to the input of the second, dragging the mouse with the left button pressed down. Some filters do not possess both inputs and outputs. You'll note this when one side of their icons is greyed out. Inputs and output in general are not limited to a single connection. A filter will accept as many connections as it can take, and reject any further.
For most filters, you want to tune their parameters, or their output will probably not come close to what you intended. Press the right mouse button on top of the filter image, and select the Properties entry. A new window will show up, where you can tune the parameters to your liking. Once all parameters are set, and all filters are connected, hit execute on the icon bar on top. When processing is finished, go to the Waveedit GUI, and watch your modified Heather tracks.
What's left to do? Back to the Swapfile GUI. It's about time to finally rename the No More Angelina project to Hymn to Heather. How? Go figure. You really should have gotten a good feeling of how GLAME works by now. Next, get the pop-up menu up on Hymn to Heather. Select Export..., and save your song as, say, heather.wav. As you may have guessed, by default the suffix determines the type of file Hymn to Heather is stored as. For some additional control, you can explicitly specify the desired file type and sample format via several rather obvious buttons and menus. Want details on that one? Hey, enough is enough! Go read the proper docs if you're that interested. Or try on of the Help entries that will present you a context sensitive entry from the manual.
Well done, you may call yourself a GLAMEr now. A Lamer even, if you don't get up immediately and present your new song to Heather. Off you go. Good luck!
Back with us again? Oh rats, Heather finally broke your heart and left you? Cheer up, there's Bozo "The Dragster"'s ultimate party next weekend, and Bozo thinks you'll fit perfect with some of his best friends. Wonder how to break the ice? Don't worry. A microphone and a box running GLAME, that's all you'll need to hook them up.
Let's get the setup straight first. In the preferences dialog... Pardon me? How to get to the preferences? Gee, guess you need a couple of Angelinas and Heathers still, until you're ready for Bozo. Found it now? Fine. In the preferences dialog, there's a little fine-tuning to do on Audio I/O for a spiffy full-duplex setup, meaning that we're going to play and record at the same time. Select OSS and configure /dev/dsp for input, and /dev/dsp1 for output. This'll work if your sound card is fancy enough to offer more than one DSP device. Otherwise, lend your neighbour's for the day. Your smartass neighbour is likely to mention something about ALSA being so much better. "The day ALSA can be considered stable is unlikely to be in the same century that Bozo holds parties," is a good answer. Learn it by heart. The curious of course can try whether there's a GLAME plugin compatible to the ALSA version du jour. If you're lucky, plughw:0,0 and plughw:1,0 might be the correct settings for input and output. Probably they aren't.
Now for some real fun. From the Swapfile GUI, you can launch the Filternetwork Editor. New Filternetwork is the menu entry we're talking about. You are already familiar with the window that pops up–remember the wave factory? This time, however, the factory is completely empty. Two filters, audio_in and audio_out, will make it work just-in-time, though. For kicks, add a flanger filter as well, and connect it to both audio_in and audio_out.
This setup is working but seriously lacking coolness. Let's fiddle with some parameters. Right-click on the flanger icon and select Properties. Set the effect depth to 50ms, the detune range to 25ms, lfo speed to 8Hz, dry/wet balance to 0.0 and the LFO Type to Ramp Up.
Once you click on Execute in the editor window, start talking into the microphone. Voila, you're talking like Mickey Mouse! Now stop the network by clicking on the Execute button again that has in the meantime morphed into Stop. Change the LFO Type to Ramp Down and execute the network again. Coolness factor rising, eh!? Time to fire up your favourite mailer and send a message to email@example.com, telling him what cool a frood he is. Some of the parameters you can even alter while the network is running. Just go on from here and play around. Once you've found the Bozo killer setting, the Save button is a good one to try next.
Now for a more sophisticated network: A sampler that will record your voice and repeat it in an endless loop. Bozo's dudes are gonna love it, honest. First, wire up the basic network from audio_in, mix, one2n, and audio_out. So far it's just a slightly complicated way of sending all input to the output unmodified. The network gets a lot more interesting when we add a feedback loop. Add a buffer filter, a delay filter, and connect them sort of backwards. That is, draw a second connection from one2n's output to the input of buffer. Connect buffer to delay, and finally hook up delay's output to the input of mix.
Still a little tuning to do. There's a little blob on the connecting line between delay and mix. Right-click on it, and select Destination Properties in the menu that pops up. Set the gain to 1.9. Next, open the properties dialog for the buffer filter and set the time parameter to 1 second. In the delay filter's properties, set the delay time to 500ms. Turn down your amp really low, execute the network and talk something intelligent like "Boh" into your microphone. If a screeching sound hurts your ears, the gain parameter probably is to high. Click on the little blob again and tune it until you're satisfied. If you set it to smaller values, your voice will slowly fade out, if it's to high it will just get louder and louder until your speakers freak out. Obviously, an endlessly repeating "Boh" isn't all that stunning. "Zoh" sounds like a good second line. Talk into the microphone, and wow, here's our vocal percussionist. The party is your's, and hey, it's time to go now. Send our best to Bozo and the drags. Have fun!
Nonsurprisingly, GLAME's graphical frontend is called glame. Usually, it will be invoked without any arguments. An optional file name may be given though, indicating an alternative location of GLAME's internal swapfile. See The Main Window, for details.
A note to the DIY folks: When running glame straight from its source
tree without prior installation,
glame/src/ has to be your current
working directory. Otherwise, glame won't be able to find its plugins.
The graphical frontend consists of three parts. The main window, also called
the Swapfile GUI, is the only one active right at the beginning. The wave
editor and the filternetwork editor can be activated from there. Controlling
glame is supposed to be rather intuitive. Should you ever feel lost,
just try pressing the right mouse button, and a context sensitive menu will pop
up and hopefully present you with the option you were looking for. If you are
looking for a list of keybindings for the current window try pressing the
F1 key. The context sensitivity buzzword also applies to GLAME's online
help. Just push the button and hope for your preferred gnome help browser
being able to display texinfo docs. (The standard gnome-help is.)
On startup, glame will present you with an application window in well-known GNOME design that contains a tree view of the so-called swapfile currently in use. Representations of all the sound tracks you want to edit will be stored here, so it's certainly a wise idea to put the swapfile on a partition with plenty of free space. By default, the swapfile resides in ~/.glameswap, but you can configure its location in the preferences window available from the Settings menu. Note that you need to restart glame for the change to become active.
Within the swapfile, individual audio tracks are combined to projects. You can create new projects using the entry New Project in the Project menu. This will insert a new item into the tree view of the swapfile and pop up a field where you can edit the project's name. Double-clicking on an item allows you to change the name later as well.
Now you're all set to start importing files into your new project, or to subdivide it further into groups. A context sensitive menu offering operations on groups or items respectively pops up when you press the right mouse button. Those are your options:
Add mono wave
Add stereo wav
Merge with parent
Sequencing multiple waves in the main window is rather easy. Using drag and drop while pressing some modifier keys, you can move waves between horizontally (hbox) and vertically (vbox) sequenced boxes (groups). See below for a list of available modifier keys.
To move a wave to a different place first hold down the proper modifier to select the mode, then select the item you want to move with the left mouse button and start dragging it. The destination is located just before the wave you drop onto, or at the last position of the group you drop onto respectively.
The following two modes are supported and can be selected via the specified modifier keys:
While dragging, you can see the mouse cursor change from a circle (indicating a drop at the current position is not possible which in turn indicates a wrong group type of the current group) to a hand (indicating a drop is possible). You can cancel a drop by dropping back on the original dragged item.
If you want to change a vbox into a hbox or vice versa, you need to go through an intermediate group. First create a dummy group and start moving items there. Then move items back to the original group with the right mode. Note that you can move whole groups at once. So sequencing stereo waves is possible, too, without breaking the stereo groupings.
In the main window's tree view you can use the following keyboard shortcuts to change the waves speaker positions. The active wave is denoted by the item the mouse is pointing at.
The following items are present in the Project menu:
[deleted]folder. This operation cannot be undone. Deleted elements are usually just moved to the
[deleted]folder so you can undo deletes by just moving items back. Emptying the
[deleted]folder can also be done by deleting the
Show console, you get access to the powerful backend of glame that can be controlled via a scheme scripting language. Or just watch the error logs that pop up here as well.
These are the items of the
Load Pluginmenu item from the filternetwork menu. This is useful for instance to use external LADSPA plugins or custom filternetworks you didn't put into the default GLAME search directory.
Settings menu you can invoke the preferences window, from
Help menu you can invoke a gnome help browser with this
documentation, or jump directly to the quick start guide.
The timeline view is highly experimental and may cause other parts of GLAME to fail operating on modified tracks. You can usually recover from this situation by flattening the affected subtree, but this may be not the thing you want to do. Be warned.
The timeline pops up when the
Timeline function is applied to a
group in the main window. The timeline presents a time vs. track view
of the group. At the top of the window there is a ruler which shows
the time in seconds.
The active item and group appear highlighted. You can move the active item horizontally (in time) using the mouse by clicking and dragging. You can move items vertically (changing the track an item is in) by using the up and down arrow keys. You can move whole groups vertically by using the up and down arrow keys in conjunction with the shift modifier key.
Like in any other window, the
Help toolbar entries
close the window, or bring up the gnome help browser with this documentation,
The wave editor pops up when the
Edit function is applied to either a
group or a single item of the swapfile tree.
Editing is done on all items of a particular group
at once. Functions to edit and explore the current items can be reached via
the right mouse button or the toolbar. The wave editor is also reached
Edit File menu entry or the
You can find keybindings listed by pressing the
F1 key in any
wave edit window.
Simple editing can be done using the ordinary
Edit submenu, that work on the current selection in
the active wave widget. You can cut and paste between different wave
widgets, if the numbers of channels match. When you operate on multiple
views of the same wave item at once, they will be kept in sync
automatically. Keybindings for
You can export the current selection by choosing the
menu entry from the
Edit submenu or by pressing the
To control the view use the
View submenu which contains the
Zoom to selection,
View all and
Goto marker. The zoom in, zoom out and
view all functionalities can also be reached from the appropriate
To specify the current selection simply use the mouse and drag it with
the left mouse-button pressed. Alternatively you can use the
Select all menu items from the
Select submenu or the
corresponding buttons in the toolbar to remove
the actual selection or select the whole wave. Pressing shift and the
left mouse-button selects everything starting from the marker position (which
you can set using the left mouse-button) to the current position. The selection
and the marker position can be changed with dragging the marker or the
selections left or right edge (the cursor will change if you move over them).
As usual, the
Help menu entries close the window, or
bring up the gnome help browser with this documentation, respectively. Those
items can also be reached from the toolbar.
Play all and
Play selection commands the whole wave or
the selected part will be sent to the default audio output device. Using the
Record at marker and
Record into selection commands you can
sample from the default audio input device either starting at the marker
position and until you press the
STOP button, or just inside the
selection. Using the play button from the toolbar will start playing either the
current selection or from the marker position if no selection is active and
will advance it until you either press the stop button (which will appear at
the place of the play button after start) or the wave has ended. Playing can be
reached through the
Space keyboard shortcut which starts playing
from the current marker position. Using
Ctrl-Space you can play the
current selection or the whole file, if nothing is selected. Pressing
Shift-Space will loop the current selection or the whole wave.
Apply operation submenu allows you to apply operations like
normalize or fade to the current selection. Some operations pop up windows
for additional arguments.
Apply filter submenu allows you to apply a pre-existing
filter to the active selection. Inside the apply window the list of
available parameters for the filter will appear which you may edit. With
the preview button you can figure out what the result after applying the
filter will sound like. You can abort the preview by pressing the
preview button again. Press the apply button if you are satisfied with
the setup. Press the cancel button if you don't want to modify the wave.
Alternatively, you can pop up the filternetwork editor
see The Filternetwork Editor, where you can construct a custom
filter or use
Apply custom... which creates a filternetwork
framework containing necessary inputs and outputs specified by the
A shortcut to the export functionality is embedded in the toolbar
Save item. This is especially useful for waveedits
opened through the
Edit File menu entry as this one does not
show the wave in the swapfile tree.
The filternetwork editor is opened when you choose one of the custom
functions in the wave editor, or the item
New Filternetwork in
Filternetwork menu of the main window. The filternetwork editor
comprises of a tool bar at the top of the window to execute, save and apply
other functions, and a main canvas for connecting and adding
new nodes to the network. A preexisting network can be edited by opening
it from the
Open... item in the
Filternetwork menu of the
All functionality in the editing window is controlled via context sensitive menus bound to the right mouse button or configurable shortcuts.
Pressing the right mouse-button over the canvas background will pop up a menu
containing the list of available plugins. Plugins are bundled into categories
to speed up finding the desired item. Selecting one will add a node cloned
from the corresponding plugin to the network. A special item,
selected at the bottom of the menu will paste the last copied node collection
at the current location. When a new node is added, its icon appears on the
editing canvas. It shows its input ports (if available) on the left, and
output ports on the right. If no ports of a type are available, the
corresponding side bar appears gray.
To connect two plugins, click on the output port using the left mouse button, and drag the appearing pipe to the desired input port. If a connection is possible, a pipe connection will be drawn. To manipulate per-pipe parameters of the connected nodes, a context menu is attached to the small black ball placed in the middle of the pipe.
Clicking with the left mouse button on a item will highlight it with a light blue frame, thus marking it as selected. Alternatively, nodes can be selected by clicking with the left mouse button into empty space in the editor, holding it down and dragging the appearing box over the desired nodes in well known file-manager fashion. You can alter selections by holding down the shift or control modifier keys. Pressing one of the modifier keys while selecting will add the selected icon to the current selection.
Selections may be manipulated in a number of fashions. A selection can be
collapsed by either choosing the corresponding context menu in the node menu or
c shortcut. Once a selection is collapsed, a new node appears in
place of it. Connections to nodes in the selection to outside nodes are saved
and ports appear on the collapsed node. Collapsed selections are real new
subnets and may be saved and opened down, and just as any node representing a
network expanded in-place using the corresponding menu entry or the
Finally, if you hover over an icon or port or the circle contained in a pipe for a little while, the current parameter settings are shown, and the node is raised to the top. The hovering delay can be adjusted in the preferences window. The same applies for the connection between two nodes.
Pressing the right mouse button over a network node will pop up a menu with the following items:
Paste selectionmenu entry from the node addition menu.
Open downmenu entry.
Pressing the right mouse button over a port will pop up a menu with the following items:
Pressing the right mouse-button over the pipe bubble will pop up a menu with the following items:
There are a few keyboard shortcuts which expose additional features:
The created network can be executed with the corresponding button in the toolbar. At execution time this button turns into a stop button which can be used to abort executing the network. If anything is not set up correctly, the malicious plugin will be drawn in red, and the error will be displayed when hovering over it.
Once you found your network to be adequate, you may save it using the
Save button in the toolbar. You can also register the network as a new
plugin that can be used in other networks. Before that, you have to add ports
to your toplevel and/or redirect parameters from nodes. Ports can be redirected
by choosing the
Connect to external port from the context menu of the
port. Parameters are redirected by choosing
redirect parameters from the
context menu of the node. You can delete or look at the external interface by
As a final feature, the zoom level can be adjusted with the
zoom out buttons. The
View all button recenters your
view and adjusts the scrollable region.
From within the preferences dialog, which you can reach from the main windows Settings menu, you can change GLAME's configuration including the swapfile setup and your audio setup. Note that some changes take effect only after restarting GLAME.
The preferences dialog presents you with three tabs, namely the Swapfile, Filternetwork, Waveedit and Audio I/O tabs. We're going through them separately.
The first tab is the Swapfile tab which has the following entries:
Depth of undo stack
Filternetwork tab lets you configure some UI parameters
Property popup timeout
Waveedit tab lets you configure some UI parameters
Audio I/O tab lets you configure the default audio input
and output device.
Default input plugin
alsa_audio_infor most Linux boxes.
Default input device
/dev/dspdevices, for alsa
Default output plugin
Default output device
Size hint for audio buffers
Note that if you have certain sound daemons running such as
from KDE or
esd from GNOME you may need to kill them before you
can access your audio devices from within GLAME.
The import dialog is spawned by selecting the menu entries "Edit File" or "Import" from the main window. This dialog is mostly self explaining. Select a file by typing its name, or search it with the file browser. There some other buttons you can toggle:
Get RMS & DC Offset
The export dialog appears in case you select "Export..." from the popup menu or see The Wave Editor. The dialog contains the following buttons:
The apply filter dialog is reached from the waveedit window through the right
mouse button menu by choosing the
Apply filter... entry and operates on
the current selection. In the upper part of the dialog, the parameters of the
selected filter are displayed and can be edited.
Two switches are available to control behavior of the
The lower part of the dialog contains a progress bar for both preview and apply operation. The following functions are available:
cglame is GLAME's console interface. Beware! cglame is not for whimps but for real men and women who dream in Scheme and chomp brackets for breakfast. It's for those who want to feel the ultimate power of GLAME. Thankfully, J. Random User won't have to dive into the perils of cglame and will be all happy with glame, the friendly and intuitive graphical frontend see Graphical Frontend.
Still there? Wheee, you're a tough one! Let's see what's in here for you: This chapter starts with a brief introduction into the cglame user interface. Afterwards, the wrapped midlayer and backend APIs are listed, and an the scheme level API on top will be described.
cglame is a scripting engine
in the sense that you are presented a
glame> command line prompt
where you can enter scheme expressions. cglame exposes GLAME's
midlayer API and the backend API via scheme wrappers. Extra convenience
scripting procedures are defined in the global glame.scm scheme
file. You can add customisations via your ~/.glame.scm file or
by loading appropriate scheme files at the appropriate time using
As command line option to cglame you may specify the swapfile to
be used like
-s path-to-swapfile. A swapfile is necessary if you
want to use any of the swapfile API procedures. To make cglame
create a swapfile for you use
Once started, cglame presents you with a command prompt where you can evaluate scheme expressions. An example session is shown below. Alternatively you may run cglame non-interactively by specifying the filename of a to be executed script as last argument to cglame.
$ cglame CGLAME for GLAME version 0.5.2, Copyright (C) 1999-2001 Alexander Ehlert, Richard Guenther, Johannes Hirche, Daniel Kobras. CGLAME and GLAME come with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. Quick help: (quit) gets you out of here. (help) gets you some additional help. glame> (play "/var/tmp/short.wav") glame> (play-eff "/var/tmp/test.wav" '("echo")) glame> (let* ((net (net-new)) ... (nodes (net-add-nodes net '("read_file" "echo" "audio_out"))) ... (echo2 (net-add-node net "echo"))) ... (node-set-param (car nodes) "filename" "/var/tmp/test.wav") ... (nodes-connect nodes) ... (nodes-connect (list (car nodes) echo2 (caddr nodes))) ... (net-run net)) glame> (quit) $
All used scheme procedures which are not documented in the following sections reside in the glame.scm file shipped with glame, usually installed as /usr/share/glame/glame.scm.
For description of the detailled semantics of the available parts of the APIs please refer to the native documentation.
C functions which return 0 on succcess and -1 on error are converted to
scheme procedures evaluating to
#unspecified on success and
'glame-error exception on error.
C functions which return an object on success and
NULL on error
are converted to scheme procedures evaluating to an object and throwing
'glame-error exception on error.
Void functions generally evaluate to
You can catch
'glame-error exceptions by using code like the
glame> (catch 'glame-error (lambda () (filter-connect foo "out" bar "in")) (lambda args (display "Cannot connect\n")))
The basic filter subsystem types,
filter_param_t exist as native scheme
types and such can be type checked.
These procedures check
objfor being of the specified type and evaluate to
#tif this is the case and
Out of a filter object you can get information and subobjects using the following procedures:
These procedures evaluate to a string containing the filters name or to lists of the specified object type representing the actual subobjects associated with the filter.
Out of a port object you can get information and subobjects using the following procedures:
These procedures evaluate to a string containing the ports label or to lists of the specified object type representing the actual subobjects associated with the port.
Out of a param object you can get and modify information using the following procedures:
These procedures evaluate to a string containing the label of the param object, the actual value of the param whose type depends on the param objects type or a boolean denoting the success of a param set command.
Out of a pipe object you can get information and subobjects using the following procedures:
These procedures evaluate to an exact number containing the samplerate of the data flowing through the pipe, a number containing the position of the audio stream or to lists of the specified object type representing the actual subobjects associated with the pipe.
Pipe objects can be queried for the actual protocol type using the following procedures:
These procedures check
pipefor being of the specified protocol type and evaluate to
#tif this is the case and
Usually you can attach key/value pairs to a per object database. Those object properties can be queried and modified using the following generic interface:
These procedures evaluate to
#unspecifiedor a string object containing the value associated with the specified key or
#fif this key has no associated value. Note that for both
valueonly string objects are allowed. Predefined key values are
The following procedures handle object serialization and creation and destruction of objects.
filter-newconstructs a new filter object by either cloning from a filter or a plugin object or creating an empty network from scratch. The delete procedures destruct the specified objects.
While the first procedure returns a string containing a scheme expression being able to recreate the filter object, the second procedure just evaluates to a string containing the value of the specified param.
filter-add-nodeadds the specified filter (second parameter) to the specified network (first parameter) using the identifier specified as third parameter.
filter-connectconnects the two specified parameters via the specified ports identified by their port names.
filter-connectevaluates to a pipe object.
Procedures to be used for exporting ports and params to the outside world in a macro filter. The first parameter is the actual network, the second parameter is the node that gets exported from. These procedures evaluate to a port or a param object.
glame_create_plugincreates and registers a new plugin using the specified name and associate it with the provided filter. Evaluates to a plugin or to
glame_plugin_defineis used internally for transparently registering or filter loading.
These procedures handle filter network execution.
The swapfile is a container for data in its raw form. It is modeled after a simple filesystem with a flat namespace (no directories) and names being just cardinal numbers.
These procedures control the swapfile subsystem.
swapfile-openinitializes the subsystem from the swapfile at the specified location.
swapfile-creattries to create a new swapfile at the specified location,
swapfile-closecleans up and closes the subsystem.
These procedures can be used to traverse the swapfile files. Function is like the libc readdir routines, but as the swapfile has a flat namespace you dont specify a subdirectory for
sw-opendirevaluates to a
sw-readdirreturns swapfile filenames as long as they are available and
#fupon directory end.
Unlinks the specified file from the swapfile. You cannot recover unlinked swapfiles. Behavior is like unlink(2), i.e. if the file is still open the deletion of the data is postponed until close of the file.
For working with a swapfile you need to obtain a handle to it. Use
sw-opento open the swapfile with the specified name. The flags argument is modeled after open(2),
O_WRONLYare available. Or them together like
(+ O_CREAT O_TRUNC O_RDWR).
sw-openevaluates to a file descriptor which you can identify using the
sw-closeif you are finished with the file.
sw-fstatobtains information about an open filedescriptor. It evaluates to a list of the form
( name size mode offset cluster-start cluster-end cluster-size )where all entries are cardinals.
To seek inside a file use
sw-lseekwhich works like lseek(2), i.e. it seeks relative to whence offset bytes. For whence
sw-lseekevaluates to the current file pointer position.
sw-ftruncatetruncates the specified file to the specified size appending zeroes in case of enlarging.
sw-sendfilecopies (by using copy on write) size bytes from the current filepointer position of the source-fd to the current filepointer position of the dest-fd. Via the optional flags argument you can specify the following
For both files you can specify
- The data is inserted at the filepointer position of the dest-fd instead of overwriting and/or extending the file.
- The data is removed from the source-fd after writing to the dest-fd
SW_NOFILEif it makes sense (i.e. for just cutting out data specify
SW_NOFILEas dest-fd and
Those are the basic read and write operations. Both strings and float vectors are supported by the scheme interface. For reading you need to specify the type via the procedure name, for writing the type is automatically determined. The read procedures read size number of objects from the current filepointer position. They evaluate to the number of objects read.
sw-writewrites the whole object to the current filepointer position and evaluates to the number of objects written. All procedures increment the filepointer position by the number of bytes read/written.
The glame plugin midlayer API is wrapped with the following procedures:
This procedure checks, if the specified object represents a plugin and evaluates to
#tin this case, else
This procedure adds the specified path to the plugin shared object search path that is used by the
Queries a plugin with the specified name out of the plugin database. Evaluates to a plugin or
#fif a plugin with the specified name cannot be found.
Queries the name or custom properties out of a plugin. Those procedures evaluate to a string,
plugin-set!sets the specified property to the specified string. Predefined property keys are
The glame gpsm midlayer API is used to represent metadata associated with wave data, i.e. samplerate and positional information. The gpsm API also wraps swapfile modification of wave data.
For global control and initialization the following procedures are available:
These procedures handle initialization and cleanup of the gpsm and the swapfile subsystem. As path you need to specify the path to the to be used swapfile.
gpsm-syncsyncs all gpsm metadata to disk.
The gpsm subsystem builds on a tree of gpsm items which are derived from a generic item type. Available item types are the gpsm group which just contains a list of children, and the gpsm swapfile which represents a wave with its metadata and swapfile representation.
These predicates check if the provided object is an gpsm item, or one of the derived types, a gpsm group or a gpsm swapfile.
These procedures give access to the basic gpsm type, the gpsm item. They evaluate to the items parent item, to its label or its position and extension.
These procedures give access to the gpsm swapfile type. They evaluate to the wave swapfile metadata, respective the swapfile filename, its samplerate and position in the stereo field.
These procedues modify one of the gpsm type properties.
For creating, copying, linking and destroying of items the following procedures are available:
For structuring, modifying and traversing of the gpsm tree the following procedures are available:
Predicates that check, if the specified group is a hbox (a set of horizontally sorted, non-overlapping items), or a vbox (a set of vertically sorted, non-overlapping items).
Placing happens without moving unaffected items. Placing needs to happen at a position where the needed space is already available.
Removing happens without moving unaffected items and reverses a previous
Insertion moves adjacend items horizontally by the size of the inserted item. Only the starting position needs to be unoccupied.
Insertion moves adjacend items vertically by the size of the inserted item. Only the starting position needs to be unoccupied.
Cutting moves adjacend items horizontally by the size of the cutted item, reversing a previous
Cutting moves adjacend items vertically by the size of the cutted item, reversing a previous
For the provided notification facility of changes to the underlying wave object (the swapfile file), the following procedures need to be called, whenever a change is made bypassing the gpsm subsystem. They all take a swapfile filename instead of a gpsm object.
Via these procedures you signal a change within the specified region of the swapfile with the specified name. Either just data modification or insertion or deletion of the region. Via
gpsm-invalidate-swapfileyou tell the gpsm subsystem to drop all its knowledge of the data of the swapfile, including its current size.
The gpsm subsystem transparently provides undo and redo operations for swapfiles via the following procedures:
Prepares the subtree specified by the provided item for later undo, i.e. restoring of the current state.
Forgets the most recent stored state of the subtree specified by the provided item.
#tif there is a previous state available that can be restored now for the subtree specified by the provided item.
gpsm-op-undorestores this state and remembers the current one for later redo.
gpsm-op-undo-and-forgetdoes not remember the current state for later redo.
#tif there is a previous state available created by an
gpsm-op-undooperation for the subtree specified by the provided item.
gpsm-op-redorestores this state and remembers the current one for later undo.
gpsm-op-redo-and-forgetdoes not remember the current state for later undo.
FIXME. See various files in
For the convenience procedures online help is (maybe) available
(help command) or
net-add-nodeadds a single node with optional parameters to the network specified by filter.
net-add-nodesadds a set of nodes with optional parameters to the network.
net-add-nodeevaluates to a
net-add-nodesto a list of
nodes-deleteyou can delete nodes from a network.
nodes-connectlinearily connects the specified lists of
node-set-paramsyou can set the parameters of the specified filter.
net-runstarts processing of the network and waits until completion.
net-run-bgstarts processing of the network and returns immediately.
The following procedures can be customised by setting
write-file to other
filters than their default ones like
(set! read-file "read-mp3").
Plays or saves the specified file after applying the specified chain of effects with parameters.
Available GLAME plugins are listed here with a short description about what
they are able to do, their input and output ports, and the parameters
they understand. Some ports allow more than one so-called pipe to be
connected. Those restrictions will be listed in the port description.
Some parameters can be set per plugin, some per pipe. Pipe parameters are
listed with the name of the pipe preceeding the parameter name, separated
by a double colon, like
out::position for parameter
out. Each parameter is followed by its type–e.g. integer,
float, or string–in parentheses.
GLAME has several ways of importing and exporting audio data: via the sound card, an external file, or an external program. Furthermore, GLAME has its own so-called swapfile that is used as a large internal cache for audio data.
The audio-in and audio-out plugins handle communication between GLAME and the sound hardware. audio-in is for recording, audio-out does the playback. Actually, there are several instances of those plugins for different sound systems like ESD, ALSA, OSS, and native SGI. If available on the system, they can be accessed directly via oss-audio-out, esd-audio-in and the like, using the same sets of parameters. Think of audio-in and audio-out as sane default methods dependent on the system's capabilities. Those defaults can be configured via the GUIs preferences dialog, too.
deviceis not set, the sound system's default device is used.
audio-out has no further specific parameters.
Transactions from and to files are handled by the plugins read-file and write-file. read-file is guaranteed to be able to read WAV files. Anything else is up to helper libraries that may or may not be installed on a system. write-file so far only second guesses the desired output format from the suffix of the given filename.
filenameparameter has no default and is required to be set.
AF_FILE_*constant. People who have libxml installed will see a option menu for the available types. If nothing is given, the type will be deduced from the filename extension.
AF_SAMPFMT_*. Default is signed.
AF_COMPRESSION_*. Default is no compression.
The two plugins swapfile-in and swapfile-out are for streaming a swapfile into the network and storing a stream into the swapfile respectively. Both refer to tracks via swapfile filenames which are integer numbers.
This hackish filter allows to stream data coming from an external
program that communicates through unix pipes. Note that at the
pipe-out seem to work
reliably, but fail inside libc.
GLAME_DEFAULT_SAMPLERATEwhich is usually 44100 Hz.
GLAME comes with a number of plugins to generate waveforms within a
filter network. They can be useful as a debugging aid, but also as
control input to other plugins. Imagine a sine wave generator hooked up
to the position port of a panning filter... So far there is a
sine plugin for generating sine waves, a
yielding a block of constant data, a
rect plugin creating a
stream of steep pulses, a
saw plugin for generating saw waves and
ramp plugin for generating saw waves.
pulse generates a
single pulse, steepness of the edges can be adjusted.
generates white noise.
wave emits a user editable chunk of
wave. All plugins emit but a short chunk of data. For a continuous
stream they have to be connected to a
const has no further specific ports.
sine has no further specific ports.
rect has no further specific ports.
saw has no further specific ports.
pluse has no further specific ports.
ramp has no further specific ports.
noise has no further specific ports.
wave has no further specific ports.
wave (sample array)
In a filter network, data streams don't get created from nowhere, neither do they disappear into a big black void: there must be a plugin at each endpoint of a connection. These Plugins in turn are allowed to dump data or create new streams.
The drop plugin is used as a sink for data that is no longer needed within the network. Any incoming data is simply discarded. It's the dead end of a network.
If the same stream of data is needed more than once, it cannot simply be applied several times to different ports, it has to be duplicated first. one2n is the plugin to perform this task, it forks the network, so to speak.
mix on the other hand acts as a junction and merges several data streams into one, just like an ordinary mixing desk. mix drops all input data after all non-feedback input streams have terminated.
For some networks you may need intermediate buffering of data to prevent deadlocks. The buffer filter is the one you should consider using.
drop has no parameters.
one2n has no parameters.
All the plugins described in this section operate on a single input stream and transform it into a slightly mangled single output stream. volume-adjust scales the amplitude of a data stream. delay and extend prepend and append zero samples to a data stream respectively. repeat resends an input sequence over and over for a fixed time or for ever. invert inverts all data of the input stream, i.e. each sample A is replaced by -A. stretch allows to lengthen or shorten a track in time, while trying to preserve its pitch. Obviously, stretch is no realtime effect.
invert has no parameters.
The pan plugin distributes a mono sample stream to two stereo (left/right) output streams.
panparameter is set. Allowed values range from -pi/2 to pi/2. As the position property ranges from -pi to pi, values with magnitude larger than pi/2 (i.e. positions in the 'back') are mirrored to the front.
The render plugin renders any number of input streams with respect to their position inside the stereo field to any number of output streams with respect of their positions given by the pipe source position parameter of the connections. You can render your multi-track song to a stereo setup for example.
The plugins mul and add perform a simple arithmetic operations on several input streams. Basically, mul multiplies and add sums up any number of input sample streams. Operations are performed sample by sample–no check is performed whether sample rates match! If a stream is shorter than others, it is zero- (add) or one-padded (mul) internally.
Each plugin allows one multiplicative and one additive constant to be set. They are interpreted differently for each plugin however, reflecting the different algorithms:
mul calculates each output sample by taking one sample from each
input pipe, adding
add to it, multiplying the results, and
finally multiplying the result by
add calculates each output sample by taking one sample from each
input pipe, summing them all up, adding the
add parameter, and
multiplying the result by
There are neither further specific ports, nor further specific parameters.
The ssp_streamer plugin offers a gateway between sample and rms data. Streamed rms data can be used later for analyzing via the maxrms plugin. Unfortunately, RMS work within GLAME is still in its early stages, so its not that useful at the moment.
Ping is a tool familiar to admins to test integrity and latency of a network connection. The ping plugin does the same within a GLAME filter network. It sends out a data packet from its output port and measures the time until the packet arrives at its input port. Obviously, the filter network should have a loop structure or ping will wait endlessly for an input. Debugging output goes to the console.
The null and dup plugins aren't really meant to be used, they are simple reference implementations for developers looking for a quick introduction to plugin programming. null passes an input stream unmodified to its output, dup duplicates an input stream to two output streams. In real life, the more complex one2n plugin can be used to achieve the same results. So use the source, not these plugins.
Guess what! The echo plugin adds an echo to an input stream.
A noisegate is used to suppress signals below a certain threshold from an
input stream. Its operation can be tuned by a number of parameters.
When the input signal (its absolute value actually) falls below
threshold_on for more than hold time, noisegate
suppresses output until the signal goes back up and above threshold_off.
Switching from and to zero output is usually not done instantaneously as this
would lead to distorted sound. Instead, a fading time can be given by
threshold_onis equal or less than
In the Spectrum category you'll find a collection of filters that alter the spectral composition of a sound. Currently included are a bandpass filter composed of chained Chebyshev lowpass/highpass stages, a one stage bandpass filter and a Chebyshev lowpass/highpass filter.
rippledefines the percentage of ripple in the pass band. It defaults to 0.5, and it is best to leave it alone unless you know what you're doing.
rippledefines the percentage of ripple in the pass band. It defaults to 0.5, and it is best to leave it alone unless you know what you're doing.
rippledefines the percentage of ripple in the pass band. It defaults to 0.5, and it is best to leave it alone unless you know what you're doing.
The flanger effect is essentially a variable delay, that operates on a comb filtered signal. The variation of the delay is given by a low frequency oscillation (LFO). Dependent on the type of LFO you get different effects. The flanger is especially useful for guitar and voice sounds. With the right settings this implementation of the flanger can be used as a detune effect using a ramp up/down LFO and setting dry gain to zero.
effect depth (float)
detune range (float)
LFO Speed (float)
Dry/Wet Balance (float)
feedback gain (float)
LFO type (int)
The distortion effect simulates a MOSFET preamplifier with adjustable clipping. With a mode parameter one can switch between a halfwave and a fullwave rectifying output stage.
clip, asym (float)
0 enables asymmetrical clipping mode
1 enables fullwave rectifying mode
Glame provides a simple framework of FFT filters to allow for the application of effects in the frequency domain of sample sounds. The core plugins are fft and ifft using the specially designed FFT protocol which supports adjustable FFT blocksizes and oversampling. All FFT processing is done based on the fftw (http://www.fftw.org) library.
The ifft plugin doesn't need any parameters. blocksize and oversampling factor are taken from the pipe properties.
Implements a resampler in the frequency domain.
Implements a bandpass filter in the frequency domain.
band minimum (float)
band maximum (float)
Implements a five band equalizer in the frequency domain. It features a low, midlow, mid, midhigh and high band which are equally distributed over the frequency range. This distribution is not really usable, but it's a proove of concept at the present time..
The normalize function can be invoked from the main menu or from the waveeditor widget. Normalize scans all given tracks for the highest peak in amplitude or the highest RMS peak for a given frequency window. You can normalize the signal in three different modes:
The fade in (and out) operations fade in (or out) the current selection linearly. These operations are only useful if invoked through the context menu of the waveedit window.
filter->string: Scheme Filter API
filter-add-node: Scheme Filter API
filter-connect: Scheme Filter API
filter-delete: Scheme Filter API
filter-launch: Scheme Filter API
filter-name: Scheme Filter API
filter-new: Scheme Filter API
filter-nodes: Scheme Filter API
filter-params: Scheme Filter API
filter-pause: Scheme Filter API
filter-ports: Scheme Filter API
filter-start: Scheme Filter API
filter-terminate: Scheme Filter API
filter-wait: Scheme Filter API
filter?: Scheme Filter API
filternetwork-add-input: Scheme Filter API
filternetwork-add-output: Scheme Filter API
filternetwork-add-param: Scheme Filter API
get-property: Scheme Filter API
glame_create_plugin: Scheme Filter API
glame_plugin_define: Scheme Filter API
gpsm-close: Scheme GPSM API
gpsm-grp-hbox?: Scheme GPSM API
gpsm-grp-items: Scheme GPSM API
gpsm-grp-vbox?: Scheme GPSM API
gpsm-grp?: Scheme GPSM API
gpsm-hbox-can-insert?: Scheme GPSM API
gpsm-hbox-cut: Scheme GPSM API
gpsm-hbox-insert: Scheme GPSM API
gpsm-init: Scheme GPSM API
gpsm-invalidate-swapfile: Scheme GPSM API
gpsm-item-can-place?: Scheme GPSM API
gpsm-item-destroy: Scheme GPSM API
gpsm-item-hposition: Scheme GPSM API
gpsm-item-hsize: Scheme GPSM API
gpsm-item-label: Scheme GPSM API
gpsm-item-parent: Scheme GPSM API
gpsm-item-place: Scheme GPSM API
gpsm-item-remove: Scheme GPSM API
gpsm-item-set-label!: Scheme GPSM API
gpsm-item-vposition: Scheme GPSM API
gpsm-item-vsize: Scheme GPSM API
gpsm-item?: Scheme GPSM API
gpsm-newgrp: Scheme GPSM API
gpsm-newswfile: Scheme GPSM API
gpsm-notify-swapfile-change: Scheme GPSM API
gpsm-notify-swapfile-cut: Scheme GPSM API
gpsm-notify-swapfile-insert: Scheme GPSM API
gpsm-op-can-redo?: Scheme GPSM API
gpsm-op-can-undo?: Scheme GPSM API
gpsm-op-forget: Scheme GPSM API
gpsm-op-prepare: Scheme GPSM API
gpsm-op-redo: Scheme GPSM API
gpsm-op-redo-and-forget: Scheme GPSM API
gpsm-op-undo: Scheme GPSM API
gpsm-op-undo-and-forget: Scheme GPSM API
gpsm-root: Scheme GPSM API
gpsm-swfile-cow: Scheme GPSM API
gpsm-swfile-filename: Scheme GPSM API
gpsm-swfile-link: Scheme GPSM API
gpsm-swfile-position: Scheme GPSM API
gpsm-swfile-samplerate: Scheme GPSM API
gpsm-swfile-set-position!: Scheme GPSM API
gpsm-swfile-set-samplerate!: Scheme GPSM API
gpsm-swfile?: Scheme GPSM API
gpsm-sync: Scheme GPSM API
gpsm-vbox-can-insert?: Scheme GPSM API
gpsm-vbox-cut: Scheme GPSM API
gpsm-vbox-insert: Scheme GPSM API
net-add-node: Network setup
net-add-nodes: Network setup
net-new: Network setup
net-run: Network setup
net-run-bg: Network setup
node-set-params: Network setup
nodes-connect: Network setup
nodes-delete: Network setup
param->string: Scheme Filter API
param-delete: Scheme Filter API
param-label: Scheme Filter API
param-set!: Scheme Filter API
param-value: Scheme Filter API
param?: Scheme Filter API
pipe-delete: Scheme Filter API
pipe-dest-params: Scheme Filter API
pipe-fft?: Scheme Filter API
pipe-position: Scheme Filter API
pipe-sample?: Scheme Filter API
pipe-samplerate: Scheme Filter API
pipe-source-params: Scheme Filter API
pipe-ssp?: Scheme Filter API
pipe?: Scheme Filter API
play: Cooked operations
play-eff: Cooked operations
plugin-add-path: Scheme Plugin API
plugin-get: Scheme Plugin API
plugin-name: Scheme Plugin API
plugin-query: Scheme Plugin API
plugin-set!: Scheme Plugin API
plugin?: Scheme Plugin API
port-delete: Scheme Filter API
port-label: Scheme Filter API
port-params: Scheme Filter API
port-pipes: Scheme Filter API
port?: Scheme Filter API
save-eff: Cooked operations
set-property!: Scheme Filter API
sw-close: Scheme Swapfile API
sw-closedir: Scheme Swapfile API
sw-fstat: Scheme Swapfile API
sw-ftruncate: Scheme Swapfile API
sw-lseek: Scheme Swapfile API
sw-open: Scheme Swapfile API
sw-opendir: Scheme Swapfile API
sw-read-floatvec: Scheme Swapfile API
sw-read-string: Scheme Swapfile API
sw-readdir: Scheme Swapfile API
sw-sendfile: Scheme Swapfile API
sw-unlink: Scheme Swapfile API
sw-write: Scheme Swapfile API
swapfile-close: Scheme Swapfile API
swapfile-creat: Scheme Swapfile API
swapfile-open: Scheme Swapfile API
swdir?: Scheme Swapfile API
swfd?: Scheme Swapfile API
Created: Jan, 21st, 2000 (dk)
Last changed: Mar, 28th, 2005 (richi)