INSTRUCTIONS FOR SINGIT!

There are two versions of SingIt! available. The one labelled "SingIt!" should
be used for Macs with a coprocessor (e.g. all recent Macs except the Power
Macs); the second is labelled "SingIt! NC" which should be used for old Mac
Pluses or Classics, or for new PowerMacs and some Powerbooks. Be sure to use
the right one! You will need the Apple program ResEdit. We are not allowed
to distribute this without paying a fee. However, you should be able to get it
off of most network services free of charge or from your local Mac nerd.

GENERAL INFORMATION:
This is a program for interactive playback of digitized songs using a
Macintosh. It requires a resource file with resources of type 'snd ', 'PICT',
and 'STR#'. These are easily generated using existing sound and graphics
programs and the resource editor ResEdit. The use of a resource file makes
playback much faster than using Hypercard or other options. SingIt! allows the
user to select any particular resource file stored on disk or diskette, import
these resources into memory, and then playback the sounds when the mouse (or
trackball) is clicked as the cursor is over a particular image, or by
assigning keys to each sound and depressing a particular key for a particular
sound. The best way to see how the program works is to start it up, and use
the File Menu to open up the Dummy Res File included with the program. This
will open a dialog box listing the names of all the sounds the program found
in the resource file. Using the usual cursor and shift key controls, select
some or all of these items and close the dialog box. This should generate a
window in which the selected song sparrow sonagrams are visible. Click on a
sonagram and your Mac should sing the song. If you look under the Apple Menu,
you will find an item called SingIt! Help. Select this for on line information
on how to use the program.

The current version has the following features available under the Utilities
Menu:

Select Sounds: This is the same dialog box which opened when the file was
read into memory. This allows you to reselect any subset of the current
file for successive playback experiments. The playback screen will be
redrawn each time different sounds are selected. Note that if an input
file has no stored names for the sounds, the program assigns names of Call
1, Call 2, etc. in the order in which the sounds occur in the resource file.

Set Playback Keys: This opens a dialog box in which the names of any
selected sounds are listed. Click on any song listed in the box and type
the key wanted for that song. Then select the next name, enter a key for
it, etc. Playback keys are made active or inactive by checking the Keys
Active box. Once activated, hitting an assigned key should play that sound.

Set Opponent Keys: This allows the user to define a list of actions which the
opponent animal, (to which the sounds are being played), might perform.
Hitting these assigned keys can be used to reset a clock visible on the
screen and add entries into a log file. The list of opponent actions and
the keys assigned to them are listed (but inactive) under the Menu
entitled OPPONENT.

Show Labels: This puts the stored labels or Call i names on top of each
sonagram picture. It will also show which keys have been assigned to that
call. To hide the labels, just select the menu item again.

Start Clock: This puts a small clock window below the sonagrams. Before
opening the window, you are asked to select the clock mode. The clock
gives the delay between playback of songs and between successive actions
by the opponent animal. The units can be milleseconds, seconds, or
minutes. The clock can start counting at the instant the song starts
playing back, or it can start counting after the song has just been played.
For long songs, the difference can be significant, so choose carefully.
Clicking on this menu item again hides the clock. Clicking it twice will
let you reset the choices of units and start time.

Start Log: This option lets the user store a text file with columns
separated by tabs which lists the time (according to your Mac) when a
song was played, the delay in units you select (and start time you select)
since the last playback song, and which song was played. If opponent keys
are assigned and active, they will also be logged. This file can be
opened up by any text editor, stats program or spreadsheet program.

To Make Your Own Resource File:

Duplicate the dummy resource file included with this program. Rename this
duplicate. It will be the new resource file. Making sure that ResEdit is
somewhere on your hard disk, double click on the new resource file to open it.
You will see a window open up which contains three icons labelled 'PICT', 'snd
', and 'STR#'. The PICT part contains the pictures of the sonagrams, the snd
contains the digitized sounds, and the STR# contains the labels. You will
want to replace these samples with your own sounds, pictures and labels.
Taking each in turn:

snd: First select the list of sounds in the new file and hit the delete
button. This will remove all the song sparrow songs. If you are going to use
Canary, leave ResEdit on and the file open to the snd resource; otherwise quit
ResEdit. You now need a program which will store a digitized sound in resource
format. SoundEdit and SoundEdit Pro will do this fine. So will some versions
of Canary (v 1.2 does; in v 1.2.1 they forgot to include cut and paste of
sounds; later versions are supposed to have the cut and paste restored). If
you have a sound in a Canary file, and a version which supports cut and paste,
just select the part you want from the waveform picture, copy it, and paste it
into the snd resource in the open ResEdit file. It will be given a resource
number. While you are in ResEdit and your new snd resource is still selected
(highlighted in the list), go to the Resource Menu and find Get Resource Info.
This will open a window and give you a chance to name this sound. Do so. It
will help you keep track of what you put in the resource file. Then hit Save
in Resedit to save your file so far. Then go back to Canary, open up your next
sound, select the desired part of the waveform, hit Copy, go to ResEdit, hit
Paste, and continue until all the sounds are saved in the resource file. If
nothing gets pasted into ResEdit, then you have a version of Canary which does
not support cut and paste. For the long term, demand the new version; for the
short term, save your Canary sound as a SoundEdit file and then open it with
SoundEdit. To use SoundEdit, do not open your resource file. While your sound
is in the front window of SoundEdit, tell the program you want to save the
sound as a Resource. It will then ask which resource file you wish to receive
the sound and what name you want to give it. Provide the name and SoundEdit
pastes the sound in for you.

