Fluajho/documentation/english.adoc

:Author: Laborejo Software Suite
:Version: 1.7.3
:iconfont-remote!:
:!webfonts:


////
This documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a
letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
A copy of the license has been provided in the file documentation/LICENSE.
////

////
https://powerman.name/doc/asciidoc
https://asciidoctor.org/docs/user-manual/
////

:sectnums:

:toc: left
:toc-title: Table of Contents
:toclevels: 3

= Fluajho

// Don't write in the empty line above line. It will be interpreted as author html tag
For program version 1.7.3

== Introduction


"Fluajho" (with jh as in pleasure) means fluid in Esperanto. It is a simple sf2 soundfont
host/player for Linux. Behind the scenes the Fluidsynth library is at work, hence the name.

This program is feature-complete with version 1.7.1 in 2022.
Further releases will be limited to maintenance and fixing problems.

.sf2 is an old file format for making MIDI signals audible through virtual instruments, although it
is still in moderate use today.

Why does Fluajho exist? There are already many soundfont players for Linux,
most of them even based on Fluidsynth. Fluajho was written for a clearly defined use case:
Load an .sf2 in the New Session Manager (Agordejo) and save the soundfont in the session directory.
This makes it possible to archive the session, for example as a backup or to share it.

If you already have a DAW, host or plugin that reliably saves soundfont files together with the
session you do not need Fluajho.

You can load one soundfont file per Fluajho instance. Each instance holds 16 of the soundfonts
instruments that can be assigned to 16 MIDI channels. All access to MIDI parameters like Volume or
Pan needs to be done via midi control changes.

Finally connect external sequencers, such as Laborejo or Patroneo, through JACK-Midi to play the
instruments. There is only one JACK-Midi input but each of the 16 midi channels has it's own stereo
JACK audio output. Additionally there is a stereo mix output pair.



=== Basic Principles

Fluajho loads exactly one `.sf2` soundfont. A soundfont can contain several instruments, of which
up to 16 can be used simultaneously.

Each of the instruments can be loaded into one MIDI channel. To do this, first select a bank in a
channel (Bank 0 if in doubt) and then a program.

On the first launch a small standard soundfont is loaded, which is General Midi (GM) compatible.

Fluajho itself has no option to play notes. To control the sounds, you send MIDI data to our input
port via JACK. The channel is a property of the midi signal and is already selected in the
sequencer.

Each channel has two separate audio outputs in JACK: Left and Right.

Saving and loading your project is done by the New Session Manager (Agordejo). There you will find
a "Save" button.

== Description of the graphical user interface and its functions

Use your browser's search function to locate the individual letters like [B] and their explanation.

image::overview-english.png[Screenshot with Captions, link="overview-english.png"]

The *[A] File* menu contains "sf2 Soundfont load" (keyboard shortcut: Ctrl+O).
Only one soundfont can be loaded at a time. If you want to use several different soundfonts at
once, just start Fluajho several times. Saving and Closing is also here.

It is also possible to load an .sf2 through drag & drop from your file manager into the Fluajho
window.

The option *[B] Ignore MIDI Bank and Program Messages* only allows instrument changes via the
graphical user interface. It ignores all messages coming in via the JACK Midi connection.

This is sometimes necessary if you are dealing with midi hardware, like keyboards, which send bank
and program changes at startup and break our settings. You can also activate this option as soon as
you have set all instruments, because a program change unfortunately happens faster than one would
think.

The option *[C] Play test sound after selecting a program* can be activated to hear some played
notes right choosing a different instrument through the program change dropdown [G]. The test signal
is *not* played when changing an instrument through an external midi signal. 


Channels are numbered *[D] Channel N* . MIDI supports exactly 16 channels, there is no adjustment
possible. More channels of the same soundfont can be obtained by simply starting another Fluajho
instance. Next to the channel is a small rectangle that lights up if MIDI is coming in.

*Play Test [E]*  plays some test notes after a click. This can be used even if option [C] is not
currently activated. 

The current *[F] Bank* is always displayed as a number. You can choose them from the drop down
list. Only the banks, which actually exist in the current sf2 are listed.

The current *[G] Program* is the instrument. It is displayed with its MIDI number and actual name.
Only the programs present in the sf2 are displayed.+ However, the soundfonts are often wrong in
that they display more instruments than they actually have. In this case you will hear a more or
less random (existing) instrument instead.


