# &app; User Manual

## Introduction

Welcome to the start of an exciting journey!

&app; is a simple to use, yet very powerful Open Source audio workstation. With it you can create and record music, audio and other projects. &app; has been specifically designed around ease of use and helping you to ignore the software and concentrate on your projects. This user guide is meant to be helpful in explaining the specific details when working with &app;.

&app; is an organic piece of software and grows and improves gradually. Due to its Open Source foundation, different people from all over the world work on it to make it the best tool for creating audio and music easily. Likewise, this guide reflects that organic nature and also grows naturally. This document presents you with a complete guide to the features and facilities available in &app;. With each new release, this guide will explain the new features available for you to use.

Like any Open Source project, &app; and this guide needs your help. Invariably in most Open Source projects, the documentation always falls behind and does not track the progress of the application it is documenting. Since &app; is made for musicians and designed to be simple and easy to use, this guide plays an essential role. If something is incorrect, outdated or just plain wrong, please fix it or report it to the &app; Project. It will be a great contribution to this important project.

## Features

&app; offers you the following features, ensuring that your audio producing experience is smooth and versatile:

- Easy to use interface, designed from the ground up. &app; uses concepts and language familiar to musicians, and is a breeze to use.

- Simple editing with splitting, trimming and moving tools.

- Multi-track volume mixing with VU sliders.

- Import audio (Ogg Vorbis, MP3, FLAC, WAV and anything else supported by GStreamer) into your projects.

- A range of instruments can be added to a project, and instruments can be renamed. Instruments can also be muted and soloed easily.

- Export to MP3, Ogg Vorbis, FLAC, WAV and anything else GStreamer supports.

- Mixdown profiles allow you to quickly automate post-mixing processes, like running a script to upload the files to a remote server.

- Powerful extension system that allows &app; to provide functionality beyond what is commonly possible, in audio editing software.

- Documentation (User Guide, FAQ, Tutorial) and User Community (Forums, IRC).

## Getting Started

### Starting &app;

You can start &app; in the following ways:

Applications menu

- Choose Sound & Video &app;

Command line

- To start &app; from a command line, type the following command, then press Return:

  `jokosher` `filename.jokosher`

  where `filename.jokosher` is the name of the file you want to open.

### The &app; Welcome Dialog

When &app; starts, you see the following window:

#### &app; Welcome Dialog

Shows &app; Welcome dialog. Contains Recent Projects dialog, Create a New Project, Browse for an Existing Project, Preferences and Quit.

The welcome dialog has a number of different facilities:

- Recent Projects - this list provides a simple means of accessing your most recent projects, with the most recent ones at the top. To load a project just double-click it.

- Create a New Project ‐ click this button to create a new &app; project. See jokosher-get-create for more information.

- Browse for an Existing Project ‐ this button pops up a file dialog box to allow you to find an existing project file on your computer. See jokosher-get-open for more information.

- Preferences ‐ clicking this button displays the main &app; preferences window.

- Quit ‐ click this to exit out of &app;.

To disable the welcome dialog, check the Don't show this on start-up checkbox. You can reenable it in the Edit Preferences window. There are other options you can configure for &app; start-up, see jokosher-main-configure for more information.

### Creating a New &app; Project

You can create project by either selecting the Create a New Project button from the welcome dialog or by clicking File New Project in the main window.

A dialog box then appears and you are asked for some details:

- Project Name — enter a name for the project here. This is most likely going to be the song title or podcast title.

- Folder — select a folder where your project will be stored. Please note that the folder you select will have a new directory created for it. So, as an example, if you select /home/user/projects for this option and your Project Name is Song, a directory called Song inside /home/user/projects will be created.

- Author — enter your name or the name of your band in this box. This is the author of the project.

When you have added these details, click the OK button to continue.

If this is your first time using &app;, jump to jokosher-main-window.

### Opening &app; Projects

You can open existing projects by either selecting Browse for an Existing Project from the Welcome Dialog or clicking File Open in the main window.

