Getting Started

Having installed XBAT, there are really only a few basic operations, which once you've learned, will take you a long way using XBAT. Like any application, XBAT takes a little bit of time to get used to; however, we hope that after learning a few of these basic operations, progress will come quickly.

Running XBAT

To run XBAT, simply change directory to the XBAT directory and run xbat.m. If you installed in your MATLAB work directory, this is easily done from the command line, by typing:

>> cd [your_xbat_directory]
>> xbat

Users and Libraries

XBAT is capable of handling multiple "users", which are not the same as operating system users. For most installations, you will really only need one. XBAT starts up and creates a new user called "Default". You may choose to create a new user by pressing the New ... button. The main motivation for creating your own user is that the Logs you create while using XBAT are attributed to the active user.

Every user gets their own set of "libraries". Libraries are basically collections of sounds. For instance, you could have one library for terrestrial animal calls, and another for marine animals. There is also a fully-functional "Default" library that you can use if you just want to start right away. Adding a new library is just like adding a new user, you simply click the New ... button, type in a name, and click OK. The library is stored in a well-organized location by default.

Adding Sounds

Now that you have a user and at least one library, you can start adding sounds so that XBAT can work with them. XBAT works either with single-file sounds or multi-file "streams" contained in directories. In the XBAT_ROOT/Samples/ directory, there are examples of both.

To add a single-file sound, just click the "Add File ... " button, and point to a file you are interested in. Adding file streams is just as simple, click "Add Folder ..." and point to the directory containing your file stream. Note that file streams are ordered by file name, so that if you already have time-stamped (or even alphebetized) files, they will load in the correct order.

There is one more option for adding sounds. You can actually open every sound in an entire branch of the file system by pointing "Add Folder ..." at it. For example, you could point to the XBAT_ROOT/Samples/ directory to add every sample sound (single- and multi-file) to the current library.

XBAT can open AIFF, WAV, AU, FLAC, OGG, and MP3 sounds. This means that if you have an album of music that you enjoy in MP3 format, you can add it as a file stream and browse its spectrogram. We enjoy doing this.

Sound Metadata

For multi-file sounds, XBAT allows you to store additional information along with the sound data the will be loaded automatically. You can load array geometry, sound speed, recording schedule and datetime information. The "humpback" example sound has geometry and sound speed files included, so you can test out this functionality. Further, the file formats are described here .

Browsing

You can open any sound in your library by double-clicking on the sound's name in the "Sounds" window, or by right-clicking and choosing "Open". The list of sound names can get quite long, so we provide a search filter. Just type all or part of the name of the sound you are looking for into the box labeled "Search", and press "Enter". The sound list and corresponding log list will be trimmed down to matching sounds and associated logs.

Opening a sound brings up an XBAT browser. The browser shows an array of spectrograms, one for each channel in the sound. There is a slider and group of zoom buttons for time naviagation, and a set of menus along the top of the window.

The browser shows one "page" (time interval) at a time. You can easily change the page duration by using the zoom buttons at the bottom-right of the screen. The third zoom button zooms to the current selection and has no effect if there is no selection.

You can play back an entire page by double-clicking anywhere on the spectrogram image. A blue "play head" line will appear, and scroll across the screen, synchronized to show you what you are hearing. Also if you have an active filter, the filter will be applied during playback. This can be a lot of fun, especially since XBAT is extensible and you can create any kind of filter you want to!

There are a few other things that you may want to do immidiately with the display, like change the spectrogram settings for example. All of the naviagtion and parameter settings in XBAT are accessed through one of several Palettes attached to a given sound browser.

Selection

You can highlight any time-frequency rectangle on the current page, called a selection. If you click and drag on the spectrogram, a red box will appear when you release the button. Click on any of the selection's "edit points" (the small squares at the corners and edge centers, and the "+" at the middle) and drag to move and change the selection boundaries.

You can play back the sound for a selection by double-clicking the spectrogram image within the selection box. If you right-click anywhere on the selection you will get a context menu containing information about the selection including its time-frequency bounds

Palettes

All of the browser control functionality is available through a set of small control windows called "palettes". These palettes are all accessed thorough the browser Window menu. Choosing any of the options in the window menu opens a "palette".

For instance, if you choose Window > Page, a small window will pop up that has controls for which channels are displayed, the duration and overlap of the page, and the minimum and maximum frequency displayed for the page.

Each palette contains a number of controls that pertain to its purpose. Feel free to open each palette and explore its functionality. We've found that it's usually helpful to have at least the "page" palette open, also the "Navigate" palette is useful for jumping from file to file in multi-file sounds, and the "Event" palette will be extremely important for exploring logs created by detection extensions, which you'll learn about a little further along.

Spectrogram Settings

You can edit the spectrogram settings to achieve whatever spectral and temporal resolution you need. However, by default, the window overlap is set dynamically based on the page duration, the FFT size and window length, to provide a spectrogram with the same approximate number of time slices as the number of horizontal pixels on your screen. This way, you will never compute the spectrogram with more resolution than you can actually see. To turn off this feature, just un-check the "Auto" box, and you will have full control of the spectrogram settings.

You will also notice that there is a second "tab" in the Slice section of the spectrogram palette, called "Summary". There are two controls there for a special aspect of XBAT's spectrogram calculation.

