README

====================================================================
      MusE  ---  Linux Music Editor
====================================================================

Welcome to MusE, the open source MIDI/Audio sequencer.

MusE is distributed under the GNU General Public License (GPL).
Please check out the file COPYING in the src/ directory for more
details.


  =============================
      Features:
  =============================
      
      MIDI sequencing:
         - Realtime record/playback
         - Midi file import/export
         - Input filter
         - Support for internal softsynth plugins using
           LV2, DSSI, VST, LinuxVST and MESS
         - much more

      Audio sequencing:
         - Realtime Record/Playback several mono/stereo inputs/outputs
         - Graphical editing of automation
         - Support for LADSPA, LV2, DSSI, VST, LinuxVST plugins

      Technologies supported:
         - LASH - for session control with external LASH enabled applications 
         - JACK - The Jack Audio Connection Kit can be used for audio and midi
         - RtAudio - basic audio input/output for Pulse, ALSA and OSS
         - ALSA midi
         - Plugin formats: LV2, DSSI, VST, LinuxVST, MESS
         - Support Inst(rument) Patch Library for enhanced fluidsynth features.
         - FLAM plugin guis.
         - Built on Qt5




,-----------------------------------------------------------------.
| NOTICE                                                          |
|-----------------------------------------------------------------|
| Some parts of MusE code are EXPERIMENTAL, and may well result   |
| in a CRASH, and who knows what other ill effects.               |
| RUN THIS SOFTWARE AT YOUR OWN RISK.                             |
`-----------------------------------------------------------------'

  =============================
      Requirements:
  =============================
      
      - CMake >= 3.10.2 
          http:/www.cmake.org/HTML/Download.html

      - Qt: Qt >= 5.9.5 (development files)
          http://qt-project.org/
          MusE does _not_ compile with older versions
          For ubuntu packages can be installed via:
          sudo apt-get install qt5-default qttools5-dev qttools5-dev-tools

      - gcc >= 7.3.0 or clang >= 6.0
          http://gcc.gnu.org/
          http://clang.llvm.org/

      - libsndfile >= 1.0.28 (development files)
          http://www.mega-nerd.com/libsndfile/

      - libsamplerate >= 0.1.9 (development files)
          http://www.mega-nerd.com/SRC/

      - JACK version 1 >= 0.125.0 (development files) or
        JACK version 2 >= 1.9.12 (development files)
          http://jackaudio.org/

      - LADSPA (development file ladspa.h)
         www.ladspa.org
      
      - extra-cmake-modules >= 5.94.0
         http://invent.kde.org/frameworks/extra-cmake-modules

  =============================
      May be required:
  =============================
  
      If building for certain architectures, such as RISCV, where
       the compiler might not have built-in atomic operations, then
       libatomic will be required. Our CMake configuration *should*
       make that determination and automatically make libatomic 
       a requirement and *should* fail if it is not found.
      Install it, but only if it is required.
       
      libatomic should be part of your OS distribution, check your
       package manager.
	 
      - https://gcc.gnu.org/
         
  =============================
      Optional:
  =============================
  
      - ALSA >= 1.1.3  Advanced Linux Sound Architecture (development files) 
          http://www.alsa-project.org/

      - fluidsynth >= 1.1.9 (formerly known as iiwusynth) (development files) 
          http://sourceforge.net/apps/trac/fluidsynth/

      - libinstpatch >= 1.0    Instrument Patch Library (development files)
          http://www.swamiproject.org/

      - RtAudio >=5.0 audio input/output support.
          https://www.music.mcgill.ca/~gary/rtaudio/
        
      - liblrdf >= 0.5.0   Library to manipulate RDF files describing LADSPA plugins
          https://librdf.org/
          
      - LV2 (LADSPA Version 2) plugin support:

        lilv >= 0.24.0 (development files)
        sord >= 0.16.0 (development files)
          http://drobilla.net/software

        lv2 >= 1.18.0 (development files)
          http://lv2plug.in
        
      - LV2 Gtk2 User Interface support:
      
        Some LV2 plugins may provide a Gtk2 based graphical User Interface.
        To view them, the following is required (development files):
        gtkmm-2
         http://www.gtkmm.org
        gtk+-2
         http://www.gtk.org
         
      - DSSI     Disposable Soft Synth Interface (development files)   
          http://dssi.sourceforge.net/

      - liblo    Lightweight OSC (Open Sound Control) (development files)   
          http://liblo.sourceforge.net/
          
        (Both recommended - DSSI can use OSC, OSC alone does nothing, for now.)

      - dssi-vst        Support for DSSI vst plugins            
          http://www.breakfastquay.com/dssi-vst/

      - LASH            Audio Session Handler                   
          http://lash.nongnu.org/
          Recently LADISH has been emulating it instead:         
          http://ladish.org/
      
      - Python    The python scripting language
          http://www.python.org
          The remote control supports Python 3. 
          See https://github.com/muse-sequencer/muse/wiki/python-remote-control.
          The bundled midi scripts ('Scripts', or 'Plugins' in earlier versions) require Python 3.
           
      - Pyro 4    Python Remote Objects
          https://pythonhosted.org/Pyro4/
          The remote control supports Pyro 4. 
          See https://github.com/muse-sequencer/muse/wiki/python-remote-control.

      - PyQt5 is used by some of the bundled midi scripts ('Scripts', or 'Plugins' in earlier versions).



  Quick instructions for Ubuntu and similar distributions:
  
  =================================
      Building MusE under Debian/Ubuntu:
  =================================

    1. Install build tools:

       sudo apt-get install git build-essential cmake

    2 Get muse source (unless you already have it).

       Choose one of the below:
         a. Download the latest muse source distribution from
           https://muse-sequencer.github.io/

         b. Clone muse source:
           git clone https://github.com/muse-sequencer/muse.git

    3. Install libraries:
       Note! When building under Debian 11 (and distros based upon Debian 11)
       remove qt5-default from the list.
       
       sudo apt-get install\
         libsndfile1-dev\
         libsamplerate0-dev\
         libjack-jackd2-dev\
         ladspa-sdk\
         qttools5-dev\
         qttools5-dev-tools\
         liblo-dev\
         dssi-dev\
         lv2-dev\
         libfluidsynth-dev\
         libgtkmm-2.4-dev\
         librtaudio-dev\
         libqt5svg5-dev\
         libinstpatch-dev\
         liblilv-dev\
         liblrdf0-dev\
	 libsratom-dev\ 
         librubberband-dev\
         python3-dev\
         python3-pyqt5\
         qt5-default

    4. Change directory:

       cd muse/src

    5. Compile:

       ./compile_muse.sh

    6. Change directory:

       cd build

    7. Install in /usr/local:

       sudo make install

    8. Run:

       muse4
  
  =============================
      Generic building MusE:
  =============================
  
      - Download source from https://github.com/muse-sequencer/muse.git

      - Unpack the source somewhere.  

        You may also try the various MusE development GIT branches for
         up-to-the-minute features and fixes, but they may be less stable. 

      - To compile MusE, run the following commands from the 
         top level directory where the source code was unpacked
         (the directory where THIS README FILE is found): 
       
	    ******************************************************
        *                      Notice:                       *
        * A quick way is to run the ./compile_muse.sh        *
        * script in the same dir, it should perform the same *
        * steps for a basic setup without asking any         *
        * questions. If it fails you may be better off using *
        * the instructions below.                            *
        ******************************************************
 
        The build directory:
        --------------------
          Building in a subdirectory is recommended to keep the build directory separate from the source tree. 
          So create a new subdirectory with a useful name like "build" or "debug" or "release": 
            mkdir build
          Change directory (cd) to the new directory: 
            cd build  

        Configuration:
        --------------
          There are a few different ways to configure (notice the two dots):

          Type "cmake -L .." to see options, then compose "cmake <options>" yourself. 
          Some <options> are:

            -DCMAKE_BUILD_TYPE=<type>
               <type> can be blank (to reset a previous cached type to 'empty'), 
                Debug, Release, RelWithDebInfo and MinSizeRel.
               Release is recommended, to get optimizations.
               If no CMAKE_BUILD_TYPE is given at all, cmake uses either the previous 
                cached value, or else 'empty' (plain or default system optimizations).

            -DCMAKE_INSTALL_PREFIX=<prefix>
               The installation <prefix> where the program is installed.
               The default is to install in /usr/local.

          Or type "ccmake .." (if you have it - text-mode GUI). It may be blank so hit  
           'C' to first-time configure. Fiddle with yer options if ye so desire, then hit 
           'C' to configure then 'G' to generate and exit, or 'Q' to quit without 
           generating. 

          Or there is also a desktop GUI for cmake called cmake-gui.

          Normally MusE builds its many internal modules as SHARED libraries and the
           executable file is small but it links to all those libraries.
          There is a special flag for building MusE as a more or less 'monolithic'
           application (one big executable) which forces MusE to build most modules
           as STATIC libraries and join them all in the final executable:
           -DMODULES_BUILD_STATIC

          --------------------------------
            *** NOTICE TO PACKAGERS: ***
          --------------------------------
          
          Some packagers of software like to ensure that there are no unresolved symbols
           in ANY shared libraries in the software, for example by using:
           -DCMAKE_SHARED_LINKER_FLAGS=-Wl,--no-undefined

          When using such flags, the -DMODULES_BUILD_STATIC flag 
           MUST BE ALSO BE SUPPLIED otherwise there will be many unresolved symbol errors.

        Compiling:
        ----------  
          After configuration, while still in the build directory,type:
            make 

        Installing:
        ----------  
          After compiling, type:
            make install (as root) 
           or
            sudo make install

  =============================
      Running MusE:
  =============================

      Recommended setup:
      ------------------
        MusE is a realtime program which requires special rights to work properly.

      - Check if you are running a sufficiently new linux kernel > 2.6.x
        A modern, standard destop kernel should suit virtually all needs.
        For even stricter realtime performance a so-called 'low latency'
         or 'realtime' kernel may be available. Check your distro's packages
         for availability.

      - create an "audio" group if it does not already exists
        and put yourself into this group

      - For realtime priority, you may want to ensure either the file:
           /etc/security/limits.conf
         or
           /etc/security/limits.d/audio.conf
         contains:
           @audio   -  rtprio     95
           @audio   -  memlock    unlimited

        Some distros have a graphical menu or tool which does this for you.

      - Start jack, typically by using the qjackctl application.
        MusE can also be run without Jack. MusE will use a dummy audio 
         driver if Jack is not detected, or the -a option is given.


      Running:
      ------------------
        start MusE by typing:
            muse4 <options>

          Some <options> are (complete list is printed by running muse4 -h):
            -h       help
            -v       print version
            -d       debug mode: no threads, no RT
            -D       debug mode: enable some debug messages
                                  specify twice for lots of debug messages
                                  this may slow down MusE massively!
            -m       debug mode: trace midi Input
            -M       debug mode: trace midi Output
            -s       debug mode: trace sync
            -a       no audio
            -A       Force inclusion of ALSA midi even if using Jack
            -P  n    set audio driver real time priority to n
                      (Dummy only, default 40. Else fixed by Jack.)
            -Y  n    force midi real time priority to n (default: audio driver prio +2)
            -p       don't load LADSPA plugins
            -I       don't load DSSI plugins
            -L       don't use LASH
            -l  xx   force locale to the given language/country code
                      (xx = de,en,es,fr,pl,ru,sv_SE)

      (JACK and all its clients (qjackctl & MusE) must run with the
      same user id)


      Startup troubleshooting tips:
      -----------------------------

      - Some rare distros might not load the alsa sequencer module by default.
        If necessary, load the alsa sequencer module with:
            /sbin/modprobe snd-seq

      - Timer accuracy for ALSA support:

        If ALSA support is enabled, a reliable source of timing is 
         desired for playback of midi notes.
         
        By default, the timer is attempted to run at 1024 Hz (ticks/second).
        
        MusE will try the Real Time Clock (RTC) first.
        If that fails it will try ALSA timers instead - typically the 
         ALSA High Resolution (HR) timer or the ALSA system timer.

        The RTC is recommended, with sufficient permissions, for best accuracy.
        
        To ensure you have permissions to use the RTC, on modern systems
         using udev rules, create this file if it does not exist:
           "/etc/udev/rules.d/40-timer-permissions.rules"
         and add the following lines to the file:  
           KERNEL=="rtc0",GROUP="audio"
           KERNEL=="hpet",GROUP="audio"
         and, as stated in "Recommended setup" above, ensure you are 
          part of the audio group.
         
        (The hpet is not supported, but that line can help other applications.)
      
        It is possible to use the ALSA system timer instead of the RTC, 
         but it usually requires a kernel built with a 1000 Hz system timer
         (low-latency, realtime, or custom kernel as in "Recommended setup" above).
        With most desktop kernels, the system timer is limited to 250 Hz,
         while the HR timer is limited to 1000 Hz.
        On such distros, without modification, MusE should end up picking 
         the 1000 Hz HR timer. 
         
        But if you set your RTC as above, you can run even higher rates.
        See the Global Settings dialog for user-adjustable high rates.
         
        Run MusE in a terminal to see what it picks. -D option gives more info. 

        
        (The following is old information! But may work for those without udev.)
        Make sure you can access the realtime clock (RTC)
            chmod 660 /dev/rtc
            chgrp audio /dev/rtc
        Make sure MusE can set the rtc clock:
            echo 8192 > /proc/sys/dev/rtc/max-user-freq
            inspect with:
            cat /proc/sys/dev/rtc/max-user-freq

  =============================
      Known bugs:
  =============================

      The odd weirdness happens and some things may not be completely implemeneted
      though we hope it is as stable for you as it is for us!

      If you differ in this opinion we are grateful for all reported issues.

      See the bug tracker for a better view of issues
      https://github.com/muse-sequencer/muse/issues



====================================================================
Let us know whether MusE works for you !!!
Have a look at the webpage https://muse-sequencer.github.io/ for details.