1---------------------- 2mhWaveEdit README file 3---------------------- 4 5mhWaveEdit is a graphical program for editing sound files. It is completely 6free (GPL). 7 8You can find the latest release of mhWaveEdit at: 9http://gna.org/projects/mhwaveedit/ 10 11The contents of this file is also available inside mhWaveEdit from the help 12menu. 13 14------------ 15Installation 16------------ 17 18 * Unpack the source: tar xjf mhwaveedit-1.4.24.tar.gz 19 * Go into the source directory: cd mhwaveedit-1.4.24 20 * Run the configure script: ./configure 21 * Compile the sources: make 22 * Install the program: su -c "make install" 23 24----------------- 25Configure options 26----------------- 27 28For most people, just using ./configure without any arguments should work fine, 29but here are some options that the configure-script supports: 30 31--disable-gtk2 32 33 If you have both GTK+ 1.2 and GTK+ 2.0 installed and want to use GTK+ 1.2, 34 specify this option. 35 36--without-portaudio 37--without-sdl 38--without-alsalib 39--without-oss 40--without-jack 41 42 Specifying this option will leave out a sound driver, even if 43 it's libs and headers are found. 44 45--without-libsndfile 46--without-libsamplerate 47 48 Specifying this option will leave out libsndfile/libsamplerate 49 support, even if the library is found. 50 51--with-libsndfile=prefix 52--with-libsamplerate=prefix 53 54 This lets you specify the prefix where libsndfile/libsamplerate is 55 installed if it wasn't auto-detected. 56 57--with-double-samples 58 59 Use double precision floating point numbers for sample processing. If 60 you intend to edit 32-bit files, you should enable this. 61 62--without-check-casts 63 64 This option disables the run-time type cast checking. It makes some parts of 65 the program faster, but makes it harder to debug. 66 67 68 69-------- 70Starting 71-------- 72 73To start the program, simply type mhwaveedit. If you want to, you can specify 74files to open on the command line, for example 'mhwaveedit file.wav'. 75 76----------- 77Sample view 78----------- 79 80The area where you 'see' the contents of the file you are editing, is called 81the 'sample view'. 82 83In the sample view there is a grey vertical bar called the 'cursor'. The cursor 84follows the sound wave when you play the sound. You can position the cursor by 85clicking with the right (2:nd) mouse button. If you do this while you're 86playing a file, the playing will continue from the new cursor position. You can 87also position the cursor more exact by using the 'Position Cursor...' command 88on the Edit menu. 89 90You can place marks in your file by holding down Ctrl and pressing a number 91from 0 to 9. This will place a mark (green vertical bar) with the same number 92at the current cursor position. You can later make the cursor go to that 93position again by just pressing the number. Setting and jumping to marks can be 94done while playing. To remove a mark, jump to the mark and set it again. 95 96------- 97Playing 98------- 99 100Playing a file is simple, just load the file and press the play button. The 101green play button plays from the current position. The yellow play button plays 102the current selection, or the entire file if nothing is selected. Stop the 103playback with the stop button (with the red square). 104 105The playback speed can be varied by adjusting the slider to the far right. 106 107You can do normal editing while the file is playing. 108 109--------- 110Recording 111--------- 112 113Recording is done with 'Record...' on the Play menu, or the Record button (the 114red circle). A dialog box will pop up where you can select what format you want 115to record in. After selecting the format, meters and numbers will appear 116showing info about the volume level of the sound input. 117 118When you want to start recording, press the "Start recording" button. When 119you've recorded everything you wanted to, press the Finish button and the 120record dialog will disappear and newly recorded sound will show up in a new 121window. 122 123Currently it is impossible to play and record at the same time, so the playback 124will stop when you record. 125 126------- 127Editing 128------- 129 130You make selections by dragging the mouse over the sample view. You can hear 131what you've currently selected by clicking on the "play selection" button (the 132button with the yellow arrow) or by selecting 'Play selection' from the Play 133menu. 134 135You can use the cursor to refine the selection. Use the 'Selection start at 136cursor' and 'Selection end at cursor' buttons to move the selection starting 137point or the selection end point to the current cursor position. You can also 138drag the selection endpoints using the mouse. 139 140The 'Cut' and 'Copy' functions work like in any other software. 141 142The 'Paste' function insert the clipboard contents at the cursor position. The 143'Paste over' function works like 'Paste', except that it overwrites the data 144after the insert position. 145 146The 'Paste mix' function combines the clipboard data with the data at the 147cursor position. 148 149The 'Paste as new' function opens a new window and puts the clipboard contents 150into it. 151 152The 'Crop' function deletes all parts of the file that are not selected. 153 154The 'Silence selection' function replaces the selected part with silence. To 155avoid clicks, the silent part is a line that meets the wave at the endpoints. 156 157All editing functions work non-destructively, that is, the file you're editing 158isn't actually changed until you save it (the effects also work this way). 159 160 161------- 162Effects 163------- 164 165mhWaveEdit has a few simple effects, which are available from the 'Effects' 166menu. 167 168 * Fade in/out 169 170 This creates a linear fade in or fade out effect. 171 172 * Normalize, Normalize to... 173 174 This amplifies the sound as much as possible without getting clipping 175distortion. The "Normalize to..." item lets you specify which level to 176normalize to. 177 178 * Volume adjust/fade... 179 180 This effect lets you select a starting volume and a ending volume and 181amplifies the selection fading from the starting volume to the ending volume. 182 183 Note that volumes above 100% may cause sound distortion. Use the 'Find top 184volume' to find out the maximum amplification possible without distortion. (You 185can use this for normalizing samples.) 186 187 By setting starting volume and ending volume to the same value you get a 188simple amplification of the sound. 189 190 * Convert samplerate... 191 192 This converts the samplerate of the entire file to one you specify. There 193are different methods for doing this, usually the one in the top has the best 194quality but can take longer than the other methode. 195 196 * Convert sample format... 197 198 This converts the sample format of the entire file. 199 200 The 'Don't actually change the data' option can be used if the program was 201wrong about the file's format. 202 203 * Byte swap 204 205 This "byte swaps" the selected part. It can be used to repair damaged files 206where the byte order is wrong. Note that if the sound looks alright but plays 207wrong, you should not use this option, instead you should use the "byte-swap 208output" option in the Preferences dialog. 209 210 * Mix to mono 211 212 This mixes all channels of the file together to a mono sound. 213 214 * Add channel 215 216 This copies the first channel to a new channel in the sound, converting mono 217to stereo etc. 218 219 * Map channels... 220 221 With this effect, you can change the number of channels in the file. You can 222also rearrange and add (i.e. mix) channels. 223 224 * Combine channels... 225 226 This effect lets you create a new sound by a linear combination of the old 227channels. This means you can do channel mixing / swapping / balance / panning / 228amplification etc. by entering different values. For example, to swap the left 229and right channel, you select that the new Channel 1 should be 0% of the old 230Channel 1 and 100% of the old Channel 2, and the new Channel 2 should be 100% 231of the old Channel 1 and 0% of the old Channel 2 232 233 * Speed adjustment... 234 235 This effect changes the speed of the selection. The tone will change as well. 236 * Pipe through program... 237 238 This effect is for advanced users wanting to pipe raw audio data through an 239external program. The output of the program is read back and replaces the 240processed part. 241 242mhWaveEdit supports LADSPA effects and can also make use of most of the SoX 243utility's effects. To find the LADSPA plugins the environment variable 244LADSPA_PATH must be properly set up. 245 246All supported effects can be found by choosing the 'Effects...' menu item. The 247effects are listed with names beginning with [B] for builtin effects, [L] for 248LADSPA effects, and [S] for SoX effects. 249 250 251------- 252Quality 253------- 254 255Some notes on sound quality. 256 257The general rule when doing audio editing/processing is to not manipulate the 258data more than necessary and keep an original copy whenever you're processing 259your important files. 260 261Cut, copy and paste operations move the data around without modifying it, so 262these don't degrade the sound quality. Because of level differences, you may 263get a "step" at the start and end of the inserted part, which can cause a small 264clicking sound. 265 266The mix paste function doesn't decrease quality, unless the peaks become too 267high and you get clipping. In that case you will get a warning message. 268 269Sound data is normally stored as integer values. Therefore, whenever you 270normalize, adjust volume, decrease sample size or filter a sound, the result 271must be rounded. If you use 24 or 32 bit sample sizes, this is not really a 272problem, but if you use 8 or 16 bits sample size, this rounding causes a 273decrease in quality. 274 275The quality decrease that the rounding causes can be masked by adding a small 276amount of noise before rounding. This is called "dithering". mhWaveEdit 277supports basic dithering and it's enabled by default. 278 279By default, mhWaveEdit uses floating-point temporary files for storing 280processed results to avoid rounding until the file is saved. 281------------ 282File formats 283------------ 284 285Even if mhWaveEdit was originally built for editing wav files, it's also 286possible to load and save in a few other formats. mhWaveEdit always supports 287wav and raw files, but if it's compiled with the libsndfile library, mhWaveEdit 288supports a couple of other formats as well. 289 290To save a file with a different file format, use "Save as..." and choose a 291format in the file type selection box. 292 293mhWaveEdit has basic support for mp3 and ogg formats. For this to work you need 294to have LAME installed for mp3 support, and OggDec/OggEnc for Ogg support. If 295you have these programs, you can open and save mp3/ogg files just like any 296other file format. 297 298If mplayer is installed, mhwaveedit can open all formats that it supports, for 299example the soundtrack of a video file. Since mplayer is only a player, these 300files can not be saved back after editing, you have to save the file into a 301supported format. 302----- 303Files 304----- 305 306mhWaveEdit creates a directory ~/.mhwaveedit where it stores configuration 307information. 308 309The configuration file is called config. It can be hand edited, but the easiest 310way is through 'Preferences' on the Edit menu. 311 312Each mhwaveedit process creates a session file in the .mhwaveedit directory 313called mhwaveedit-session-<pid>-<session>-<state>, where <session> is the 314session ID number and <state> is a character code showing the state of the 315session ('r' for running sessions). 316 317Temporary files are by default also stored in the ~/.mhwaveedit directory. 318Which directories to use can be set through the preferences dialog. To get the 319best performance, you should have one temporary directory for each local 320filesystem. The temporary files have names of the form 321"mhwaveedit-temp-<pid>-nnnn-<session>". Do NOT open or remove temporary files 322with the same pid number as a currently running mhWaveEdit. 323 324mhWaveEdit checks on startup for leftover temporary files and lets the user 325open them. After opening a crashed session, the files can be saved or thrown 326away. 327------------------ 328Keyboard shortcuts 329------------------ 330 331F1 Help 332F12 Record 333 334Ctrl+(number) Set mark 335(number) Goto mark 336 337Ctrl+P Preferences 338Ctrl+E Effects 339 340Ctrl+O Open file 341Ctrl+S Save file 342Ctrl+U Save selection as 343 344Ctrl+C Copy 345Ctrl+X Cut 346Ctrl+D Delete 347Delete Delete 348Ctrl+V Paste 349Ctrl+Z Undo 350Ctrl+A Select all 351 352Ctrl+G Position cursor (Go to) 353Ctrl+H Position cursor at file start 354Ctrl+J Position cursor at file end 355Ctrl+K Position cursor at selection start 356Ctrl+L Position cursor at selection end 357Y,U Move cursor to nearest all-channel zero-crossing 358I,O Move cursor to nearest any-channel zero-crossing 359 360Ctrl+Q Selection start at cursor 361Ctrl+W Selection end at cursor 362 363+,= Zoom in 364- Zoom out 365> Zoom to selection 366< Zoom all 367Arrow keys Scroll left/right 368 369Home Move view to file start 370End Move view to file end 371Tab Move view to cursor 372Ctrl+Tab Move cursor to center of view 373 374Space Play/Stop 375Shift+Space Play all 376, Play from cursor pos 377. Stop 378/ Play selection 379H,J Move cursor (and playback) 1/8 of view 380K,L Move cursor one sample 381Ctrl+arrow Move cursor (and playback) half second 382( Play first 3 seconds of selection 383) Play last 3 seconds of selection 384------------- 385Bug reporting 386------------- 387 388If you find a bug or flaw in the program that's not mentioned in the BUGS file, 389report the bug in the bug tracker (see contact info) or mail a bug report 390describing the bug to: magnus.hjorth@home.se 391 392In case of a crash, please do not send me any core dumps. They are huge and 393completely useless to me. Instead, create a backtrace. Backtraces tell you 394exactly where the program crashed. 395 396How to create a backtrace: 3971. Enable core dumps: ulimit -c unlimited 3982. Run the program: mhwaveedit 3993. Make the program crash. You should now get a file named core or core.1234 in 400the directory you're in. 4014. Run gdb with the program and core file: 402 gdb /usr/local/bin/mhwaveedit core | tee backtrace.txt 4035. After gdb has loaded, use the command: bt 4046. Quit gdb with the command: quit 4057. Now you should have a back trace in the file backtrace.txt 406 407----------- 408Helping out 409----------- 410 411There are plenty of things you can do if you want to help the development of 412mhWaveEdit. 413 414First of all, look for bugs and report all bugs you find into the bug tracker 415or through e-mail. Sometimes a bug can get overlooked for a long time because 416nobody reports it, so don't be afraid to report bugs that have been there for a 417few releases. You don't have to provide fixes or very detailed information, 418although it helps of course. 419 420Feature requests are also welcome, report them to the mailing list or to the 421bug tracker. 422 423If you speak a language other than English and mhWaveEdit isn't translated to 424your language, you can contribute a translation. To do that, copy the template 425mhwaveedit.pot in the po directory into a new file ll.po, where ll is your 426language code (see 427http://www.gnu.org/software/gettext/manual/html_node/gettext_221.html for a 428list of language codes). 429 430It's possible to edit po-files by hand, but I recommend a program such as 431poEdit (http://www.poedit.org) for editing translations. 432 433Note that for those translatable strings that look like "RecordStatus|Paused", 434you should ignore what's to the left and only translate the string to the right 435("Paused" in this example). This convention is there to make it possible to 436translate the same string to different things depending on context. 437 438After you've filled in all the translations you want (you don't have to 439translate all the strings), mail in the po file to me (see contact info) and 440I'll add it to the next release. 441 442If a translation is incomplete, you're very welcome to translate the remaining 443untranslated messages and mail them in. Corrections to translations are also 444appreciated, but they may need to be checked with the previous translator 445before including them. 446 447 448------- 449Contact 450------- 451 452For bug reports, translation updates, patches and PayPal donations: 453magnus.hjorth@home.se 454 455Project page with bug tracker, mailing list membership: 456http://gna.org/projects/mhwaveedit 457 458Mailing list (you must be a subscriber before you can post messages): 459mhwaveedit-discuss@gna.org 460 461 462