If the page is long enough that even with the window advance set to full (no overlap) there will be more slices than you have pixels, XBAT will begin "summarizing" spectrogram slices by computing a statistic on each "bin" over a number of slices such that the number of summary slices falls back under the number of screen pixels.

You can select the statistic to use in the summarization, as well as the "quality". Lower "quality" settings mean that some slices are never computed, and thus dropped from the statistic.

Filters

XBAT is extensible, and one of the places where this ability shows through is in the ability to filter sounds and spectrogram images. We have included a number of filter extensions along with the XBAT core. At some point you may want to write your own, but for now, you can try out one of the included ones.

The browser has a menu called "Filter". If you click on this menu and choose "Frequency > Bandpass", a palette will come up that shows you a filter frequency response, and a set of controls for changing the filter design. The top section of this palette has two controls "Fade" and "On". Clicking the "On" button, not surprisingly, filters the signal, and the browser spectrogram display updates.

You will be able to clearly see the effects of the band-pass filter. You can also listen to the effect of the filter by playing back the page or selection. Filtered data is automatically passed through every part of the system, including playback, spectrogram computation, detection, and measurement.

We have also included a large selection of image filters. You can open any of the image filter palettes, and turn them on to get some interesting effects on your spectrogram, and have some fun. XBAT currently allows only one signal, and one image filter to be "active" at a given time. We do not support "chaining" of filters at present.

Logs

Let's say you make a selection that contains a particularly interesting "Northern Hump-backed Woodpecking Tree Frog" calls. You would probably like to save the selection in some way. XBAT lets you do this by providing "logs", which are really just collections of saved events. By default, there are no logs associated to a new sound.

You can attach a new log by opening the "Log" palette, and clicking on the "New Log" button. A dialog will appear, just like the "New User" and "New Library" dialogs, asking you to specify a name. If you click "Ok", a new log will be created for the open sound with the name that you specify. You can also create logs by right-clicking on the sound name in the XBAT root palette and choosing "New Log ...".

Now, if you want to log your selection, you can either right-click on the selction and choose "Log Selection To > (Log Name)", or just press the "L" key. The selection will turn green and have a numeric label. The selcction is now called an "event".

You could (if you really wanted to) browse through an entire sound, and log every interesting event you found. You can also create multiple logs for each sound, and color-code them using the "Options" panel of the Log palette, for instance to log calls of two completely different animals in the same sound.

if you click anywhere within a logged event, that event becomes "selected", and you can edit its boundaries just like editing a selection. All changes to logs are saved automatically, so you never need to worry about losing your logging work.

Detection

Manually selecting and logging is tedious work (you'd have to really want to do it). Fortunately, you probably won't have to: another extremely useful type of XBAT extension is the detector. Like filters, we have included several examples of detectors.

The most mature of these, and arguably the most useful, is the "Data Template" detector, which essentially looks at the time cross-correlation sequence between an example event and the sound, and creates events corresponding to the significant peaks.

You can try out the template detector by loading a sound that has many calls of relatively consistent shape. First, open the data template detector palette by choosing "Data Template ..." from the browser's "detect" menu. Select the type of event you want to detect, and press "Ctrl-C" on the keyboard to load the selection into the detector as a template. You can give the template a tag just by typing your desired tag into the "Tag" box and pressing "enter".

Once you have a template loaded in, you can turn the detector on by clicking the "On" checkbox under the "Detect" panel and the "Active" tab. A waitbar will display, and then flashing dotted selections will appear around events that look like the one you selected. Nothing has been logged yet, you turned on "Active" detection, which lets you preview the results of a detection before you commit to logging.

If you are not satisfied with the performance, you can change the threshold using the "threshold" control, or pick a different template. You can visualize what the detector is doing using the "Explain" control, which brings up a window showing the cross correlation function and the threshold.

Once you have a template that seems to work well enough, you can try running a persistent detection. Click on the "Persistent" tab. The control called "Output Log" should display the name of the currently active log. Then just press "Scan". The results of the detection will be saved in the current log.

Event Browsing and Navigation

If you picked a template of which there were many occurrances, you should now have a log with a substantial number of events. XBAT makes it easy to explore a log in the browser using the "Event" palette. Open it up, and you should see a list of events - labelled with the tag you supplied in the detector, along with time, channel, Log name, and "score" information.

double-clicking on any event in the event will bring up the page in the browser that contains that event, and make the event the current selection. You can choose the order in which events are displayed with the pop-up menu control to the top-right of the event list.

Perhaps the most interesting order is "Score" order, the default. Detectors have the ability to say how "good" any event they detect actually is, and the data template detector simply outputs the raw peak correlation value for every event. So, the first event in the list had the highest peak correlation of any event in the entire sound!

You can add annotation to events by typing in the "Tags" and "Notes" boxes. this will work for either single- or multiple-event selections, so you can tag every event with the same tag if you want.

You can also manually "rate" events, to express your subjective judgement of how "good" they are, by clicking on the "Rating" control. The number of filled-in dots indicates your rating. Note: some of the features of the event palette are quite new, and not all of the functionality has been thoroughly tested.

Wrapping Up

We've tried to cover most of the usage bases with this document, but there are features that are not even mentioned here. You can explore all of the palettes and menus in the browser and try out the various options.

You may also be anxious to ge started integrating your own code into XBAT, and we wrote a tutorial to creating a simple kind of extension called an "Action" that should allow you to plug in any existing code with a bare minimum of overhead. This Developer tutorial is available. Happy sound analysis!