# GDAM Documentation

Dave
Benson
Geoff
Matters

## GDAM

### Introduction

GDAM is Geoff and Dave's Audio Mixer

GDAM is a digital dj mixing software package. It aims to be a powerful, professional-quality music mixing and remixing system, suitable for live performance. It was conceived on some beautiful summer morning (in 1998), and developed with drive and enthusiasm that seemed completely unnatural. Nearly two years later, we have achieved many of our goals; yet, development remains as hectic. Here is a list of features:

- client-server architecture based around glib

- streaming and mixing of any number of mp3 files

- dynamic filter insertion and removal

- multiple sound device support

- plugin support

- cacheing / playing loops

- contiguous queueing - plays albums without gaps between songs, regardless of output buffer size

- dj turntable-style interface

- assisted beat matching

- waveform viewer / beat calculator

- sequencer

- record from any point in the stream, to disk or another process

- gtk gui's, with simple skin support

- flexible command-line interface

- `gdam123` - an `mpg123` clone that talks to a gdam server

- hardware input support (midi and other)

- support to use LADSPA plugins

- support to create LADSPA plugins graphically

- online help

#### The Programs in GDAM

GDAM is an audio server, a client library, and a few powerful, extensible clients.

gdam-server

  The server does all of the audio processing and sound device handling. It can accept connections from multiple clients, optionally from remote computers.

gdam-launcher

  The graphical frontend, `gdam-launcher` creates gui components from xml description files.

gdamcli

  This simple command line interface to the gdam server allows inspection and manipulation of sound sources attached to a given sound device. It is useful for scripting and debugging.

gdam123

  This is a command line mp3 playlist frontend. It emulates `mpg123`'s `-z` and `^C` handling, and offers a healthy set of vi key bindings for interactive control and playlist manipulation.

In general you just run one `gdam-server`, but you may connect many clients (`gdam-launcher`, `gdamcli`, and `gdam123`) to it. The server opens multiple sound devices, moves streams between devices, and does all sound processing. Clients connect to a server on `localhost:6003` by default, but the `--gdam-server` option allows clients to connect to a different host and port. Clients connect to the default sound device unless the `--device` argument is given. Clients which use can use more than one device (ie `gdam-launcher`) accept several `--device` args.

##### Important Files

These files are used to customize the behavior and appearance of gdam.

server.config

  server config file, contains information about available sound devices. Usually in `/usr/local/lib/gdam/` or similar default location. Can be specified with `--config configfile` when starting the server.

default.rc

  gtk rc file used to control colors and fonts in gui components. Usually in `/etc/gdam/skin/` or `~/.gdam`. Can be specified with the `--rcfile` flag when starting `gdam-launcher`.

launcher.xml

  when `gdam-launcher` starts, it creates an initial skin from this xml file. The skin defined by `launcher.xml` is a panel of buttons to launch skins of other types and built from other xml files. This file is usually in `/etc/gdam/skin`, and the other xml files referenced are there or in subdirectories. If an xml file is given as an argument to `gdam-launcher`, the initial skin will be built from that file.

song.database

  xml database of song information: filenames, tempo and phase data, loop descriptions and other user-specified info. This information is used by client programs (`gdam-launcher`, `gdam123`). Can be specified to most clients with the `--database` flag.

gdam123rc

  file of ex-style `gdam123` commands, parsed on startup. Usually in `~/.gdam/` Used to set initial volume, mp3 file buffer size, etc.

input.devices

  describes hardware input devices (midi controllers, etc) Usually in `~/.gdam/`. This file is currently only used by client programs.

## Installing GDAM

### Dependencies

GDAM requires that a number of programs and libraries are installed on your computer. The exact dependencies vary between distributions and platforms. Pre-compiled `.rpm` and `.deb` packages require fewer libraries than compiling from source.

In order to decode mp3 files you need a fairly fast processor- maybe a 486 can decode a single mp3 but for serious mixing you'll definitely need something faster (any pentium should do nicely). The faster the processor, the more simultaneous mp3 streams you'll be able to decode.

For any of it, `gtk+ 1.2.5` or higher is required. Even the server requires it. Skins are created at run time from libglade xml description files. You'll need the following:

- `libglade`

- `libxml`

Recent Redhat `libxml` rpm's have required the following gnome libs:

- `gnome-core`

- `gnome-libs`

- `gnome-audio`

`Mpg123` is used for decoding mp3 data, so you must have it installed.

If compiling from cvs source, the `sgmltools-lite` package is required to generate documentation. This is available from the sgmltools-lite project. In addition, people compiling from source (cvs or tarball) will need the header files from the following packages:

- `libglade-devel`

- `libxml-devel`

Recent Redhat `libxml-devel` rpm's have required the following gnome libs:

- `gnome-core-devel`

- `gnome-libs-devel`

- `gnome-audio-extra`

Recent RPM packages are available on our web page, gdam.org.

#### Quick Installation Guide

##### Installing From Precompiled Packages

if you have an `.rpm` package, run the following as root:

    % rpm --install packagefile.rpm

if you have a `.deb` package, run the following as root:

    % dpkg --install packagefile.deb

###### Installing From Compiled Source

If you have compiled from source (see 'Compiling from Source'), you can install by doing the following as root:

    % make install
    % ldconfig

If you use `--prefix` to the `./configure` script, you may not need to be root: but you may need to set the `LD_LIBRARY_PATH` to include `lib` and `PATH` environment to include `bin`.

If you don't even want to `make install` you can just add `gdam/lib` to your `LD_LIBRARY_PATH`. Then run the client and server separately.

###### Running Gdam

If you have fully installed gdam onto your system, the server should automatically be launched when you run `gdam-launcher`, so it is a one step process.

Often it is easier to run the client and server separately:

- if something is going wrong,

- you want to specific command line flags to the server,

- you want to connect multiple clients to the server,

- or you want the server to keep running after the client has detached.

In that case it is recommended to use two separate terminal windows to run the commands. In the first window:

    % gdam-server --config /etc/gdam/server.config

Sometimes the `--debug` flag will print out useful information, especially if things aren't going well.

In the second window,

    % gdam-launcher

It should pop up, using the first window's server.

###### Compiling GDAM from Source

We recommend that each time you compile GDAM, you use a fresh copy of the source code. The reason for this is that many configuration options are stored in files such as `config.cache` and it is therefore possible that the makefiles don't match your current system configuration. (This can happen if you install a package after running configure). Check out a new copy from cvs, or re-unzip the tarball or (faster) delete the config.cache.

We use GNU automake for building our programs. This means that once you have the tarball, the following standard procedure should apply:

    	% ./configure
    	% make
    	% make install

###### Compiling GDAM from CVS Source

If you have the cvs version, run `./autogen.sh` instead of `./configure`. This will install gdam in `/usr/local/lib/gdam/`, `/usr/local/bin/gdam*`. If you specify the option `--prefix=/usr` to `./configure` it will install in `/usr` instead.

###### Compiling on FreeBSD

The version of gcc most commonly distributed with FreeBSD, 2.95.2 19991024, will not compile GDAM. To work around this, upgrade to `egcc`. If you have not already done so, install ports by running `/stand/sysinstall`. Then move to `/ports/lang/gcc-devel/` and `make install`.

When configuring GDAM, you need to specify the proper path to the `gtk-config` command, and to use `egcc`. Your command will probably be:

    	% GTK_CONFIG=/usr/X11R6/bin/gtk12-config CC=egcc ./configure

Now, use gmake to build:

    	% gmake; gmake install

###### Libraries

In order for your system to know were the libs are installed, you might need to do the following:

    	% ldconfig

If you still get errors about missing libraries running gdam:

1. Make sure that `/etc/ld.so.conf` contains the relevant `/usr/*/lib` directory.

2. Alternately, to use GDAM without installing it, set the `LD_LIBRARY_PATH` environment variable to include the directory where the libraries reside. You should modify your shell startup script or `/etc/profile` if you are going to run gdam frequently.

###### Configuring the Server Config File

The default server config file should work for most people using OSS or ALSA with OSS emulation. Nevertheless, many will want to edit the file to tune device options, select default devices, or enable native ALSA support. The file is fairly self-explanatory, it will most likely have been installed in `/usr/local/lib/gdam/server.config`. It contains a list of device types (OSS,ALSA), a list of specific devices, and some global server options. An abbreviated example follows:

    #    GDAM Server Config File
    #
    # This is the default server config file that should
    # be shipped with distributions.
    #
    # Please delete this comment when you edit it!
    #

    #
    # define the types of output devices available.
    #
    DeviceType      "plugin"        "oss"
    #DeviceType      "plugin"        "alsa"

    #
    #  If you have OSS or ALSA + OSS compatability, use these.
    #  Some devices need the 'fork' option to keep from hanging.
    #
    #Device   "oss"   "/dev/dsp"   "numfragments=3:logfragsize=12:fork"
    Device    "oss"   "/dev/dsp"
    Device    "oss"   "/dev/dsp1"
    Device    "oss"   "/dev/dsp2"

    #
    # ALSA Devices [if you have sys/asoundlib.h installed.]
    #
    #  appending '#n' to a device name causes gdam to use subdevice n,
    #  if possible.   otherwise, the first available subchannel is used.
    #  You probably don't want entries for both specific subdevices and
    #  the general device, it may conflict.
    #
    #Device  "alsa"  "/dev/snd/pcmC0D0"   "numfragments=3:logfragsize=12"
    #Device  "alsa"  "/dev/snd/pcmC0D0#0" "numfragments=3:logfragsize=12"
    #Device  "alsa"  "/dev/snd/pcmC0D0#1" "numfragments=3:logfragsize=12"
    #Device  "alsa"  "/dev/snd/pcmC0D1"   "numfragments=3:logfragsize=12"

    # Don't allow mpg123 to swallow all the cpu from us...
    ExternalPriorityDrop   "7"

    #
    # If server is run as root, change to this user and group for safety.
    #
    IfRoot User     "nobody"
    IfRoot Group    "audio"

    #
    # Files to store log info and pid
    #
    LogFile         "/var/log/gdam.log"
    PidFile         "/var/run/gdam.pid"

    #
    # Whether to run in daemon mode
    # (runs in background with different permissions)
    #
    Daemon          "no"

    #
    # If you specify `no' then anyone can connect.  Else, only
    # localhost connections are accepted.
    #
    BindLocalhost   "yes"

    Debug           "no"

    #DispatchLog     "dispatch.log"
    #Microphone "/dev/dsp1"
    #TcpSocket	"6005"		"punk"