When you select this option, the GNOME file picker will appear. &app; projects are stored in a directory with the same name as the project. Inside that directory is a `.jokosher` file. Double click on it to load it.

If this is your first time using &app;, jump to jokosher-main-window.

## The Main &app; Window

The main &app; window is where the action happens:

### &app; Main Window

Shows &app; Main Window. Contains the Menus, the Toolbar, Click Track, Time Line, Time Display, Workspace Selector and Project Zoom area.

On &app;, everything happens inside a single window, making it simple to see what is going on at any time.

### The Menus

Along the top side of the screen you can see the menus. Virtually every possible action in &app; is available through them, so if you are can't figure out how to do something, be sure to browse them first.

#### File

- New — opens a new project in the existing window. If there are changes in the current project, you will be offered a chance to save them.

- Open — opens an existing project. If there are changes in the current project, you will be offered a chance to save them.

- Save — saves the current project. This option quickly saves all information in the project including Undo and Redo history.

- Save As — analogous to the Save functionality, but this option allows you to save the project under a different name.

- Close — closes the current project without closing &app;. Again, you'll get a chance to save the project if there are changes.

- Recent Projects — this submenu lists up to the last 8 projects opened in &app;. This is a convenient way to move quickly from one project to another.

- Mixdown Project — brings up a dialog that begins the final stage of your project - the mixdown. Choose a name for the output file, a location where you want it saved, and an output format. &app; will then mix the project and save it as a single audio file in your chosen format.

  Optionally, you can add additional mixdown steps to further customize what happens during the mixdown operation. For example, you can run a script that gets executed after mixing the files down, uploading them to a remote server.

- Quit — quits &app; completely. You will get a chance to save any unsaved work.

#### Edit

- Undo — Reverts the last change made to the project.

- Redo — Redoes the last thing that was reverted with Undo.

- Cut — Removes the selected object from the project and places it on the clipboard, replacing what was there previously.

- Copy — Puts a copy of the currently selected object on to the clipboard, replacing what was there previously.

- Paste — Places the contents of the clipboard into the project. See jokosher-views-recording-editing for details on selecting pieces of audio to cut, copy and paste.

- Delete — Removes the selected object from the project and discards it.

- Preferences — Opens the &app; Preferences window.

#### Project

- Add Instrument — See jokosher-views-recording-addinstrument for more information.

- Add Audio File — Imports a given audio file into a new Audio file instrument. This is equivalent to adding a new instrument, then importing an audio file into it.

- Recording Inputs — This dialog lists each instrument in the project and shows which input from your sound card is connected to it. For each instrument, you can change its connection by clicking the drop-down box and choosing an input to connect.

- Time Format — Selects how time is displayed on the Time Line. The options are Show as Bars, Beats, Ticks or Show as Hours, Minutes, Seconds.

#### Instrument

- Add Audio File — Adds an audio file to an already existing instrument. This is very similar to the Project — Add Audio File function, but it doesn't create a new instrument to place the imported audio into.

- Change Instrument Type — Changes the type of the selected instrument.

- Remove Selected Instrument — Removes the currently selected instrument from the project.

#### Extensions

- Extension Menu* — This menu section is variable since it lists all the available extensions. Each entry opens the corresponding extension.

- Manage Extensions — Opens the extension manager dialog. It allows adding, removing and disabling extensions. See jokosher-extensions for more information.

#### Help

- Help — Opens the &app; user manual you are currently reading.

- Report Bug... — Opens the &app; Launchpad site to report bugs.

- Online Forums — Opens the &app; online forums website on your preferred web browser.

- Contributing to &app; — Lists the different ways you can contribute to &app;. &app; is still in development and can always use your help.

- About

  - Credits — Opens a dialog box that lists the many people who have worked to bring you &app;.

  - License — The complete license for &app;.

### The Toolbar

Below the menus are the main toolbar buttons. These buttons are ideal when you're perched over the desk, holding your guitar. They can be used to perform the following actions:

- Add Instrument — click this button to add an instrument to the project. See jokosher-views-recording-addinstrument for more information.

- Add Audio File — Same as Project Add Audio File.

