From 0b451a4d867c22ea7a5cb4625460913960978c31 Mon Sep 17 00:00:00 2001
From: kaotisk <kaotisk@arching-kaos.org>
Date: Mon, 14 Oct 2024 21:12:45 +0300
Subject: Some documentation

---
 README            | 42 +++++++++++++++++++++++++++++++
 client/index.html | 75 ++++++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 103 insertions(+), 14 deletions(-)

diff --git a/README b/README
index 616bb2e..7f8ac80 100644
--- a/README
+++ b/README
@@ -1,3 +1,5 @@
+Radio Station Emulator
+----------------------
 That's a small proof-of-concept for radio-station-emulator
 
 For obvious reasons, we don't guarantee that the program/list creator won't be
@@ -21,3 +23,43 @@ Helping scripts:
 Deploy scripts:
 - ./init.sh
 - ./deploy.sh
+
+About
+-----
+This is a "Radio Station Emulator". We create lists with shows to be played, but
+since we are not doing streaming of the playlists, we offer another way of
+"tuning in".
+
+Providing the time a list started playing and having pre-calculated the starting
+timestamps of each show relevant to the list start timestamp, we can calculate
+which show is on and what its current time of playing is.
+
+Ultimately, you are hearing what we would be streaming, as
+you would do for a regular radio station.
+
+Steps
+-----
+First, your browser is going to ask our server here, what is the current list
+that plays right now. It will get a response and will fetch that list.
+
+Based on properties of the list overall and the time of visit, your browser will
+start comparing each show's properties found in the list, to figure the relative
+time of yours on the list. A progress bar labeled "Live progress" will be
+indicating the correct time on the show.
+
+Having figured out the show that is playing, it will go and download the whole
+show. This would be observable via the "Download progress" bar.
+
+Upon completion of the download, the "Sync" button is auto pressed and the
+player start playing the show from the calculated second it calculated
+previously.
+
+Notes
+-----
+Sometimes, you might need to press the "Sync" button more than once. That's
+mostly due to bandwidth capabilities of both the server and the client. The
+"tune" would be right if you press it multiple times and land near the same
+timespace over and over.
+
+Ideally, if "Listening at:" and "Show playback:" have the same value then you
+are in sync!
diff --git a/client/index.html b/client/index.html
index fb473f5..f203c6a 100644
--- a/client/index.html
+++ b/client/index.html
@@ -17,20 +17,67 @@
             </div>
             <details open>
                 <summary>Info to get you started</summary>
-            <p>
-                If you are visiting for the first time, you might need to "Allow Audio" first.
-                Please do and refresh the page.
-            </p>
-            <p>
-                Sometimes, you will need to press the "Sync" button more than once. That's mostly
-                due to bandwidth capabilities of both the server and the client. The "tune" would
-                be right if you press it multiple times and land near the same timespace over and
-                over.
-            </p>
-            <p>
-                Ideally, if "Listening at:" and "Show playback:" have the same value then you are
-                in sync!
-            </p>
+                <h2>Notice</h2>
+                <p>
+                    If you are visiting for the first time, you might need to
+                    "Allow Audio" first. Please do and refresh the page.
+                </p>
+                <h2>About</h2>
+                <p>
+                    This is a "Radio Station Emulator". We create lists with
+                    shows to be played, but since we are not doing streaming of
+                    the playlists, we offer another way of "tuning in".
+                </p>
+                <p>
+                    Providing the time a list started playing and having
+                    pre-calculated the starting timestamps of each show relevant
+                    to the list start timestamp, we can calculate which show is
+                    on and what its current time of playing is.
+                </p>
+                <p>
+                    Ultimately, you are hearing what we would be streaming, as
+                    you would do for a regular radio station.
+                </p>
+                <h2>Steps</h2>
+                <ol>
+                    <li>
+                        First, your browser is going to ask our server here,
+                        what is the current list that plays right now. It will
+                        get a response and will fetch that list.
+                    </li>
+                    <li>
+                        Based on properties of the list overall and the time of
+                        visit, your browser will start comparing each show's
+                        properties found in the list, to figure the relative
+                        time of yours on the list. A progress bar labeled "Live
+                        progress" will be indicating the correct time on the
+                        show.
+                    </li>
+                    <li>
+                        Having figured out the show that is playing, it will go
+                        and download the whole show. Progress of that would be
+                        observable via the "Download progress" bar below.
+                    </li>
+                    <li>
+                        Upon completion of the download, the "Sync" button is
+                        auto pressed and the player start playing the show from
+                        the calculated second it calculated previously.
+                    </li>
+                </ol>
+                <h2>Notes</h2>
+                <ul>
+                    <li>
+                        Sometimes, you might need to press the "Sync" button
+                        more than once. That's mostly due to bandwidth
+                        capabilities of both the server and the client. The
+                        "tune" would be right if you press it multiple times and
+                        land near the same timespace over and over.
+                    </li>
+                    <li>
+                        Ideally, if "Listening at:" and "Show playback:" have
+                        the same value then you are in sync!
+                    </li>
+                </ul>
             </details>
             <div>
                 <p>Download progress:</p>
-- 
cgit v1.2.3