pbr/pbr-vision.adoc

= Dokument wizji projektu Harmonia
:toc:
:author: Robert Bendun
:email: robben@st.amu.edu.pl
:revnumber: 1.0.0
:revdate: 2023-10-29
:nofooter:
// Polish translation, courtesy of Łukasz Dziedziul <l.dziedziul@gmail.com> with updates via Matthew Blissett <mblissett@gbif.org>
:appendix-caption: Dodatek
:appendix-refsig: {appendix-caption}
:caution-caption: Uwaga
:chapter-signifier: Rozdział
:chapter-refsig: {chapter-signifier}
:example-caption: Przykład
:figure-caption: Rysunek
:important-caption: Ważne
:last-update-label: Ostatnio zmodyfikowany
ifdef::listing-caption[:listing-caption: Listing]
ifdef::manname-title[:manname-title: Nazwa]
:note-caption: Notka
:part-signifier: Część
:part-refsig: {part-signifier}
ifdef::preface-title[:preface-title: Wstęp]
:section-refsig: Sekcja
:table-caption: Tabela
:tip-caption: Sugestia
:toc-title: Spis treści
:untitled-label: Bez tytułu
:version-label: Wersja
:warning-caption: Ostrzeżenie

== Historia wersji

[cols="1,2,3,2"]
|===
| Osoba | Data | Zmiany | Wersja

| Robert Bendun | 2023-10-29 | Stworzenie dokumentu | 1.0.0
|===

Stosowane jest https://semver.org/lang/pl/::[wersjonowanie semantyczne] oraz format dat https://en.wikipedia.org/wiki/ISO_8601::[ISO 8601].

== Wymagania biznesowe

=== Kontekst

Orkiestry laptopowe są jednym z współczesnych metod tworzenia awangardowych doświadczeń muzycznych, wykorzystując nowoczesne techniki definiowania dźwięku w ramach niezależnych laptopów sterowanych przez orkiestrantów.
Wykorzystują one tradycyjną organizację wykonania utworu muzycznego (orkiestrę z dyrygentem) do stworzenia doświadczenia "żywych" utworów tworzonych programowo.

Orkiestra http://lambdaensemble.com.pl::[Lambda Ensamble] od ponad roku prowadzi przedświęcia mające na celu rozszerzyć repertuar wykonywanych utworów.
Jednym z głównych przedsięwzięć był język programowania dedykowany muzycznej kompozycji https://musique.students.wmi.amu.edu.pl::[Musique], będący wynikiem projektu inżynierskiego studentów UAM (w tym autora dokumentu).
Jeden z jego kluczowych komponentów była partycypacyjna synchronizacja rozpoczynania utworu oraz utrzymania wspólnego tempa przez orkiestrę laptopową w trakcie wykonywania utworu.

Synchronizacja wykonania utworu z oddolną kontrolą startu przez orkiestrantów okazała się zbyt dużym wyznawaniem, szczególnie w ramach implementacji języka programowania.
Pomimo zauważalnie lepszego wykonania utworu w przypadku startu z synchronizacją, implementacja w ramach projektu Musique nie pozwalała na realizację pełnego zamierzonego doświadczenia.

Z uwagi na trudność implementacji języka programowania w formie pozwalającej na deterministyczne i optymalne sterowanie jego wykonaniem, zdecydowano się rozdzielić tymczasowo przedsięwzięcie do roli samego odtwarzacza - definiowanej w tym dokumencie Harmonii.

=== Cele biznesowe i kryteria sukcesu

Celem Harmonii jest umożliwienie wykonywania utworów muzyki algorytmicznej przez orkiestry laptopowe. Utwory dedykowane do wykonywania w Harmoni posiadają następującą charakterystykę:

- konieczność wykonywania zdarzeń muzycznych w sposób równoczesny przez wielu członków orkiestry laptopowej z niezaleznymi komputerami
- brak centralnej jednostki sterującej
- wykorzystanie warstwy sieciowej do dynamicznego tworzenia utworu

Utwory posiadające jedną z cech powyżej nie są możliwe do satysfakcjonującego wykonania bez mechanizmu synchronizacyjnego.
Jest to kluczowa funkcjonalność oferowana przez Harmonię.

Tworzone rozwiązanie powinno mieć możliwość wykorzystania do działalności artystycznej orkiestry laptopowej Lambda Ensamble, z możliwością ewaluacji w postaci próbnego wykonania utworu przez kilku orkiestrantów, z zauważalnym równym wykonaniem utworu na niezależnych komputerach wykorzystujących Harmonię do synchronizacji wykonania utworu.

=== Ryzyka

- klasa utworów, których implementacja jest możliwa dzięki Harmonii jest na tyle mała, by móc pozostać artystycznie interesującą dla grupy docelowej
- wykorzystywanie dynamicznej warstwy sieciowej może mieć zbyt wysoki koszt implementacji w stosunku do dedykowanych rozszerzeń istniejących środowisk muzyki algorytmicznej
- brak integracji z istniejącymi środowiskami muzyki algorytmicznej zwiększa niszowość rozwiązania

