SongCanvas User's Manual Table of Contents Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Quick Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 General Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Editing Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 MIDI Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Appendix A Installation Ä Detailed Instructions . . . . . . . . . . . . . . 8 Appendix B Command-Line Parameters . . . . . . . . . . . . . . . . . . . . . 9 Appendix C Terminating Errors . . . . . . . . . . . . . . . . . . . . . . . 10 Appendix D MIDI Information . . . . . . . . . . . . . . . . . . . . . . . . 11 Appendix E MIDI Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 1 OVERVIEW The SongCanvas is a complete IBM-compatible patch editor and librarian program for Roland's GS synthesizers (SOUNDCanvas SC-55, SC-155, SCC-1, LM-300 and JV-30). It supports all popular MIDI interfaces and works equally well under DOS, Windows 3.1 and DESQview. The SongCanvas plays your MIDI files as you editÄyou hear your changes instantly in the context of your own musical projects! It saves its data in standard binary format (also called "MIDIEX format") so it is compatible with bulk loaders and other utilities. Finally, it gives you complete control over all parameters. To maximize data integrity, the SongCanvas is designed for one-way MIDI communication only (from the computer to the SOUNDCanvas). Data can't be lost when other windows transmit extraneous data and/or switch the interface's operating mode. A GS sound module or keyboard is referred to as a "Canvas" throughout this manual. "GS" is Roland's General StandardÄa superset of the nascent General MIDI standard. If you have an SCC-1, please ignore references to the "display" or "LCD"Äit doesn't have one. Note also that the SCC-1 is hardwired as device #17. This manual describes how to modify, save and audition the various parameters within the Canvas. It does not describe what these parameters do. For example, it describes how to turn Parts On and Off, but it doesn't state what effect that has on the sound nor why you may want that effect. The various Canvas owner's manuals do a good job explaining these features. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 2 QUICK INSTALLATION 1ÄConnect a MIDI cable from the computer's MIDI Out to the Canvas's MIDI In (pre-wired on the SCC-1). 2ÄCopy and/or PKUNZIP all files into a new directory and change to that directory. 3ÄIf you have an MPU401 or -compatible interface using IRQ 2 and address 330h, go to step #5 (if you don't know which type you have, you can probably go to step #5 as well). Otherwise, run CANVAS /? for details on configuring your MIDI interface with the DOS SET command. (The SCC-1's MIDI interface is an MPU401.) 4ÄType the SET command as determined in step #3 and press ; for example: SET OPT1=-dmpu:5:336 (Now is also a good time to add this command to your AUTOEXEC.BAT file. Note the "-" between the "=" and the "d".) 5ÄEnter one of these four commands and press : C runs as device #17 (Canvas default). C /D:18 runs on device #18 (change "18" to any device # from 1 to 32). CANVAS /D:0 runs with MIDI disabledÄ"demo" mode for computers without a MIDI interface. CANVAS /? displays help screens explaining all of the SongCanvas's command-line options. See Appendix A for details on segregating data and program files, etc. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 3 GENERAL INSTRUCTIONS You perform all SongCanvas functions from menus. You can move the highlighted cursor bar to the desired choice using the keyboard (arrow keys, , , and ); you then press to select it. If you have loaded your mouse driver (recommended), you can also point your mouse cursor at an item and left click to select it. Note the scroll arrows within the right border of scrollable pop-up menus (e.g., Master Pan). You may cursor as needed or position the mouse cursor on the appropriate scroll bar and hold down the left button. For fastest scrolling, you can click and drag the right border's scroll button with the mouse. Throughout the program, the right mouse button functions exactly like the key. If you're left handed, you can swap the mouse buttons for all functions with the /L command-line option. Press to back out one menu level. Pressing from the MAIN MENU quits the program after confirming your request. However, if you try to quit or LOAD a new library file before saving your current library, the program will tell you so and ask if you're sure you want to continue. Select Yes to continue the operation. Select No (or press ) to cancel the operation and position the cursor bar on SAVE. The SongCanvas will not accept invalid data (e.g., periods in filenames, hieroglyphic patch names) nor data past the end of the field (e.g., nine- character filenames). During any edit, you may backspace to change dataÄnothing becomes "permanent" until you press . You may always change your mind before then by pressing to revert to the prior value. The SongCanvas displays the current patch filename in the upper left corner and the patch name in the upper right corner of the screen. These areas are blank at the start of the program. The SongCanvas accesses patch files in the current directory only (though this can be different from where the program is stored). This design simplifies the user interface and minimizes set-up headaches. See Appendix A for more information. Whenever the SongCanvas is transmitting system exclusive MIDI data, SysEx will display in the lower center of the screen. This data is always transmitted on the MIDI device # you specify on the command-line. This transmission temporarily pauses the MIDI file player (when playing) so system exclusive and channel messages don't collide with each other. Help is available at any time by pressing . Within Help, press for the Help Index. to How To Use Online Help and press for full instructions. Registered users can also get Help by clicking on the -Help "button" on the bottom left of the screen. See the MIDI Menu section for other keyboard and mouse shortcuts. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 4 MAIN MENU The MAIN MENU has four options Ä LOAD, EDIT, RENAME, and SAVE. You must first LOAD a file before using the other options. LOAD pops-up a list of data files in your current directory. Selecting a file sends its data to the Canvas. Press to exit without loading a data file. EDIT displays a list of the Canvas's parameter groups and asks you to select one for editing. See EDITING PATCHES for more information. RENAME redisplays the current patch name and allows you to rename it. All displayable ASCII characters are valid. A patch name can be up to sixteen characters long. Type in the new name and press . This displays the new name on the Canvas's display. Press to exit without renaming the patch. SAVE pops-up a dialog box with three options: SAVE, to save the file with its current filename; SAVE AS, to save the file with a new filename; or CANCEL, to change your mind. For SAVE AS, type in the new data filename and press (don't type the file extension (the SongCanvas will prevent you from doing so)). Press to exit without saving the file. (Registered versions of the program will additionally save only the changed data as a small "MIDIEX" file with a .CHG file extension. You can use these to "prime" your Canvas with various set-ups.) ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 5 EDITING PATCHES The MAIN EDIT MENU lists several parameter groups which correspond roughly to the Canvas's internal data layout. Select a parameter group to display its edit screen. Within the individual edit screens, the parameter prompts generally mimic those found on the Canvas's LCD. The edit interface is very straightforward once you understand the three types of data and respective procedures (please experiment here): (1) two-value toggles (e.g., Receive Note On/Off) Ä Select toggles back and forth between the two available values. (2) pop-ups Ä these are parameters whose values are either: (a) non-ordinal numbers (e.g., Reverb Macro 5 does not reverberate "more" than Macro 4), or (b) not described by numbers (e.g., Part 1 plays a Mandolin instead of a Banjo). Select pops-up a list of the valid values. If you don't want to change the value, press . Non-ordinal parameters have an attempt at "describing" the qualitative aspect so you don't have to reference the Canvas's manual. For example, Reverb Macro 4 is described as Hall 2 per the SCC-1 manual. (3) quantitative numbers (e.g., Master Volume) Ä these values do have ordinal relationships (e.g., a Master Volume value of 127 is louder than 126). Select asks you for a new value within the valid range (e.g., "Enter a new value between 0 and 127"). Enter the number and press . If you don't want to change the value, press . Note that although several parameters are quantitative (e.g., MOD LF01 PITCH DEPTH), only certain discrete values are available. Thus, they are edited like the pop-ups in (2) above. Each valid change sends the new MIDI data immediately to the Canvas. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 6 MIDI MENU The MIDI MENU has five options Ä RESET, LOAD, PLAYER, REWIND, and THRU. You can access the MIDI Menu from other menus by pressing ("MIDI" will display on the bottom border when available). Registered users can also click on this "MIDI button" to pull up the menu. RESET puts the MIDI interface back into the correct operating mode. This option should only be necessary in multi-program environments when another window sets the interface into a new mode. LOAD pops-up the list of song files (*.MID) in the directory specified by the command-line's /MID: parameter. (If /MID: is not specified, it defaults to your current directory.) Select a file to start playing it in a continuous loop. LOAD displays an error message if there is a problem loading the file; it then reloads, rewinds and replays the prior file if one was loaded and if it can do so. PLAYER toggles the MIDI file player On and OffÄit starts a stopped song and stops a playing song. will also toggle the player On and Off. The elapsed time from the start of the song displays in the lower right corner of the screen. PLAYER is not available if a song is not loaded. REWIND resets the player to its beginning and then restarts the current song. REWIND is not available if a song is not loaded. THRU toggles MIDI Thru On and Off. When Thru is On, MIDI data received at the computer's MIDI In is re-routed to the MIDI Out whenever the program is idle. will also toggle Thru On and Off. The words Thru and Play are highlighted or dimmed on the bottom of the screen to indicate their On or Off states, respectively. Registered users can click on these "buttons" to toggle the functions; they can also click on the -Help and MIDI buttons. Finally, registered users can toggle the player On and Off with the bar. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 7 Appendix A INSTALLATION Ä DETAILED INSTRUCTIONS System Requirements: Any IBM-compatible personal computer with an 80-column monitor, DOS 3.0 or higher and 450K free RAM. For system exclusive MIDI communication, you'll also need a supported MIDI interface and (of course!) a Canvas. You can play MIDI files without a Canvas, however. Run CANVAS /? for information on configuring your MIDI interface with the DOS SET command. CANVAS.EXE is the main program file, CANVAS.HLP contains the help information, and CANVAS.REG contains your personal registration information. All three files must be in the same directory. (As implied, CANVAS.REG is not necessary nor included in the unregistered version.) PLAYD.EXE is the MIDI engine. See the MIDI ENGINE appendix for complete information. Data files (*.CVS) can be in a separate directory (recommended). The SongCanvas comes with one data file; FACTORY.CVS contains the data that exists in the Canvas when shipped from Roland. (You'll need to rename this file with the new extension if you use the /EXT: command-line option.) To run the SongCanvas when the data and the program are in separate directories, type the following commands: D: go to the drive containing the data (given as D: in this example) CD \SYSEX go to the directory containing the patch data (given as \SYSEX in this example) C:\MTOOLS\PLAYD -a64 type the fully-qualified path to PLAYD.EXE (given as C:\MTOOLS\PLAYD.EXE in this example). See PLAYD.TXT for all of the MIDI engine's command-line options. C:\SC\CANVAS /D:18 type the fully-qualified path to CANVAS.EXE (given as C:\SC\CANVAS.EXE in this example). See the COMMAND- LINE PARAMETERS appendix for all of the SongCanvas's command-line options. Note: You can put these commands in a batch file (like C.BAT) or your menu system. You can also customize the included CANVAS.PIF or SC-PIF.DVP files for use in Windows 3.1 or DESQview 2.x, respectively. At least one data file is always required; because of the 1-way communication discussed in OVERVIEW, the program reads data from disk, not from the Canvas. I suggest leaving FACTORY.CVS in your data directory to avoid problems. Even better, make the file read-only with DOS's ATTRIB +R FACTORY.CVS command. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 8 Appendix B COMMAND-LINE PARAMETERS The SongCanvas has several optional command-line parameters to maximize its flexibility. Note that parameters (a) are not case-sensitive (e.g., /d:17 is the same as /D:17), (b) must be separated by at least one space (i.e., there must be a space before each "/" character), and (c) may not contain imbedded spaces (e.g., /D: 18 is invalid). CANVAS /D:n /EXT:fe /MID:dir /L /M /R /? /D:n Device # Ä use MIDI device #"n". /D:0 disables MIDI output and overrides /MID:dir. /EXT:fe Extension Ä use file extension "fe" to LOAD and SAVE patch library data files. /MID:dir MIDI files Ä load standard MIDI files from the "dir" directory. Defaults to the current directory if not specified. The SongCanvas handles pathnames like DOS doesÄe.g., if you're in D:\MIDI and the song files are in D:\MIDI\Jams, each of these three options will work: /M:Jams, /M:\MIDI\Jams, or /M:D:.\Jams. The SongCanvas will play CANVAS.MID at startup if it exists in this directory. /L Left-handed mouse Ä swaps the left and right mouse buttons for left- handed users. /M Monochrome Ä display black and white. This option is most useful for portables and other computers whose "colors" don't contrast. /R Resident Ä do not unload PLAYD upon termination. /? Help Ä displays DOS 5.0-style help. This parameter overrides all others. Defaults: CANVAS /D:17 /EXT:CVS /MID:.\ ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 9 Appendix C TERMINATING ERRORS Five errors terminate the SongCanvas before it starts. These errors display an informative message on the middle of the screen and return the displayed error number to DOS (see the batch file section in your DOS manual if you're interested in using this information with the IF ERRORLEVEL command). The errors are easy to correct: 1 Ä Command-line syntax error Ä a command-line "spelling" error. Embedded spaces are not allowed within any parameter (e.g., /D: 17 is invalid); at least one space is required between parameters (i.e., before each "/"). Run CANVAS /? if you want command-line help. 2 Ä Non-numeric device # requested Ä all characters after the /D: parameter must be numeric. 3 Ä Illegal device # requested Ä the characters after the /D: parameter must indicate an integer between 1 and 32 (or 0 to disable MIDI output). 4 Ä CANVAS.HLP file not found Ä CANVAS.EXE and CANVAS.HLP need to be in the same directory. 5 Ä CANVAS.HLP file wrong version Ä current versions of CANVAS.EXE and CANVAS.HLP need to be in the same directory. Be sure to install the latest version of the software correctly. CANVAS.EXE will still run if the MIDI engine doesn't correctly initialize, but MIDI will be disabled. See the MIDI ENGINE appendix for MIDI I/O troubleshooting information. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 10 Appendix D MIDI INFORMATION If your edits do not update the Canvas, it's probably because (1) another window within your multi-program environment has changed your MIDI interface's operating mode, (2) your SOUNDCanvas is set-up to ignore sysex data, or (3) the device #s on the SongCanvas and your SOUNDCanvas don't match. Don't worryÄyour data is safe. To correct (1), RESET the interface from the MIDI MENU. To correct (2), see the instructions in the SOUNDCanvas's owner's manual. Finally, to correct (3), change the device # on the Canvas (also in the owner's manual) and/or specify the correct SongCanvas device # via the /D:n option. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Copyright 1992 by Jeff Cazel Ä All Rights Reserved 11 Appendix E MIDI ENGINE DOS versions of Jeff Cazel MIDI software now use FM Software's PLAYD.EXE as the MIDI `engine'. PLAYD.EXE is actually a separately executed programÄCANVAS.EXE by itself no longer sends sysex data nor plays MIDI files. This modular set-up provides greater device independence and supports more MIDI interfaces using less memory. PLAYD handles CANVAS's requests to send sysex data and to start and stop song playback. You load PLAYD with the correct options for your interface and then run CANVAS. The two programs then work in tandem so you can immediately check the effects of your edits in the context of your own musical projects. Run CANVAS /? to see PLAYD's configuration options. Power users who seek complete details on PLAYD can read the PLAYD.TXT file. Registered SongCanvas users can purchase MidiTools for 25% off of the regular price. See the MTOOLS.TXT file for complete information. Notes The maximum path length for a PLAYD song file is 40 bytes. Longer file names will return a "file not found" error message upon LOAD. Use the DOS SUBST command if this becomes a problem. PLAYD handles MIDI files up to 16 tracks. All tracks numbered greater than 16 are ignored during playback. PLAYD can handle MIDI files up to 64K in size. Larger files will not load. The SongCanvas unloads PLAYD from memory upon exiting; you can leave it resident for future edit sessions by specifying CANVAS's /R option, however. ________________________________________________________________________________ SongCanvas Ä GS Editor/Librarian Ä Version 1.0 Contact me via CompuServe Mail Ä #72461,3345 12