How to get the Rosegarden Sequencer working with aRts
=====================================================

                                             Modified: 18.9.2001
                                                       Richard Bown
                                                       (bownie@bownie.com)
						       15.10.2003: warning
						       Chris Cannam

WARNING
-------

This document is out of date.  Although in principle the information
in it is still correct -- that is, it does still describe how to use
Rosegarden with aRts -- it is misleading, because we no longer
recommend the use of aRts with Rosegarden at all.

If you are using Linux, you should be using Rosegarden with the ALSA
sequencer interface for MIDI I/O and JACK for audio.  The default
configure options for Rosegarden assume that you want to use ALSA and
JACK instead of aRts, and should work smoothly if you have ALSA
installed correctly.

If you are using a system other than Linux, aRts is probably your only
option, so this document may still be of interest.  Be aware that aRts
support is not the default configure option and is rarely tested and
not guaranteed to work especially well, although we would like to know
about it if you find that it doesn't work at all.


Introduction
------------

Rosegarden Version 4.0 for KDE works with the aRts sound system
that comes with the KDE multimedia packages.  To compile the
sequencer section of Rosegarden you'll need some additional
packages (see mandrake8_rpms.txt for Mandrake 8 RPM examples).

To get the development version of Rosegarden to work you'll need to
ensure that artsd is running (through artswrapper), ensure that your
~/.mcoprc file is pointing to the relevant Rosegarden server stubs
and that you've mapped the sequencer output device to a relevant
port.  Read on for more explanations of these terms and what they
mean.


  Update 19.9.2001

  This far results are patchy.  Testing on my machine gives random
  results - sometimes playback is acceptable, sometimes it is lagged
  and choppy.  Guillaume's testing so far has been successful - playback
  seeming to be solid enough.  This could still be a system issue or an
  artsd issue or a Rosegarden issue though.

  
  Update 1.10.2001 [cc]

  bownie's fixed the big problem with playback, and now it seems pretty
  stable.  My rather underspecified system still gets leaps and jumps
  if I do cpu-intensive stuff at the same time -- it's not as solid as
  rg2.1 + OSS -- but it's good all the same.

  The two big problems for me are: When playing through the artsd
  soft synth, it drops all but the first note in any sequence of more
  than one note with the same pitch on the same instrument (a known
  aRts problem I think); and it can't make use of the soundcard's
  own FM/wavetable synth a la OSS, it can only use soft synth or
  external MIDI devices (an aRts design decision I think?).


  Update 14.10.2001 [rwb]

  After just reinstalling my system I've suddenly got the urge
  to put together a troubleshooting section to reiterate the 
  points made here - see the end for some of the gotchas that
  got me, again.

  Update 2.1.2002 [rwb]
 
  And again here.  arts and alsa/oss relationships are tricky sometimess.



Building aRts
-------------

Always use the latest version of aRTS.  To install a new version of
aRTs on your system:

o download from http://www.arts-project.org
o build and install to a good place (say /opt/arts-0.n.m)
o ensure LD_LIBRARY_PATH or ldconfig can find the relevant libs
o setup your ~/.mcoprc point to include these libs as well (see below)


Starting and stopping artsd
---------------------------

Artsd usually starts with your UID as you log into (say) KDE.  When
developing with artsd it's advisable to run it in the foreground with
debug on ('-l0') to catch any messages.  When starting artsd manually
use "artswrapper" to ensure the daemon starts with real time priorities.

Start artsd (something) like this:

 % artswrapper -F 10 -S 4096 -a oss -l0

Open artscontrol (KDE menu item under Multimedia/Sound) and from that
open the MidiManager.  To use the MIDI ports of your soundcard map the
MidiManager to the OSS midi ports (try either /dev/midi or /dev/midi00).

If you do restart artsd at any point you'll have to restart your arts
clients as well (artscontrol, rosegardensequencer).

Once the Rosegarden sequencer starts up it'll create two new MIDI ports
labelled Playback and Record.  These can be connected to anything you
can create in the MidiManager.



Registering the Rosegarden implementations with artsd
-----------------------------------------------------

To get artsd to work with the Rosegarden MCOP implementations
we have to tweak your $HOME/.mcoprc file and restart artsd to
pick up the changes.

