1
This is glame.info, produced by makeinfo version 4.1 from glame.texi.
5
* GLAME: (glame). GNU/Linux Audio Mechanics-A capable audio editor.
9
File: glame.info, Node: Scheme Filter API, Next: Scheme Swapfile API, Up: Wrapped API
14
The basic filter subsystem types, `filter_t', `filter_port_t',
15
`filter_pipe_t' and `filter_param_t' exist as native scheme types and
16
such can be type checked.
18
- Function: ( filter? obj )
19
- Function: ( port? obj )
20
- Function: ( pipe? obj )
21
- Function: ( param? obj )
22
These procedures check `obj' for being of the specified type and
23
evaluate to `#t' if this is the case and `#f' otherwise.
25
Out of a filter object you can get information and subobjects using the
28
- Function: ( filter-name filter )
29
- Function: ( filter-nodes filter )
30
- Function: ( filter-ports filter )
31
- Function: ( filter-params filter )
32
These procedures evaluate to a string containing the filters name
33
or to lists of the specified object type representing the actual
34
subobjects associated with the filter.
36
Out of a port object you can get information and subobjects using the
39
- Function: ( port-label port )
40
- Function: ( port-pipes port )
41
- Function: ( port-params port )
42
These procedures evaluate to a string containing the ports label or
43
to lists of the specified object type representing the actual
44
subobjects associated with the port.
46
Out of a param object you can get and modify information using the
49
- Function: ( param-label param )
50
- Function: ( param-value param )
51
- Function: ( param-set! param value )
52
These procedures evaluate to a string containing the label of the
53
param object, the actual value of the param whose type depends on
54
the param objects type or a boolean denoting the success of a param
57
Out of a pipe object you can get information and subobjects using the
60
- Function: ( pipe-samplerate pipe )
61
- Function: ( pipe-position pipe )
62
- Function: ( pipe-source-params pipe )
63
- Function: ( pipe-dest-params pipe )
64
These procedures evaluate to an exact number containing the
65
samplerate of the data flowing through the pipe, a number
66
containing the position of the audio stream or to lists of the
67
specified object type representing the actual subobjects
68
associated with the pipe.
70
Pipe objects can be queried for the actual protocol type using the
73
- Function: ( pipe-sample? pipe )
74
- Function: ( pipe-fft? pipe )
75
- Function: ( pipe-ssp? pipe )
76
These procedures check `pipe' for being of the specified protocol
77
type and evaluate to `#t' if this is the case and `#f' otherwise.
79
Usually you can attach key/value pairs to a per object database. Those
80
object properties can be queried and modified using the following
83
- Function: ( set-property! obj key value )
84
- Function: ( get-property obj key )
85
These procedures evaluate to `#unspecified' or a string object
86
containing the value associated with the specified key or `#f' if
87
this key has no associated value. Note that for both `key' and
88
`value' only string objects are allowed. Predefined key values
89
are `FILTERPARAM_DESCRIPTION', `FILTERPARAM_GLADEXML' and
90
`FILTERPORT_DESCRIPTION'.
92
The following procedures handle object serialization and creation and
93
destruction of objects.
95
- Function: ( filter-new [filter|plugin] )
96
- Function: ( filter-delete filter )
97
- Function: ( port-delete port )
98
- Function: ( param-delete param )
99
- Function: ( pipe-delete pipe )
100
`filter-new' constructs a new filter object by either cloning from
101
a filter or a plugin object or creating an empty network from
102
scratch. The delete procedures destruct the specified objects.
104
- Function: ( filter->string filter )
105
- Function: ( param->string param )
106
While the first procedure returns a string containing a scheme
107
expression being able to recreate the filter object, the second
108
procedure just evaluates to a string containing the value of the
111
- Function: ( filter-add-node filter filter node-name )
112
- Function: ( filter-connect filter port-name filter port-name )
113
`filter-add-node' adds the specified filter (second parameter) to
114
the specified network (first parameter) using the identifier
115
specified as third parameter. `filter-connect' connects the two
116
specified parameters via the specified ports identified by their
117
port names. `filter-connect' evaluates to a pipe object.
119
- Function: ( filternetwork-add-input filter filter port-name name
121
- Function: ( filternetwork-add-output filter filter port-name name
123
- Function: ( filternetwork-add-param filter filter param-name name
125
Procedures to be used for exporting ports and params to the
126
outside world in a macro filter. The first parameter is the actual
127
network, the second parameter is the node that gets exported from.
128
These procedures evaluate to a port or a param object.
130
- Function: ( glame_create_plugin filter name )
131
- Function: ( glame_plugin_define filter name )
132
`glame_create_plugin' creates and registers a new plugin using the
133
specified name and associate it with the provided filter.
134
Evaluates to a plugin or to `#f' on error. `glame_plugin_define'
135
is used internally for transparently registering or filter loading.
137
- Function: ( filter-launch filter )
138
- Function: ( filter-start filter )
139
- Function: ( filter-pause filter )
140
- Function: ( filter-wait filter )
141
- Function: ( filter-terminate filter )
142
These procedures handle filter network execution.
145
File: glame.info, Node: Scheme Swapfile API, Next: Scheme Plugin API, Prev: Scheme Filter API, Up: Wrapped API
150
The swapfile is a container for data in its raw form. It is modeled
151
after a simple filesystem with a flat namespace (no directories) and
152
names being just cardinal numbers.
154
- Function: ( swapfile-open path )
155
- Function: ( swapfile-close )
156
- Function: ( swapfile-creat path )
157
These procedures control the swapfile subsystem. `swapfile-open'
158
initializes the subsystem from the swapfile at the specified
159
location. `swapfile-creat' tries to create a new swapfile at the
160
specified location, `swapfile-close' cleans up and closes the
163
- Function: ( swdir? dir )
164
- Function: ( sw-opendir )
165
- Function: ( sw-readdir dir )
166
- Function: ( sw-closedir dir )
167
These procedures can be used to traverse the swapfile files.
168
Function is like the libc readdir routines, but as the swapfile
169
has a flat namespace you dont specify a subdirectory for
170
`sw-opendir'. `sw-opendir' evaluates to a `swdir' object.
171
`sw-readdir' returns swapfile filenames as long as they are
172
available and `#f' upon directory end.
174
- Function: ( sw-unlink name )
175
Unlinks the specified file from the swapfile. You cannot recover
176
unlinked swapfiles. Behavior is like unlink(2), i.e. if the file
177
is still open the deletion of the data is postponed until close of
180
- Function: ( swfd? fd )
181
- Function: ( sw-open name flags )
182
- Function: ( sw-close fd )
183
For working with a swapfile you need to obtain a handle to it.
184
Use `sw-open' to open the swapfile with the specified name. The
185
flags argument is modeled after open(2), `O_CREAT', `O_EXCL',
186
`O_TRUNC', `O_RDWR', `O_RDONLY' and `O_WRONLY' are available. Or
187
them together like `(+ O_CREAT O_TRUNC O_RDWR)'. `sw-open'
188
evaluates to a file descriptor which you can identify using the
189
`swfd?' predicate. Use `sw-close' if you are finished with the
192
- Function: ( sw-fstat fd )
193
`sw-fstat' obtains information about an open filedescriptor. It
194
evaluates to a list of the form `( name size mode offset
195
cluster-start cluster-end cluster-size )' where all entries are
198
- Function: ( sw-lseek fd offset whence )
199
To seek inside a file use `sw-lseek' which works like lseek(2),
200
i.e. it seeks relative to whence offset bytes. For whence
201
`SEEK_CUR', `SEEK_SET' and `SEEK_END' are available. `sw-lseek'
202
evaluates to the current file pointer position.
204
- Function: ( sw-ftruncate fd size )
205
`sw-ftruncate' truncates the specified file to the specified size
206
appending zeroes in case of enlarging.
208
- Function: ( sw-sendfile dest-fd source-fd size [flags] )
209
`sw-sendfile' copies (by using copy on write) size bytes from the
210
current filepointer position of the source-fd to the current
211
filepointer position of the dest-fd. Via the optional flags
212
argument you can specify the following
214
The data is inserted at the filepointer position of the
215
dest-fd instead of overwriting and/or extending the file.
218
The data is removed from the source-fd after writing to the
219
dest-fd For both files you can specify `SW_NOFILE' if it
220
makes sense (i.e. for just cutting out data specify `SW_NOFILE' as
221
dest-fd and `SWSENDFILE_CUT' as flag).
223
- Function: ( sw-read-floatvec fd size )
224
- Function: ( sw-read-string fd size )
225
- Function: ( sw-write fd data )
226
Those are the basic read and write operations. Both strings and
227
float vectors are supported by the scheme interface. For reading
228
you need to specify the type via the procedure name, for writing
229
the type is automatically determined. The read procedures read
230
size number of objects from the current filepointer position.
231
They evaluate to the number of objects read. `sw-write' writes the
232
whole object to the current filepointer position and evaluates to
233
the number of objects written. All procedures increment the
234
filepointer position by the number of bytes read/written.
237
File: glame.info, Node: Scheme Plugin API, Next: Scheme GPSM API, Prev: Scheme Swapfile API, Up: Wrapped API
242
The glame plugin midlayer API is wrapped with the following procedures:
244
- Function: ( plugin? plugin )
245
This procedure checks, if the specified object represents a plugin
246
and evaluates to `#t' in this case, else `#f'.
248
- Function: ( plugin-add-path path )
249
This procedure adds the specified path to the plugin shared object
250
search path that is used by the `plugin-get' procedure.
252
- Function: ( plugin-get name )
253
Queries a plugin with the specified name out of the plugin
254
database. Evaluates to a plugin or `#f' if a plugin with the
255
specified name cannot be found.
257
- Function: ( plugin-name plugin )
258
- Function: ( plugin-query plugin key )
259
- Function: ( plugin-set! plugin key value )
260
Queries the name or custom properties out of a plugin. Those
261
procedures evaluate to a string, `plugin-set!' sets the specified
262
property to the specified string. Predefined property keys are
263
`PLUGIN_DESCRIPTION', `PLUGIN_PIXMAP', `PLUGIN_CATEGORY',
264
`PLUGIN_GUI_HELP_PATH' and `PLUGIN_LABEL'.
267
File: glame.info, Node: Scheme GPSM API, Next: Scheme GUI interaction, Prev: Scheme Plugin API, Up: Wrapped API
272
The glame gpsm midlayer API is used to represent metadata associated
273
with wave data, i.e. samplerate and positional information. The gpsm
274
API also wraps swapfile modification of wave data.
276
For global control and initialization the following procedures are
279
- Function: ( gpsm-init path )
280
- Function: ( gpsm-sync )
281
- Function: ( gpsm-close )
282
These procedures handle initialization and cleanup of the gpsm and
283
the swapfile subsystem. As path you need to specify the path to
284
the to be used swapfile. `gpsm-sync' syncs all gpsm metadata to
287
The gpsm subsystem builds on a tree of gpsm items which are derived
288
from a generic item type. Available item types are the gpsm group which
289
just contains a list of children, and the gpsm swapfile which
290
represents a wave with its metadata and swapfile representation.
292
- Function: ( gpsm-item? item )
293
- Function: ( gpsm-grp? item )
294
- Function: ( gpsm-swfile? item )
295
These predicates check if the provided object is an gpsm item, or
296
one of the derived types, a gpsm group or a gpsm swapfile.
298
- Function: ( gpsm-item-parent item )
299
- Function: ( gpsm-item-label item )
300
- Function: ( gpsm-item-hposition item )
301
- Function: ( gpsm-item-vposition item )
302
- Function: ( gpsm-item-hsize item )
303
- Function: ( gpsm-item-vsize item )
304
These procedures give access to the basic gpsm type, the gpsm item.
305
They evaluate to the items parent item, to its label or its
306
position and extension.
308
- Function: ( gpsm-grp-items item )
309
`gpsm-grp-items' evaluates to the list of childs of the group.
311
- Function: ( gpsm-swfile-filename item )
312
- Function: ( gpsm-swfile-samplerate item )
313
- Function: ( gpsm-swfile-position item )
314
These procedures give access to the gpsm swapfile type. They
315
evaluate to the wave swapfile metadata, respective the swapfile
316
filename, its samplerate and position in the stereo field.
318
- Function: ( gpsm-item-set-label! item label )
319
- Function: ( gpsm-swfile-set-samplerate! item rate )
320
- Function: ( gpsm-swfile-set-position! item position )
321
These procedues modify one of the gpsm type properties.
323
For creating, copying, linking and destroying of items the following
324
procedures are available:
326
- Function: ( gpsm-newswfile label )
327
- Function: ( gpsm-swfile-cow swfile )
328
- Function: ( gpsm-swfile-link swfile )
330
- Function: ( gpsm-newgrp label )
332
- Function: ( gpsm-item-destroy item )
334
For structuring, modifying and traversing of the gpsm tree the
335
following procedures are available:
337
- Function: ( gpsm-root )
338
Evaluates to the gpsm tree root item.
340
- Function: ( gpsm-grp-hbox? grp )
341
- Function: ( gpsm-grp-vbox? grp )
342
Predicates that check, if the specified group is a hbox (a set of
343
horizontally sorted, non-overlapping items), or a vbox (a set of
344
vertically sorted, non-overlapping items).
346
- Function: ( gpsm-item-can-place? grp item hposition vposition )
347
- Function: ( gpsm-item-place grp item hposition vposition )
348
Placing happens without moving unaffected items. Placing needs to
349
happen at a position where the needed space is already available.
351
- Function: ( gpsm-item-remove item )
352
Removing happens without moving unaffected items and reverses a
353
previous `gpsm-item-place' operation.
355
- Function: ( gpsm-hbox-can-insert? grp item hposition vposition )
356
- Function: ( gpsm-hbox-insert grp item hposition vposition )
357
Insertion moves adjacend items horizontally by the size of the
358
inserted item. Only the starting position needs to be unoccupied.
360
- Function: ( gpsm-vbox-can-insert? grp item hposition vposition )
361
- Function: ( gpsm-vbox-insert grp item hposition vposition )
362
Insertion moves adjacend items vertically by the size of the
363
inserted item. Only the starting position needs to be unoccupied.
365
- Function: ( gpsm-hbox-cut item )
366
Cutting moves adjacend items horizontally by the size of the cutted
367
item, reversing a previous `gpsm-hbox-insert' operation.
369
- Function: ( gpsm-vbox-cut item )
370
Cutting moves adjacend items vertically by the size of the cutted
371
item, reversing a previous `gpsm-vbox-insert' operation.
373
For the provided notification facility of changes to the underlying
374
wave object (the swapfile file), the following procedures need to be
375
called, whenever a change is made bypassing the gpsm subsystem. They
376
all take a swapfile filename instead of a gpsm object.
378
- Function: ( gpsm-notify-swapfile-change name position size )
379
- Function: ( gpsm-notify-swapfile-cut name position size )
380
- Function: ( gpsm-notify-swapfile-insert name position size )
381
- Function: ( gpsm-invalidate-swapfile name )
382
Via these procedures you signal a change within the specified
383
region of the swapfile with the specified name. Either just data
384
modification or insertion or deletion of the region. Via
385
`gpsm-invalidate-swapfile' you tell the gpsm subsystem to drop all
386
its knowledge of the data of the swapfile, including its current
389
The gpsm subsystem transparently provides undo and redo operations for
390
swapfiles via the following procedures:
392
- Function: ( gpsm-op-prepare item )
393
Prepares the subtree specified by the provided item for later undo,
394
i.e. restoring of the current state.
396
- Function: ( gpsm-op-forget item )
397
Forgets the most recent stored state of the subtree specified by
400
- Function: ( gpsm-op-can-undo? item )
401
- Function: ( gpsm-op-undo item )
402
- Function: ( gpsm-op-undo-and-forget item )
403
`gpsm-op-can-undo?' evaluates to `#t' if there is a previous state
404
available that can be restored now for the subtree specified by
405
the provided item. `gpsm-op-undo' restores this state and remembers
406
the current one for later redo. `gpsm-op-undo-and-forget' does not
407
remember the current state for later redo.
409
- Function: ( gpsm-op-can-redo? item )
410
- Function: ( gpsm-op-redo item )
411
- Function: ( gpsm-op-redo-and-forget item )
412
`gpsm-op-can-redo?' evaluates to `#t' if there is a previous state
413
available created by an `gpsm-op-undo' operation for the subtree
414
specified by the provided item. `gpsm-op-redo' restores this state
415
and remembers the current one for later undo.
416
`gpsm-op-redo-and-forget' does not remember the current state for
420
File: glame.info, Node: Scheme GUI interaction, Prev: Scheme GPSM API, Up: Wrapped API
422
Scheme GUI interaction
423
----------------------
425
FIXME. See various files in `src/gui'.
428
File: glame.info, Node: cglame Convenience, Prev: Wrapped API, Up: Console Frontend
433
For the convenience procedures online help is (maybe) available via
434
`(help command)' or `(help)'.
439
* Cooked operations::
442
File: glame.info, Node: Network setup, Next: Cooked operations, Up: cglame Convenience
447
- Function: ( net-new )
448
Creates a new filternetwork. `net-new' evaluates to a filter.
450
- Function: ( net-add-node filter node '("label" value) ... )
451
- Function: ( net-add-nodes filter node '(node '("label" value) ...)
453
- Function: ( nodes-delete filter ... )
454
`net-add-node' adds a single node with optional parameters to the
455
network specified by FILTER. `net-add-nodes' adds a set of nodes
456
with optional parameters to the network. `net-add-node' evaluates
457
to a `filter', `net-add-nodes' to a list of `filter's. Using
458
`nodes-delete' you can delete nodes from a network.
460
- Function: ( nodes-connect nodes ... )
461
`nodes-connect' linearily connects the specified lists of
464
- Function: ( node-set-params filter '("label" value) ... )
465
Using `node-set-params' you can set the parameters of the
468
- Function: ( net-run filter )
469
- Function: ( net-run-bg filter )
470
`net-run' starts processing of the network and waits until
471
completion. `net-run-bg' starts processing of the network and
475
File: glame.info, Node: Cooked operations, Prev: Network setup, Up: cglame Convenience
480
The following procedures can be customised by setting `audio-out',
481
`read-file' or `write-file' to other filters than their default ones
482
like `(set! read-file "read-mp3")'.
484
- Function: ( play filename )
485
Plays the specified file.
487
- Function: ( play-eff filename '(effect ("label" value) ...) ... )
488
- Function: ( save-eff infile outfile '(effect ("label" value) ...)
490
Plays or saves the specified file after applying the specified
491
chain of effects with parameters.
494
File: glame.info, Node: Plugin Collection, Next: Function and Type Index, Prev: Console Frontend, Up: Top
499
Available GLAME plugins are listed here with a short description about
500
what they are able to do, their input and output ports, and the
501
parameters they understand. Some ports allow more than one so-called
502
pipe to be connected. Those restrictions will be listed in the port
503
description. Some parameters can be set per plugin, some per pipe.
504
Pipe parameters are listed with the name of the pipe preceeding the
505
parameter name, separated by a double colon, like `out::position' for
506
parameter `position' on pipe `out'. Each parameter is followed by its
507
type-e.g. integer, float, or string-in parentheses.
512
* Elementary Plugins::
518
File: glame.info, Node: In- and Output, Next: Elementary Plugins, Up: Plugin Collection
523
GLAME has several ways of importing and exporting audio data: via the
524
sound card, an external file, or an external program. Furthermore, GLAME
525
has its own so-called swapfile that is used as a large internal cache
533
* Abusing External Apps::
536
File: glame.info, Node: Audio I/O, Next: File I/O, Up: In- and Output
541
The `audio-in' and `audio-out' plugins handle communication between
542
GLAME and the sound hardware. `audio-in' is for recording, `audio-out'
543
does the playback. Actually, there are several instances of those
544
plugins for different sound systems like ESD, ALSA, OSS, and native
545
SGI. If available on the system, they can be accessed directly via
546
`oss-audio-out', `esd-audio-in' and the like, using the same sets of
547
parameters. Think of `audio-in' and `audio-out' as sane default methods
548
dependent on the system's capabilities. Those defaults can be
549
configured via the GUIs preferences dialog, too.
555
Sound device to be used. Note: While audio-in and audio-out are
556
generic plugins, interpretation of the device parameter is
557
dependent on the underlying sound system which the value is passed
558
to unmodified. For example, OSS takes devices parameters like
559
`/dev/dsp' where ALSA would like `0:0'. If `device' is not set,
560
the sound system's default device is used.
566
Recorded stream of sample data. Maximum number of allowed
567
out-connections depends on hardware capabilities.
569
`audio-in' parameters
570
.....................
573
The sample rate in Hertz.
576
Recording time in seconds. Defaults to no limit.
578
`out::position (float)'
579
Horizontal placement of sample stream in radians from -pi to pi.
585
Sample stream to play back. Maximum number of allowed
586
in-connections depends on hardware capabilities.
588
`audio-out' has no further specific parameters.
591
File: glame.info, Node: File I/O, Next: Swapfile I/O, Prev: Audio I/O, Up: In- and Output
596
Transactions from and to files are handled by the plugins `read-file'
597
and `write-file'. `read-file' is guaranteed to be able to read WAV
598
files. Anything else is up to helper libraries that may or may not be
599
installed on a system. `write-file' so far only second guesses the
600
desired output format from the suffix of the given filename.
606
Name of the file to be read from or written to. The writer takes
607
the filename suffix as a hint to the desired type of output. The
608
`filename' parameter has no default and is required to be set.
614
Sample data read in from a sound file. The number of allowed
615
out-connections varies from file to file.
617
`read-file' parameters
618
......................
620
`out::position (float)'
621
Horizontal placement of sample stream in radians from -pi to pi.
627
Sample stream to store to a sound file. Maximum number of allowed
628
in-connections depends on the desired sound format.
630
`write-file' parameters
631
.......................
634
Type of the file to write. This is a libaudiofile `AF_FILE_*'
635
constant. People who have libxml installed will see a option menu
636
for the available types. If nothing is given, the type will be
637
deduced from the filename extension.
640
Sampleformat of the file, as defined by libaudiofiles
641
`AF_SAMPFMT_*'. Default is signed.
644
Sample width in bits. 16 is default.
647
Compression type, as defined by libaudiofiles `AF_COMPRESSION_*'.
648
Default is no compression.
651
File: glame.info, Node: Swapfile I/O, Next: Abusing External Apps, Prev: File I/O, Up: In- and Output
656
The two plugins `swapfile-in' and `swapfile-out' are for streaming a
657
swapfile into the network and storing a stream into the swapfile
658
respectively. Both refer to tracks via swapfile filenames which are
665
Swapfile filename. This parameter is required to be set and there
669
This parameter denotes the offset inside the file to start
670
reading/writing from. The default is 0 which denotes the start of
671
the file. Setting offset to a negative value will throw away
672
samples for swapfile_out and feed in zeroes for swapfile_in.
675
This parameter denotes the number of samples to read/write. The
676
default is -1 which means to read the whole file / write all data.
677
For sizes that in conjunction with offset exceed the file size,
678
zeroes will be streamed in for swapfile_in, for swapfile_out the
679
file will be extended.
685
Sample stream coming out of the swapfile.
687
`swapfile-in' parameters
688
........................
691
The samplerate the data has.
694
The position of the data in the stereo field.
697
Flags are 1 to endless stream data by looping the file.
703
Sample stream to be stored in the swapfile.
705
`swapfile-out' parameters
706
.........................
709
Flags are 1 to create the file, if it does not exist, 2 to truncate
710
it before writing, 3 for both.
713
File: glame.info, Node: Abusing External Apps, Prev: Swapfile I/O, Up: In- and Output
715
Abusing External Apps
716
---------------------
718
This hackish filter allows to stream data coming from an external
719
program that communicates through unix pipes. Note that at the moment
720
neither `pipe-in' nor `pipe-out' seem to work reliably, but fail inside
727
Command string of the program which should be launched. This
728
parameter is required to be set and there is no default value.
731
Extra tail to be appended to the command string, usually a
732
filename. It defaults to an empty string.
738
Streams created out of the (possible interleaved) data coming from
739
the external program. You have to ensure to connect two pipes if
740
the external program generates stereo output. Dataformat is signed
741
16 bit in native endianness only.
747
Sample rate of the data coming from the external program. Defaults
748
to the compile-time setting of `GLAME_DEFAULT_SAMPLERATE' which is
755
Streams created out of the (possible interleaved) data coming from
756
the external program. You have to ensure to connect two pipes if
757
the external program generates stereo output. Dataformat is signed
758
16 bit in native endianness only.
761
File: glame.info, Node: Elementary Plugins, Next: Effects, Prev: In- and Output, Up: Plugin Collection
768
* Generating Waves:: Sound out of Nowhere
769
* Junctions and Dead Ends:: Splitting, mixing, merging and buffering
770
* Mangling Data Streams:: Shifting and rescaling
771
* Orientation:: Panning and rendering
772
* Arithmetics:: Adding and multiplying streams
773
* The Sample Analyst:: Sample statistics
774
* Catching Bugs:: Sending network pings
775
* How to Code:: Useless plugins
778
File: glame.info, Node: Generating Waves, Next: Junctions and Dead Ends, Up: Elementary Plugins
783
GLAME comes with a number of plugins to generate waveforms within a
784
filter network. They can be useful as a debugging aid, but also as
785
control input to other plugins. Imagine a sine wave generator hooked up
786
to the position port of a panning filter... So far there is a `sine'
787
plugin for generating sine waves, a `const' plugin yielding a block of
788
constant data, a `rect' plugin creating a stream of steep pulses, a
789
`saw' plugin for generating saw waves and a `ramp' plugin for
790
generating saw waves. `pulse' generates a single pulse, steepness of
791
the edges can be adjusted. `noise' generates white noise. `wave' emits
792
a user editable chunk of wave. All plugins emit but a short chunk of
793
data. For a continuous stream they have to be connected to a `repeat'
800
Generated data stream. Only one connection is allowed.
806
Horizontal placement of sample stream in radians from -pi to pi.
809
Samplerate of generated data stream. Defaults to compile-time
810
setting of GLAME_DEFAULT_SAMPLERATE, usually 44100 Hz.
815
`const' has no further specific ports.
821
Constant signal value. Defaults to 0.
826
`sine' has no further specific ports.
832
Amplitude of generated sine wave. Allowed value range is from 0 to
836
Frequency of generated sine wave in Hz. Defaults to 441 Hz.
841
`rect' has no further specific ports.
847
Amplitude of generated rectangular wave. Allowed value range is
848
from 0 to 1. Defaults to 1.0.
851
Frequency of generated rectangular wave in Hz. Defaults to 440 Hz.
856
`saw' has no further specific ports.
862
Amplitude of generated saw wave. Allowed value range is from 0 to
866
Frequency of generated saw wave in Hz. Defaults to 440 Hz.
871
`pluse' has no further specific ports.
877
Time to start switching from neutral to on state. Ignored if zero.
880
Time to start switching from on to neutral state. Ignored if zero.
883
Length of complete output in milliseconds.
886
Time in milliseconds to switch from neutral to on state.
889
Time in milliseconds to switch from on to neutral state.
894
`ramp' has no further specific ports.
900
Amplitude of generated ramp wave. Allowed value range is from 0 to
904
Frequency of generated ramp wave in Hz. Defaults to 440 Hz.
909
`noise' has no further specific ports.
915
Amplitude of generated noise. Allowed value range is from 0 to 1.
921
`wave' has no further specific ports.
926
`wave (sample array)'
927
The to be generated wave.
930
File: glame.info, Node: Junctions and Dead Ends, Next: Mangling Data Streams, Prev: Generating Waves, Up: Elementary Plugins
932
Junctions and Dead Ends
933
-----------------------
935
In a filter network, data streams don't get created from nowhere,
936
neither do they disappear into a big black void: there must be a plugin
937
at each endpoint of a connection. These Plugins in turn are allowed to
938
dump data or create new streams.
940
The `drop' plugin is used as a sink for data that is no longer needed
941
within the network. Any incoming data is simply discarded. It's the dead
944
If the same stream of data is needed more than once, it cannot simply be
945
applied several times to different ports, it has to be duplicated first.
946
`one2n' is the plugin to perform this task, it forks the network, so to
949
`mix' on the other hand acts as a junction and merges several data
950
streams into one, just like an ordinary mixing desk. `mix' drops all
951
input data after all non-feedback input streams have terminated.
953
For some networks you may need intermediate buffering of data to prevent
954
deadlocks. The `buffer' filter is the one you should consider using.
960
Data to be dropped. Any number of input connections is allowed.
962
`drop' has no parameters.
968
Stream to be replicated.
971
Replicated stream. Any number of output connections is allowed.
973
`one2n' has no parameters.
979
Audio streams to be mixed. Any number of input connections is
989
Gain of the input. Defaults to 1.
992
Start mixing in input stream after relative time offset (in
993
seconds). Defaults to 0.
996
Gain of the output stream. Defaults to 1.
999
Horizontal placement of sample stream in radians from -pi to pi.
1005
Data stream to be buffered. Exactly one connection is allowed.
1008
Buffered data stream. Exactly one connection is allowed.
1014
Size in bytes of the buffer.
1017
Size in seconds of the buffer. Can be used only for SAMPLE streams.
1020
File: glame.info, Node: Mangling Data Streams, Next: Orientation, Prev: Junctions and Dead Ends, Up: Elementary Plugins
1022
Mangling Data Streams
1023
---------------------
1025
All the plugins described in this section operate on a single input
1026
stream and transform it into a slightly mangled single output stream.
1027
`volume-adjust' scales the amplitude of a data stream. `delay' and
1028
`extend' prepend and append zero samples to a data stream respectively.
1029
`repeat' resends an input sequence over and over for a fixed time or
1030
for ever. `invert' inverts all data of the input stream, i.e. each
1031
sample A is replaced by -A.
1037
Stream of input sample data.
1040
Stream of transformed output sample data.
1045
`invert' has no parameters.
1047
`volume-adjust' parameters
1048
..........................
1051
Value to scale input stream's amplitude with.
1057
Input data stream is prepended with zero samples for delay
1058
milliseconds. Defaults to 0ms.
1064
Zero samples are appended to input stream for delay milliseconds.
1071
The input pattern is repeated until a total time of duration
1072
seconds is reached. Defaults to 0s which is endless repetition.
1075
File: glame.info, Node: Orientation, Next: Arithmetics, Prev: Mangling Data Streams, Up: Elementary Plugins
1080
The `pan' plugin distributes a mono sample stream to two stereo
1081
(left/right) output streams.
1087
Mono stream to pan. Only a single connection allowed.
1091
`right-out (output)'
1092
Left/right stereo output stream. Only one connection per port is
1099
Pan value (virtual direction) of mono input stream. By default,
1100
`pan' uses the input pipe's position property as pan value. It is
1101
overridden if the `pan' parameter is set. Allowed values range
1102
from -pi/2 to pi/2. As the position property ranges from -pi to
1103
pi, values with magnitude larger than pi/2 (i.e. positions in the
1104
'back') are mirrored to the front.
1106
The `render' plugin renders any number of input streams with respect to
1107
their position inside the stereo field to any number of output streams
1108
with respect of their positions given by the pipe source position
1109
parameter of the connections. You can render your multi-track song to a
1110
stereo setup for example.
1116
Stream(s) to render. Any number of connections allowed.
1119
Output stream(s). Any number of connections allowed.
1124
`out::position (float)'
1125
Parameter controlling the position of the output stream inside the
1126
stereo field. By default 0.0 is assumed (which is forward, or
1127
mono). The position property ranges from -pi to pi. To render
1128
multiple tracks to a stereo speaker setup provide -1.57 (left) and
1129
1.57 (right) to two connected output pipes.
1132
File: glame.info, Node: Arithmetics, Next: The Sample Analyst, Prev: Orientation, Up: Elementary Plugins
1137
The plugins `mul' and `add' perform a simple arithmetic operations on
1138
several input streams. Basically, `mul' multiplies and `add' sums up
1139
any number of input sample streams. Operations are performed sample by
1140
sample-no check is performed whether sample rates match! If a stream
1141
is shorter than others, it is zero- (add) or one-padded (mul)
1144
Each plugin allows one multiplicative and one additive constant to be
1145
set. They are interpreted differently for each plugin however,
1146
reflecting the different algorithms:
1148
`mul' calculates each output sample by taking one sample from each
1149
input pipe, adding `add' to it, multiplying the results, and finally
1150
multiplying the result by `factor'.
1152
`add' calculates each output sample by taking one sample from each
1153
input pipe, summing them all up, adding the `add' parameter, and
1154
multiplying the result by `factor'.
1160
Input sample stream. Any number of input connections is allowed.
1163
Output sample stream of computed data. Only one connection is
1170
Additive constant, see above. Defaults to zero.
1173
Multiplicative constant, see above. Defaults to one.
1175
There are neither further specific ports, nor further specific
1179
File: glame.info, Node: The Sample Analyst, Next: Catching Bugs, Prev: Arithmetics, Up: Elementary Plugins
1184
The `ssp_streamer' plugin offers a gateway between sample and rms data.
1185
Streamed rms data can be used later for analyzing via the `maxrms'
1186
plugin. Unfortunately, RMS work within GLAME is still in its early
1187
stages, so its not that useful at the moment.
1189
`ssp_streamer' ports
1190
....................
1193
Input sample stream to be converted.
1196
RMS data stream generated out of the sample input stream.
1198
`ssp_streamer' parameters
1199
.........................
1202
Window size for computing the running average.
1208
Input stream of RMS data.
1210
`maxrms' parameters.
1211
....................
1214
The maximum rms value found in the stream (sofar).
1217
File: glame.info, Node: Catching Bugs, Next: How to Code, Prev: The Sample Analyst, Up: Elementary Plugins
1222
Ping is a tool familiar to admins to test integrity and latency of a
1223
network connection. The `ping' plugin does the same within a GLAME
1224
filter network. It sends out a data packet from its output port and
1225
measures the time until the packet arrives at its input port. Obviously,
1226
the filter network should have a loop structure or ping will wait
1227
endlessly for an input. Debugging output goes to the console.
1233
Input port packets are received at.
1236
Output port packets are sent from.
1242
Number of packets to send. Defaults to 10.
1245
Time in microseconds between successive packets. Defaults to 250000
1246
microseconds (1/4 second).
1249
Number of samples in a test packet. Defaults to 128 samples.
1252
File: glame.info, Node: How to Code, Prev: Catching Bugs, Up: Elementary Plugins
1257
The `null' and `dup' plugins aren't really meant to be used, they are
1258
simple reference implementations for developers looking for a quick
1259
introduction to plugin programming. `null' passes an input stream
1260
unmodified to its output, `dup' duplicates an input stream to two
1261
output streams. In real life, the more complex `one2n' plugin can be
1262
used to achieve the same results. So use the source, not these plugins.
1265
File: glame.info, Node: Effects, Next: FFT Plugins, Prev: Elementary Plugins, Up: Plugin Collection
1279
File: glame.info, Node: Echo, Next: Noisegate, Up: Effects
1284
Guess what! The `echo' plugin adds an echo to an input stream.
1290
Stream of input sample data. Only one connection is allowed.
1293
Mixed stream of input and echoed data. Only one connection is
1300
Delay time for echo in milliseconds. Defaults to 100 milliseconds.
1303
Mix ratio of echoed to original stream. Defaults to 0.7.
1306
File: glame.info, Node: Noisegate, Next: Spectrum, Prev: Echo, Up: Effects
1311
A noisegate is used to suppress signals below a certain threshold from
1312
an input stream. Its operation can be tuned by a number of parameters.
1313
When the input signal (its absolute value actually) falls below
1314
`threshold_on' for more than `hold' time, `noisegate' suppresses output
1315
until the signal goes back up and above threshold_off. Switching from
1316
and to zero output is usually not done instantaneously as this would
1317
lead to distorted sound. Instead, a fading time can be given by
1318
`attack' and `release' respectively.
1326
`noisegate' parameters
1327
......................
1329
`threshold_on (float)'
1331
`threshold_off (float)'
1332
On and off threshold for sample data between 0 and 1, see above.
1333
Default to 0. A noisegating effect is only achieved if
1334
`threshold_on' is equal or less than `threshold_off'.
1337
Hold time in milliseconds, see above. Defaults to 0.
1340
Attack time in milliseconds, see above. Defaults to 0.
1343
Release time in milliseconds, see above. Defaults to 0.
1346
File: glame.info, Node: Spectrum, Next: Flanger, Prev: Noisegate, Up: Effects
1351
In the Spectrum category you'll find a collection of filters that alter
1352
the spectral composition of a sound. Currently included are a bandpass
1353
filter composed of chained Chebyshev lowpass/highpass stages, a one
1354
stage bandpass filter and a Chebyshev lowpass/highpass filter.
1364
File: glame.info, Node: bandpass, Next: bandpass_a, Up: Spectrum
1373
Input stream of sample data. Only one connection is allowed.
1376
Output stream of filtered sample data. Only one connection is
1379
`bandpass' parameters
1380
.....................
1383
defines the number of stages used for the low/highpass filter. The
1384
more stages you add, the more accurate is the impulse of the
1385
filter. Defaults to 1.
1388
Defines the center frequency of the passband. Defaults to 1000 Hz.
1391
Defines the width of the passband. Defaults to 500 Hz.
1394
`ripple' defines the percentage of ripple in the pass band. It
1395
defaults to 0.5, and it is best to leave it alone unless you know
1399
File: glame.info, Node: bandpass_a, Next: lowpass, Prev: bandpass, Up: Spectrum
1408
Input stream of sample data. Only one connection is allowed.
1411
Output stream of filtered sample data. Only one connection is
1414
`bandpass_a' parameters
1415
.......................
1418
Defines the center frequency of the passband. Defaults to 1000 Hz.
1421
Defines the width of the passband. Defaults to 500 Hz.
1424
File: glame.info, Node: lowpass, Next: highpass, Prev: bandpass_a, Up: Spectrum
1433
Input stream of sample data. Only one connection is allowed.
1436
Output stream of filtered sample data. Only one connection is
1439
`lowpass' parameters
1440
....................
1443
defines the number of stages used for the filter. The more stages
1444
you add, the more accurate is the impulse of the filter. Defaults
1448
defines the cutoff frequency. Defaults to 1000 Hz.
1451
`ripple' defines the percentage of ripple in the pass band. It
1452
defaults to 0.5, and it is best to leave it alone unless you know
1456
File: glame.info, Node: highpass, Prev: lowpass, Up: Spectrum
1465
Input stream of sample data. Only one connection is allowed.
1468
Output stream of filtered sample data. Only one connection is
1471
`highpass' parameters
1472
.....................
1475
defines the number of stages used for the filter. The more stages
1476
you add, the more accurate is the impulse of the filter. Defaults
1480
defines the cutoff frequency. Defaults to 1000 Hz.
1483
`ripple' defines the percentage of ripple in the pass band. It
1484
defaults to 0.5, and it is best to leave it alone unless you know
1488
File: glame.info, Node: Flanger, Next: Distortion, Prev: Spectrum, Up: Effects
1493
The flanger effect is essentially a variable delay, that operates on a
1494
comb filtered signal. The variation of the delay is given by a low
1495
frequency oscillation (LFO). Dependent on the type of LFO you get
1496
different effects. The flanger is especially useful for guitar and
1497
voice sounds. With the right settings this implementation of the
1498
flanger can be used as a detune effect using a ramp up/down LFO and
1499
setting dry gain to zero.
1505
Input stream of sample data. Only one connection is allowed.
1508
Output stream of processed sample data. Only one connection is
1511
`flanger' parameters
1512
....................
1514
`effect depth (float)'
1515
Size of delay buffer in ms. A larger depth allows for a larger
1516
sweep depth and more dramatic effects.
1518
`detune range (float)'
1519
The detune range defines the maximum oscillation amplitude of the
1520
LFO in ms and thereby modifies the intensity of the effect. The
1521
maximum value it can take is effect depth/2.
1524
Specifies the oscillation frequency for the LFO. Good values are
1525
between 0.5 and 10 Hz. Higher frequencies generate rather weird
1528
`Dry/Wet Balance (float)'
1529
This parameter defines the ration of the dry signal to the
1530
effect(wet) signal, e.g. setting it to 0.0 you you only hear the
1531
wet signal, setting it to 1.0 you don't hear any effect.
1533
`feedback gain (float)'
1534
The feedback gain speficies the amount of the mixed dry/wet signal
1535
that is mixed to the input signal. Mixing is done according to:
1536
(inputsignal + feedbackgain * drywetsignal)
1539
Defines the amount of preamplification in the input stage of the
1543
At the present time you can choose between three different LFO
1546
A sine shaped LFO, which generates a sound sweeping up and
1547
down. Use for genuine flanger sound.
1550
ramp up, generate a signal with higher frequency.
1553
ramp down, generate a signal with lower frequency.
1556
A fractal shaped LFO (more or less a random curve) creating a
added
removed
doc/glame.info-2
