architecture #1
This commit is contained in:
Robert Bendun
parent
0985293673
commit
e70322b934
|
|
@ -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
|
||||
|===
|
||||
|
||||
3
serve.py
3
serve.py
|
|
@ -3,4 +3,5 @@ from livereload import Server, shell
|
|||
if __name__ == "__main__":
|
||||
server = Server()
|
||||
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')
|
||||
|
|
|
|||
Loading…
Reference in New Issue