----------------------
mhWaveEdit README file
----------------------

mhWaveEdit is a graphical program for editing sound files. It is completely free
(GPL).

You can find the latest release of mhWaveEdit at:
http://www.mtek.chalmers.se/~hjormagn/mhwaveedit.html


------------
Installation
------------

 * Unpack the source:                 tar xzf mhwaveedit-1.2.3.tar.gz
 * Go into the source directory:      cd mhwaveedit-1.2.3
 * Run the configure script:          ./configure
 * Compile the sources:               make
 * Install the program:               su -c "make install"


-----------------
Configure options
-----------------

For most people, just using ./configure without any arguments should work fine,
but here are some options that the configure-script supports:

--without-portaudio 
--without-sdl
  
  Specifying this option will leave out the PortAudio/SDL driver, even if the
  PortAudio/SDL libs exist.

--without-libsndfile

  Specifying this option will leave out libsndfile support, even if libsndfile
  is installed.

--with-libsndfile=prefix

  This lets you specify the prefix where libsndfile is installed if it wasn't
  auto-detected.

--with-double-samples

  Use double precision floating point numbers for sample processing. If
  you intend to edit 32-bit files, you should enable this. 
  
--without-check-casts

  This option disables the run-time type cast checking. It makes some parts of
  the program faster, but makes it harder to debug.

--disable-gtk2

  If you have both GTK+ 1.2 and GTK+ 2.0 installed and want to use GTK+ 1.2, 
  specify this option.


--------
Starting
--------

To start the program, simply type mhwaveedit. If you want to, you can specify
files to open on the command line, for example 'mhwaveedit file.wav'.


---------------
The sample view
---------------

The area where you 'see' the contents of the file you are editing, is called the
'sample view'. 

In the sample view there is a grey vertical bar called the 'cursor'. The cursor
follows the sound wave when you play the sound. You can position the cursor by
clicking with the right (2:nd) mouse button. If you do this while you're
playing a file, the playing will continue from the new cursor position. You can
also position the cursor more exact by using the 'Position Cursor...' command on
the Edit menu.

You can place marks in your file by holding down Ctrl and pressing a number 
from 0 to 9. This will place a mark (green vertical bar) with the same number at
the current cursor position. You can later make the cursor go to that position
again by just pressing the number. Setting and jumping to marks can be done 
while playing. To remove a mark, jump to the mark and set it again.


-------
Editing
-------

You make selections by dragging the mouse over the sample view. You can hear
what you've currently selected by clicking on the "play selection" button (the
button with the yellow arrow) or by selecting 'Play selection' from the Play
menu.

You can use the cursor to refine the selection. Use the 'Selection start at
cursor' and 'Selection end at cursor' buttons to move the selection starting
point or the selection end point to the current cursor position.

The 'Cut' and 'Copy' functions work like in any other software. 

The 'Paste' function insert the clipboard contents at the cursor position. The
file you paste into must have the same file format as the file you cut/copied
from. The 'Paste over' function works like 'Paste', except that it overwrites
the data after the insert position. 

The 'Paste mix' function combines the clipboard data with the data at the cursor
position.

The 'Paste as new' function opens a new window and puts the clipboard contents
into it. 


------------------
Keyboard shortcuts
------------------

Ctrl+(number) Set mark
(number)      Goto mark

Ctrl+O        Open file
Ctrl+S        Save file

Ctrl+C        Copy
Ctrl+X        Cut
Ctrl+D        Delete
Ctrl+P        Paste
Ctrl+Z        Undo
Ctrl+A        Select all

Ctrl+G        Position cursor (Go to)
Ctrl+H        Position cursor at file start
Ctrl+J        Position cursor at file end
Ctrl+K        Position cursor at selection start
Ctrl+L        Position cursor at selection end

Ctrl+Q        Selection start at cursor
Ctrl+W        Selection end at cursor


+             Zoom in
-             Zoom out
>             Zoom to selection
<             Zoom all

,             Play from cursor pos
.             Stop


-------
Effects
-------

mhWaveEdit has a few simple effects, which are available from the 'Effects'
menu. 

 * Volume adjust/fade...

   This effect lets you select a starting volume and a ending volume and
   amplifies the selection fading from the starting volume to the ending
   volume. To create a basic fadeout effect, select starting volume 100% and
   ending volume 0%. 

   Note that volumes above 100% may cause sound distortion. Use the 'Find top
   volume' to find out the maximum amplification possible without
   distortion. (You can use this for normalizing samples.) 

   By setting starting volume and ending volume to the same value you get a
   simple amplification of the sound. 

 * Speed...

   This effect changes the speed of the selection. The tone will change as
   well... 

 * Convert samplerate...

   This converts the samplerate of the entire file to one you specify. The
   'linear interpolation' gives smoother sound when increasing the
   samplerate, but has no effect when decreasing the samplerate.

 * Convert samplesize...

   This converts the sample size and sign of the entire file.

   The 'Don't actually change the data' option can be used if the program was
   wrong about the file's format.

 * Mix channels...

   This mixes all channels of the file together to a mono sound.

 * Split channel...

   This copies the first channel to a new channel in the sound, converting
   mono to stereo etc.

 * Combine channels...

   This is a very powerful effect, which lets you create a new sound by a
   linear combination of the old channels. This means you can do channel
   mixing / swapping / balance / panning / amplification etc. by entering  
   different values. For example, to swap the left and right channel, you
   select that the new Channel 1 should be 0% of the old Channel 1 and
   100% of the old Channel 2, and the new Channel 2 should be 100% of the
   old Channel 1 and 0% of the old Channel 2 


-------
Playing
-------

Playing a file is simple, just load the file and press the play button. The
green play button plays from the current position. The yellow play button plays
the current selection, or the entire file if nothing is selected. Stop the
playback with the stop button (with the red square). 

You can do normal editing while the file is playing.


---------
Recording
---------

Recording is done with 'Record...' on the Play menu, or the Record button (the
red circle). A dialog box will pop up where you can select what format you want
to record in. There is a 'Volume test' button that lets you see the volume
of the input signal without actually recording.

Currently it is impossible to play and record at the same time, so the playback
will stop when you record.


-----
Files
-----

mhWaveEdit creates a directory ~/.mhwaveedit where it stores temporary files and
configuration information. 

The temporary files have names of the form "mhwaveedit-temp-<pid>-nnnn". Do NOT
open or remove temporary files with the same pid number as a currently running
mhWaveEdit.

The configuration file is called config. It can be hand edited, but the
easiest way is through 'Preferences' on the Edit menu.


----------------------------------------
Loading and saving in other file formats
----------------------------------------

Even if mhWaveEdit is mainly built for editing wav files, it's also possible to
load and save in a few other formats. mhWaveEdit always supports wav and raw
files, but if it's compiled with the libsndfile library, mhWaveEdit supports a
couple of other formats as well. 

To save a file with a different file format, save it under a name that
does not end with '.wav'. A few other suffixes are recognized directly
(for example '.iff') but if the suffix is not recognized a dialog box
will pop up and ask you in what format to save the file.