== Wizja rozwiązania

=== Podstawowy zarys rozwiązania

Harmonia jest muzycznym odtwarzaczem umożliwiającym interaktywne wykonywanie synchronicznych utworów muzyki algorytmicznej dla orkiestr laptopowych.
Odtwarzacz posiada graficzny interfejs umożliwiający kontrolę odtwarzanej treści wraz z parametrami wykonania, w szczególności kontrolą startu oraz wyjścia komunikatów dźwiękowych.

=== Główne funkcjonalności

==== Synchronizacja

Harmonia powinna umożliwać synchronizację wykonania utworów poprzez wykorzystanie infrastruktury sieciowej łączącej komputery uczestniczące w wykonaniu utworu.
Jest to wyróżniająca cecha projektu z perspektywy użytkowej, jak i badawczej.

Synchronizacja opiera się o tworzenie rozproszonej wspólnej sesji synchronizacyjnej pomiędzy komputerami połączonymi sieciowo w ramach orkiestry.
Sesja jest tranzytywna ze względu na połączenie: jeśli komputer należy do dwóch sieci w których jest on jedynym współdzielonym urzadzeniem między dwoma sieciami, to sesja jest wspólna dla obu sieci.

Synchronizacja powinna być:

oddolna:: każdy orkiestrant niezależnie dołącza do wykonania utworu, a protokół synchronizacji ujednolica wykonanie by spełnić wymagania czasowe utworów (w szczególności zapewnić równe rozpoczęcia emisji dźwięków na każdym komputerze w orkiestrze). Prowadzi to do tworzenia współnej linii czasowej, według której każdy uczestnik orkiestry wykonuje utwór.
trwała:: jeśli z niezależnych przyczyn węzeł tworzący sesję synchronizacyjną opuści ją po jej stworzeniu i rozpropagowaniu, a w trakcie jej wykonania, wykonanie powinno pozostać nienaruszone - wykonywanie utworu powinno być możliwe niezależnie od awarii jednego z komputerów wykonujących utwór.
spójna:: w trakcie wykonania utworu każdy z członków sesji powinien być zgodny co do kluczowych dla realizacji wymagań czasowych utworów faktów. Rozbieżności powinny być możliwie szybko eliminowane, by nie być słyszalnymi.


Sesje synchronizacyjne powinny mieć możliwość tworzenia podsesji w ramach jednego wykonania, umożliwając realizację utworów z podziałem na grupy wykonujące różne części wspólnego utworu.

==== Interfejs użytkownika

Harmonia nie powinna ograniczać się do jednego z systemów operacyjnych, dlatego wykorzystuje najpowszechniejszy system graficzny, wspierany przez większość użytkowych systemów operacyjnych - interfejs aplikacji webowej.
Archiektura aplikacji jako lokalnego serwera z powodzeniem wykorzystywana jest w środowiskach takich jak https://jupyter.org/::[Jupyter Notebook].

Interfejs powinien umożliwiać monitorowanie oraz edytowanie parametrów odtwarzacza, protokołów sieciowych oraz innych modułów projektu, w sposób przejrzysty i czytelny.
Wszystkie funkcjonalności wymagające szybkiego dostępu, takie jak:

- rozpoczęcie wykonywania danej ścieżki dźwiękowej
- zmiana odtwarzanej ścieżki dźwiękowej
- wstrzymania i wznowienie odtwarzania

powinny być dostępne przy pomocy skrótów klawiszowych, konfigurowalnych przez użytkownika.

==== Odtwarzacz

Odtwarzacz, kontrolowany przez mechanizm synchronizacji oraz interfejs użytkownika, powinien realizować odtwarzanie zadanych ścieżek dźwiękowych w formatach MIDI oraz audio (WAV, OGG) oraz swobodne przełączanie się między nimi.

Stan wiedzy pomiędzy modułem synchronizacji, a odtwarzaczem powinien być spójny - odtwarzacz musi realizować wyznaczoną przez protokół synchronizacji ścieżkę czasową.

==== Rozszerzalność

Aplikacja powinna być podatna na rozbudowę, w celu umożliwienia rozbudowy wykonania utworów o dodatkowe aspekty sieciowe.
Możliwości rozszerzalności jest kluczową cechą projektu, determinującym jego architekturę.
Równocześnie nie jest priorytetem determinującym powodzenie projektu.

Możliwe rozwiązania rozszerzalności aplikacji to:

- przykładowy moduł rozszerzający możliwości Harmonii o wykonanie utworu wykorzystującego sieciowy aspekt ponad synchronizację wykonania
- integracja języka skryptowego (Lua, TCL) umożliwiająca definiowanie interakcji sieciowych między instancjami Harmonii
- integracja Harmonii z istniejącymi środowiskami muzyki algorytmicznej

=== Założenia i zależności