You need to add entries to the directory that holds these files:

  RosegardenMidiRecord.mcopclass
  libMidiArts.la

A complete example file (indented) as follows:


  # global port - we use the temp directory
  #
  #
  GlobalComm=Arts::TmpGlobalComm

  # rwb 06/01 - don't use spaces between the elements in this list
  # as aRts won't pick them up.
  #
  #
  ExtensionPath="/usr/lib","/usr/lib/mcop","/home/bownie/rosegarden/sound/"
  TraderPath="/usr/lib/mcop","/home/bownie/rosegarden/sound/"


Once you've edited ~/.mcoprc then you'll have to restart artsd to
pick up the changes


Configuring for playback using aRts Midi Manager
------------------------------------------------

Once you have everything built for Rosegarden and you've made the
changes to your ~/.mcoprc you should ensure artsd is running and
then you're ready to start up the application.

You can start either "rosegardengui" or "rosegardensequencer" first
as they only look for each other's presence when they need them (i.e.
when playing or recording).

When "rosegardensequencer" starts up it'll let you know its status on the
command line.  If you're running the artscontrol MidiManager you should
see the Rosegarden Play and Record ports registering with aRts.

Successfully creating the System Midi Port (OSS) on the arts Midi Manager
will enable you to send and receive MIDI events from your soundcard's
MIDI ports.  Creating an aRts Synthesis Midi Output device is equivalent
to a soft synth (TiMidity type device) which can also act as a sink for
Rosegarden events and allow you to test the sequencer without needing any 
external MIDI equipment or cables.

At the moment a limitation of the aRts Midi Manager is that every time
aRts is restarted you'll need to recreate devices and mappings and also
that the synthesis devices are not multitimbral - i.e. an entire piece
will only be played in the single voice that the Play port is connected
to.


Testing the Rosegarden Sequencer
--------------------------------

Assuming you've followed all of the above steps you should have
now have the rosegardensequencer running, the artscontrol Midi Manager
showing Rosegarden Play and Record ports and at least one available
Midi Output port that'll allow you to test whether the Sequencer is
making sound i.e. an OSS Midi Port that's connect to an external
MIDI device or an aRts synthesis device.  Select the Rosegarden (Play)
port and the output port you want and "Connect" them together.

If you know start the "rosegardengui" application and load in a test
file you should be able to hit "Play" on the sequencer and hear some
playback.  The song position pointer on the GUI should move from
left to right across the screen in time with the notes being sent out.
Note that at the moment you can Fast Forward and Rewind whilst the
sequencer is stopped or playing.



Troubleshooting Audio and MIDI installation
-------------------------------------------

There are lots of gotchas waiting for the unwary.  Here is
a brief checklist of things, just to reiterate:

- you're using a recent enough version of aRts (certainly later than 0.5.4)

- aRts is installed in a sensible place (/opt/arts-0.5.4/) and 
  your /etc/ld.so.conf (or equivalent) is pointing to the libraries:
  e.g.

    /opt/arts-0.5.4/lib
    /opt/arts-0.5.4/lib/mcop
  
- if you require alsa to get your soundcard working properly that
  it's also included in the /etc/ld.so.conf and you've updated
  your /etc/modules.conf (or equivalent) with the correct module
  details.

- that your ~/.mcoprc is correctly formatted (remember no spaces!)
  and points to valid libraries.

- that you can play CDs/wavs/mp3s on your system.

Things to look out for:

- if you start artsd (through artswrapper) with no command line
  debug options and it still gives warnings then make sure that
  you library paths (especially in ~/.mcoprc) are correct.

- if you "play" the sequencer but the song pointer doesn't start
  moving across the screen then see the above point.  The sequencer
  should play (i.e. the pointer should move across the screen)
  whether or not an arts output device is connected.

- if you're having problems getting the record midi port to work
  (i.e. Rosegarden is connecting to aRTS but you can't get any
   MIDI events) then try a different sound system.  i.e. if you're
   currently starting aRTS with oss (-a oss) then try to start it
   with ALSA (-a alsa).  If you don't have ALSA installed then
   download it (www.alsa-project.org), build and install and try
   again.  ALSA and aRST are evolving systems - ALSA provides 
   low level support for many soundcards (more than OSS does) so
   it's always worth a try if you're having problems.
