Stosowane jest https://semver.org/lang/pl/::[wersjonowanie semantyczne] oraz format dat https://en.wikipedia.org/wiki/ISO_8601::[ISO 8601].
== Wstęp
Dokument prezentuje różnorodne omówienie architektury systemu, poprzez omówienie przypadków użycia, logicznych komponentów systemu, funkcjonujących w niej procesów oraz aplikacji w kontekście jej wdrożenia.
Zarządzanie fragmentu utworu (dodawanie, usuwanie, zmiana nazwy, uruchamianie wykonania)::
Użytkownik ma możliwość dodania, usuwania oraz zmiany nazwy przypisanej utworowi.
Wgrane utwory są zachowywane pomiędzy sesjami używania programu.
Użytkownik może przesłać pliki audio i MIDI i wgrać jako utwory przy użyciu systemowego okienka eksploratora plików.
Wgrane utwory można pobrać na dysk lokalny.
Skróty klawiszowe uruchamiające fragmenty utworu i zarządzanie skrótami::
Skróty klawiszowe są podstawowym mechanizmem uruchamiania fragmentów utworu.
Możliwość ich przypisania powinna być dowolna w ramach możliwości przeglądarki.
Ich wykorzystanie jest dostępne w dowolnym momencie aplikacji, z wykluczeniem edycji skrótów klawiszowych i pól tekstowych.
Dostęp do fragmentów utworów innych węzłów::
Lista znanych przez system węzłów w sieci, umożliwiająca odwiedzenie interfejsu graficznego węzła.
Umożliwia prostą manualną synchronizację poprzez możliwość sklonowania listy fragmentów innego węzła, pobranie pojedyńczych fragmentów lub złączenie własnej listy fragmentów z listą innego węzła.
Identyfikacja własnego adresu::
Umożliwia łatwe umożliwienie dostępu do swojej instancji z innego węzła.
Blokada edycji listy utworów oraz skrótów klawiszowych::
Zagwarantowanie bezpieczeństwa konfiguracji w trakcie występu.
Przypisanie urządzenia wyjściowego do fragmentu utworu::
Różne fragmenty utworu mogą być realizowane na różnych urządzeniach wyjściowych audio/MIDI.
// * synchroniczny start wykonywania fragmentu utworu w 4 możliwych przypadkach:
// ** w zależności od momentu rozpoczęcia utworu:
// *** start w trakcie wykonywania innego fragmentu (system wykonuje fragment i synchronizuje rozpoczęcie nowego fragmentu)
// *** start na samym początku wykonywania utworu (system oczekuje na rozpoczęcie)
// ** w zależności od grupy rozpoczynającej start
// *** grupa obejmuje całą orkiestrę rozpoczyna (wszystkie osoby co chcą rozpocząć rozpoczynają)
// *** podgrupa rozpoczyna, chcąca zachować synchronizację z całą orkiestrą, ale mieć synchronizację w ramach podgrupy
=== Widok logiczny
Zdefiniowano następujące komponenty systemu:
* realizacja interfejsu graficznego w postaci serwera HTTP
** widoki realizowane w postaci funkcji tworzących fragmenty pełnego dokumentu HTML opisującego interfejs graficzny, realizowane przez statyczną konkatenację oraz dynamiczną przy pomocy biblioteki https://htmx.org/[htmx]
*** widok listy dostępnych urządzeń wyjściowych audio i MIDI
** zachowanie stanu pomiędzy sesjami - zapisywanie każdych zmian i ładowanie stanu przy uruchomieniu aplikacji
* wątek audio wykonujący fragment z użyciem mechanizmu synchronizacji
** realizujący wykonanie utworu w postaci wątku wysyłającego komunikaty do interfejsu wyjściowego MIDI na podstawie linii czasu wyznaczonej przez synchronizację
** czyszczący ustawiony stan na wyjściu MIDI w przypadku zmiany utworu (zatrzymanie odtworzonych nut)
* mechanizm synchronizacji: rozbudowana biblioteka https://github.com/Ableton/link[Ableton/Link]
** bazowa biblioteka Ableton/Link
** nadbudowa w postaci podsystemu realizującego synchronizację wielu grup
* serwer mDNS udostępniający podstawowe informacje o instancji
| lista pozostałych instancji | odczyt | - | - | odczyt/zapis
|===
=== Widok wdrożenia
Wdrożenie składa się z 1 instancji aplikacji Harmonia uruchomionej w ramach 1 węzła oraz możliwych pozostałych węzłów z którymi wykonanie będzie synchronizowane.
Harmonia propaguje swój stan na każdym z interfejsów sieciowych z wykorzystaniem systemu multicast.
Dzięki temu, że każdy węzeł z uruchomioną instancją aplikacji Harmonia ustala i propaguje stan na każdym interfejsie sieciowym,
węzły należące do wielu sieci umożliwiają stworzenie wspólnego stanu synchronizacji dla wszystkich dostępnych sieci.
Interfejs graficzny wyświetlany jest w ramach przeglądarki internetowej wspierającej język JavaScript,
udostępniony w ramach lokalnego serwera Harmonii.
Aplikacja wspiera systemy GNU/Linux, Microsoft Windows oraz macOS.
// TODO: == Wydajność i rozmiar
// TODO: == Jakość
== Harmonogram prac
Harmonogram prac przewiduje dwa możliwe scenariusze, w celu wysokiej szansy zapobieganiu największego ryzyka - problemów z biblioteką Ableton/Link.