
Rosegarden FAQ
==============


General questions
-----------------


Do I have to be using a particular desktop environment (KDE or whatever)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No.  Rosegarden uses the KDE libraries for various common controls,
but you can run it under any window manager or graphical environment
you like with no change in functionality.


What are the hardware requirements like?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reasonably demanding, because of the mixture of graphical and
interactive GUI stuff with precisely timed audio stuff.  See
<URL:http://www.rosegardenmusic.com/getting/requirements>) for more
details.



Does it support my soundcard?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rosegarden uses the ALSA (Advanced Linux Sound Architecture) soundcard
drivers.  To find out whether your card is supported by ALSA, see the
ALSA project's soundcard matrix
(<URL:http://www.alsa-project.org/alsa-doc>).


Does it support my language?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Translations are included for Russian, German, Spanish, French,
Italian, Estonian, Welsh, Swedish, Dutch, and Japanese.  These
translations are provided by independent contributors and so may not
always be up to date with the current state of the GUI.

If you can help out with translating musical or technical
documentation (no programming required, but it's quite hard work),
please let us know!

See also docs/howtos/i18n.txt in CVS if you are interested in the
technical aspects of translation.


Rosegarden apparently saves in a binary format, where can I find the format definition ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Actually it's just gzipped XML.

gzip has a bit of trouble with gzipped files that don't end in .gz, so the
easy way to have a look is to use

	gunzip -c somefile.rg > somefile.xml


Compilation or installation problems
------------------------------------

macro `AM_PATH_ALSA' not found in library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This can happen only when building from CVS. It means you're missing
the 'alsa.m4' file (usually in /usr/share/aclocal) which is normally
part of libalsa (look for a libalsa2-devel package for your
distribution). This causes the 'configure' file to be misconstructed
because the 'aclocal.m4' file won't be properly generated.

If you can't install libalsa, you can still compile Rosegarden by
pre-building the aclocal.m4 file yourself, like this :

  $ aclocal -I .

(that's what the 'ac_include_me_if_no_alsa.m4' file is for.)

Then restart make -f Makefile.cvs. You will still see the error
message, but the 'configure' file will be properly generated.


arts/artsmidi.idl not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may be missing the kdemultimedia package (and associated -devel
package, if appropriate to your distribution).  Note that you need
this even if you're building --with-alsa.


Rosegarden is crashing at startup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Try running up the sequencer by itself first to see if it's a problem
with that or the main part of the program.  Run:

  $ rosegardensequencer

And you should get a few lines of output finishing with:

  RosegardenSequencer - started OK

If the sequencer starts up OK, try to start the main application
with the command line switch "--nosequencer".  If that fails, see next
question on how to obtain a stack trace, which you should provide as
part of any bug report you submit.


How to get a stack trace for a crash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First export the environment variable KDE_DEBUG as follows (in bash):

  $ export KDE_DEBUG=1

Start rosegarden from the command line, and reproduce the crash.  You
should now have a core file in your current directory. The core file
is either named "core" or "core.<number>". Run gdb :

  $ gdb rosegarden <core_file>

Then once you get the gdb prompt, use the command 'where' to get the
stack trace, and mail to the authors or to the Rosegarden development
mailing list, or include in a bug report.


Crash at startup with LADSPA plugins enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you find that Rosegarden segfaults immediately upon startup, and if
when you run rosegardensequencer by itself as mentioned earlier in
this FAQ you get the following output:

  rosegardensequencer: created plugin manager
  MappedAudioPluginManager::discoverPlugins - discovering plugins
  Segmentation fault

and if you have the Steve W. Harris LADSPA plugins (swh-plugins)
installed, and have Rosegarden compiled with JACK and LADSPA support,
then you may have hit Weird Plugin Startup Crash Bug That We Don't
Understand #421.

Check to see if you have the sfftw2 package for your distro installed.
The versions of swh-plugins provided by some distros appear to require
sfftw2 instead of fftw2 for some reason, but do not specify it as a
dependency, resulting in a broken set of plugins.  If you find that
installing sfftw2 fixes the problem, you might also want to submit a
bug report to the maintainer of your distro's swh-plugins package.

I'm having trouble with a missing 'gzgets' function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a zlib function normally defined in zlib.h.  We've had reports
about this error from people using Slackware or Gentoo.  It turned out
that these distribs install more than one version of the zlib header,
the older one not having this function.

Our configure script actually checks that you have gzgets in your zlib
library, so if the configure succeeds, you definitely have the right
version somewhere -- the compiler is just picking up the wrong header.
Simply making sure the compiler picks up the right one by either
removing the old one or adding a
'--with-extra-includes=/the/path/to/the/right/zlib.h' to your
./configure parameters should work.

Can't build MidiArts.h
~~~~~~~~~~~~~~~~~~~~~~

If the build fails with something like:

  In file included from ArtsDriver.h:30,
                   from Sequencer.cpp:40:
                   MidiRecord.h:25:22: MidiArts.h: No such file or directory
                   make[2]: *** [Sequencer.lo] Error 1

then you've come across our aRts build dependency problem.
Until we get around to fixing it the workaround is to:

  $ ( cd sound ; make MidiArts.h )

and then continue with the build as normal.


I'm using RedHat version (whatever), what packages do I need?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is most often asked by someone who's also using GNOME and hasn't
built a KDE application before, in which case the answer is that you
need the kdelibs, kdemultimedia and arts packages (yes, you currently
need the arts package for trivial reasons even if you aren't building
aRts support), plus the -dev versions of all of those.

Note that at the time of writing RedHat don't ship ALSA 0.9.x, so if
you want to build on a RedHat system with ALSA support you have to
upgrade rather than using the ALSA packages they supply.

ladspa.h: No such file or directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a known build problem that we haven't been able to fix.  You
don't have LADSPA installed, so we shouldn't try to compile against
it, but we can't get automake to behave, and it's doing the wrong
thing.

Your two possible remedies are to configure --with-ladspa=no or to
scrounge up a ladspa.h from somewhere.  Many distros have a ladspa
package, which will include this header.


The Composition View
--------------------

How do I set a loop?
~~~~~~~~~~~~~~~~~~~~

While holding down Shift and and the left mouse button sweep out a loop
region in the ruler at the top or bottom of the main composition window.  
The loop icon in the transport will become enabled and playback will 
always occur within this loop until you disable it.  You can disable
the loop by clicking on the loop icon or shift+left clicking in either
loop ruler.


How do I view the track labels?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On the main window go to Settings->View Track Labels


How do I change the instrument for a track?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Either click with the right mouse button, or click and hold with the
left mouse button, on the track/instrument label.  A pop-up will appear
from which you can choose a new instrument for the track.


How do I rename a segment?
~~~~~~~~~~~~~~~~~~~~~~~~~~

Click the "..." button next to the segment's name shown in the Segment
Parameters box.

How do I rename a track?
~~~~~~~~~~~~~~~~~~~~~~~~

Double-click on the track label.


How do I make a composition more than 100 bars long!?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A composition has a nominal duration that you can change.  Go to
Composition -> Change Composition Duration... and enter the number of
bars you'd like.


Notation and Matrix editing
---------------------------

Can I get more than one staff at once in the notation editor?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The _Open in Notation Editor_ option on the main view's _Segments_
menu will open all the currently-selected segments together in a
single editor.  So to open them all, first use the _Edit_ menu's
_Select All Segments_ option, then this one.  (You can also edit a
subset of segments by selecting them with shift-click on the main
view, then using _Open in Notation Editor_.)


How do I do something like a two-staff piano part?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are various angles to this question, and there's not (yet) any
one perfect answer.

One thing you can't do is make the notation view use more than one
staff for a single segment based on the pitches or other properties of
the notes (it's a possibility under consideration, but not likely in
the near future).  So you have to split the segment onto multiple
tracks, and then open a multi-segment notation editor (see the
question above this one).

Versions 0.9 and later include a split-by-pitch function (finally!) 
which you can use to divide a segment into two parts.

You can also select events within a certain pitch range in the Matrix
view: you can shift-click on a key in the piano keyboard to select all
the notes of that pitch, and you can shift-click and drag to select a
range of pitches.  The notes are added to any existing selection, so
if you want a clean new selection, clear any old one first (by
clicking in space with the select tool on the matrix or just hitting
Esc).


Can I edit all the segments at once in the matrix editor?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No.  A matrix editor shows a single segment only.


Notation rendering is rather slow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Yes, it can be.  Unlike most other notation applications (including
Rosegarden 2.1), we render the full length of each segment to a canvas
when the notation editor starts, instead of rendering sections at a
time when it scrolls.  This means scrolling should be smooth and quick
but the initial rendering phase relatively slow.  This can be a
problem for long segments, although for other practical reasons you're
probably better off dividing long pieces into more manageable segments
anyway.



Playback and recording
----------------------


aRts?  ALSA?  JACK?  Huh?
~~~~~~~~~~~~~~~~~~~~~~~~~

Right, it's like this.  Rosegarden can be built without any sound
support ("configure --disable-sound"), with ALSA support (the default
configure option), or with aRts support ("configure --with-arts").
You have to choose one option when you run configure: you can't
currently have more than one compiled in.

ALSA (<URL:http://www.alsa-project.org/>) is the standard sound system
in Linux 2.5+, and is available for installation on earlier versions
of Linux.  (Some distributions also include it as an optional
package.)  Rosegarden-4 supports ALSA version 0.9.0 (_not_ 0.5.x),
with which it can play to outboard MIDI synths, onboard soundcard MIDI
synths, and ALSA soft-synths, and can record from outboard MIDI
devices.  For audio support, you will also need to obtain and use the
JACK (<URL:http://jackit.sourceforge.net/>) audio system.

aRts (<URL:http://www.arts-project.org/>) is the standard KDE sound
server.  In theory, Rosegarden can use aRts for audio, MIDI soft
synths and outboard MIDI devices.  In practice, this support is highly
unlikely to work for you.

We strongly recommend you use ALSA and JACK.


My soundcard has no built-in MIDI synth and I have no external MIDI devices.  How can I get sound?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need a soft synth!  See the next question.


How do I use an ALSA soft synth, such as fluidsynth or Timidity?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Well first, here's how to get fluidsynth working with a soundfont.
First get fluidsynth -- see <URL:http://www.fluidsynth.org/>.  Then
find a soundfont: one reasonable GM example is Musica Theoria 2,
available as mustheory2.sf2 from the Collections area of
<URL:http://www.hammersound.net/>, although it's large and it's packed
using some stupid Windows-only format (common problem -- a few of the
soundfonts on there are only zipped, though, so have a look around).

Then run up fluidsynth with

  $ fluidsynth -m alsa_seq ./mustheory2.sf2

or equivalent for whichever soundfont you want to use.  Alternatively
get hold of qsynth (URL:http://qsynth.sourceforge.net/> which provides
a nice GUI for fluidsynth.

If you're relatively short on CPU power, also give it "-R no" to turn
off reverb and you'll get a bit more polyphony before it breaks up.
(If you're _very_ short on CPU power, forget it.)  You may find you
have to run it as root or else the pitch goes awry, particularly on
laptops with variable-speed CPUs.

Anyway, when fluidsynth is running you should be able to assign tracks
to it in Rosegarden.  To set a track to one of the soft-synth
instruments, right-click on the track label at the left of the track
until the instrument menu appears and select the instrument on there.
(If you have no other MIDI devices at all, then the soft-synth should
be the default device.)

You can also use Timidity as an ALSA soft-synth with soundfonts.  Run
it in ALSA input mode:

  $ timidity -iA

You can also use Timidity to play to JACK with reasonably low latency,
with some magic incantation like:

  $ timidity -iA -Oj -B2,8

In my experience it takes rather more CPU power than fluidsynth for
rather lower-quality output, though I'm sure these things vary a lot
depending on how the soundfont is made.


How do I select an Instrument?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can check which Instrument is selected for your Track by making
sure that Settings->Show Track Labels is unchecked.  You can change
Instrument for a Track by right-clicking or clicking and holding on
the Track/Instrument label.  A pop up menu will appear from which you
can select a different output Instrument.  Rosegarden automatically
assigns the first available synth device on your soundcard for its
default output Instrument when importing MIDI files.


I've selected a synth Instrument but I don't hear any sound
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're hearing silence with a Synth device (say "Emuk10k1 Port 0" or
"OPL 3") then make sure you've loaded a soundfont for your soundcard.
To load soundfonts use the "sfxload" utility.  For example the Creative
SBLive! soundcard comes with a set of standard soundfonts (2gmgsmt.sf2,
4gmgsmt.sf2, 8mbgmsfx.sf2) and you can load the 8MB soundfont as follows:

  $ sfxload 8mbgmsfx.sf2

For more fun with soundfonts including how to create them for yourself
have a look at the Smurf/Swami project: <URL:http://swami.sourceforge.net/>.

The other classic problem for new users of ALSA is that the mixer
settings are either zero or muted.  Run alsamixer and check that your
levels are okay and unmuted.  (Muting is displayed and changed
separately from the levels themselves: you can be on 100% but still
muted.)


I've followed all your instructions but I still don't hear any sound
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you've done everything we've suggested above then you can check
what devices the sequencer is seeing by running the Rosegarden 
sequencer up by itself.  Try:

  $ rosegardensequencer

and examine the output of the screen.  The output for JACK and ALSA
for an SBLive! should look something like this:

  rosegardensequencer: created plugin manager
  MappedAudioPluginManager::discoverPlugins - discovering plugins
  Rosegarden 4-0.9 - AlsaDriver - alsa-lib version 0.9.3
  AlsaDriver::jackSampleRate - sample rate changed to 44100
  AlsaDriver::createJackInputPorts - adding input port 1
  AlsaDriver::createJackInputPorts - adding input port 2
  AlsaDriver::createJackInputPorts - getting ports
  AlsaDriver::createJackInputPorts - found 2 JACK physical inputs
  AlsaDriver::createJackInputPorts - connecting from "alsa_pcm:capture_1" to "rosegarden:in_1"
  AlsaDriver::createJackInputPorts - connecting from "alsa_pcm:capture_2" to "rosegarden:in_2"
  AlsaDriver::initialiseAudio - JACK sample rate = 44100Hz
  AlsaDriver::initialiseAudio - added output port 1 (left)
  AlsaDriver::initialiseAudio - added output port 2 (right)
  AlsaDriver::initialiseAudio - found 2 JACK physical outputs
  AlsaDriver::initialiseAudio - connecting from "rosegarden:out_1" to "alsa_pcm:playback_1"
  AlsaDriver::initialiseAudio - connecting from "rosegarden:out_1" to "alsa_pcm:playback_2"
  AlsaDriver::initialiseAudio - JACK playback latency  0.092879R
  AlsaDriver::initialiseAudio - JACK record latency  0.046439R
  AlsaDriver::initialiseAudio - initialised JACK audio subsystem

  ALSA Client information:

    64,0 - (Rawmidi 0 - EMU10K1 MPU-401 (UART), EMU10K1 MPU-401 (UART))                 (DUPLEX) [ctype 2, ptype 2, cap 127]
    65,0 - (Emu10k1 WaveTable, Emu10k1 Port 0)          (WRITE ONLY) [ctype 2, ptype 2078, cap 66]
    65,1 - (Emu10k1 WaveTable, Emu10k1 Port 1)          (WRITE ONLY) [ctype 2, ptype 2078, cap 66]
    65,2 - (Emu10k1 WaveTable, Emu10k1 Port 2)          (WRITE ONLY) [ctype 2, ptype 2078, cap 66]
    65,3 - (Emu10k1 WaveTable, Emu10k1 Port 3)          (WRITE ONLY) [ctype 2, ptype 2078, cap 66]

  Creating device 0 in Play mode for connection 65:0 Emu10k1 Port 0 (write)
  Default device name for this device is MIDI soundcard synth
  Creating device 1 in Play mode for connection 65:1 Emu10k1 Port 1 (write)
  Default device name for this device is MIDI soundcard synth 2
  Creating device 2 in Play mode for connection 65:2 Emu10k1 Port 2 (write)
  Default device name for this device is MIDI soundcard synth 3
  Creating device 3 in Play mode for connection 65:3 Emu10k1 Port 3 (write)
  Default device name for this device is MIDI soundcard synth 4
  Creating device 4 in Play mode for connection 64:0 Rawmidi 0 - EMU10K1 MPU-401 (UART) (duplex)
  Default device name for this device is MIDI external device
  Creating device 5 in Record mode for connection 64:0 Rawmidi 0 - EMU10K1 MPU-401 (UART) (duplex)
  Default device name for this device is MIDI hardware input device
  Record client set to (64, 0)

  AlsaDriver::initialiseMidi -  initialised MIDI subsystem

  rosegardensequencer: RosegardenSequencer - started OK


Note the ALSA device list shows the external MIDI port and the
wavetable on-board synth devices.  If you're using a soft synth, you
should see it here too.  All of these will be available in the
drop-down Instrument list inside Rosegarden.

If you're using a recent version of Rosegarden-4 (0.9 or greater) then
you can also access this sequencer status information by using the
application itself.  Go to:


  Settings->Configure Rosegarden->Sequencer->General->Show detailed status


What if I see Rosegarden itself in the client list when I start the sequencer?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Then you've probably got an old version of rosegardensequencer hanging
around.  That can happen when Rosegarden exits abnormally or perhaps
when there was a problem with the JACK server.  If you're having problems
getting Rosegarden to play or record then close it down (and JACK too if
you're running it) and look for any instances of rosegarden,
rosegardensequencer or lt-rosegardensequencer in the process table.

  $ ps -ef|grep rosegarden

Kill any instances of rosegarden, rosegardensequencer or lt-rosegardensequencer
that are still hanging around and try to restart Rosegarden.


Playback is only happening once every second
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When built with optimisation using the gcc-3.3-pre compiler included
with SuSE 8.2, Rosegarden-4 0.9.1 and earlier will incorrectly play
all notes on one-second boundaries -- all notes happening during a
second are played at once at the end of the second.  (More recent
versions of Rosegarden will play correctly, but the transport window
will still only update once per second.)

To fix this, configure with

  $ CXXFLAGS='-O0' ./configure

to disable optimisation (a pity, but that's life).

Note that this also affects the Rosegarden-4 0.8.5 package shipped
included with the distribution itself.  Obviously nobody actually
tested it.  (They also forgot to include the help file, icon etc --
it's not a very well-made package.)


Only notes at the very start of the composition are played at all
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If Rosegarden plays notes at time zero but then gets stuck and doesn't
play anything else afterwards, you might have a non-running sequencer
timer selected.

Rosegarden can use one of a number of timing sources, and by default
it tries to choose sensibly, but it can get confused especially if
you're using JACK and you have JACK configured to output to a
soundcard that is not the first one in your system.

Try going to Settings -> Configure Rosegarden... -> Sequencer ->
Synchronisation and changing the "Sequencer timer" setting from
"(auto)" to one of the other options (system timer, RTC timer, or a
PCM playback device timer).

How do I get audio to work?
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're using ALSA, then you need to obtain and install JACK
(<URL:http://jackit.sourceforge.net/>) and run jackd before starting
the Rosegarden sequencer.  If you give jackd the -v option, it will
report when Rosegarden succeeds in connecting to it.

Unfortunately getting the right combination of magic incantations to
make JACK work is not always easy.  Good values for an SBLive and
indeed on the built-in via868 on my Acer laptop as follows:

  $ jackd -d alsa -d hw -r 44100 -p 2048 -n 2

This will usually ensure that I don't get any xruns (JACK being
unable to process audio in time) and provide reasonable latency.
The '-r 44100' option sets the sample rate for the JACK server
which will in turn define the rate at which WAV audio files will
be recorded.  This is important if you want to transfer any of
the WAVs directly to CD - 44100Hz (44.1KHz) is the sample rate
that audio CDs work at.


I'm not seeing the right program names for my MIDI device (or any at all)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rosegarden has an internal Studio to map your MIDI Program Change
information into meaningful instrument labels.  You need to set this
up do this mapping in the MIDI device manager (Studio->Manage MIDI
Devices->Banks or Import).  Once you've made changes in your current
Rosegarden file you can save it as a default studio (replacing your
autoload.rg file) so that all your subsequent sessions in Rosegarden
utilise your specialised Studio settings.


Improving Performance
---------------------

I get drop outs or xruns with JACK.  How do I improve performance?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The short answer to this is with care and with some luck.  There are
various recipes for improving JACK performance.  Some are more labour
intensive than others.  Ask on the rosegarden-user and rosegarden-devel
lists for the latest advice and also keep an eye on jackit-devel for
more JACK tips.