ExternalPriorityDrop

  This causes the GdasExternal class to renice the child process the specified number of steps.

There are a few device options you may wish to try out:

bits=[8|16]

  How many bits per sample for the sound device.

mono

  Monophonic aka one-channel sound.

stereo

  Stereo aka two-channel sound.

rate

  Sampling rate of the device in samples per second.

fork

  Fork the device into its own process. This is necessary if your sound device doesn't support "polling". If clents hang, timers stuck at 0:00, this might be the answer.

wrong_endian

  Swap byte order of sound for this device. If you hear static, try this option.

logfragsize

  Log base 2 of the size of a single audio buffer fragment. Larger sizes increase latency but protect against dropout.

numfragments

  Number of audio buffer fragments to circle through. Larger numbers increase latency but protect against dropout.

no_ioctls

  Don't attempt to send the device the normal ioctls, which may fail on some devices spuriously, but is mostly useful if the "device" is really just a fifo.

###### Setting Up Permissions

Gdam can be run in many modes, the best one for you depends on how you want to use it.

- if you always use gdam through `gdam-launcher` then it should be completely secure to run it in `secure` mode, letting it run the server for you.

  Serious users will find the convenience of having multiple client connections very valuable; we really intend this more as a "demo" mode, for playing with few security worries.

- If you run gdam on a network where you don't trust the computers directly connected to you (for example, if you are on the internet and don't have a firewall), you can add `Bind Localhost`to the config file to prevent other computers from connecting.

- if you more-or-less trust the computers in your network you can probably run gdam without `Bind Localhost` fairly safely. Make certain that `gdam-server` ddrops priviledges from root. (use `ps`)

If gdam works for you "out of the box" there is probably little reason to configure it to behave more securely, although we recommend always running `gdam-server` behind a firewall. (We have designed it to be secure in many sensible ways - but there is a lot of auditting to do. Currently, lack of strong authentication is the biggest problem.)

If you wish to run gdam realtime you will have to run it as root. This is also a situation you must consider if you run `gdam-server` from an initscript.

If you add `Username` and `Group` tags to the configuration file and run it as root, `gdam-server` drops to that identity before opening the audio devices. This means that the user or group must have unix permission to open sound devices. Either

1. the audio device must be owned and writable by the specified Username.

2. the audio device must be owned and writable by the specified Group.

If you don't know what to do, we recommend making your audio devices readable and writable by a group "audio" (which you may have to create using the `addgroup` or `groupadd` or by editting `/etc/group` directly. This boils down to:

        % addgroup audio
        	    # may complain if the group exists.
        % chgrp audio /dev/dsp*
        % chmod 660 /dev/dsp*
    	    # alsa users should add /dev/snd/pcm*

###### Setting Up Festival

gdam can be used with the freely-available festival speech generation package, which was made at the University of Edinburgh.

First install festival and a voice or two from either packages or source code from the link above.

Then copy the `text2wave` script from the example directory onto your path. Make sure it is marked as executable, using `chmod +x`. For my debian system, the following suffices:

    % zcat /usr/share/doc/festival/examples/text2wave.gz $gt; /usr/local/bin/text2wave
    % chmod +x /usr/local/bin/text2wave

You'll also need to install one or more of the voices. As of writing, package names for festival voices include:

1. festvox-kallpc16k

2. festvox-kallpc8k

3. festvox-kdlpc16k

4. festvox-rablpc16k

When you run `gdam-launcher` just specify `--define festival`.

###### Computers Without Soundcards

While most users will have a soundcard present, it is possible to run both the server and the clients on computers without sound cards.

Wherever the server runs, it requires a device to draw data from it. ALSA provides a dummy driver which mimics /dev/dsp, but produces no sound. User running in this mode will most likely add a recording output so that audio data can be saved to disk or sent to icecast server.

###### Computers With Multiple Soundcards

###### Installing Multiple Soundcards On A Linux System

With the standard kernel code, this can be tricky. You'll probably compile sound support as modules, and insert the cards one at a time with any necessary parameters.

With the commercial OSS drivers from 4front technology, I had no problem getting several cards to work at once. Their configuration utility autodetected and installed all three of my sound cards. Many cheap and a few professional cards are supported. A basic license costs $20, certain cards require more expensive options.

The ALSA project has developed a free set of drivers meant as a powerful alternative to the standard kernel drivers. Many cards are supported, and the system is designed to support multiple cards without conflict.

###### Supporting Multiple Soundcards In GDAM

Make sure all of your available devices are listed in the server.config file. Any client can be run with the `--device` flag to change the default sound device. The `gdam-launcher` program accepts multiple `--device` flags, and can switch a source from one device to another. If no `--device` flags are given, most clients will use the value of the `GDAM_DEVICE` environment variable. `gdam-launcher` will use both `GDAM_DEVICE` and `GDAM_DEVICE2` if not given other soundcards on the command line.

###### Supporting Four-Channel or "Surround" Soundcards In GDAM

An alternative to multiple sound cards is a four-channel sound card. I get great performance from my Trident 4DWave sound card, which features seperate front and rear stereo outputs. SoundBlaster Live cards also offer four channels of audio output. A benefit of cardlike this over two seperate soundcards is that the timing of two channels, and the devices which feed them, is identical... they will not drift or be read from at different times.

Four-Channel soundcards offer seperate front and rear stereo outputs. This is usually accomplished by having multiple "subdevices" for writing audio data to the soundcard. Hardware mixing controls determine whether each subdevice sends sound to the front outputs, the rear outputs, or both. The mixer controls are reset each time a subdevice is opened, so i have to set the mixer controls each time i restart the gdam server.

In order to use front and rear outputs of a card such as the 4DWave or the Soundblaster Live, you need drivers which support the card's internal mixing controls. The ALSA drivers, version 0.5 and higher, support these controls and the following instructions apply to alsa drivers. I am unaware whether the kernel OSS drivers or the commercial OSS drivers export these mixer controls... if so, a similar process should allow output.

After installing ALSA drivers, add entries to the server.config file which describe specific subdevices on your four-channel soundcard.

    # ALSA Devices [if you have sys/asoundlib.h installed.]
    #
    #  appending '#n' to a device name causes gdam to use subdevice n,
    #  if possible.   otherwise, the first available subchannel is used.
    #  You probably don't want entries for both specific subdevices and
    #  the general device, it may conflict.
    #
    #Device  "alsa"  "/dev/snd/pcmC0D0"   "numfragments=3:logfragsize=12"
    Device  "alsa"  "/dev/snd/pcmC0D0#0" "numfragments=3:logfragsize=12"
    Device  "alsa"  "/dev/snd/pcmC0D0#1" "numfragments=3:logfragsize=12"

Once the GDAM server knows about subdevices, GDAM clients need to be told to use them. Run `gdam-launcher` with multiple `--device` flags, or set the `GDAM_DEVICE` and `GDAM_DEVICE2` environment variables.

    % GDAM_DEVICE=/dev/snd/pcmC0D0#0 GDAM_DEVICE2=/dev/snd/pcmC0D0#1 gdam-launcher

The mixing controls on your soundcard need to be set each time the subdevice is opened (i.e. when `gdam-server` is run.) I use `alsactl` and `gamix` to change these settings. Each time an ALSA driver opens a subdevice, new controls are made available to set that device's volume to the front and rear outputs. In `alsactl`, these controls are named "PCM Front Volume" and "PCM Reverb Volume" for each subdevice. `gamix` presents front/rear/pan controls for each subdevice under headings such as "PCM Playback" and "PCM Playback 1". Whichever method you use, set subdevice 0 to full volume on the front channel / zero volume on the rear, and set subdevice 1 to zero volume on the front channel / full volume on the rear.

Screenshot of gamix

Once you are pleased with the soundcard settings, use `alsactl -f ~/fourout.ctl store` to save soundcard settings. After restarting `gdam-server` and `gdam-launcher`, you can restore the setting with `alsactl -f ~/fourout.ctl restore`

###### `gdam-server`: Audio Processing Server

###### Running `gdam-server`

`gdam-server` is responsible for all of GDAM's audio processing. For any GDAM client program to work, it must have a gdam server available. Properly installed distributions will automatically start the `gdam-server` when a client is run. When the server is automatically started, it does not accept connections from other clients. For this reason, it is usually desireable to run the `gdam-server` as a seperate process. By default all clients attach to `localhost:6060`, but that can be changed by giving them the `--gdam-server` flag. The client and server need not be on the same computer, but the server needs to have access to the audio files and devices.

    	gdam-server
    	--port port_number
    	--config config_file
    	--realtime

###### Recording Sound from the `gdam-server`

Server support is in place for recording sound output by the gdam server to a given device. The sound can be written directly to disk, or sent to another process (i.e. an mp3 encoding process on some machine).

###### Starting and Stopping Recording with `gdamcli`

The long way to do this is to use the `gdamcli` program to start and stop the recording. You do this:

    	% ./gdamcli [--device /dev/dsp?]

    	          #  Print out the mixer's information.  The `parent'
    		  #     is always the recording filter.
    	gdam-cli> ls -a $mixer
    	source 1.
    	  arg 0: mixed => []
    	  arg 1: parent => 2
    	  arg 2: terminates => 0
    	  arg 3: paused => 0
    	  arg 4: mode => eternal
    	  arg 5: parent_device => 0
    	  arg 6: position => 182272L
    	  arg 7: subsources => []

    		# The number after `call' should be the parent number.

    	gdam-cli> call 2 add_output connect your_host:your_port_number

    	  arg 0: output_id => 1

    		# So now it'll be connecting/recording on your host.

And to stop it:

    	gdam-cli> call 2 remove_output output_id 1

    		# will stop it (use the output_id it gives you)

    		# You can record to multiple computers this way.

    		# Finally, instead of `connect' you can say `file'
    		# which will make the server write the raw sound data
    		# to a local file.

So if you set up something to record at that port, you're ready to go.

###### Starting and Stopping Recording with `record-mp3` and `record-stop`

The `cli/record-mp3` script attempts to automate this, as its first argument it takes the host and port to tells the gdam server to connect to host:port as specified as the argument to the script. The `cli/record-stop` scripts removes the output which record-mp3 adds.