- Rewind, Play, Forward, Record — these buttons control playback and recording.

- Time display — shows the current elapsed time in the project. Time will be displayed in hours, minutes and seconds or bars, beats and ticks, depending on the time format you've chosen in the Project menu.

- Workspace Selector — these buttons allow you to switch between the two workspace views in &app;.

- Click Track — this feature generates a click that you can play along with. You can set its speed in beats per minute and change its time signature.

- Time Line — this ruler gives you a visual representation of your project in time. The line will be marked off in measures or in seconds, depending on your current time format.

- Project Zoom — this area at the bottom of the main window will help you zoom in and out and scroll the project quickly. The minus and plus icons will zoom the time line out and in, respectively. The center icon will return you to a medium zoom. If the area of your project doesn't fit entirely on the screen, you can drag the scroll bar to adjust the zoom level dynamically.

### Configuring &app; Preferences

The &app; preferences menu can be accessed by clicking Edit Preferences . Here you can change many settings that determine how &app; works. Note that these settings will be saved for &app; globally, not on a per-project basis.

- Application Start-up — Chooses how &app; will act when it first starts. The available options are:

  - Show welcome dialog — the default. Choose this option if you'd like to pick a project everytime &app; starts.

  - Open most recent project — Choose this option if you'd like to skip the welcome dialog and jump to the project you had open the last time you used &app;.

  - Don't open anything — Choose this option if you want total control. You can open a project later from the File menu.

- Recorded Audio Format — Choose the format in which &app; will save the audio during recordings.

- Recording Sample Rate — Choose the sample rate used for recording audio in &app;.

- Audio Output Plugin — Choose the audio hardware and Gstreamer pipeline used for playback.

  - Output — Sets the output profile for &app;.

  - Pipeline — Sets the custom pipeline to use for Gstreamer.

  - Device — Sets the ALSA device to use with &app;.

Available recording formats, sample rates and playback devices will depend on the hardware and plugins installed on your system.

## The Recording Workspace

### Recording View

Inside the recording view, only the instruments are displayed. This is where you will spend most of your time recording, editing and re-recording.

Recording is the first step in the process of creating a project. You will add instruments, usually one at a time, record audio into that instrument, then add the next instrument. Working in the recording view usually follows the steps listed here.

#### Adding Instruments

Instruments are a key concept in &app;. Think in terms of instruments, instead of tracks. Instruments allow you to infer a lot about your project at a glance.

Currently, instruments are very simple - they just contain the name and icon of the instrument.

##### Adding Instruments

Dialog for adding new instruments to the current project.

To add an instrument, click on the Add Instrument button to bring up the dialog, then pick the instrument that best resembles what you'll be recording. Click OK to finish.

Notice that once an instrument is added, you can click on its name and change it to anything you want.

#### Recording

1. Add Instruments — After adding an instrument, you will see that it has the following features:

   ##### Instrument Features

   Shows Instrument lane features. Contains Instrument Icon, Instrument label, Record, Mute and Solo buttons and Recording Lane.

   - Instrument Icon — the selected icon for the instrument.

   - Instrument Label — this can be changed at will simpy by clicking on it. It is just a label to identify the instruments in case you have several with the same icon.

   - Record Button — this button will be clicked to arm the instrument prior to recording.

   - Mute Button — his button will silence the instrument during playback.

   - Solo Button — the opposite of the Mute button. When pressed, you will hear this instrument as solo during playback, with all other instruments muted.

   - Recording Lane — to the right of the buttons is an area where recorded audio will be displayed for this instrument.

2. Set Connections — as explained in jokosher-main-menu-project, the different sound card inputs can be routed to different instruments at will. In this way, even if there is only one input, by connecting it to each instrument -one at a time-, multiple instruments can be sequencially recorded.

3. Record — at this point you are ready to record this instrument. If it's a live instrument, plug it in, press the Record button on the instrument to arm it, then hit the Record button on the main Toolbar. When done recording, click Stop.

   To import an existing audio file, right-click on the instrument Recording Lane then click Import Audio File. Select the file you'd like to import, then click Open. Notice that the audio is now in the recording lane for that instrument. The waveform shows you the volume level at any point in the recording.

   Alternatively, you can use the Add Audio File button in the main toolbar, or drag and drop the audio file.