Harmonia wymaga funkcjonującej infrastruktury sieciowej, łączącej wszystkie urządzenia partycypujące w wykonaniu utworu. W testach projektu Musique wykazano konieczność posiadania dedykowanego routera - router w postaci telefonu tworzącego sieć WiFi okazał się niewystarczający do rzytelnego i sprawnego przesyłania komunikatów.
Komputery powinny umożliwiać ruch sieciowy łączący z routerem - w przypadku standardowych występów jest to możliwość komunikacji poprzez sieć WiFi.

Komputery powinny być wyposażone w przeglądarkę obsługujące język JavaScript (minimum ECMAScript 6) oraz standard https://websockets.spec.whatwg.org/::[WebSocket].

W przypadku wykonywania utworów MIDI konieczny jest syntezator (sprzętowy lub programowy) dostępny poprzez systemowy interfejs MIDI.
W przypadku systemów operacyjnych Microsoft Windows występuje brak możliwości systemowego definiowania wirtualnych portów MIDI, co czyni koniecznym wykorzystanie zewnętrznego progrmau umożliwiającego taką możliwość.

== Zakres i ograniczenia

=== Zakres kolejnych wydań

[cols="1,2,2,2"]
|===
| Funkcjonalność | Wydanie alpha | Wydanie beta | Wydanie pełne

| Synchronizacja
a|
- synchronizacja startu utworu (i jego kolejnych fragmentów)
- synchronizacja lini czasowej odtwarzania (synchronizacja kolejnych momentów)
a|
- synchronizacja wielu ścieżek czasowych w ramach wspólnej sesji wykonywania utworu
|

| Webowy interfejs użytkownika
a|
- podstawowy interfejs użytkownika
- monitorowanie podstawowych parametrów systemu
- uruchamianie odtwarzania
- konfiguracja odtwarzacza i dostarczanie plików audio
- konfigurowalne skróty klawiszowe przypisywane
a|
- przyjazny interfejs użytkownika
a|
- monitorowanie urządzeń w sieci

| Odtwarzacz
a|
- odtwarzanie plików MIDI zgodnie z rytmem wyznaczanym przez mechanizm synchronizacji
a|
- odtwarzanie plików audio (WAV, Ogg) zgodnie z rytmem wyznaczanym przez mechanizm synchronizacji
|

| Rozszerzalność
|
|
a|
- Proof-of-concept utwór z wykorzystaniem dodatkowych interakcji sieciowych poprzez środowisko
|===

=== Ograniczenia

Z uwagi na wykorzystanie infrastruktury sieciowej wydajność oraz trwałość systemu jest ograniczona przez możliwości urządzeń łączących komputery.

W momencie definiowania dokumentu systemy operacyjne z rodziny Microsoft Windows nie wspierają wirtualnego tworzenia portów MIDI. Najpopularniejszym rozwiązaniem jest wykorzystanie zamkniętoźródłowej aplikacji https://www.tobias-erichsen.de/software/loopmidi.html::[loopMIDI].

== Kontekst biznesowy

=== Profil interesariuszy

Grupą docelową projektu są orkiestry laptopowe, chcące wykonywać utwory w sposób synchroniczny.
Nie muszą posiadać umiejętności oraz wiedzy informatycznej.
W przypadku orkiestry laptopowej Lambda Ensamble główną potrzebą jest wykonywanie synchroniczne plików MIDI.

Projekt posiada potencjalne zastosowania w dalszych pracach związanych z synchronizacją odtwarzania - w szczególności w odtwarzaniu wspólnym filmów w ramach zdalnych sesji towarzyskich.
Rozwiązanie to wykracza poza możliwości odtwarzacza Harmonii i wykorzystywałoby wyłącznie mechanizm synchronizacji z wydania alpha.

Wyniki projektu w przypadku sukcesu będą zintegrowane do projektu Musique, stanowiąc bazę do dalszych prac nad rozwojem muzycznego języka programowania.
Odtwarzacz Harmonii stanowiłby podstawę do definicji maszyny wirtualnej umożliwiającej synchroniczne wykonywanie utworów muzykii algorytmicznej.

=== Priorytety projektu

Priorytetem projektu jest zapewnienie działalności modułu synchronizacyjnyego oraz współpracującego z nim odtwarzacza.
Z uwagi na orkiestrę laptopową Lambda Ensamble jako głównych odbiorców i użytkowników projektu, najważniejszym formatem wspieranym przez odtwarzacz jest MIDI.

Interfejs może pozostać prosty, ale funkcjonalny - musi posiadać skróty klawiszowe do efektywnej kontroli interfejsu w trakcie występu. Koniecznym jest jego responsywność i adaptacja do różnych rozmiarów ekranu ponad walory estetyczne.
W przypadku występu kluczowym jest zapewnienie widoczności dla ważnych parametrów systemu i szybkiego dostępu do akcji powiązanych z odtwarzaczem (skróty klawiszowe).