###### Recording from within the GUI

The gdam-launcher pops up single turntables with an entry at the bottom for a recording location. Format is 'host:port'. Pressing the Record button will cause the entire mix being sent to the first sound device (the value of the first `--device` flag, or the `GDAM_DEVICE` environment variable, or `/dev/dsp` by default) to be mirrored to the given host. While it is recording, the button will remain depressed. Press it again to stop the recording.

###### Setting Up Something to Record

We have used `gogo` to encode mp3 data, and with some success, but it seemed a bit unstable. `lame` isn't quite as fast, but it hasn't crashed yet. Try the following line in your `inetd.conf`:

    	6060 stream tcp nowait nobody.audio /usr/sbin/tcpd /usr/local/sbin/run-lame

And the following 3-line shell script as `/usr/local/sbin/run-lame`:

    	#! /bin/sh
    	DATE=`date +%d-%b-%Y-%H:%M:%S`
    	/usr/local/bin/lame -r -x -m s - /mnt/18/lame/l-$DATE.mp3 > /tmp/lame.log.$DATE 2>&1

Alternately, use `/usr/local/sbin/run-gogo`:

    	#! /bin/sh
    	DATE=`date +%d-%b-%Y-%H:%M:%S`
    	/usr/bin/gogo stdin /mnt/18/gogo/$DATE.mp3 -offset 0 > /tmp/gogo.log.$DATE 2>&1

And you have to accept that this is probably a security hole if you are outside a firewall :) See the appendix for more security info.

###### Icecast / Shoutcast

If you want to talk to a Shoutcast server, here is an untested alternate script that can be run from inet.d by Scott Manley (aka Szyzyg) spm@star.arm.ac.uk.

    	#! /bin/sh
    	DATE=`date +%d-%b-%Y-%H:%M:%S`
    	mkfifo /tmp/mp3pipe
    	echo "password" > /tmp/shoutheaders
    	echo "icy-name: Test" >> /tmp/shoutheaders
    	echo "icy-genre: Mixed" >> /tmp/shoutheaders
    	echo "" >> /tmp/shoutheaders
    	/usr/bin/lame - - > /tmp/mp3pipe &
    	cat /tmp/shoutheaders /tmp/mp3pipe | nc localhost 8000

Should suffice to have it bounce off to an mp3 encoding server... As a note, `icecast` has broken support for piping in raw audio data which could be used live. Alternately, I hacked the `shout` utility to support streaming a file which was growing in size. This was sufficient to manage a live broadcast.

Further `icecast` utilities to come...

###### `gdam-launcher`: GDAM's GUI

###### Running `gdam-launcher`

The `gdam-launcher` is the primary gui for gdam. When it is run, it brings up a panel of buttons, each of which will launcher a virtual "component". In order to nicely color the widgets, `gdam-launcher` looks for a gtk rcfile `default.rc` in, among other places, `~/.gdam`; a system default is provided.

    	gdam-launcher
    	--gdam-server host:port
    	--device device
    	--rcfile rcfile
    	--rcpath rcpath
    	--database songdb
    	--define variable
    	--mp3buffer mp3_file_buffer_size_in_seconds

###### Available Components

Turntable

  an mp3-player with resampling and synching capabilities, wrapped in a filter stack.

Wheels

  two turntables and a crossfader

Wavetable

  a looping resampling buffer, for "wavetable" synthesis or looping sound cut from a song

Buffer Editor

  a sample editor

Sequencer

  sequence many short samples, at different gain levels and resample rates

Beat Calculator

  a tool to help determine the beat information which describes a song.

###### Skin Hotkeys

Hotkeys refer to key bindings which are attached to one window, and respond to the normal keyboard when that window has focus (unless a text-entry widget is activated.) Before version 0.933 hotkey bindings were defined in the xml skin files, and could only be changed by editing the skin xml file. As of version 0.933, hotkey bindings are part of the input binding file format (also xml) and are stored outside the skin files. The skin file `wheel-mp3.xml` references a file of bindings, `wheelshotkeys.xml`. To extend or change the hotkey bindings, a user can copy the binding file into `~/.gdam/skins/` and edit it. Their copy of the file will be found whenever a skin file references it.

The binding file format is described elsewhere. All of our hotkeys are defined using the gdam_packer_trap_key_press handler. Example Handler:

            gdam_packer_trap_key_press:e:tt1:gdam_skin_arg_int:play_or_synch:-1

Translation: The 'e' key applies to named child 'tt1' (the turntable). When 'e' is pressed the argument 'play_or_synch' is set to a value of -1. (If the turntable is playing, the value of -1 stops it. If the turntable is stopped, -1 seeks to the first beat).

Example Handler:

    	gdam_packer_trap_key_press:q:tt1:gdam_skin_arg_double:seek_by_bars:-2

Translation: The 'q' keys sets the turntable's 'seek_by_bars' arg to -2. (This seeks the position backwards by two bars.)

###### The Turntable

###### Turntable Overview

One of the basic gdam gui components us the turntable. The turntable embodies the ability to start, stop, seek, and change the speed of a sound. A turntable contains a sound-producing source (ie an mp3 player) which it controls. If available, a turntable makes use of beat information about the sound it is controlling. In addition, the turntable offers drag-n-drop functionality to coordinate between songs.

The default turntable, containing an mp3 player, looks something like this:

Screenshot of the Turntable

Screenshot of the Turntable

Screenshot of the Turntable

To use the turntable, a song must first be loaded. Drag and drop a filename from the song selector onto the filename entry box.[*] Alternatively, use the => (import) button to load the currently selected song. When the song is dropped, the turntable loads information about it from the song database. If known, the song's position will automatically be set to the location of the first beat.

[*] Initially the song database will be empty, making the song selector empty. Please see Section V, Song Database.

The middle two buttons on the top row stop and start the song playing. The >-style buttons nudge the song a small amount. They are useful for aligning songs which are slightly out of sync. The >| style buttons seek the song an even bar, based on bpm information from the song database. These buttons are useful to move around within the song while staying on beat. The anchor button will set the turntable to be the lead source. This means that if it is playing, other songs can sync to it. To sync a running turntable to the lead source, press its play button a second time.

Turntables can resample their songs to match any tempo. To cause one turntable to resample its song to match another song's tempo, drag and drop the desired tempo from one turntable's bpm label to the other turntable's resampling area. Double clicking a turntable's bpm label will cause it to match to the lead (anchored) component. By checking the 1/2 button in the resampling area, the turntable treats its song as if it was half the normal speed. This allows one to sync an 80 bpm song to a 160 bpm one, without extensive resampling.

In addition to the iconated buttons, there are a number of other displays and controls:

Annotated Screenshot of the Turntable

###### Buttons

Play Button

  Without Modifier - Starts the song playing. If the song is already playing, synchronize this song with the lead song. Both songs must have beat information in the song database for this to work.

  With CONTROL pressed - Starts the song in sync with a different, playing song. Both songs must have beat information in the song database for this to work.

Stop Button

  Without Modifier - Stops the song. If the song is not playing, seeks to the first beat.

Nudge Back Button

  Without Modifier - Nudges the song back a tiny amount (1/200 sec) Useful for aligning songs which aren't quite playing in time.

Nudge Back Back Button

  Without Modifier - Nudges the song back a small amount (1/20 sec)

Nudge Forward Button

  Without Modifier - Nudges the song forward a tiny amount (1/200 sec)

Nudge Forward Forward Button

  Without Modifier - Nudges the song forward a small amount (1/20 sec)

Nudge Measure Back Button

  Without Modifier - Nudges the song back exactly one measure, if the bpm is known. Useful for looping part of a song, or seeking through a song while keeping the beat.

  With CONTROL pressed - Nudges the song back exactly one beat.

Nudge Measure Back Back Button

  Without Modifier - Nudges the song back exactly two measures.

  With CONTROL pressed - Nudges the song back exactly two beats.

Nudge Measure Forward Button

  Without Modifier - Nudges the song forward exactly one measure.

  With CONTROL pressed - Nudges the song forward exactly one beat.

Nudge Measure Forward Forward Button

  Without Modifier - Nudges the song forward exactly two measures.

  With CONTROL pressed - Nudges the song forward exactly two beats.

###### Other Controls

Position Range

  Display the current position within the song. Drag to change.

Time Label

  Displays the current time in minutes and seconds.

Beat Number

  If the beat information of the underlying source is known, then this displays the number of beats away from the first, corresponding to the current position.

Sync Preview

  If the turntable is capable of synching the playing song (i.e., it has beat information for that song and for the lead song) then this shows how far out of sync it is. The value is a fraction of a beat. A negative value indicates that the song should be nudged back by that amount to be in sync.

Resample Range

  Controls the resample rate (ie playback speed) of the song. Drag to change.

Anchor Button

  When this button is pressed, the turntable is set as the lead component. This means that other components' songs will attempt to sync to the turntable's. If the beat information of the turntable's song is unknown, it won't make a very useful leader.

Resample Rate

  This display indicates what speed the song is playing at.

BPM Display

  This display indicates the bpm of the resampled song. This value can be dragged onto another turntable's BPM display (using the middle or right button) causing the other turntable to resample itself such that its output bpm matches ours.

Jump Paddle

  This widget allows measured jumps of 1 to 16 beats. Drag the paddle until the label indicates the number of beats you'd like to jump. Release and the jump occurs. Clicking in the trough and at the ends also allow easy jumping.

Tempo Lock

  If this control is active, then the turntable will automatically adjust its resampling rate when a new song is loaded. The rate will be adjusted so that the new output tempo is the same as the old. Of course, the beat information of both songs must be known for this to happen.

Tempo Scale Arrows

  These arrows are adjacent to the tempo display, in the style of a spinbutton. The up arrow doubles the effective tempo of the song, and the down button halves it. When the effective tempo of a 180 bpm song is halved, the first beat remains at the same location but seeking and synchronization treat it as if it were 90 bpm.

Cycle Beat Info

  Some songs have a complicated beat info description, because different parts of the song have different phases and tempos. At any point, the turntable uses a single firstbeat and tempo value. When the position of the song is changed, the turntable will automatically cycle the beat info to the range which describes the current position. At times it is useful to select which beatinfo range to follow at any point in the song. A left click on this control cycles to the next beatinfo range. In some skins, a right click on this control will lock the beatinfo, to prevent the turntable automatically selecting the range it thinks is appropriate.