4. Repeat — unarm this instrument and begin the process again by adding the next instrument until all desired instruments are recorded.

#### Editing

Once all instruments are recorded, editing begins. Think of the instruments as raw materials that you will shape into a final project. &app; offers several tools to help with editing:

- Move — this function shifts a piece of audio in time. To Move a piece of audio, click it and drag it left or right until it is in the desired position. When recording Instruments separately, this function can be used to get Instruments in sync with each other.

- In order to edit audio, a recording often needs to be divided into pieces. &app; offers two main tools to do this:

  - Split — this function divides the audio in an instrument into two sections. Use Split when you want to keep the entire recording, but need to separate it into pieces. To split, double-click in the instrument lane at the point where the audio should be divided.

  - Trim — this function deletes the non-selected portion of the instrument audio. To Trim, hold down the Shift key, click with the mouse at the beginning of the section you'd like to Trim, drag the mouse to the right to the end of the desired section, and release both the Shift key and the mouse button. A Trim tab will appear below the selected section. Click this tab to Trim the non-selected portion of audio.

- Volume fades — volume levels can be edited for sections of audio. Select a section of an instrument by pressing Shift, then clicking and dragging. You see a selection as in the figure below. Notice the red fade points, which will initially be labeled 100%. Grab the corresponding fade point and drag it up or down to adjust volume at that point.

  ##### Volume Fades

  Image describing the use of fade points for volume levels.

- Cut and Paste — this process moves sections of audio from one place to another. If you don't want to Cut a complete recording, Split it into pieces or Trim as above, to separate the piece you'd like to work with. Next, click on the piece you'd like to Cut and select Ctrl X Edit Cut . Finally, click Ctrl V Edit Paste in the spot where the section should go.

- Copy and Paste — this process is used to make copies of the same audio in more than one place. It is similar to Cut and Paste above. First select a piece of audio and click Ctrl C Edit Copy . Then click in the spot where this piece should go and select Ctrl V Edit Paste to complete the operation.

- Delete — this removes a piece of audio completely from the current project. Select the section you want to delete and then click Edit Delete or hit the Delete key on the keyboard.

- Undo — in case you accidentally deleted a piece of audio or pasted it into the wrong spot, select Ctrl Z Edit Undo to revert the last change you performed. To undo more steps, repeat this process.

- Redo — if you wish to bring back a change you reverted with the Undo function, you can use Redo. Click Ctrl R Edit Redo and the last change you reverted with Undo will be restored.

## The Mixing Workspace

This is the main mixing view. This view displays smaller versions of your instrument tracks as well as mixing sliders for adjusting instrument volume levels. This is where you mix your final project.

### &app; Mixing Window

Shows &app; Mixing Window. Contains the instruments and volume and pan sliders.

### Mixing View

Much of the functionality of the jokosher-workspaces-recording is still available. The emphasis, though, is on getting the balance right between the instruments.

- Volume Slider — each Instrument has a corresponding slider. These sliders control the overall volume in the mix of that Instrument. Volume is displayed on the slider as a range from 0% to 100%. Notice that as the slider is moved, the volume level changes audibly and visually.

- Instrument Hide — at the top of each slider is an icon that can be clicked to hide that instrument. It's still there, just hidden out of view. At the bottom of the screen just above the status bar is an Instruments Not Shown list. Click on an instrument in the list to display it normally again.

  Hiding Instruments is useful when you have many instruments and only want to work on a few at a time. For example if you have 3 vocalists, you could mute and hide all other instruments, while you mix the vocals.

- Master volume — at the far right of the screen is the Master Volume slider. This slider changes the overall volume of the project.

### Mixdown Profiles

Once your project is ready to be mixed down, the Mixdown Profiles allow you to automate post-mixing processes like podcasts, uploading files to a server, creating playlists and so on.

