# &app; manual (&appversion;)

&rel_year;
Stefan Kost
Buzztard Developer Team

&legal;

Stefan
Kost
Buzztard Developer team

     buzztard-devel@lists.sourceforge.net

&app; manual (&appversion;)
&rel_date;

Buzztard Developer team buzztard-devel@lists.sourceforge.net

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, see the Buzztard website at http://www.buzztard.org.

## Introduction

&app; is a music composer for the GNOME desktop. It partly follows the concepts of programs like SoundTracker, FastTracker and the like, but is based on a modern media engine (gstreamer). This engine supports virtual sound generator and effects in the form of numerous plugins.

During the next section we describe the concept of the &app; and also compare it to similar applications. If you are familiar with some of those, the retrospective sections should help to understand the way &app; works.

The main chapter of the help system is separated into these sections:

The chapter is introducing the &app; in a tutorial style. The later chapter have reference character, describing each view and dialog.

### The concept behind &app;

&app; follows the concept of tracker applications. This is quite different when compared to other music composers. The tracker concept is more focused on the event data. There is no piano roll (at least not now). Instead song fragments (patterns) are shown in a tabular way.

Important design criteria for &app; are:

- fast and system compliant ui

- keyboard shortcuts for everything

- total recall

### Comparison to Buzz

&app; is inspired of lot by Buzz. Some features are still missing and some things already work better. The UI in is not a 1-to-1 copy, for Buzz users the UI will still look familiar.

&app;:

- can render songs to wav/mp3,ogg-vorbis/... including song-meta-data (tags) and multi track exports

- uses color-codes for machine-types through its ui

- generates cleaner machine UIs (collapsing parts, more distinct widgets)

- has a scalable machine view

- can use beats other that 4/4

- shows volume and pan on wire

- does balance on stereo wires

- has analyzers and mixing controls in sequence view

- can have multiple wire-analyzers open

- can be remote controlled with UPnP a/v software

- supports HID input devices for effect control (e.g. joysticks)

- has only marginal MIDI support

- has no pattern recording yet

- does not support machine templates

### Comparison to Tracker applications

While &app; has much in common with tracker applications, there are some notable differences.

- trackers are sample based, buzztard also uses software synthesizers

- trackers have a fixed track concept, buzztard uses tracks per machine (source/effect/sink)

- trackers do not have the virtual machine routing

## Getting started

The below tutorials will introduce &app; by going though a few examples. Each example will introduce new features.

### Live Effects

This tutorial demonstrates how to use &app; as a toy for live audio effects.

Start the graphical editor 'buzztard-edit'. The first tab shows the machine view. Here you can create elements (sound generators and effects) and link them together. To create an element, right click on the background and select an element from the context menu. For the example choose alsasrc.

Please note, that not all the elements in the list will work perfectly in a live situation right now. Also useing livesrc and normal source does not work reliable right now. This will be address in a future versions of buzztard and gstreamer.

In your sound card mixer you should enable recording from the microphone or provide some music on line-in. Next add audiodelay and equalizer-10band elements. Now wire them together by pointing on the source element (alsasrc) and dragging a wire to the target (audiodelay), while holding the shift-key pressed. The wire will become green when the mouse is over a valid target. Releasing the mouse creates the link. Repeat the procedure for audiodelay &rrar; equalizer and equalizer &rrar; master. The wires have a pointer shape in the middle, showing the direction. A left click onto it allows to change the volume of the link, a shift left-click the stereo panorama or balance and a right click shows a context menu for disconnecting the elements and for showing an "analyzer dialog". Open that one for the link between equalizer and master. Finally double click the equalizer and the audiodelay to open their real-time settings windows. Now you should see something like this:

(FIXME: need screenshot)

Now lets give it a try. Activate the loop in the toolbar and press play. Now you can tweak the settings of the effects while making some noise. The parameter-changes will be effective right away. In the "analyzer window" you can see the frequency spectrum of the sound and the volume level.

### Synthesized Melody Sequence

This tutorial will introduce the sequencer functionality and explain patterns.

Start the graphical editor 'buzztard-edit'. On the first tab - the machine view - add one simsyn. This is a very basic synthesizer. Also add an audiodelay and link simsyn &rrar; audiodelay &rrar; master. Now switch to the sequence view. Buzztard has automatically added a track for the simsyn. Also the song has a default length of 64 ticks (the time axis goes from top to bottom). The track will take patterns. Patterns are the actual building blocks of the score. Patterns are a block of control events, like triggering a note or changing a machine parameter. The right side shows existing pattern for the machine the cursor is in. Simsyn has one called '00'. Press '0' four times to fill the sequence track with this pattern. Buzztard will repeat the events there 4 times and stop. If you press play now, you won't hear anything yet, as we have not recorded any events into the pattern. Lets switch to the pattern editor. This can be done, by just pressing "Enter" in addition to using the tabs.