###### The Wheels

One handy collection of components is the wheels gui. This emulates a set of dj turntables, packing two turntable components into a window with a crossfader to control the relative volumes of the two channels, a widget to select the output device of a channel, and builders to dynamically add filters to a channel.

The default wheels skin appears thus:

Annotated Wheels Screenshot

###### The Builder

The builder provides dynamic insertion and removal of filters. Many sound-producing components come packed into builders, so that a wide range of filters can be applied.

A builder with one gain and one bounce filter looks like this:

Annotated Builder Screenshot

Filter Launch Buttons

  These buttons add filters of different types to the filter stack.

Filter Control Panel

  The X button removes the filter from the stack.

  The O button disables and reenables the filter.

  The < button moves the filter up the stack one position.

  The > button moves the filter down the stack one position.

Help

  Launch online help.

###### Using the Various Filters

###### Using the Equalization Filter

This filter is an extremely simple lo/hi/band/notch filter.

You can change its mode with the pulldown menu. The modes are:

notch

  ... cut out a particular frequency.

bandpass

  cut out everything but a particular frequency.

lopass

  cut out above a particular frequency.

hipass

  cut out below a particular frequency.

hishelf

loshelf

  ...

peaking eq

  ...

The frequency is in hertz, and its meaning depends on the selected mode.