To access them, go to File Mixdown Project. In there, you'll be able to customize your mixing down process. By default, an export to ogg action is added automatically. You can change the its file format if you wish to do so.

## &app; Extensions

&app; now has a new feature called Extensions. This allows for third party developers to add features to &app;, make it support new file types or even do something amazing that none of us has anticipated.

### Extension Manager

You can configure Extensions in the Extensions menu which contains at least the Manage Extensions item which brings up the Extension Manager shown in the following figure. Depending on which extensions you have installed, other entries may appear in this menu.

#### Extension Manager

Shows the extension manager dialog used to add or remove available extensions.

The extension manager allows you to see a list of installed extensions. You can also:

- Add an extension — installs an extension into &app;. This opens up a file selection dialog that allows you to chose a .py or .egg file. After confirming that you really want to install the extension, you should see it in the Installed Extensions list. See jokosher-extensions-finding below for more information on getting new extensions.

- Remove an extension — removes the currently selected extension from your system.

- Preferences — allows you to configure the currently selected extension. What you can configure here depends entirely on the extension. Please see its documentation for more information.

- Close — closes the Extension Manager and brings you back to the &app; Main Window.

### Finding new extensions

To find extensions that are currently available, check the Development site .

Join in the &app; Forums to hear news on new extensions, discuss ideas, and contribute information on extensions you're working on.

If you'd like to write an extension, full documentation on the extension system is available on the &app; Development Website

## Instrument Effects

&app; allows LADSPA audio effects to be applied to each individual instrument. With them, you can build complex effect chains to achieve the sound you're looking for.

### The Effects Window

Just click the Effects Button on a particular instrument and you will be presented with the Effects Window for that instrument:

#### Instrument Effects

Shows the instrument effects dialog. It can be used to add, remove and configure the effects for individual instruments.

The following actions are available through this window:

- Activate Effects — The list on the left will list all the effects you have installed on your system, under the chosen category, indicated by the left combobox. From this list select the effect you would like to use, then click on the Activate button (the arrow pointing right), double click on the effect or right click on it and select Activate Effect. In the same way you can add as many effects as needed.

- Adjust Effect Settings — Once an effect is activated, double click on it inside the right list to display the effect settings dialog. Settings available will depend on the specific effect. In this dialog you can tweak all the settings for a particular effect. Click Close when done.

  You can also access the settings dialog right clicking the effect and selecting Settings, or selecting the effect and then clicking on the Settings button beneath the active effects list.

- Preview Effects — Click the Play button at the bottom of the Effects Window and the Instrument will be played back with the effects so you can hear the changes.

- Effects Presets — When you've configured a group of effects that you'd like to keep, they can be saved together as a preset. In the text box labeled Presets type the name for this preset (whatever you'd like to call it), then click Save. The next time you add effects to an Instrument, this preset will be available in the drop down list for you to use again.

- Rearrange Effects — To rearrange active effects, use the Up and Down buttons under the active effects list. You can also right click the effect and click Up or Down accordingly. This is very useful because effects sound different, if placed in other positions inside the effects chain.

- Delete Effects — To remove an unwanted effect, select it and then click on the Delete button under the active effects list. You can also right click the effect and select Delete. No confirmation is requested, so be careful when deleting effects.

### Instrument and Effect Presets

It is important to realize that there are two kind of effect related presets in Jokosher. This section will explains them briefly.

#### Instrument Presets

These presets are meant for common effect combinations, or chains, used in instruments. They are listed in the main effects window described in the earlier section jokosher-instrumenteffects.

For example, a combination of reverb, compression and a delay is normally used in lead guitars. With instrument presets, you can save that effect chain under the guitar instrument and quickly apply it to future recordings, without having to search for the effects you like.

#### Effect Presets

Effect presets save a particular effect configuration. These are listed inside the settings window for each individual effect.

As an example, you could think of several effect presets for a delay called: "5ms delay", "10ms delay", "Hall delay" and "Grand Canyon delay". These presets are useful for storing those perfect settings you just found, for a given effect.