Fluajho/documentation/german.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: Inhaltsverzeichnis
:toclevels: 3

= Fluajho

// Don't write in the empty line above line. It will be interpreted as author html tag
Für Programmversion 1.7.3


== Benutzung

Schön, dass Sie sich für Fluajho entschieden haben. Fluajho ist ein Sampler für sf2 Soundfonts. Dies
ist ein altes Dateiformat um MIDI-Signale durch virtuelle Instrumente hörbar zu machen.

Sie können jeweils eine Soundfontdatei pro Fluajho-Instanz laden, was bedeutet das aus dieser Datei
jeweils 16 Instrumente gleichzeitig in MIDI Kanäle eingeordnet werden können.

"Fluajho" (mit jh wie in Jalousie) heißt Flüssigkeit auf Esperanto. Denn im Hintergrund Programmes
arbeitet die Programmbibliothek "Fluidsynth".

=== Anwendungszweck und Zielgruppe

Es gibt viele Soundfontsampler für Linux, die meisten auf Fluidsynthbasis. Fluajho wurde für einen
klar umrissenen Anwendungsfall geschrieben: Ein .sf2 im New Session Manager (Agordejo) laden und
das Soundfont im Sessionverzeichnis mit abzuspeichern. Das ermöglicht es die Session zu
archivieren, etwa als Backup oder um sie weiterzugeben.

=== Grundlagen

Fluajho läd genau ein `.sf2` Soundfont. Ein Soundfont kann mehrere Instrumente enthalten, davon
können bis zu 16 gleichzeitig benutzt werden.

Jeweils ein Instrument kann in je einen MIDI Kanal geladen werden. Dazu wählt man in einem Kanal
zuerst eine Bank aus (im Zweifelsfall Bank 0) und dann ein Programm.

Beim ersten Aufruf wird ein kleines Standard Soundfont geladen, welches General Midi (GM)
kompatibel ist.

Fluajho selbst hat keine Möglichkeit Noten abzuspielen. Um die Klänge anzusteuern, sendet man per
JACK Mididaten in unseren Eingangsport. Der Kanal ist eine Eigenschaft des Midisignals und wird
bereits im Sequencer ausgewählt.

Jeder Kanal hat zwei eigenene Audioausgänge in JACK: Links und Rechts.

Das Speichern und Laden ihres Projektes wird durch den New Session Manager (Agordejo) erledigt.
Dort befindet sich ein "Save" Knopf.

== Beschreibung der grafischen Oberfläche und ihrer Funktionen

Benutzen Sie die Suchfunktion ihres Browsers um nach den einzelnen Buchstaben wie [B] und deren
Erläuterung zu suchen.

image::overview-german.png[Screenshot mit Beschriftung, link="overview-german.png"]

Im *[A] Datei* Menü befindet sich der Befehl "sf2 Soundfont laden" (Tastaturkürzel: Strg+O). Es
kann jeweils nur ein Soundfont zur gleichen Zeit geladen werden. Möchten Sie mehrere verschiedene
Soundfonts auf einmal benutzen starten Sie Fluajho einfach mehrmals. Außerdem findet sich hier
Speichern und Beenden.

Es ist ebenfalls möglich ein .sf2 mit Drag&Drop aus einem Dateimanager irgendwo in das
Fluajhofenster zu ziehen.

Die Option *[B] Ignoriere MIDI Bank und Program Nachrichten* lässt nur noch Instrumentenänderungen
über die grafische Benutzeroberfläche zu. Sie ignoriert alle Nachrichten, die über die JACK Midi
Verbindung herein kommen.

Das ist manchmal nötig, wenn man es mit Midi-Hardware, wie Keyboards, zu tun hat die beim Start
Bank- und Programchanges schicken und damit unsere Einstellungen kaputt machen. Sie können diese
Option aber auch einfach so aktivieren um auf der sicheren Seite zu sein. Sobald Sie alle
Instrumente eingestellt haben sperren Sie die Änderungen, denn ein Programm-Change passiert leider
schneller als man denkt.