The pattern editor shows a grid. Again the time goes from top to bottom. From left to right the editor shows parameter groups. This simple synthesizer has just one. More complex ones have a block with global parameters and one for each voice. Each column shows some info in the status bar when the cursor is in there. The first column is for entering notes. It works like it always worked in trackers - by using the computer keyboard. The two rows above the space key form one octave and the two rows above one octave above. The lower row is for while keys and the upper row for black keys, y/z &rrar; c, s &rrar; c#, x %rrar; d, d &rrar; d#, c &rrar; e, f unused, v &rrar; f and so on. Press Ctrl-2 to set cursor stepping to go down 2 rows on each edit and enter "yqy3ywyr". If you press play now, you should hear a simple melody. (FIXME: patterns + sequence view)

### Sampled Sounds

This tutorial explains how to work with sampled sound.

(FIXME: wave-table view)

## The main window

After starting the &app; Music Editor, you will see the main window. If you start the application without specifying an initial file (as a parameter on the command line or by double clicking a song in Nautilus), the window will look like this.

### &app; window

Shows &app; main window with menu bar, toolbars, editor views and status area.

On the very top of the window is the menu bar. Below one finds the toolbar. And below again are tabs to switch between various views. Each view is for editing certain aspects of the song. On the bottom is a status bar.

Many parts in the UI show tooltips with brief explanations. Hover the mouse pointer over the region and wait a moment.

The UI uses context menus in several places. Press right mouse button to get the menu. The menu offer crucial functionally not available elsewhere right now.

### The menu bar

The menu bar gives you access to file operations, standard editing function, settings and help.

The File menu allows to start a new song, load and save songs, as well as end the program. Songs need other resources in order to be played. These are the sound-generators and effects that are used and eventually digital audio-samples. When loading a song &app; checks if all needed resources are available and if not lists them in one dialog (FIXME: document and link).

The Edit menu contains clipboard functions and invocation of .

#### Limitations

Cut/Copy/Paste functionality in the edit menu is still not implemented.

The View menu offers customization for the shown UI elements. It also contains shortcuts to the different song-views.

### The tool bar

In contrast to the menu bar the tool bar only shows common operations as shortcuts. On the right end the toolbar shows a volume-meter for each audio-channel and a volume control.

### The song views

Each part of a song is represented by a specialized views which one can switch to with the tabs. Next we briefly introduce each tab, where in the next sub section they will be described in detail.

#### The machine view of a song

A song utilizes sound generators, effects and sinks - all called machines. A new machine can be added from the context menu that appear on a right click over the page area. Machines can be moved around by grabbing them with the mouse and dragging them around. To connect machines, move pointer over the source, press shift+left mouse-button and drag the wire to the target machine. The wire turns green, if the connect can be made. Connected machines are shown in bright color and disconnected one in a desaturated style.

##### Machine view

The songs machine view.

Wires have volume and panorama control support. A left-click on the pointer-shape in the middle of the wire open a volume popup. A click outside closes it again. Shift+left-click opens the panorama control.

Machines and wires have context menus. The menu for the wire can be accessed by right clicking over the pointer shape in the middle. Not yet connected elements can be removed immediately (without any dialogs).

A double click on a machine brings up the .

#### The pattern view of a song

Patterns are the building blocks of a song. They are short snippets of events for one machine, that can be reused in the sequence. The vertical axis shows ticks (time) and the horizontal axis has the parameters. Parameters are organized in groups. There is a group for global settings and groups for each voice if the machine is polyphonic.

##### Pattern view

The songs pattern view.

In the page toolbar one can select the machine and the pattern for the machine. Pattern names in gray color indicated that the pattern is not used in the sequence (thus save to be removed or changed). One can also select the base octave for entering notes via keyboard and the sample that should be used for wave-table based machines.

A context menu in the pattern area allows to create new patterns and modify existing ones. Unused patterns can be removed immediately (without any dialogs). If the machine is polyphonic, one can add or remove voices by using the context menu.

To switch to the sequence editor press Enter while the pattern editor has focus.

(FIXME: write about keyboard short cuts)

#### The sequence view of a song

A song consists of several tracks (columns), where in each track patterns are played. The rows are time slots.