If you run Fluajho under Session Management, as intended, tere is no internal way to *close* it.
If you use the function of your window manager like [X], Alt+F4 etc. the graphical user interface
is only hidden.

To really close Fluajho you can use Agordejo (New Session Manager). Here you can
also restore visibility by showing the GUI again.

The current visibility setting is saved. This is because you normally only spend a relatively short
time loading a soundfont. Afterwards, the window would only get in the way.


== Installation and Start

Fluajho is exclusive for Linux. The best way to install is to use your package manager. 
If it is not there, or only in an outdated version, please ask your Linux distribution to provide a recent version.

If available in the package repository, please continue reading directly at "Start fluajho from Agordejo / New Session Manager".
If not, you can build Fluajho yourself.

.Build and Install
* Please check the supplied README.md for dependencies.
* You can download a release or clone the git version
  ** Download the latest version from https://www.laborejo.org/downloads and extract it.  
  ** git clone https://git.laborejo.org/lss/fluajho.git
* Change into the new directory and use these commands:
* `./configure --prefix=/usr`
  ** The default prefix is /usr/local
* `make`
* `sudo make install`

.Start fluajho from Agordejo (New Session Manager, NSM)
* Run `agordejo`
* Press the `New` button, and enter a name for your piece of music.
* Use the launcher to add `fluajho` to the session.
* Add any compatible programs, e.g. synthesizers.

Please read README.md for other ways of starting fluajho, which are impractical for actual use but can
be helpful for testing and development.

== Help and Development
You can help Fluajho in several ways: Testing and reporting errors, translating, marketing, support, programming and more.

=== Testing and Reporting Errors
If you find a bug in the program (or it runs too slow) please contact us in a way that suits you best.
We are thankful for any help.

.How to contact us
* Report bugs and issues: https://www.laborejo.org/bugs
* Website: https://www.laborejo.org
* E-Mail: info@laborejo.org
* If you see the opportunity and know that a developer will read it also forums, social media etc..

=== Programming
If you want to do some programming and don't know where to start please get in contact with us directly.
The short version is: clone the git, change the code, create a git patch or point me to your public git.

=== Translations
Fluajho is very easy to translate with the help of the Qt-Toolchain, without any need for programming.
The easiest way is to contact the developers and they will setup the new language.

However, here are the complete instructions for doing a translation completely on your own and integrating it into the program.
The program is split in two parts. A shared "template" between the Laborejo Software Suite and the actual program.

The process is the same for both parts, but needs to be done in different directories:
`template/qtgui` and plain `/qtgui`, relative to the root directory, where the fluajho executable is.

Everytime you see "template/qtgui" below you can substitute that with just "qtgui" to translate the other part of Fluajho.

You can add a new language like this: 

* Open a terminal and navigate to template/qtgui/resources/translations
* Edit the file `config.pro` with a text editor
  ** Append the name of your language in the last line, in the form `XY.ts`, where XY is the language code.
  ** Make sure to leave a space between the individual languages entries.
* Run `sh update.sh` in the same directory
  ** The program has now generated a new `.ts` file in the same directory.
* Start Qt Linguist with `linguist-qt5` (may be named differently) and open your newly generated file
* Select your "Target Language" and use the program to create a translation
* Send us the `.ts` file, such as by e-mail to info@laborejo.org

You can also incorporate the translation into Fluajho for testing purposes. This requires rudimentary Python knowledge.

* Run the "Release" option in QtLinguists "File" menu. It creates a `.qm` file in the same directory as your `.ts` file.
* Edit `template/qtgui/resources/resources.qrc` and duplicate the line `<file>translations/de.qm</file>` but change it to your new .qm file.
* run `sh buildresources.sh`
* Edit `engine/config.py`: add your language to the line that begins with "supportedLanguages" like this: `{"German": "de.qm", "Esperanto: "eo.qm"}`
  ** To find out your language string (German, Esperanto etc.) open the `python3` interpreter in a terminal and run the following command:
  ** `from PyQt5 import QtCore;QtCore.QLocale().languageToString(QtCore.QLocale().language())`

To test the new translation you can either run the program normally, if your system is set to that language. Alternatively start fluajho via the terminal:

* `LANGUAGE=de_DE.UTF-8 ./fluajho -V --save /dev/null`