The bandwidth is supposed to be the cutoff rate (meaning how sharply the filter's output over frequency drop to 0). It doesn't work very well in some modes.

###### Using the Fader

The fader allows you to adjust an envelope which is applied over a certain number of beats. Enveloping means to change the volume gradually over time.

###### Using the Bounce Filter

The bounce filter temporarily replaces the sound stream with sound from a fraction of a beat earlier in the song. By applying this filter in time with the music, it is possible to double or drop beats.

The bounce filter has one parameter, the amount of delay. This is displayed as a number of eighth beats; a value of four corresponds to half of a beat.

###### Using the Spin Filter

The spin filter temporarily causes a section of music to be looped. While this loop is being played back, the underlying song continues to play at a normal speed, so that it will stay synchronized.

The primary parameter is the amount of boffer. This is displayed as a number of whole beats. If the bpm of the song is not known, a tempo of 60 bpm is assumed. If a negative number is specified as the beat factor, then the delay will be the negative inverse of that number; for instance, a value of -2 corresponds to a half beat period.

The spin filter can be locked into a spin mode. In this situation, depressing the temporary spin button will cause the looped buffer to be overwritten by incoming sound. The spun sound will die if the underlying song stops.

###### Using the Fir Filter

The fir filter allows users to graphically place echoes of different delays and volumes. At small delays, this will affect the tone of the sound. The fir filter can also be used to place echoes with delays equal to a fraction of a beat.

The largest component in the fir filter is the display area. Grid units are marked off on the display area for guidance. The horizontal axis represents time, and vertical bars are drawn every n samples. The vertical axis represents volume. Clicking with the left button will add an echo. An echo can be dragged with the left button, and removed with the right. To the right of the display area is a scrollbar which controls the zoom level in the time domain.

The grid unit adjustment controls the time represented by each vertical bar. This number is in samples, where 44100 samples equal one second. The time between bars can also be set as a number of beats. When the beats scrollbar is set to non-zero value, the grid unit value is remembered, and this value is restored when the beat_factor is set to zero.

The normalize toggle button causes the total volume of all echoes to be held constant. The maximum value is given by the scale adjustment. If the volume is not normalized, then the scale value is applied to each echo's volume.

###### Using the Flange

The flange filter applies a reverb with a varying delay, resulting in "swooshing" sounds.

The flange filter has a display area similar the the fir filter's, into which echoes can be placed and relocated. However, note that multiple echoes will greatly increase the instability of the filter.

The echoes are varied according to a sine wave, triangle wave, or buffer. The frequency of the this waveform can be adjusted with the hz slider. The lowest, center, and greatest values can be set with the three horizontal sliders.

The overall amount of effect applied is controlled with the effect slider.

###### Using the Mininetwork

The mininetwork filter allows users to build simple filter networks by graphically arranging filter icons.

When the mininetwork filter is launched, two icons are present. The green icon at the top represents the input, and the red icon the output. These two are connected such that sound flows straight through the filter.

Select a filter type, e.g. delay, from the list. Clicking on the display area will add a delay filter. The icon can be dragged by its center to move it. Drawing a line from the bottom of the green input icon to the top of the delay filter will connect the two. There is no restriction to how many connections can be made from the output of any filter, so the input will retain its connection to the output. Once the output of the delay filter is connected to the large read icon, sound will also flow through the delay filter.

Clicking on any icon will bring up a panel displaying the parameters of the filter. For instance, clicking on the delay filter allows control over the amount of delay. For convenience, the scale of the delay can also be changed.

Filters can be inserted between existing filters. After selecting the desired filter type (say, gain) click with the middle button on a connection between two filters. A gain filter is inserted and connected such that it controls the volume of the sound flowing through that connection.

A filter and all its connections can be removed by clicking on the filter with the right button.

The middle button will remove the filter, but restore as many connections as possible. A connection can be removed by right clicking on it.

###### The Buffer Editor

###### Loading a Buffer

The Buffer Manager button opens the buffer manager. At first this will contain only the default waveforms (sin, square...) but wav files can be loaded from disk with the sample picker, and bits of mp3 files can be cached using the cache component. After selecting a waveform within the buffer manager, drag it onto buffer editor. Alternately, the => button loads the selected buffer without dragging.

###### Moving Around and Selecting

A long horizontal sliders seeks within the waveform. The zoom level is controlled by the vertical slider at the right edge of the display area. Buttons zoom to the entire audio sample or to the selected region. The left and center mouse buttons can be used to select an area of the waveform. The select all button selects the entire waveform.

###### Operating on the Selected Region

Once a region of the waveform has been selected, it can be transformed. The Cut button removes a section of waveform to the buffer manager. Copy leaves the waveform untouched and copies the selection to the buffer manager. Kill replaces a segment with silence. Replace swaps the selected data with a waveform from the buffer manager. Insert Before and Insert After paste a buffer next to the selection. Reverse reverses the selected audio data.

###### The Beat Calculator

To make full use of GDAM's beat information-aware features, you must determine the beat information which describes your favorite songs. The primary tool to assist with this task is the beat calculator. Given an estimation of the bpm and firstbeat location for a song, the beat calculator will graphically display predicted beats over a picture of the waveform. These can be stretched and moved until (if possible) the bars correctly predict each beat.

The beat calculator looks like this:

Annotated Beatcalc Screenshot

Waveform Display

  Here is displayed a picture of a section of the song, overlaid with bars where beats are predicted. Songs can be dropped onto this area in order to load them. Left-clicking near a beat line will relocate it to the position of the click by adjusting the bpm slightly. Clicking while shift is depressed will relocate the nearest beat line by shifting the location of the first beat slightly. Control-click will set the location of the first beat. The second mouse button can be used to highlight a section of the song (not shown), which can then be replayed. This aids you in identifying features within the sound.

Zoom Level

  Used to zoom in on / out from the song. Examining the song up close makes it possible to identify features by sight, and perfect the accuracy of the beat information.

Load From Song Selector

  The circular button opens the song selector, and the arrow button imports the currently selected song from the song selector, and begins it loading.

Load From Disk

  Rather than loading from the song database, any song can be loaded from disk.

Play Selection

  The PLAY and STOP buttons can be used to hear a portion of sound. If a portion of sound is selected, that portion will be played. Otherwise, the song will be played from the current position.

Estimate BPM By Tapping

  To get a good first estimate of the tempo of a song, click the tap button in time with the music. The bpm value (calculated since the time of the first tap) is displayed, and you can start over by pressing the reset button.

Update Database

  Once you are satisfied that the current beat info provides an accurate description of the song's rhythm, use the Update Database button to write the information to the song database. Don't forget to save the database (in the song selector) before quitting, so that you will forevermore be able to have full control over this song.

Current Beatinfo

  The bpm and first beat fields hold the current values being used to draw beatlines on the waveform. These values can be set here, although fine adjustments will most likely be made with the mouse on the waveform display.

Position

  This slider controls the position within the song which is displayed in the center of the waveform display. When you are zoomed in very close on a song, you'll have to click in the trough and arrows to get fine enough position control.

Help

  Like most components, the beat calculator has online help which can be launched by clicking on the button with the question mark.

###### Beat Calculator Example

To make full use of GDAM's beat information-aware features, you must determine the beat information which describes your favorite songs. The primary tool to assist with this task is the beat calculator. Given an estimation of the bpm and firstbeat location for a song, the beat calculator will graphically display predicted beats over a picture of the waveform. These can be stretched and moved until (if possible) the bars correctly predict each beat.

This is a step-by-step journal of using the beat calculator to find firstbeat and bpm values which describe a song.

1. Find a promising song, and drop it onto the beat calculator. Alternately, use the arrow button to import the currently selected song from the song selector. After a short delay, an image of the song's waveform is displayed.

   Beatcalc Example Pic 1

2. I use the middle mouse button to set the position marker (vertical red line) near the beginning of the song. I press play, and listen for the first measure of the song. Noting the time (five and a half seconds of introduction on this track) i begin to click on the tap button in time with the music. After a minute or so, the bpm value given by the timing of my taps has closed in on a reasonable first estimate.

   Beatcalc Example Pic 2

3. I enter my first guess at the tempo of the song and the location of the first beat. Yellow bars appear on the image where beat locations are predicted. I zoom in close to the first beat, and play the song from there. This time, i can hear a clicktrack marking the locations of the beat lines.

   Beatcalc Example Pic 3

4. A closer look supports what my ears told me: the beats are predicted a little early of their actual location.

   Beatcalc Example Pic 4

5. I control-click on the actual location of the first beat, and the bars jump into alignment. I can hear the clicks move much closer into synch with the music.

   Beatcalc Example Pic 5

6. Moving further into the song, I see that my bpm estimate is too high; the clicks are getting ahead of the music.

   Beatcalc Example Pic 6

7. I left-click on precise beat locations, and the bpm value is nudged down so that the beat lines fall on my mouse press locations.

   Beatcalc Example Pic 7

8. I continue through the song, improving the bpm estimate, until i reach the end.

   Beatcalc Example Pic 8

9. I return to the first beat, zoom in closer, and make another pass through. Shift-click is used to shift the first beat location slightly without disturbing the bpm value. I also verify that the clicks are reasonably accurate throughout the entire song. When i'm happy with the values, i use the update database button to write the bpm and firstbeat data into the database. I'll save the database so the data will forever be available.

   Beatcalc Example Pic 9

###### The Sequencer

First, use must produce some samples to sequence. Open the "Sample Picker" and "Buffer Manager" and select some .WAV files somewhere. Select one of them in the buffer manager.

Then, clicking on the sequencer's background area should yield a circle. If you press the Play button you should hear that sample play repetitively.

You may select different samples in the buffer manager.

To move a sample, drag it with the mouse.

To delete a sample, right-click on it.

To move a bunch of samples, select them with the middle-button, then they all drag as a unit. You can use shift to copy.

By default, the vertical axis represents volume. By pressing the By Resample Rate button, the vertical axis will represent the frequency (that is, pitch). In this mode you can compose limited melodies.

You may enter a filename in the entry box between the Save and Load buttons. Then when you press the Save button the sequence will be saved to that file.

A playing sequence can be altered by tapping in time on a gui button, a keyboard key, or a MIDI keyboard. In the first two cases, the pitch and volume of the new samples will be the current default pitch and volume. In the last case, the pitch and volume will be determined by the MIDI input (i.e., which key was pressed and how hard.) MIDI input must be enabled and the correct channel selected for this to work.

###### Overview of Beat Matching in GDAM

This document is an explanation of beat matching in GDAM. See gdam.org for more information.

In addition to complete control over position and speed, GDAM can make use of meta-information about the song. This data must be entered manually by the user once, and resides in a database which GDAM references (`~/.gdam/song.database` is a common location.)

Currently, two values are used to describe the beat information of a song - the tempo (beats per minute) and phase (location of the first beat.) Knowledge of the tempo allows the user to automatically resample songs so that they will play in time, seek around within a song by even beats, and coordinate many effects to fit with the song. Knowledge of both the location of the first beat and the bpm allows GDAM to extrapolate the location of every single beat. This can then be used to force songs to play in time with eachother, ensuring that the beats overlap nicely.

Several tools exist to help one build their song database. The Database Builder is accessible from the song selector, and uses find and/or locate to add mp3 files to the database. The Beat Calculator graphically displays the waveform of a song, and draws lines where beats are predicted. The user can then stretch and move the beats until (if possible) they accurately describe the position of every beats. Chunks of the song can be highlighted and played back for orientation. In addition, a click track is played in time with song. One can hear the effect of adjusting the beat information instantly, and audibly verify the accuracy of a song's beat information. The volume of the click track can be adjusted. Once satisfied, the user can update the database with the song's info, and then save the database.

Collecting beat information takes a little practice, but will soon become easy. The impact of a beat is percieved when the waveform jumps from low amplitude to high amplitude, where the slope is the greatest. Percussion often stands out from the surrounding music as a strong nearly-vertical boundary between a looser, lower-frequency waveform and a more dense clump representing the high frequencies of, say, a snare hit.

Some songs will drift or change tempo over time. A more descriptive system of describing beat information will be introduced in the future to account for these cases. For now, use beat info as a guidline if you wish. Note that a song may display small local drift when zoomed in upon which is not apparent when listened to.

###### `gdamcli`: Command Line Interface to the GDAM Server

###### Running `gdamcli`

`gdamcli` is a barebone text interface to the `gdam-server`. It is useful for

- writing test code.

- scripting (and hence batch processing).

- very primitive interface to everything gdam can do.

    	gdamcli
    	--gdam-server host:port
    	--device device

    	     script_name
    	     -e "command"

`Gdamcli` is a command line interface which allows one to examine the state of the mixer, and adjust sources by hand. `ls $mixer` returns a list of sources attached the top level mixer. `detach n` removes source n from the mix (useful if an unwanted song is somehow playing on the server.) `ls n` returns info about source n. `set n arg value` sets argument arg to value for source n. Each source has its own set of arguments, which can be determined by `ls`'ing it.

If no script_names or commands are given, `gdamcli` enters into "interactive mode" much like many shells. Commands and script_names are useful for automated tasks.

###### `gdamcli` Command Summary

Here are most of the commands:

-     ls

      -a
      -R
      source_id

  ls - list (or print) soundsources. The source_id's may be those returned by subsource creation routines, or may be determined by `ls` or other means.

  Options:

  -a

    show all arguments

  -R

    recurse -- print the entire tree. usually `ls` shows just one layer: this makes it ascend the entire tree.

-     silence
      mixer_id

  silence - remove all sound sources for a device. Defaults to the mixer for the default device.

-     mixer

  mixer - return the default mixer id number. This is the source id to `ls` and the default mix_id for `add`.

-     device
      device_id

  device - return the default device id number.

-     source
      name
      GdamSourceType

        arg_name
        arg_value

  source - create a sound source. Creates a new source named the specified variable name, and sets the specified arguments. The source is generally then set as another's child or `add`-ed to the mix.

-     set

         source_id
         $variable_name

         arg_name
         arg_value

  set - set a source's arguments. TODO: finish writing.

-     detachid

  detach - orphan a sound source. This causes the source id to stop feeding whatever it is feeding. It usually dies thereafter (unless it is not attached or is still otherwise accessible).

-     add
      source_id
      source_id

  add - add a source to a mixer. Add the given source to the given mixer (or the default mixer if no mix is specified).

-     helptopic

  If no topic is specified, a list of topics is printed.

help - online help TODO: write me!

###### `gdam123`: Command Line Mp3 Player

###### Running `gdam123`

`gdam123` is a command line utility to play mp3 files on a gdam server. It takes a list of mp3 files, and emulates `mpg123`'s ^C handling. In addition, `gdam123` features a healthy set of vi key bindings and playlist handling features.

    	gdam123
    	--gdam-server host:port
    	--device device
    	-z

    	     filename

    	     directory

    	     playlist

Mp3 files, playlists, directories, and gdam song databases can be given on the command line. Playlists are files with some lines which are paths to mp3 files. If any path is not absolute, then the path to the playlist is prepended. If a directory is given, then any mp3 files within that directory will be added. Each directory will be sorted according to playlist or ccdb data files which exist in that directory. Subdirectories are recursively processed. If `-z` is given, the playlist is shuffled before playback.

###### Key Bindings

Most of these keys can be preceeded by a number, which usually means to apply the command that many times.

###### simple `gdam123` key bindings

key action j,k skip to next/prev song nG skip to nth song. G skips to last song, h,l seek back/forward a beat, or a second if bpm is unknown [,] seek back/forward a bar, or four seconds if bpm is unknown ^ seeks to beginning of song n| skip to nth second i pause/unpause song o,p decreases/increases volume by delta%, default 10% O,P set volume to 0%, 100% z shuffle playlist r toggle repeat mode n repeat last search N repeat last search, in opposite direction ^G (control-g) print extended information about the current song. Info includes length, sampling rate, and id3 tags. q quit `gdam123`

###### Ex-Style Commands

Gdam123 also accepts ex-style input. A colon(:) initiates an ex command, which can be seen as it is entered. `:help` produces a full list of key bindings and ex commands. `:a filename` appends a file to the playlist. Directories and playlists can also be appended.

###### ex-style `gdam123` key bindings

command action :volume n set volume to n%. Volumes above 100% are allowed. :set volume_delta delta changes the effect of a volume nudge to delta%. Affects o,p key bindings. :print print playlist. :append filename if filename is an mp3 file, it is appended to playlist if it is an mp3 file. If it is a playlist, the contents are added. If it is a directory, the subdirectories are sourced for mp3 files. :n skip to the nth song.

###### LADSPA Support

###### Ladspa Plugins

LADSPA is a relatively new simple audio plugin architecture. This standard is open, and aims to enable linux audio applications to share audio plugins. GDAM has preliminary support for both loading LADSPA plugins and creating them from mininetwork layouts.

###### Installing LADSPA

- Download the LADSPA SDK, available online

- Copy `ladspa.h` to `/usr/local/include`.

Note: if compiling, you must do this BEFORE you configure GDAM - otherwise it will automatically compile without LADSPA support. You'll need to remove `config.cache` and reconfigure... best to start with a fresh copy of the source.

The binary distribution packages should always include LADSPA support. However, even with the packages, you will need `ladspa.h` to compile new plugins.

###### Installing `ladspapluginmaker`

The latest version of `ladspapluginmaker` is available on the web at gdam.org, in the download section. Source tarballs, rpms and debs are available.

###### How to Write LADSPA Plugins Using GDAM

###### Overview

The procedure has two steps:

- Create a flow graph graphically using GDAM (inside the mininetwork filter). Save it to XML.

- Convert the XML to a LADSPA plugin using `ladspapluginmaker`. Usually this will convert the xml to C code, then it runs the compiler.

###### Using the Mininetwork

The mininetwork has many types of "nodes" which you can create, delete, and connect.

Here is the example we will use throughout:

Screenshot of the Mininetwork Widget

This actually sounds like a plucked string filter. (I'll describe it a bit more below).

You can see it contains a bunch of nodes which are connected. You can drag them around, and drag pipes from inputs to outputs. Here are exactly what the various mouse buttons do:

left mouse button:

  If you clicked on a node's input or output, you may drag a pipe to another node's input or output. (you must connect inputs to outputs though!). If you clicked on a node, you may drag it, and it will be selected. When it is selected, a menu of adjustable parameters appears. (eg for the gain filter, a gain slider appears in that window.) If you clicked outside a node, a new unconnected node is formed.

middle mouse button:

  If you clicked on a node, it is deleted, but its inputs are attached to its outputs. If you clicked on a pipe, a new node is formed in the middle of the pipe, properly connected.

right mouse button:

  If you clicked on a node, it and all its pipes will be deleted. If you clicked on a pipe, it will be deleted.

The inputs to each node are on the top of the node -- each node has only one output, but you can connect an arbitrary number of things to that output.

Here are some common nodes:

Mix

  This just adds all its inputs together.

Modulator

  This multiplies its inputs like a ring modulator. Or equivalently it is a variable gain.

Constant Gain

  This multiplies its single input by a constant value. [in the gui, you can change the constant, but it is constant once it is converted to a LADSPA plugin].

Constant Delay

  This delays its input for a certain number of samples. [in the gui, you can change the constant, but it is constant once it is converted to a LADSPA plugin].

Variable Delay

  This delays its input for a number of samples, which is computed from another nodes output.

  The actual delay at any time is given by:

  delay = (base_delay) + (delay_fluctuation * input_value)

  where the input_value is from the delay-input (which is the top-right connector on the variable delay).

Input

  This represents where sound is input to the filter from the source above it. You cannot create new inputs or destroy the existing one.

Output

  The output from the filter. You cannot create new outputs or destroy the existing one.

###### Brief Digression into the Plucked String Filter

The plucked string is basically a feedback of the tuning frequency with a lowpass filter.

- In the upper-left corner, the input is revolumized (by a modulator) with a control node (at left). This implements the input gain slider.

- In the mix in the center is the mix which is collecting feedback.

- The right side is the feedback loop. It is revolumized to control how loud the reverb should be.

- The two lower-right nodes implement a very simple lowpass filter that just averages the last two samples.

This is usually called a Karplus-Strong string filter.

###### Saving the New Filter

You just press the save button, at the left. It will prompt you for a filename -- you'll have to specify it in the next step.

###### Converting the Filter to a LADSPA Plugin

Suppose you saved the mininetwork as pluckedstring.xml. Then you would run the following command:

    	ladspapluginmaker --input pluckedstring.xml \
    	                  --output output_dir \
    			  --class PluckedString \
    			  --basename pluckedstring \
    			  --description "Karplus-Strong Plucked String" \
    			  --unique-id 10 \
    			  --build

The `--unique-id` option deserves brief mention. Currently all plugins are centrally allocated by talking to Richard Furse, richard@muse.demon.co.uk. He will assign you a list of UniqueIDs. In the interim, you can use ids less than 4000 for development purposes.

(TODO: put more of these options in the xml!)

This will create a directory `output_dir` with three files in it:

- `output_dir/pluckedstring.c` - the c file implementing the plugin (online)

- `output_dir/pluckedstring.h` - the h file with the instance structure (which is named PluckedString) in it. Available online.

- `output_dir/pluckedstring.so` - the library we obtained by compiling the above source files.

###### Loading LADSPA Filters with GDAM

GDAM automatically scans for LADSPA plugins when it starts up. It looks in `/usr/lib/ladspa` and `/usr/local/lib/ladspa`. It will write a summary file to `~/.gdam/ladspa.xml`.

This is what the loaded plugin looks like:

Screenshot of the Compiled Ladpsa Plugin

###### Hardware Input Support

###### Hardware Input in GDAM

GDAM supports hardware input in a few ways. Midi devices, auxilliary keyboards, and ultrasonic rangefinder input plugins exist already. As of writing, only gui components make use of hardware input, but it is implemented on a lower level, so other clients may support it in the future.

You can get started immediately: open the midi selector and then open a gain widget. It should have a MIDI button once the selector is opened. Depressing that button with the mouse, which wiggling a midi knob will automatically attach the gain's volume to the knob.

You can also specify more information about your device. Then the messages will be more readable, and that is the only way to trap "System Exclusive" messages.

NOTE: hardware input has been rewritten as of version 0.922. Changes include unification of hardware input methods, and the ability to assign a set of bindings to a component by reading an xml file.

GDAM supports midi hardware input. Through plugins, other hardware input devices (i.e. sonic rangefinders) can be supported. Hardware input devices are cool because they transcend the clumsy mouse-and-keyboard interface most computer users suffer. For instance, midi sliders allow a user to vary several parameters simultaneously. Also, hardware input assignments don't obey window focus the way a computer's normal keyboard does, and will continue working regardless of what application the user may be mousing around in. Additionally, hardware input devices allow the operator to spend less time hunched over a monitor.

###### MIDI Controllers

GDAM can make use of many knobs, sliders, and pitch wheels found on midi keyboards. If your hardware offers a mode of operation where all controls emit "continuous controller" type messages (most often used for interfacing to computer sofware) select that. GDAM may not be able to use all system exclusive and nonstandard messages. For midi input to work, several files must be in place describing the device. create a file `~/.gdam/input.devices` with entries as follows:

    /dev/midi /home/geoff/gdam/skin/midi/roland-jp8000.xml GdamMidiDevice

listing each device, the patch description file (or "none"), and the corresponding gdam class. The patch file contains descriptions for different input mechanisms, as shown here:

    <Gdam-Trap-Descriptions>
      <trap>
        <description>funky pitchwheel</description>
        <GdamMidiEventPitchWheel>
          <input_id>0</input_id>
          <device>/dev/midi</device>
        </GdamMidiEventPitchWheel>
      </trap>
    </Gdam-Trap-Descriptions>

The default input.devices file contains a generic entry which should allow instant use of many midi devices... just open `/dev/midi`. See the links section for commercial midi controller devices.

###### Ultrasonic Rangefinders

A friend of mine hacked a parallel port interface to a few ultrasonic rangefinders. GDAM supports these devices as midi input via a plugin. Thus, we can control aspects of the sound by moving our hands through space. This interface was originally developed for the Texas Instruments Calculator Based Rangefinder:

Picture of CBR Rangefinder

Pasco scientific equipment offers a compatible model which performs much better:

Picture of Pasco Rangefinder

Once we've reconstructed the hardware a bit, we will most likely post instructions here so that others can try it out. The `input.devices` line describing a rangefinder looks as follows:

    /dev/rangefinder none GdamRangeFinder

###### Secondary Computer Keyboards

A recent development, secondary keyboards may be the easiest way for the greatest number of users to add hardware input, because the requirements are slight. Because I have my mouse on a ps2-to-serial convertor, I have a free ps2 port on my computer. I can attach a second computer keyboard to this port, and open it as a hardware input device in gdam. I can then use keys on the second keyboard to control gdam, without worrying about window focus, and while simultaneously using the normal keyboard for whatever I need. Perhaps better than a standard keyboard would be a bank of 10-key pads, one for each turntable... if i get a USB port, i'll look into it. The default `input.devices` file contains a line:

    /dev/psaux none GdamPs2Keyboard

which should allow any user with a second keyboard on /dev/psaux to make immediate use of it.

###### Dynamic Input Assignment

Many components have buttons labeled midi or m adjacent to adjustments. These are used to assign hardware control over that adjustment (or rather, the value which that adjustment controls). While holding the button down with the mouse, move a midi slider or other device. From then on, that device will have control over the corresponding value. An adjustment can be freed from control by right clicking on the m button. These buttons will only respond to their most recent dynamic assignment, but a piece of hardware can control several different adjustments. This method of assignment is useful for quickly adding control to a newly created filter, or reassigning some unique input device like a ribbon pad or rangefinder.

###### Input Binding Files

Sets of hardware input bindings can be read from an xml file and applied to a component. This is useful for, say, assigning one of five standard keybinding sets to a new turntable; in one simple step, an entire row of keyboard buttons can be set to control all the iconated buttons.

###### Binding File Format

A gdam hardware binding file looks like this:

    <Gdam-Binding-Interface>
      <constant>
        <argument>seek_by_bars</argument>
        <value>2</value>
        <GdamPs2KeyboardPress>
          <key>c</key>
          <device>dev/psaux</device>
        </GdamPs2KeyboardPress>
      </constant>
    </Gdam-Binding-Interface>

The file is a list of bindings between Gdam-Binding-Interface tags:

    <Gdam-Binding-Interface>
      [binding]
      [binding]
    </Gdam-Binding-Interface>

###### Binding Descriptions

Each binding is nested between tags describing the type of input behavior, and contains a comonent argument and corresponding values(s). The "constant" type of binding causes an arg to be set to a specific value. Allowed values vary depending on the component argument being manipulated... boolean args can be 0 or 1, float args can vary over an allowed range, and string args need to be certain predefined tokens. The "range" bindings translate a range of midi values to a range of argument values. This cannot be used with a string arg.

The arguments and values which each type of model accepts can be determined by reading the `model/*.c` source files and searching for `gdam_arg_register` function calls. Alternately, you can examine the skin xml files to see how arguments are attached.

The constant binding prototype looks like this:

      <constant>
        <argument>argument_name</argument>
        <value>value to set on input event</value>
        [input event description]
      </constant>

the range binding prototype looks like this:

      <range type="SomeType">
        <argument>argument_name</argument>
        <min_value>min midi value translates to this arg value</min_value>
        <max_value>max midi value translates to this value</max_value>
        [input event description]
      </range>

and the signal binding prototype (which doesn't need an event input description) looks like this:

      <signal type="GdamPacker">
            <signal>whatever</signal>
            <handler>gdam_packer_trap_key_press:e:tt1:gdam_skin_arg_int:play_or_synch:-1</handler>
      </signal>

Either tag can take a `type` arg, causing the binding to be applied only to components of a certain type. This allows a single file to contain bindings for a variety of components, and each component or skin sourced will apply only the bindings which are relevant to that type. The following attaches only to turntables, and causes the turntable to play when the specified event happens.

      <constant type="GdamTurntable">
        <argument>play_or_synch</argument>
        <value>3</value>
        [input event description]
      </constant>

And the following unmutes a gain component.

      <constant type="GdamGain">
        <argument>muted</argument>
        <value>0</value>
        [input event description]
      </constant>

###### Event Descriptions

An input event description identifies a particular event on a particular device. When input device events are caught from opened devices, they are added to the midi device manager gui. The description printed there should contain enough information to create event binding descriptions.

The exact prototype of an event description varies depending on the type of event trapped. The basic form is as follows:

        <EventType>
          <event_param>value</event_param>
          <other_event_param>other_value</other_event_param>
        </EventType>

This is a description for pressing the 'q' key on a ps2 keyboard attached to `/dev/aux`. It is appropriate for driving a constant argument binding:

        <GdamPs2KeyboardPress>
          <device>/dev/psaux</device>
          <key>q</key>
        </GdamPs2KeyboardPress>

The following traps the note off event for note index 24 (octave 1, note c) on midi channel 0 (which will most likely be labelled '1' on the hardware).

        <GdamMidiEventNoteOff>
          <input_id>0</input_id>
          <midi_index>24</midi_index>
          <device>/dev/midi</device>
        </GdamMidiEventNoteOff>

The following traps a midi sysex string of a certain value. 'System Exclusive' messages are used by hardware manufacturers to extend the midi protocol in various ways. Switching instruments, modes, patterns, and waveforms will often cause midi sysex strings to be emitted. The only parsing available is to match a hex string, as printed in the midi device manager gui when the event occurs.

        <GdamMidiEventSysex>
          <sysex>0x01 0x02 0x03 0x04</sysex>
          <device>/dev/midi</device>
        </GdamMidiEventSysex>

The following catches midi set-parameter events (parameter events are most often emitted when a knob, slider, ribbon bar or other continuous controller is adjusted). This type of event is appropriate for controlling a range-type arg. If used with a constant argument binding, the arg's value will be set to that constant anytime the midi parameter changes. This is most likely not the desired behavior. 'input_id' is the midi channel being monitored, and 'parameter' the continuous controller index (ie which slider);

        <GdamMidiEventParameter>
          <input_id>0</input_id>
          <parameter>3</parameter>
          <device>/dev/midi</device>
        </GdamMidiEventParameter>

Midi pitchwheels, used to bend the pitch of a midi note by a sub-half-step interval, emit a different range of values than parameter sliders. For this reason, they require a special binding.

        <GdamMidiEventPitchWheel>
          <input_id>3</input_id>
          <device>/dev/midi</device>
        </GdamMidiEventPitchWheel>

###### Example Input Binding Files

When you have a new piece of midi hardware, and want to use it with gdam, you usually follow a simple procedure. Plug the device into `/dev/midi`, run `gdam-launcher`, and open the midi selector. Type `/dev/midi` into the device entry, and press open. Play with the device, and watch which controls produce new events in the event list. Decide what controls are available, what you want to use them for, and what xml is needed to describe this binding.

###### Boss Dr Rhythm DR-660

This is a small drum machine, with 16 drum pads. It has the ability to play back midi tunes, but we're not interested in that. What is useful to us is that the 16 drum pads emit note-on and note-off events, each pad a different note. Furthermore, there is a 'pad bank' button which cycles through sets of pad-to-note bindings. If we carefully program to pad banks so that there are no conflicting note values, we could control 32 or 48 or 64 different events with the unit. When i open the device in the midi selector, and tap the first two drum pads, i get the following new events:

    note on, channel 9, c# octave 3, idx=49
    note off, channel 9, c# octave 3, idx=49
    note on, channel 9, a octave 3, idx=57
    note off, channel 9, a octave 3, idx=57

I notice that even if i press and hold a drum pad, a release event immediately follows the press event. This is unfortunate because the pads can only be used as event triggers, not as momentary-on buttons. I decide to use the first two pads to seek backwards in a turntable by one and two bars respectively, and to write a binding file which i can source on a set of wheels. From looking at `wheels-hotkeys.xml` and other input binding files, i know how to make a binding associate with the left turntable of a set of wheels, addressing it by name. The following xml file implements these two bindings.

    <Gdam-Binnding-Interface>
      <constant type="GdamPacker:tt1">
        <argument>seek_by_bars</argument>
        <value>-2</value>
        <GdamMidiEventNoteOn>
          <input_id>9</input_id>
          <midi_index>49</midi_index>
          <device>/dev/midi</device>
        </GdamMidiEventNoteOn>
      </constant>
      <constant type="GdamPacker:tt1">
        <argument>seek_by_bars</argument>
        <value>-1</value>
        <GdamMidiEventNoteOn>
          <input_id>9</input_id>
          <midi_index>57</midi_index>
          <device>/dev/midi</device>
        </GdamMidiEventNoteOn>
      </constant>
    </Gdam-Binding-Interface>

###### Roland A-30 Midi Keyboard Controller

This is a full-sized midi controller keyboard with a pitchwheel, an expression lever, and one slider. The slider can be assigned to any parameter value, so it could be reused to control more then one value. The expression lever emits parameter one, and is activated by pressing upwards on the pitch wheel lever. Exercising these controls in `gdam-launcher` produces the following new events.

    note on, channel 0, e octave 4, idx=64
    note off, channel 0, e octave 4, idx=64
    note on, channel 0, f octave 4, idx=65
    note off, channel 0, f octave 4, idx=65
    note on, channel 0, f# octave 4, idx=66
    note off, channel 0, f# octave 4, idx=66
    pitchwheel, channel 0
    parameter 1, channel 0
    parameter 56, channel 0

The keys emit seperate press and release events, so they can be used as momentary-on buttons. I decide to use the first note to mute the gain on the left turntable; when i depress the 'e' key the gain will be muted, and when i release the gain key the volume will be restored. At the same time, I'll have the data slider control the volume of the left turntable. The following xml does the trick:

    <Gdam-Binding-Interface>
      <range type="GdamPacker:gain1">
        <argument>volume</argument>
        <min_value>0.0</min_value>
        <max_value>2.0</max_value>
        <GdamMidiEventParameter>
          <input_id>0</input_id>
          <parameter>56</parameter>
          <device>/dev/midi</device>
        </GdamMidiEventParameter>
      </range>
      <constant type="GdamPacker:gain1">
        <argument>muted</argument>
        <value>1</value>
        <GdamMidiEventNoteOn>
          <input_id>0</input_id>
          <midi_index>64</midi_index>
          <device>/dev/midi</device>
        </GdamMidiEventNoteOn>
      </constant>
      <constant type="GdamPacker:gain1">
        <argument>muted</argument>
        <value>0</value>
        <GdamMidiEventNoteOff>
          <input_id>0</input_id>
          <midi_index>64</midi_index>
          <device>/dev/midi</device>
        </GdamMidiEventNoteOff>
      </constant>
    </Gdam-Binding-Interface>

I'll also use the pitchwheel with a "bend" filter. The bend filter applies a temporary rate change to a song, with the ability to rewind. The 'wheels' guicomponent doesn't have a bender packed in, so i cannot address it by name. However if i create a bender in the filter stack, i can source the following file to have it follow the pitchwheel. I choose the speeds to range from still to double speed. This puts a rate of 100% in the center. As the pitchwheel is spring-loaded to return to its center, this is convenient.

    <Gdam-Binding-Interface>
      <range type="GdamBender">
        <argument>bend_amount</argument>
        <min_value>0</min_value>
        <max_value>1</max_value>
        <GdamMidiEventPitchWheel>
          <input_id>0</input_id>
          <device>/dev/midi</device>
        </GdamMidiEventPitchWheel>
      </range>
    </Gdam-Binding-Interface>

###### Assigning Input Bindings

Components which support binding sets will have buttons labeled with the hardware input icon (a circle with several pins inside) or the word Bind. Clicking on such a button will open a file selection dialog. Select a file appropriate to the type of component and input device (ie `ps2.turntable.xml` to attach a turntable to a secondary keyboard.) The file will be parsed, the hardware device opened if needed, and the bindings applied.

###### Frequently Asked Questions

How do I enable multiple devices with GDAM?

How do I enable multiple devices with GDAM?

Some client can make use of several devices at once. These clients take several devices as arguments:

    	      gdam-launcher --device /dev/dsp1 --device /dev/dsp

The deviceswitcher component allows gui components to be switched between the first and second devices. If you are using more than two devices, you'll have to modify `deviceswitcher*.xml` to contain more device selection buttons.

Additionally you may have to add lines to your `server.config` file:

    	  Device          "oss"           "/dev/dsp8"

where `/dev/dsp8` is the device you are trying to use.

In what ways can gdam use multiple devices?

In what ways can gdam use multiple devices?

With only one sound device, a user has no ability to cue a new track. (ie listen to something which isn't played to the entire room.) In this situation, all sound sources are mixed into a single stream which goes to the device. Continuous mixing can only be done using the automated beatmatching system, which requires knowledge about each song used.

With two sound devices, there are different ways to mix. The first method is to mix the room's sound on one device, and use the other channel for previewing new tracks, setting up loops and sequences, etc. Streams are output to only one device, but which device can be switched on the fly. This allows the user to preview a song playing alongside the current mix, then mute it, switch devices, and fade it into the main mix. However, be aware that sound output by the two sound cards will most likely be slightly out of synch. Thus, one will likely use the automatic beatmatching after switching devices.

An alternate method is use an external, physical mixer to crossfade between two sound cards. One stream is assigned to each device, and new tracks are cued by making one channel audible only on the mixers' headphone output. This allows the user to adjust the speed and position of each stream until they play in synch, and then bring up the room volume of the new channel. Thus, songs can be beatmatched by hand, as with a standard dj turntable setup. A benefit of this method is that beat info isn't required to get a clean mix. If beatinfo is know, it can be used to automatically beatmatch songs across devices. However, the sound output by the two sound cards will likely be slightly out of synch, so the user will most likely need to nudge it slightly for perfect alignment.

There is a further phase of device usage which we are working towards. In this next stage, any stream can be output to multiple devices, with different volumes. This will allow the user to preview a copy of the room mix with a new stream audible only to him. This full cueing capability will allow beatmatching by hand without an external mixer.

How does the beat synching work?

How does the beat synching work?

In short, beat synching works by relying on information about songs read from a database to automatically match the tempo and phase of multiple streams. This information must be determined by a person at some point, probably using tools provided with gdam. Beat synching is optional, to provide users instant, perfect control over their favorite songs. see doc/beatmatching.txt for more information.

Can it automatically determine the beat?

Can it automatically determine the beat?

No, we've never found an algorithm that was fast and accurate enough. We have a link to a paper by Eric Scheirer which is about the best starting point we've found... See gdam.org.

Why are labels/tooltips blank or redrawn improperly?

Why are labels/tooltips blank or redrawn improperly?

If the labels are drawing over themselves without erasing the old text, or tooltips are popping up without text, it is probably because you're using an early, buggy gtk themes package. Upgrade to the latest gtk packages, see gdam.org for details.

Is there an easy way to remove all sound sources from a device?

Is there an easy way to remove all sound sources from a device?

Yes. `gdamcli -e silence` will remove all sources attached to the default sound device. Other devices can be specified with the `--device` flag.

Why is GDAM complaining about not having "Group Audio"?

Why is GDAM complaining about not having "Group Audio"?

In unix, every file and every process is owned by a "user". Also, every file is owned by a "group" and every process can be a member of a number of groups. You can use the "groups" command to see which groups you are a member of.

If you are in the same group or user as a file, you can change or destroy that file. If you are in the same group as a process, you can `kill' that process.

In order to be more secure, by default, GDAM "drops privileges" and runs as user "nobody" and group "audio".

Your system is complaining because you don't have a group "audio". It is recommended you add one.

To add the group run either (as root):

          groupadd audio

or

          addgroup audio

If you do not have either of these commands you should consult your system documentation (you may have to edit /etc/group manually).

You should probably add yourself to group audio:

       usermod -G audio your_username

(You may have to modify /etc/group manually if you don't have that program).

Finally, make the sound devices accessible to group audio:

          chgrp audio /dev/dsp*
          chmod g+rw /dev/dsp*

This should help gdam run securely, even if you start it as root.

Why is GDAM complaining about "DeviceAlias"?

Why is GDAM complaining about "DeviceAlias"?

This is left over from an old feature. Remove all 'DeviceAlias' lines from your server config file.

Why isn't my favorite filter/component available anymore?

Why isn't my favorite filter/component available anymore?

Try running gdam-launcher with the "--define unstable" flag. Features which are under development, or have been found to be buggy, are marked unstable and require this flag to be available. Please note that if you define "unstable" at startup, gdam-launcher may make horrid sounds or seg fault.

How can I get low latency sound without dropouts?

How can I get low latency sound without dropouts?

GDAM opens each sound device with an output buffer. The larger the output buffer, the greater the latency between pressing a button and hearing the result. A smaller output buffer gives a more responive system, but is more likely to suffer dropouts when the processor is busy. The goal is to find a buffer size small enough to feel responsive, but large enough to avoid dropouts under normal use.

The `server.config` file lists the amount of buffer each sound device will be opened with. The amount is given as a number of memory fragments, and the log of the fragment size. Three fragments of base twelve corresponds to 70 milliseconds:

     Message: Set soundcard fragments:  3 frags of 4096 bytes; 0.070s

If the server is feeding several sound cards, it may have trouble keeping up with small buffers.

Running the server as root allows it to run at a high priority, decreasing the likelihood of dropouts. If you don't run the server as root, use a root shell to nice it to -20. This will help prevent other programs from competing for processor time.

A few boot-time options and system tunings can be helpful. Try passing your kernel the 'no-hlt' option at boot. Use hdparm to tune your hard drives, enabling 32-bit transfers and turning on DMA.

Certain hardware can occupy the kernel for long amounts of time, making low-latency sound impossible. When i had an old pci video card, i had to keep the soundcard output buffer at 140ms or greater to avoid dropouts. After replacing it with a new agp video card, i was able to reduce the output buffer to 17ms. I've read that some ps2 mice can occupy the kernel for up to 50ms, but mine doesn't seem to do so.

Low-latency advocates have developed patches for the linux kernel designed to improve low-latency performance. If you are using a 2.2 kernel, try patching with mingo's low-latency patches. If you are using a 2.4 test kernel, try looking for the appropriate patches on the linux-kernel mailing list.

For more information see the low latency mini-howto and the linux audio quality howto.

I'd like to put two sound cards in my linux system.

I'd like to put two sound cards in my linux system.

With the standard kernel code, this can be tricky. You'll probably compile sound support as modules, and insert the cards one at a time with any necessary parameters.

With the commercial OSS drivers from 4front technology, I had no problem getting several cards to work at once. Their configuration utility autodetected and installed all three of my sound cards. Many cheap and a few professional cards are supported. A basic license costs $20, certain cards require more expensive options.

The ALSA project has developed a free set of drivers meant as a powerful alternative to the standard kernel drivers. Many cards are supported, and the system is designed to support multiple cards without conflict.

An alternative to multiple sound cards is a multi-channel sound card. I get great performance from my Trident 4DWave sound card, which features seperate front and rear stereo outputs. A benefit to a card like this is that the timing of two channels, and the devices which feed them, is identical... they will not drift or be read from at different times. One aspect of using this card is that i have to adjust the front and rear volumes of my sound devices by hand each time i restart the gdam server.

I'd like to use the front and rear outputs of my four-channel soundcard.

I'd like to use the front and rear outputs of my four-channel soundcard.

Those with SoundBlaster Live or Trident 4DWave cards can use your rear output for an independent cue channel. Currently This is only possible with ALSA drivers. See "Supporting Four-Channel Soundcards In GDAM" in the user manual.

Why don't I see MIDI control buttons in my filters?

Why don't I see MIDI control buttons in my filters?

To keep things simple for users without midi devices, filters will be created without midi-related buttons unless the Midi Selector has been opened.

I only have one sound card. Can use the left channel for the main mix and the right channel for cueing?

I only have one sound card. Can use the left channel for the main mix and the right channel for cueing?

With gdam-0.938 and later, try `gdam-launcher --define mono_cue` The usual device-switching controls will move sources between the left and right channels.

GDAM is too confusing!

GDAM is too confusing!

With gdam-0.938 and later, try `gdam-launcher --define simple` Advanced and uncommon controls will be hidden.

How can i exactly match tempos?

How can i exactly match tempos?

Most tempo displays are drag-n-drop sources and destinations. Use the right mouse button to drag the desired tempo onto a tempo of a different value. The destination will change its resample rate to match the dropped value. Alternately, double-clicking a tempo label will match the tempo of the anchored turntable.

###### Troubleshooting

###### Common Problems and Solutions

###### GDAM Won't Compile?

if it complains thusly:

          /usr/lib/libglade.so: undefined reference to `xmlSAXUserParseFile'
          /usr/lib/libglade.so: undefined reference to `xmlSAXUserParseMemory'
          collect2: ld returned 1 exit status

then you are most likely using libglade-0.11 with an old libxml. try the packages from our web page, or the most recent version.

###### GDAM seg faults?

run it in debug mode, (the `--debug` flag does this) with a large terminal history. page up to find the first of the spewage.

- If you get messages like "error, placeholder in xml file" trying upgrading to libglade 0.11 or higher

- If you get invalid casts to GDAM types... then maybe you aren't linking with the most recent version of the libraries; then perhaps you haven't made clean. or, if you have installed an earlier version of gdam, the libraries may be hanging around on your system causing conflicts. Try removing `/usr/local/lib/libgdam*`. and remaking. If you make often in `/home/joe/gdam/`, and run `/home/joe/gdam/server/gdam-server`, then add `/home/joe/gdam/lib` to your `LD_LIBRARY_PATH` to ensure you always link with the correct version. `echo $LD_LIBRARY_PATH` and make sure that no other libgdam binaries will be found before the correct one.

- If gdam seg faults when creating skin, and the above does not help, perhaps libglade doesn't work on your machine. try compiling the libglade demo program:

            % cp /usr/doc/libglade-devel-0.11/examples/test-libglade.c .
            # edit test-libglade.c to delete the line
      	    #include <config.h>
      	    (line 44)
            % gcc -o test test.c `libglade-config --libs --cflags`
            % cp /usr/doc/libglade-devel-0.11/examples/test.glade .
            % ./test test.glade

  if it seg faults, then libglade is unstable for you. sorry. look for a newer version.

###### GDAM Server Stalls on Play?

If clients can connect to the server, but position indicators stay at 0:00, try adding the `fork` option to the appropriate device in your `server.config` file. Buggy drivers may require this option. Also, run `/sbin/ifconfig` and make sure you have an interface for localhost.

###### GDAM Outputs Loud Static?

If `gdam-server` outputs loud static, perhaps the sound card requires that the byte ordering be switched. On some mac notebooks, this is the case. Add the `wrong_endian` flag to the appropriate device in your `server.config` file.

###### GDAM Can't Load Plugins?

again, check that your `LD_LIBRARY_PATH` is correct. Also, make sure that you aren't accidentally running old gdam libraries. Previous versions installed binaries in `/usr/bin`. These are no longer useful, and should be removed. In debugging mode, gdam will note each attempt to open a plugin module, and the manner in which each failed to load. Perhaps you will find a message about a permissions problem, an unresolved symbol in the module, or see that gdam isn't looking any place where your modules have been installed. Cut and paste relevant information into mail to the gdam-user list or one of the authors for help.

###### Executable and Plugin Versions Dont Match?

GDAM plugins are compiled with version numbers, and these version numbers are checked when plugins are loaded. If the plugin's version doesn't match the executables, GDAM will complain as follows:

    ** WARNING **: the module gdamspin.c is compiled for version 0.930;
    			but lt-gdam-launcher is compiled for 0.929

If you have been compiling from a copy of the CVS source, it is possible that the release number has changed, but the plugins haven't needed recompiling. In this case, the warning is nothing to worry about, and making clean will ensure all plugins have the same version number. If this is not the case, then you're probably loading old plugins which wont work properly and might crash. Again, check that your `PATH` and `LD_LIBRARY_PATH` don't point to old executables , libraries, or plugins.

###### Reporting Problems

If you continue to have trouble getting GDAM to run, please email the authors. Include details on which release, whether it was precompiled or a source distribution, if you use OSS or native ALSA, and the results of running the program(s) with the `--debug` flag. We'll attempt to explain the problem, and/or fix it in future releases.

###### GDAM's Security Model

Security of your system is very important. GDAM grants permission to many resources: it uses memory, disk, cpu and sound devices.

We've added a feature to let you connect to the server without listening on any port; this happens automatically if you run `gdam-launcher` when no server is running. This is a relatively safe mode of operation.

Currently there are few checks in place for attacks based on using up all available memory, disk or cpu. If you care, use ulimit or nice to change the amount of resources gdam has available to it.

However we've attempted to limit control in two ways:

- the authenticator - this grants access to a user for certain priviledges

  currently we don't have a useful authenticator in GDAM. If you want to help us write one, please contact us.

- access to the users system is available by: querying and reading files, writing to the disk, reading and writing from sound devices, loading plugins in the plugin directories, potentially unlimited use of cpu and memory.

So how do you make a gdam-server fairly secure?

- set the user to nobody and the group to audio.

- make your audio devices readable or writable by group audio (`chgrp audio /dev/dsp*; chgrp audio /dev/dsp*`), and not by the anonymous user (`chmod o-rwx /dev/dsp*`).

###### Root and Realtime

- Running `gdam-server` as root allows you to run it in `--realtime` mode. This allows gdam to consume all the resources on your computer, and potentially get very low latency in conjunction with the `numfragments=` and `logfragsize=` server config options.

- gdam will drop permissions when run as root, but in still runs realtime. this means it can entirely crash your computer if it gets confused or too far behind. we recommend running non-realtime mode (or maybe just increasing the priority using `renice`).