architecture #1

This commit is contained in:
Robert Bendun 2023-11-26 07:14:33 +01:00
parent 0985293673
commit e70322b934
2 changed files with 208 additions and 1 deletions

206
architecture.adoc Normal file
View File

@ -0,0 +1,206 @@
= Architektura i planowany harmonogram prac projektu Harmonia
:toc:
:author: Robert Bendun
:email: robben@st.amu.edu.pl
:revnumber: 1.0.0
:revdate: 2023-11-26
: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
// Użyty szablon: https://www.ecs.csun.edu/~rlingard/COMP684/Example2SoftArch.htm#Use-Case%20View
== Historia wersji
[cols="1,2,3,2"]
|===
| Osoba | Data | Zmiany | Wersja
| Robert Bendun | 2023-11-26 | 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].
== 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.
Na podstawie zdefiniowanej architektury stworzono planowany harmonogram prac.
== Architektura
=== Widok przypadków użycia
Zdefiniowano następujące przypadki użycia:
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 zewnętrznych adresów IP węzła wykonującego aplikację
*** widok statusu systemu synchronizacji
*** widok zarządzania fragmentami utworu (dodawanie, usuwanie, przypisanie skrótów klawiszowych, zmiana nazwy)
*** 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
=== Widok procesu
==== Zarządzanie stanem
Zarządzanie stanem jest ważne w Harmonii z uwagi na bycie wielowątkową aplikacją czasu rzeczywistego.
[cols="2,1,1,1,1"]
|===
| Stan | Interfejs graficzny | Wątek audio | Mechanizm synchronizacji | mDNS
| realizowana linia czasowa | odczyt | odczyt | odczyt/zapis | -
| start/stop, przydział grup | odczyt/zapis | - | odczyt/zapis | -
| lista utworów | odczyt/zapis | odczyt | - | -
| plik zrzutu stanu | odczyt/zapis | - | - | -
| lista interfejsów audio/MIDI | odczyt/zapis | odczyt | - | -
| nazwa instancji | odczyt/zapis | - | - | odczyt
| 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.
Planowany:: Pomyślne wykorzystanie rozbudowanej biblioteki Ableton/Link
Alternatywny:: Problem z rozbudową biblioteki Ableton/Link lub problem z implementacją partycypacyjnego startu
[cols="1,2,2"]
|===
| Data | Planowany | Alternatywny
| 2023-03 - 2023-07
a|
Realizował prototyp #1, obejmujący użycie biblioteki Ableton/Link.
* Prototyp aplikacji z użyciem natywnego systemu rysowania okienek
* Integracja z biblioteką Ableton/Link w ramach prototypu #1
a| nie dotyczy
| 2023-09 - 2023-10
a|
Rozpoczyna realizację prototypu #2, niezależnego od prototypu #1.
Prototyp #1 został porzucony, a jego potencjał badawczy wykorzystany.
* Prototyp interfejsu graficznego realizujący następujące widoki:
** informacje o węźle (adresy IP, interfejsy audio)
** informacje o synchronizacji
** zarządzanie listą fragmentów utworu
* Zrzuty stanu (zachowanie stanu pomiędzy sesjami)
* Wsparcie fragmentów MIDI: dodawanie, wykonywanie podstawowych instrukcji MIDI, usuwanie
* Wsparcie synchronizacji: synchronizacja orkiestry, zarówno startu jak i wykonania
| nie dotyczy
| 2023-11
a|
* Rozbudowa mechanizmu wykonania oraz synchronizacji
* Wewnętrzne testy
| nie dotyczy
| 2023-12
a|
* Testy synchronizacji utworów MIDI z orkiestrą laptopową Lambda Ensamble
* Rozpoczecie prac nad synchronizacją podgrup
a|
* Opracowanie autorskiego protokołu na podstawie wcześniejszej znajomości biblioteki Ableton/Link
| 2023-01 - 2023-02
a|
* Synchronizacja wykonania utworu audio
* Testy synchronizacji MIDI w ramach podgrup z orkiestrą laptopową Lambda Ensamble
a|
* Implementacja oraz wewnętrzne testy autorskiego protokołu
| 2023-03
a|
* Rozbudowa wizualna interfejsu graficznego
a|
* Testy synchronizacji MIDI z orkiestrą laptopową (orkiestra + podgrupy)
* Implementacja synchronizacji audio
| 2023-04
| nie dotyczy
a|
* Implementacja synchronizacji audio
* Wewnętrzne testy
| 2023-05
| nie dotyczy
a|
* Rozbudowa wizualna interfejsu graficznego
|===

View File

@ -3,4 +3,5 @@ from livereload import Server, shell
if __name__ == "__main__": if __name__ == "__main__":
server = Server() server = Server()
server.watch('pbr-vision.adoc', shell('asciidoctor pbr-vision.adoc')) server.watch('pbr-vision.adoc', shell('asciidoctor pbr-vision.adoc'))
server.serve(default_filename='pbr-vision.html') server.watch('./architecture.adoc', shell('asciidoctor ./architecture.adoc'))
server.serve(default_filename='./architecture.html')