dokument wizji: realny pierwszy draft

pbr-vision.adoc

@@ -35,7 +35,7 @@ ifdef::preface-title[:preface-title: Wstęp]
 |===
 | Osoba | Data | Zmiany | Wersja
 
-| Robert Bendun | 2023-10-25 | Pierwszy zarys dokumentu | 0.1.0
+| Robert Bendun | 2023-10-29 | Pierwszy zarys dokumentu | 0.1.0
 |===
 
 Stosowane jest https://semver.org/lang/pl/::[wersjonowanie semantyczne] oraz format dat https://en.wikipedia.org/wiki/ISO_8601::[ISO 8601].
@@ -44,7 +44,17 @@ Stosowane jest https://semver.org/lang/pl/::[wersjonowanie semantyczne] oraz for
 
 === Kontekst
 
-TODO: Wspomnieć o orkiestrze laptopowej Lambda Ensamble, Musique, jaką klasę utworów może wykonywać aktualnie orkiestra laptopowa.
+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
 
@@ -57,7 +67,7 @@ Celem Harmonii jest umożliwienie wykonywania utworów muzyki algorytmicznej prz
 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ę.
 
-Sukces można zdefiniować przez pomyślne wykorzystanie Harmonii w ramach działalności artystycznej orkiestry laptopowej Lambda Ensamble.
+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
 
@@ -70,19 +80,68 @@ Sukces można zdefiniować przez pomyślne wykorzystanie Harmonii w ramach dzia
 === 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
 
-==== Webowy interfejs użytkownika
+Harmonia posiada możliwość synchronizacji 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ń
@@ -127,4 +186,28 @@ a|
 
 === Ograniczenia
 
-- zależność od infrastruktury sieciowej i jej możliwości
+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).