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 <Enter>; 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 <Enter>:

  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, <Home>, <End>,
<PgUp> and <PgDn>);  you then press <Enter>  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
<Escape>  key.  If you're  left handed, you  can swap the mouse  buttons for all
functions with the /L command-line option.

Press <Escape> to back out one menu level.  Pressing <Escape> 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  <Escape>) 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 <Enter>.   You may always  change your mind
before then by pressing <Escape> 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 <F1>.  Within  Help, press <Alt-I> for
the Help  Index.  <Tab>  to How To  Use Online Help  and press <Enter>  for full
instructions.

Registered users can also get Help by  clicking on the <F1>-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  <Escape> 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 <Enter>.  This displays the new
name  on the  Canvas's display.   Press  <Escape> 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 <Enter>
(don't type the file extension (the SongCanvas will prevent you from doing so)).
Press <Escape>  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 <Escape>.   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
        <Enter>.  If  you don't want to change the value,  press <Escape>.  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 <Alt-M> ("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.   <Alt-P> 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.
<Alt-T> 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 <F1>-Help
and MIDI  buttons.  Finally, registered  users can toggle the player  On and Off
with the <Space> 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