Die Option *[C] Spiele Klangtest nach Programmauswahl* kann aktiviert werden um direkt nach einer
Änderung des Instruments über die Programmauswahlbox[G] zu hören wie dieses klingt. Das Testsignal
wird *nicht* gespielt wenn Änderungen über MIDI gemacht werden.

Die Kanäle *[D] Channel* sind fest durchnummeriert. MIDI unterstützt genau 16 Kanäle, hier gibt es
keine Einstellmöglichkeit. Mehr Kanäle mit dem gleichen Soundfont erhält man, indem man Fluajho
einfach noch einmal startet. Nebem dem Kanal befindet sich ein kleines Kästchen, dass bei
Midiaktivität aufleuchtet.

Der *Klangest [E]* spielt durch einen Klick eine kurze Tonfolge ab. Das kann auch benutzt werden,
wenn der Haken bei [C] nicht gesetzt ist.

Die aktuelle *[F] Bank* wird immer als Nummer angezeigt. Man kann sie durch Auswahl in der Liste
ändern. Es werden nur die Bänke angezgeit, die im aktuellen sf2 vorhanden sind.

Das aktuelle *[G] Programm* ist das tatsächliche Instrument. Es wird mit seiner MIDI Nummer und
seinem tatsächlichen Name angezeigt. Es werden nur die Programme angezeigt, die im aktuellen sf2
vorhanden sind.

Oft sind die Soundfonts allerdings falsch, indem sie mehr Instrumente anzeigen,
als sie tatsächlich haben. In diesem Fall wird man statt dessen irgend ein anderes (vorhandenes)
Instrument hören.

Wenn Fluajho, wie angedacht, unter Session Management (Agordejo) läuft gibt keine interne Möglichkeit
es zu *schließen*. Benutzt man die Funktion seinen Fenstermanagers wie [X], Alt+F4 etc. wird die
grafische Oberfläche lediglich versteckt.

Um Fluajho wirklich zu schließen kann man Agordejo (New Session Manager) benutzen. Hier kann man
auch die Sichtbarkeit wieder herstellen, indem man auf den *GUI* Knopf klickt.

Die momentane Sichtbarkeitseinstellung wird gespeichert. Das hat den Grund, dass man normalerweise
nur relativ kurze Zeit damit verbringt ein Soundfont zu laden. Anschließend wäre das Fenster nur im
Weg.



== Installation und Start

Fluajho ist exklusiv für Linux. Am besten installieren Sie Fluajho über deinen Paketmanager.
Falls es dort nicht vorhanden ist, oder nur in einer veralteten Version, bitten sie ihre
Linuxdistribution Fluajho bereitzustellen.

Falls in den Paketquellen vorhanden bitte direkt bei "fluajho in Agordejo (New Session Manager)" weiterlesen.
Falls nicht kann man Fluajho auch selbst "bauen".

.Abhängigkeiten
* Eine Liste der Abhängigkeit befindet sich in der README.md
* Kompilieren und Installieren geht entweder mit einem Releasedownload oder mit der Git-Version:
  ** Laden Sie von https://www.laborejo.org/downloads die aktuelle Version herunter und entpacken Sie sie.
  ** `git clone https://git.laborejo.org/lss/fluajho.git`
* Wechseln Sie in das neue Verzeichnis und benutzen diese Befehle:
  ** `./configure --prefix=/usr`
  ** Das Standardprefix is /usr/local
* `make`
* `sudo make install`

.fluajho im Agordejo (New Session Manager, NSM) starten
* Starten Sie `agordejo`
* Erstellen Sie eine neue Session, geben Sie einen Namen für das Musikstück ein.
* Benutzen Sie den Launcher um `fluajho` hinzuzufügen.
* Fügen Sie beliebige kompatible Programme hinzu, z.B. Synthesizer.

In der Datei README.md befinden sich weitere Möglichkeiten fluajho zu starten. Diese sind zum
Musikmachen nicht praktikabel, aber nützlich für Tests und Entwicklung.

== Helfen und Entwicklung
Sie können Fluajho auf viele Arten und Weisen helfen: Testen und Fehler melden, übersetzen, marketing,
anderen Nutzern helfen und schließlich programmieren.

