simsam - a simple sampleplayer

	Free Software under the GNU GPL (see COPYING)
	
	(c) 2002-2004 Christian Henz (chrhenz@gmx.de)

	Just a small app that lets you load audio samples into slots and play 
	them via MIDI. Audio output is implemented using ALSA or JACK, MIDI 
	is implemented using the ALSA sequencer interface. The alsa/jack code 
	was largely taken from M. Nagorni's alsa howto, jack's simple_client.c 
	and the source for alsaplayer.

	Please let me know of any bugs, comments and feature requests you might
	have. Help on code, GUI, docs and packaging is also most welcome.

Warning:
	
	This is beta quality software. Use it at your own risk.

	See 'Issues' below for known bugs.


Requirements:

  Runtime:

	qt3-mt 		http://www.trolltech.no
	alsa-0.9.x	http://www.alsa-project.org
	libjack		http://jackit.sourceforge.net
	libsndfile	http://www.zipworld.com.au/~erikd/libsndfile/
	libsamplerate	http://www.mega-nerd.com/SRC/

  Compiling:

	*-dev packages for all libs above

	make		http://www.gnu.org
	pkg-config	http://freedesktop.org/Software/pkgconfig

  Compiling from CVS:
 
	automake	http://www.gnu.org
	autoconf


Running:

	usage: simsam [-v][-h][-a output] [file]

	  -v                      show version

	  -h                      display help (this text)

	  -a <output>             select audio output system. Options are
	                          'alsa' (default) and 'jack'

	  [file]                  patch file to load


	After starting the program use an ALSA sequencer utility like aconnect
	to connect simsam to your other MIDI applications.

	The JACK outputs connect to alsa_pcm:playback_1 and 2 by default. 


Keymapping:

	Select a sample in the listbox and then go to the keymapping Window.
	You can assign a note to the selected sample by pressing the CTRL key
	and clicking on the keyboard in the display. Other methods include 
	using the midi note spinbox, or the learn midi function.

	You can change the range of keys the sample is mapped over by pressing
	the SHIFT key and clicking on the keyboard image. Left button will set 
	the beginning, right button the end of the range. Use the mousewheel to
	scroll the keyboard image to the left(wheel up) and right(wheel down).
	
	When setting a new midi note for a sample, the range is reset to that
	one note.
	
	Also, setting a midi note or range will unmap any samples that are 
	mapped on that note or a note within the range.

	Another way to import/map samples is to use drag and drop. Simply 
	pull samples over from your favourite file manager and drop them on a 
	key in the keymapping display. The samples will be automatically added
	to the current instrument and mapped, starting at the key they were
	dropped on.


Mutltiple Outputs:

	Multiple outputs are currently only available with the JACK output
	module. Trying to create additional outputs while using the ALSA 
	output module will give you an error message.

	To add or remove outputs, select Config/Output in the menu. When
	adding an output, you have to name it. The name has to be unique.

	For the JACK module, simsam will then create a pair of output ports
	called name-L and name-R, where name is the given name.
		

Config files:

	On start up, simsam tries to load the file 'settings.xml' in the 
	directory '~/.simsam'.

	Settings in this file will overwrite the hardcoded defaults. Afterwards
	the command line gets parsed.

	See the end of this document for an example with all the default 
	values.

	When the audio output gets initialized, simsam look for the file 
	'outputs.xml' in the '~/.simsam' directory. If it is found, simsam
	will create additional outputs as listed in that file. The default
	output 'main' gets created independently from the file.


Waveform viewer:

	Right and left mouse clicks set start and end points for the sample,
	or the loop, depending on which is activated for selection.

	Use the mousewheel while pressing CTRL to zoom in and out. Mousewheel
	alone lets you scroll left and right. Mousewheel and SHIFT button lets
	you scale the height that the waveform is drawn, this is useful when
	dealing with a low signal.


Issues:

	- Still some inconsistencies in the GUI, some bugs with the new 
	  instrument/output code, some thread/blocking issues

	- Some GUI operations rely on the mousewheel, alternatives will be 
	  added soon.

	- Outputs created in the GUI won't get saved. You have to edit outputs.xml
	  for now.

	- The alsa PCM code doesn't seem to work with the dmix plugin

	- The binary .simsam files from version 0.1.3 and before are no longer
	  supported at all. Please use simsam versions 0.1.4 to 0.1.6 in order
	  to convert them to the new format.

	- The patches rely on absolute paths for the sample files. This means
	  that you cannot easily move them to different machines. Eventually 
	  it will be possible to import all files into one directory and use
	  relative paths.

	- autotools support still basic



Example settings.xml:

--8<--------

<settings>
  <outputMethod>alsa</outputMethod>
  <jackClientName>simsam</jackClientName>
  <jackLeftConnection>alsa_pcm:playback_1</jackLeftConnection>
  <jackRightConnection>alsa_pcm:playback_2</jackRightConnection>
  <alsaPcmDevice>default</alsaPcmDevice>
  <alsaSeqClientName>simsam</alsaSeqClientName>
  <alsaSeqPortName>simsam-midi-in</alsaSeqPortName>
  <alsaBufferLength>1024</alsaBufferLength>
  <alsaSampleRate>44100</alsaSampleRate>
  <samplePath>/home/foo</samplePath>
  <patchPath>/home/foo</patchPath>
</settings>

--8<--------

Example outputs.xml:

--8<--------

<outputs>
  <output>sub</output>
  <output>drums</output>
</outputs>

--8<--------
