1Info for hackers 2---------------- 3 4-- Document history -- 5 6Oct 28, 2006: First version 7 8-- General info -- 9 10mhWaveEdit is written completely in C, and tries to be as portable as 11possible. There's no point in being more portable than GTK+ though, 12since we depend on it. 13 14The only hard dependency is GTK+, version 1.2 or newer. All other 15dependencies should be autodetected by the configure script or at 16runtime. In general I prefer calling separate programs, such as 17Lame and SoX, rather than using libraries, because programs can be 18portably detected at runtime so the user can install these programs 19after installing mhWaveEdit. 20 21The philosophy is to never remove a feature. If a behavior is changed, 22there should be an option to get the old back (unless it's a bug of 23course). 24 25All settings should be configurable via the Preferences menu, there 26should not be any hidden settings, except for "automatic" things like 27recently opened files etc. Settings are handled through inifile.h. 28 29-- Code conventions -- 30 31Most functions returning a boolean return TRUE on failure and FALSE on 32success. The function that fails is usually responsible for displaying 33an error message, so if a function returns TRUE an error message has 34already been displayed. 35 36I have avoided threads for several reasons. The main reasons are 37that it's not portable, makes the program much more complex and a lot 38harder to debug. Most problems that are solved by threads can be 39solved by other means, for example forking, non-blocking IO, select 40calls, and/or clever coding. Some sound drivers use threads though. 41 42mhWaveEdit doesn't use the GTK+ main loop, instead I have coded my own 43(mainloop in main.h), allowing me to control the priority of the 44different activities. 45 46-- File handling -- 47 48File handling is separated into layers. 49 50The lowest layer is the efile functions in gtkfiles.h, that provides a 51wrapper around the C library IO functions. 52 53Above that is the Datasource layer. Each Datasource object gives access 54to some audio data. The data can be in a file, in memory or converted 55from another datasource. The Datasources are "immutable", meaning the 56data never changes after the datasource has been created. The objects 57are using the standard GtkObject reference counting scheme so data in 58memory and temporary files are removed when nobody needs them anymore. 59 60The Chunk layer is above the Datasource layer. A Chunk object is a 61collection of data from different Datasource objects. Each Chunk 62contains a list of Datasources, positions and lengths of data. Chunk 63objects are also immutable. 64 65The filetypes.h and tempfile.h functions are in both the Chunk layer and 66the Datasource layer. This is because sometimes temporary data end up 67in multiple files, so a Chunk must be returned to represent the data. 68 69The Document object contains a Chunk with the file currently being 70edited, along with information on selection, view info, history etc. 71 72The Chunkview object is a graphical GTK component displaying a Document. 73 74The Mainwindow is a GtkWindow subclass containing a Chunkview and a 75Document. 76 77-- Sound handling -- 78 79The sound handling is also separated into layers. 80 81The lowest layer is the sound driver. Each sound driver is in a file 82called sound-xyz.c. The sound drivers are not compiled separately, but 83are included in sound.c 84 85The layer above is the sound.h module. This contains glue code for the 86drivers and handles byte-swapping of output and locking of driver (an 87option to not actually stop the driver when playback stops). 88 89The layer above the sound module is the player.h module. This handles 90many things; reading data from the playing chunk, looping, converting 91speed (optional) and sending the data to the sound driver. Also 92estimating cursor position. The player has a function called player_work 93that has to be called periodically. 94 95The playback position and speed can be changed at runtime. There are 96also functions for smooth switching of playback between two Chunks to 97allow editing while playing. 98 99The player layer handles sample type conversion if the sound driver 100doesn't support the file's sample type. Sample rate conversion is done 101at the same time when applying varispeed. 102 103Recording is done through the recorddialog.h module, which is above the 104sound.h layer. This contains both the recording dialog component and a 105recording function. This module has it's own main loop and blocks the 106rest of the application while recording. 107 108-- Utility modules -- 109 110um.h has functions for displaying messages and getting simple input. 111 112rateest.h contains code for estimating the true playback sample rate and 113detect underruns by studying the time and size of writes to the sound 114driver. 115 116ringbuf.h contains a lock-free ring buffer implementation. 117 118main.h contains apart from the main() function main loop, some utility 119macros and functions. 120