=== Testen und Programmfehler
Falls Sie einen Fehler im Programm entdecken (oder es zu langsam läuft) melden Sie diese bitte auf
eine Art und Weise, die ihnen am besten passt.

.Kontaktmöglichkeiten
* Bugs und Probleme melden: https://www.laborejo.org/bugs
* Webseite: https://www.laborejo.org
* E-Mail: info@laborejo.org
* Wenn Sie die Gelegenheiten sehen und wissen, dass ein Entwickler es lesen wird sind auch Foren, Socialmedia etc. möglich.

== Entwicklung
Falls Sie an der Entwicklung interessiert sind, melden Sie sich am besten direkt bei uns (s.o.)
Kurzversion: clone git, programmieren, einen git-patch erstellen oder uns eine git URL zukommen lassen.

=== Übersetzungen
Fluajho ist mit Hilfe der Qt-Toolchain sehr einfach zu übersetzen, ohne, dass man dafür Programmieren muss.
Die einfachste Variante ist es einfach die Entwickler anzusprechen und sie werden die neue Sprache einrichten.

Hier ist dennoch die komplette Anleitung, um eine Übersetzung komplett alleine anzufertigen und in
das Programm einzubinden. Das Programm ist in zwei Teile aufgeteilt: Ein gemeinsames "Template"
(für alle Laborejo Software Suit Programme) sowie das eigentliche Programm.

Der Übersetzungsprozess ist der gleiche für beide Teile, man muss ihn jedoch in unterschiedlichen
Verzeichnissen durchführen:
`template/qtgui` und nur `/qtgui`, relativ zum Stammverzeichnis, wo sich die ausführbare Datei
fluajho befindet.

Jedes "template/qtgui" hier kann durch nur "qtgui" ersetzt werden um den zweiten Teil zu übersetzen.

So fügt man eine neue Sprache hinzu:

* Öffnen Sie ein Terminal und navigieren zu template/qtgui/resources/translations
* Bearbeiten Sie die Datei `config.pro` in einem Texteditor.
  ** Hängem Sie in der letzten Zeile den Namen der neuen Sprache an, in der Form `XY.ts`, wobei XY der Sprachcode ist.
  ** Achten Sie bitte darauf ein Leerzeichen zwischen den einzelnen Sprachen zu lassen
* Führen Sie `sh update.sh` im selben Verzeichnis aus.
  ** Das Programm hat nun eine neue `.ts`-Datei im Verzeichnis erstellt.
* Starten Sie Qt Linguist mit `linguist-qt5` (kann evtl. anders heißen) und öffnen von dort die neu generierte Datei.
* Wählen Sie die "Target Language", also Zielsprache, aus und benutzen das Programm um eine Übersetzung anzufertigen.
* Senden Sie uns bitte die .ts Datei, z.B. per E-Mail an info@laborejo.org (s.u bei Bugs und Programmfehler für mehr Kontaktmöglichkeiten)

Die Übersetzung können Sie auch selbst, zum Testen, einbinden. Dafür sind rudimentäre
Python Kentnisse nötig.

* Im Qt Linguist "Datei" Menü ist eine "Release" Option. Das erstellt eine `.qm` Datei im gleichen Verzeichnis wie die `.ts` Datei.
* Bearbeiten Sie `template/qtgui/resources/resources.qrc` und kopieren die Zeile `<file>translations/de.qm</file>` . Dabei das Länderkürzel zum Neuen ändern.
* Führen Sie `sh buildresources.sh` aus
* Bearbeiten Sie `engine/config.py`: Die neue Sprache hinzufügen. z.B. `{"German":"de.qm", "Esperanto:"eo.qm"}`
  ** Um den Sprachstring herauszufinden öffnen Sie den `python3`-Interpreter im Terminal und führen aus:
  ** `from PyQt5 import QtCore;QtCore.QLocale().languageToString(QtCore.QLocale().language())`


Um die neue Übersetzung zu testen starten Sie das Programm, falls ihr System bereits auf diese
Sprache eingstellt ist.
Ansonsten starten Sie fluajho mit diesem Befehl, Sprachcode ändern, vom Terminal aus:

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