From 0e351f13437a75672fe4d967f392ce3fc8a07f3a Mon Sep 17 00:00:00 2001 From: EvanR Date: Tue, 30 Dec 2008 10:55:51 -0600 Subject: [PATCH] Updated documentation. There is now a BUGS file which lists bugs as soon as I remember them (and encounter new bugs). Controls docs is more finalized. The manual was rewritten, and is still incomplete. The final version will take the form of a webpage with a diagram. The README now correctly lists where to get the source. --- AUTHORS | 1 + BUGS | 32 +++++++ TODO | 222 +++++++---------------------------------------- doc/README | 7 +- doc/controls.txt | 60 +++++++------ doc/guide.txt | 3 +- doc/manual.txt | 123 +++++++++++++++----------- 7 files changed, 173 insertions(+), 275 deletions(-) create mode 100644 BUGS diff --git a/AUTHORS b/AUTHORS index b649525..86f6433 100644 --- a/AUTHORS +++ b/AUTHORS @@ -15,3 +15,4 @@ kfoltman mefistofeles Vertelemming doughsay +fleg diff --git a/BUGS b/BUGS new file mode 100644 index 0000000..11521d0 --- /dev/null +++ b/BUGS @@ -0,0 +1,32 @@ + event on end of frame bug + +there is a 1 frame error caused by a kludge in the sequencer mechanism. +there are cases where a midi event is to be dispatched on the first +frame of the buffer, but also on the frame right after the last, i.e. +index 1024 in a frame buffer of 1024 frames. When a event appears to be +destined for 1024, i dispatch at 1023 rather than waiting until next +process. a real solution would check the sequencer play mechanism and +its interation with the backend's real time to see why its considering +playing these notes. + + + + out of order dispatch bug + +if events are dispatched out of order, they are put in order by playing the +rest of the notes after the first-out-of-order at the end of the buffer, causing +an error on the order of nframes/samplerate = 21 ms on my system. to fix it, +the events must be dispatched in time order. solution is to enqueue and sort +before dispatch. the above workaround was done because if you try to dispatch +them out of order jack crashes. this occurs when events occur near each other +but not exactly at the same time, or at high bpm. + + + + zoom range bug in arranger + +zooming has no effect on the possible range of scrolling. + + + + diff --git a/TODO b/TODO index 0dcd7ef..f357fbd 100644 --- a/TODO +++ b/TODO @@ -1,197 +1,35 @@ -short list of features not yet implemented +Short list + +remaining mouse editing + resize notes + move notes + paste notes + paste blocks + +remaining tools + quantize note on + quantize note off + join blocks + split blocks + unclone block + (note off tool) + (aftertouch tool) + (portamento tool) + +enhance recording + overwrite block + layer block + extend block + new block -keyboard input - allow remapping -the rest of the mouse commands - select many notes/patterns - delete all selected - move all selected - copy all selected - split/join - no overlapping patterns -the event editor - mouse commands - display - menu -import midi file -record midi input - overwrite mode - layer mode - out of bounds behavior - metronome lead in undo and redo -graphical upgrades -trackselect in piano roll - toggle tracks shown - switch edited track + +midi files + import smf + export smf (partially working now) + jack transport -lash - -big list of features - - -create seqpat (with new blank pattern) -create note -create event -delete seqpat -delete note -delete event -move note -move seqpat -resize seqpat -resize note -select seqpat -select note -select event -shift select seqpat -shift select note -shift select event -box select seqpat -box select note -box select event -change event value -add track -remove track - -copy selected notes -copy selected events -soft copy selected seqpats -hard copy selected seqpats -uniquify seqpat -split seqpat in half -join two seqpats - -save textfile -load textfile -save type 1 standard midi file -import type 0/1 standard midi file - -set loop start -set loop end -set song position - -play notes on virtual keyboard -play notes on real keyboard - -x zoom in pattern editor or song editor - -options -bpm -beats per measure -measures per phrase -metronome lead in -always hard copy -record pass thru -play note insertion -play note selection -follow playback -quantize note off -record modes -merge - insert notes into current track -overwrite - erase all notes before inserting into current track -layer - on each loop create new track (muted) -new - merge into new track created at time of recording - -toggle display of tracks on piano roll - -keyboard shortcuts -ctrl-c copy -ctrl-v paste -ctrl-z undo -ctrl-y redo -ctrl-a select all -ctrl-s save -ctrl-o load - -graphics - -change pattern color -timeline shows correct indicator -trackmodule has updated info -toggle buttons show correct state -piano keyboard highlights keys - - - -save records the following -track name -track vol -track pan -track mute -track solo -track port -track chan -track prog -loop positions -loop flag -keyboard flag -song title -song author -song info -seqpats -patterns -arranger scroll positions -seqpat event editor controller -beats per measure -measures per phrase -bpm -metronome lead-in -always hard copy -auto track name -record pass through -play note insertion -play note selection -follow playback -play note selection -quantize note off -record mode - - - - - -immediate features to be implemented - - -volume and pan controls dont work -change time signature and bars per measure - -select many patterns -select many notes - - -what i did instead (changes since last) - -saveload restores/clears title/author/info -vol pan mute solo widgets work -mute and solo works -autohell - - -BUGS - -if events are dispatched out of order, they are put in order by playing the -rest of the notes after the first-out-of-order at the end of the buffer, causing -an error on the order of 1024/48000 = 21 ms. to fix it, the events must be -dispatched in time order. solution is to enqueue and sort before dispatch. -the above workaround was done because if you try to dispatch them out of order -jack crashes. this occurs when events occur near each other but not exactly -at the same time, or at high bpm. - -the pattern drag sound bug is that when a pattern is moved, note offs do not -occur. to fix it, when dragging a pattern you must dispatch note offs in one -way or another. - -the hand doesnt point directly at notches 1 and 3 if they are numbered 0 1 2 3 -for each beat. - -there is a 1 frame error caused by a kludge in the sequencer mechanism. -there are cases where a midi event is to be dispatched on the first -frame of the buffer, but also on the frame right after the last, i.e. -index 1024 in a frame buffer of 1024 frames. When a event appears to be -destined for 1024, i dispatch at 1023 rather than waiting until next -process. a real solution would check the sequencer play mechanism and -its interation with the backend's real time to see why its considering -playing these notes. +(track toggler) +(sample name) diff --git a/doc/README b/doc/README index b7c48f2..7564e99 100644 --- a/doc/README +++ b/doc/README @@ -21,7 +21,7 @@ aware softwares and hardware devices. Epichord is licensed under the GNU GPL, so by using this program you implicitly accept the ability to get the source code if you do not already have it. -the source is... somewhere... +the source is in a git repo at http://repo.or.cz/w/epichord.git **how to build** @@ -31,6 +31,11 @@ some additional libs to build this program. fltk-2.0 graphical user interface jack-0.109.2 or any recent version of jack with midi support +lash use the latest version if you want to actually use lash + +Lash is currently required because autoconf does not define-or-not HAVE_LASH +based on whether lash is available. If you would like to add this to the +configure.ac please do and contribute your changes. After installing those, you can build and do a default install by: diff --git a/doc/controls.txt b/doc/controls.txt index 6bd58c7..e49de99 100644 --- a/doc/controls.txt +++ b/doc/controls.txt @@ -1,33 +1,31 @@ -Controls +==controls== -! means not yet implemented +left click drag on empty space - new blocks/notes +left click drag on selected pattern - move or resize blocks/notes +left click - select block/note +shift left click - select more blocks/notes +shift left click drag - box select blocks/notes +right click - delete blocks/notes +middle click - paste selected blocks/notes -left click drag on empty space - new pattern/note -left click drag on selected pattern - move or resize pattern/note -left click - select pattern/note -!shift left click - select more patterns/notes -!shift left click drag - box select -right click - delete pattern/note -middle click - paste clone pattern -!middle click on pattern (song view) - make unique copy if a clone +control c - copy selected blocks / notes +control v - paste copied blocks / notes +control z - undo +control y - redo +control a - select none / select all +delete - delete selected blocks / notes -!control v - paste clone pattern -!delete - delete selected patterns/notes -!control z - undo -!control y - redo -!control a - select none / select all +right arrow - zoom in +left arrow - zoom out -shift+= - zoom in -- - zoom out - -!control s - save -!control o - open -!control w - save as -!control n - erase everything - -!backspace - reset play head -!return - toggle recording +control s - save +control o - open +control w - save as +control n - erase everything +ctrl+backspace - reset play head +ctrl+return - toggle recording +ctrl+space - toggle play You can play notes with the keyboard. @@ -42,20 +40,20 @@ q w e r t y u i o p [ ] s d g h j k l z x c v b n m , . / +space - sustain pedal shift+[ - octave down one shift+] - octave up one -song view special controls - -!control left click (song view) - mute/unmute pattern -double left click (song view) - edit pattern +==song view special controls== +control left click - mute/unmute pattern +double left click - edit pattern -Event Edit special controls +==event edit special controls== left click drag - change event values with line shift left click drag - box select ctrl left click drag - insert new event right click drag - delete events in range right click - clear selection -!delete key - delete all selected events +delete key - delete all selected events diff --git a/doc/guide.txt b/doc/guide.txt index 2bba3e1..a8f943c 100644 --- a/doc/guide.txt +++ b/doc/guide.txt @@ -59,8 +59,7 @@ to be compressed into an ogg vorbis file or some such. Here is a list of JACK programs which will accomplish this for you. JAmin - full featured audio mastering suite -SoX - audio swiss army knife - +jackrec - comes with jack For more linux audio applications just go to this website diff --git a/doc/manual.txt b/doc/manual.txt index 9897ce1..539db84 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -1,70 +1,95 @@ -scratch work for manual text +Song View Widgets -overview of the widgets +1 pattern block arranger - this canvas area allows you to create, move, resize, delete, copy, +join, split, recolor, mute and unmute blocks, among other things. -The first screen that opens is the song view. You can use this to configure -the initial state of the tracks and manipulate the song at a high level. +2 song timeline - it shows you where in the song you are putting blocks. Use the mouse buttons +to change the loop endpoints and change the song position. -On the left is the track info panel which has a vertical list of tracks and -their configuration. Each track has the following widgets in the track -info from left to right: +3 track info panel - contains a lot of info about tracks. Press the + button to toggle more +track settings. -input selector - clicking here makes the keys appear next that track. -midi input and keyboard input will be recorded on this track. +4 track selector - the piano keys next to a track means that recording and keyboard input will +use this track. -track name - type anything you want here to describe the track. +5 track name - you can put whatever you want here. epichord uses fltk2's unicode support. -volume control - sets the initial volume of the channel. -pan control - sets the initial pan of the channel. -solo toggle - if enabled only this channel will play -mute toggle - if enabled this channel will not play. +6 track settings - these widgets display the track settings and allow you to edit their values. +Volume, pan, solo, and mute widgets are displayed by default. Press + at the top of the track +info panel to toggle the program, bank, channel, and port settings. Drag your mouse on a widget +to change the value or use the mouse wheel. -by pressing the + button at the top of the track info panel, you toggle -whether four more track settings are shown, from leftmost to rightmost: +7 color tool - when the color tool button is activated, your mouse will edit the color of +blocks. Drag on a block to change the color. Click on a block to copy color. Middle click on a +block to paste color. Right click on a block to paste color on the entire channel. Your last +used color will be used as a basis for future block insertions. -program - select the program for this track -bank - select the bank for this track -channel - select the channel for this track -port - select which port this track sends on +8 unclone tool - when blocks are copied the default behavior is to make clones. Any changes to +a clone block will affect the pattern in other clones. Use the clone tool to make a clone unique +with its own copy of a pattern. + +9 join tool - after pressing join, click on two blocks that are adjacent. These blocks will be +joined. If either are clones, they will be uncloned first. + +10 split tool - after pressing split, click on a block at a position you want to split it. The +block will be split into two new blocks. If it is a clone it will be uncloned first. -On the right is the pattern arranger. You use this to create delete copy move -and resize patterns in the song. -The timeline at the top of the arranger gives an indication of the current -play position and current loop endpoints. You can click in this to change the -endpoints or set current play position. +Global Widgets -The bottom of the screen contains buttons that are always visible whether or -not you are in song edit or pattern edit mode. From left to right: +1 play/pause - Press this to make the sequencer start playing the song from the current play +position. Press it again to pause playback at current play position. Pause sends all notes off +and all sound off midi messages. -play button (arrow) - begin playing the song at current position -pause button (bars) - appears while playing, pauses play at current position -stop button (square) - stop playback and reset to time zero -record button (circle)- toggle whether midi input is recorded +2 stop - Press this to stop the sequencer and reset the play position to zero. Any time the play +position becomes zero by any means, tracks will be reset to values shown in their track +settings. Stop sends all notes off and all sound off on all tracks. This can be used as a panic +button. -loop button - toggle whether the play will loop between current loop endpoints. -keyboard button - change keyboard layout -oscillo button - open the configuration window -floppy button - open the save/load menu -question button - open the info/help window +3 record - When this is pressed and the sequencer is playing, midi input, keyboard input, and +virtual keyboard input will be recorded. The default is to insert events into existing blocks +only. More advanced behavior is described in the manual section on recording. + +4 metronome - A graphical metronome to help keep rhythm. + +5 loop toggle - When pressed the song will loop between loop points. + +6 configuration - Opens the configuration panel. + +7 scope - Opens the midi scope panel. + +8 file - Opens the file menu so you can save or load your work. + +9 help - Opens the info panel with help docs and song info. -When you double click on a pattern in the song view, you will open the pattern -editor. Here you can view or edit individual notes and other midi events in -a given pattern. +Pattern Editor Widgets -On the left is the keyboard. This shows what note each horizontal delineation -corresponds to. You can click on the keyboard to send a midi note on this -channel. +1 piano roll - This canvas area lets you insert, move, resize, copy, and delete notes. -The timeline shows the same thing as the song view timeline but zero begins -at the start of the pattern and not the start of the entire song. +2 virtual keyboard - Lets you see where you are placing the notes. You can also click on it with +the mouse to play notes. Space bar acts as a sustain pedal. The + button above the virtual keyboard +does nothing. -The grid or the piano roll region shows notes. You click here to create delete -move resize select or copy notes in much the same way as the arranger. +3 pattern timeline - Equivalent to the arranger timeline except zero is the start of the block +rather than the start of the song, and it counts beats rather than measures. Use the mouse to +set loop endpoints or change the song position. -The event editor at the bottom of the pattern view screen lets you create delete -edit move and copy individual midi messages. +4 event editor - Shows you the value of many midi messages that are stored in the pattern. By +default it shows the note on velocity, but you can change that with the mouse wheel or by +opening the event type menu with the E button on the right. You can also create, delete, or +modify event values with the mouse. -the left arrow button in the bottom left will return you to the song editor. +5 back button - Exist the pattern editor and return to the block arranger. + +6 quantization settings - Inserting, moving, and resizing operations will be snapped to the grid +using granularity chosen by these buttons. The shorter the note length, the smaller the grid +snap width. Simply imagine placing quarter notes or eighth notes when you click on the canvas. +Press the blank button to turn off snapping altogether. + +7 quantize note on - Quantize the selected notes so they snap to the grid using the current +quantization settings. + +8 quantize note off - This is the same as quantize note on, but it effectively quantizes the +length of the note.