Note that you can also replay any sound while in ResEdit by selecting it and
choosing "Try Sound" under the snd Menu. Under the View Menu in ResEdit,
select "By Order in File". This lists the songs in their order in the file.
Note that the last song you entered is the first one in the file. If you want
your songs displayed in Singit! in a particular order, this is the order you
should see here. If you do not have the correct order, then use "New" under
the File Menu in ResEdit to make a new resource file. Then under the Resource
Menu, select "Create New Resource". Use the list provided to select a new
resource of type 'snd '. Delete any snds in this new resource by selecting
them and hitting the delete button. Then go to your original list of snds,
and select the one you want LAST in your list. Copy it and paste it into the
snd resource window of the new file. Repeat with the next to last, etc. until
you have copied all the snds from the original file into the new one. Close
the snd windows for each resource file, delete the snd icon in the original
file, copy the new snd file in the new resource file, paste this into the
original file, and then dump the new resource file. Your songs are now in the
order you wish to have them displayed. Be sure to check by using the By Order
in File view.

STR#: Leaving your resource file open, close the box listing the snd's, and
double click on the STR# icon. A new window opens listing one resource with
ID 128. Double click on this and a list of the stored labels is seen. If you
have 5 or more songs stored as snd's, then simply select the first text item
and change it to the name you want for the first song stored in your snd list.
Continue until the 5th is changed. To add more, click on the last item in the
list (e.g. 6) *****); it will be selected if it has a box around it. Now go
to the Resource Menu and select the Insert New Fields item. A new text box
will appear and you can add your name to this. Continue clicking on the last
***** to add new fields and fill them as you require. When through, hit the
Save. Be sure that the number of names stored in STR# 128 is the same as the
number of snd's you stored earlier, and that the order is identical. Close
the resource file and quit ResEdit.

PICT: Now you need to add the images which will be shown for each sound in
the SingIt! window. We use Canary to generate sonagrams of each sound, and
SuperPaint to clean up the images. Just copy the image from the Canary
sonagram and paste it into the Paint layer of SuperPaint. Clean it up and
store it on disk. We use the two-bit (instead of grayscale or color formats)
because the sounds take so much memory, it is silly to have a picture which is
any fancier (and hence memory demanding) than necessary. The pictures are
really only a mnemonic for which song to play. When all the pictures are
ready, close Canary but leave whatever graphics program you are using open.
Load the picture for the first sound into the graphics program, select the
part of the image you want, and copy it to the clipboard. Double click on your
resource file and then double click on the PICT icon. The 5 song sparrow
sonagrams will be shown. Select the sparrow images one by one and hit the
Delete button. Then go to the Resource Menu of Resedit and hit the Create New
Resource item. A box will open. Hit paste and your first image will be
stored with ID 128. Go back to your graphics program and copy the next image
to the clipboard. Return to your resource file, hit Create New Resource
again, and paste in your next picture. As with snds, PICTs are listed in the
resource file in the inverse order with which they are listed: the first PICT
added will be last in the list. Be sure to organize your PICTs so that the
View "By Order in File" is that which you want in the viewing window and that
which correctly matches the order of the snds. To do this, you will first need
to attach a name to each PICT added. Select each PICT in the resource file by
clicking on its image. Then under the Resource Menu, select "Get Resource
Info". Fill in the name in the box provided. If all the PICTs are named, you
can check their order in the file by selecting "By Order in File" under the
View Menu. If the order is wrong, set up a dummy resource file, paste the
PICTs into it in the order you want, and then replace the PICT icon in the
original file with the new one. When all the pictures are pasted in, hit Save
in ResEdit. Now count again to be sure that the number of snds, labels, and
picts are the same and that all are in the same order.

You are now ready to play the sounds.

If you are confused about the ordering of the PICTs, snds, or STR# fields, use
ResEdit to open up the resource file called Speech Test. This has all of the
components in proper order, properly labelled, and clearly verifiable (by
looking at the PICT or by playing the snd).

PlayBack: The sound output jack on the Mac can be fed directly to a field
amplifier and speaker system. Configuration depends on your system.

Memory Limitations: The program itself can take as many songs as the computer
has RAM. The program will try to fit all the images into a single non-
scrolling window: the more images, the smaller each will appear in the single
window. Remember that sounds take a very large amount of memory. The program
is set for 1500 K of memory. If you try to import a file larger than this,
the program cannot take it until you use the Get Info item in the File menu of
the Finder to reset the program's memory to a higher value. That value must,
of course, be less than the maximum RAM you have available. Make any change
in the memory assignment to the program when it is not running.

Caveats: This program was designed for our own experimental use. We take no
responsibility for any problems, bugs, or time you may lose using it. Do let
us know if bugs are encountered: we may have no time to work on them now, but
may get around to it eventually. It works great with parrots and song
sparrows!
------------------------------------------------------------------------------

Jack Bradbury and Sandra Vehrencamp
Dept. of Biology 0116
UCSD
9500 Gilman Drive
La Jolla, CA 92093

email: jbradbury@ucsd.edu svehrencamp@ucsd.edu