##### Sequence view

The songs sequence view.

The sequence header for each track shows the name of the machine, mute, solo. bypass buttons (depending whether it is a generator, effect or sink) and a level-meter.

One can navigate around using cursor keys. When changing tracks, the list of patterns on the right is updated to show the patterns for the current machine. Again gray pattern label color indicates that the pattern is not in use. Patterns can be entered into tracks by pressing the associated key (shown left to the pattern name in the list). To switch to the pattern editor with the pattern the cursor is over selected, press Enter.

To set play position click with left-mouse button in the first column at the desired time location. To modify the loop start/end instead hold down the Ctrl or Win (Mod) key while clicking.

To expand the sequence, scroll down with the cursor and press Ctrl e to set the end-line. If the cursor is above the end-line, pressing Ctrl e will set the loop-end marker. When the cursor is on the loop-end marker Ctrl e will shorten the sequence. To set the loop-begin marker press Ctrl b.

It is also possible to insert and delete full rows or just entries in a track. The shortcuts for this are Ctrl i to insert a full row and Ctrl d to remove a full row. To only insert or remove inside the current track hold the Shift key in addition.

(FIXME: special-patterns = {mute, break, solo, bypass})

#### The wavetable view of a song

The wavetable hold sampled audio snippet that can be used e.g. from tracker sources.

##### Wave-table view

The songs wave-table view.

The left column is the wavetable. Samples are loaded by double clicking them in the right side file-browser. The toolbar above the browser allows to pre-listen before loading. Waves in the table can also be played, renamed and removed.

Each wavetable entry can have multiple wave levels, which are shown below the wavetable for the selected wave. Some of the details are editable. Right to the wave level list is a waveform preview widget. It shows loop markers and a playback position indicator.

#### The information view of a song

This page allows you to change song parameters, such as speed and timing resolutions and to enter information about the song. The meta data will be used for the tags when creating a final mix-down.

##### Info view

The songs info view.

### The status bar

The status bar that is located at the bottom of the window. On the left side it shows the status of longer operations like saving and loading with a text message. It also shows some extra detail in some song views. On the right side, it displays the length of the song, the loop range, the playback position and the current CPU usage.

## Dialog windows

There are various dialogs that are invoked from the main-menu or from context menus.

### The settings window

This window contains all settings for the &app; application. All settings are grouped into categories that can be chosen from the list on the left side.

#### Settings dialog

#### Audio device settings

Select the audiosink to use. It will be changed immediately, except when a song is playing (will be switched after stopping).

##### Audio device settings

All offered audio sinks should be fine for song-playback. One area where they differ is latency. Low latency is important when playing machines live - that is playing notes in the pattern editor or changing parameters in the machine window. The lower the latency, the more immediate the changes are. Jack is known for being able to achieve a low latency, but also a well configured alsa or pulseaudio can achieve a reasonable latency.

(FIXME: write more)

#### Playback controller settings

UPnP A/V remote control via Coherence. (FIXME: explain)

##### Playback controller settings

#### Interaction controller settings

Interactive controller for machine parameters. (FIXME: no settings yet)

##### Interaction controller settings

#### Color settings

(FIXME:)

##### Colors settings

#### Shortcut settings

(FIXME:)

##### Shortcut settings

#### Directory settings

Configure default directories used for various file types.

##### Directory settings

### Machine properties dialog

The main area of the dialog is covered by the parameters of the machine. These parameter control the generated audio or the effects. If parameters are controlled by patterns, the ui will reflect the changes as the music plays.

Parameters are grouped. There is a group from global parameters and one for each voice (for polyphonic machines). Effects and the master also have a group for each input allowing to change volume and panorama. These are the same parameters that can be changed in the wire in the machine view.

Each parameter has a context menu. The menu allows to bind the parameter to a hardware controller and unbind it. If a parameter is bound, the changes on the hardware controller will effect the parameter. &app; supports hid (e.g joysticks, wiimotes, harddisk accelerometers) and midi devices.

At the top of the dialog is a small toolbar. One button allows to show or hide the right side preset pane. Most machines support presets. Presets are a collection of parameter sets.

#### Info view

Machine properties dialog.

### Machine preferences dialog

Machine preferences are settings that are configured for the whole song. These settings can be changed over time.

#### Warning

Right now this contains also some low-level settings, where changing them could break playback.

#### Info view

Machine preferences dialog.

## Reference

This chapter contains a few useful lists for reference.

### Keyboard shortcuts

Currently keyboard shortcuts are listed on the buzztard wiki. (FIXME:)

## Index