From 8ab565e25ae31cfcea070a4a3eed2d3441a6d79d Mon Sep 17 00:00:00 2001
From: Dennis Scheiba <dennis.scheiba@gmx.de>
Date: Tue, 5 Dec 2023 01:02:06 +0100
Subject: [PATCH 1/2] add tutorial

---
 caster-back/gencaster/schema.py       |   2 +
 caster-back/story_graph/__init__.py   |   2 +-
 caster-back/story_graph/models.py     |  25 ++++
 caster-back/stream/__init__.py        |   2 +-
 docs/Makefile                         |   6 +-
 docs/_static/custom.css               |  12 ++
 docs/back/api/index.rst               |  10 --
 docs/back/{api => }/gencaster.rst     |   0
 docs/back/graphql.rst                 |  13 ---
 docs/back/index.rst                   |  11 +-
 docs/back/{api => }/story_graph.rst   |   0
 docs/back/{api => }/stream.rst        |   0
 docs/conf.py                          |   2 +
 docs/deployment.rst                   |   4 +-
 docs/editor.rst                       |  12 +-
 docs/front.rst                        |  15 ---
 docs/glossary.rst                     | 145 +++++++++++++++++++++++
 docs/index.rst                        |  26 ++---
 docs/quickstart.rst                   |   6 -
 docs/services.rst                     |  40 ++++++-
 docs/sound.rst                        |   4 -
 docs/story_graph.rst                  | 105 -----------------
 docs/tutorial.rst                     |  47 ++++++++
 docs/tutorial/01-story_graph.rst      | 130 +++++++++++++++++++++
 docs/tutorial/02-listening.rst        |  43 +++++++
 docs/tutorial/03-connecting-nodes.rst | 123 ++++++++++++++++++++
 docs/tutorial/04-live-editing.rst     |  42 +++++++
 docs/tutorial/05-speaking.rst         |  87 ++++++++++++++
 docs/tutorial/06-interaction.rst      | 150 ++++++++++++++++++++++++
 docs/tutorial/07-node_doors.rst       | 161 ++++++++++++++++++++++++++
 docs/tutorial/08-debugging.rst        |  23 ++++
 31 files changed, 1060 insertions(+), 188 deletions(-)
 delete mode 100644 docs/back/api/index.rst
 rename docs/back/{api => }/gencaster.rst (100%)
 delete mode 100644 docs/back/graphql.rst
 rename docs/back/{api => }/story_graph.rst (100%)
 rename docs/back/{api => }/stream.rst (100%)
 delete mode 100644 docs/front.rst
 create mode 100644 docs/glossary.rst
 delete mode 100644 docs/quickstart.rst
 delete mode 100644 docs/sound.rst
 delete mode 100644 docs/story_graph.rst
 create mode 100644 docs/tutorial.rst
 create mode 100644 docs/tutorial/01-story_graph.rst
 create mode 100644 docs/tutorial/02-listening.rst
 create mode 100644 docs/tutorial/03-connecting-nodes.rst
 create mode 100644 docs/tutorial/04-live-editing.rst
 create mode 100644 docs/tutorial/05-speaking.rst
 create mode 100644 docs/tutorial/06-interaction.rst
 create mode 100644 docs/tutorial/07-node_doors.rst
 create mode 100644 docs/tutorial/08-debugging.rst

diff --git a/caster-back/gencaster/schema.py b/caster-back/gencaster/schema.py
index 6379b054..1e434429 100644
--- a/caster-back/gencaster/schema.py
+++ b/caster-back/gencaster/schema.py
@@ -1,4 +1,6 @@
 """
+.. _schema:
+
 Schema
 ======
 
diff --git a/caster-back/story_graph/__init__.py b/caster-back/story_graph/__init__.py
index b2a8b272..0f863109 100644
--- a/caster-back/story_graph/__init__.py
+++ b/caster-back/story_graph/__init__.py
@@ -10,7 +10,7 @@
 Graph
 -----
 
-.. figure:: ../../graphs/story_graph.png
+.. figure:: ../graphs/story_graph.svg
 
     Model graph for the story graph app.
 
diff --git a/caster-back/story_graph/models.py b/caster-back/story_graph/models.py
index 5816eb96..a37aa428 100644
--- a/caster-back/story_graph/models.py
+++ b/caster-back/story_graph/models.py
@@ -35,6 +35,31 @@ class Graph(models.Model):
     """
 
     class StreamAssignmentPolicy(models.TextChoices):
+        """
+        Each graph can handle different "connection" mechanisms when a listener
+        accesses a graph.
+
+        The implementation of each policy is defined in :class:`~story_graph.engine.Engine`.
+
+        .. list-table::
+            :header-rows: 1
+
+            * - StreamAssignmentPolicy
+              - Comment
+            * - `ONE_GRAPH_ONE_STREAM`
+              - All users share the same stream.
+                When the first user visits a graph, a new stream will be set up.
+                Any following user visiting the same story graph stream will be
+                "redirected" to the same stream as long as there is still *any*
+                user listening to the graph.
+                All users still execute the story graph from the beginning.
+            * - `ONE_USER_ONE_STREAM`
+              - Upon connection, each user will obtain a new and exclusive stream
+                and the graph will be executed upon the stream.
+            * - `DEACTIVATE`
+              - Non functional, for administrative work.
+        """
+
         ONE_GRAPH_ONE_STREAM = "one_graph_one_stream", _(
             "Each graph has only one stream"
         )
diff --git a/caster-back/stream/__init__.py b/caster-back/stream/__init__.py
index 82ffd1ca..0532a9a5 100644
--- a/caster-back/stream/__init__.py
+++ b/caster-back/stream/__init__.py
@@ -8,7 +8,7 @@
 Graph
 -----
 
-.. figure:: ../../graphs/stream.png
+.. figure:: ../graphs/stream.svg
 
     Model graph for the stream app.
 
diff --git a/docs/Makefile b/docs/Makefile
index c38f1a93..400ee961 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,9 +17,9 @@ help:
 build-graphs: export DJANGO_SETTINGS_MODULE=gencaster.settings.test
 build-graphs:
 	echo "Start building model graph images"
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/stream.png stream
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/story_graph.png story_graph
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/global.png stream story_graph
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/stream.svg stream
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/story_graph.svg story_graph
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/global.svg stream story_graph
 	echo "Finished building model graph images"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index eeb2c93a..9203276a 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -48,8 +48,20 @@ html[data-theme='light'] a {
     color: var(--blue) !important
 }
 
+html[data-theme='dark'] {
+    --blue: #fff !important;
+}
+
 /* {--background-color: #212a2e;--text-color: #F7F8F8;--link-color: #828fff;} */
 
 .sig-name.descname .pre {
     background-color: var(--green);
 }
+
+.py.method {
+    margin-top: 25px;
+}
+
+.py.class {
+    margin-top: 50px;
+}
diff --git a/docs/back/api/index.rst b/docs/back/api/index.rst
deleted file mode 100644
index f033201c..00000000
--- a/docs/back/api/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-API
-===
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Contents:
-
-    ./story_graph.rst
-    ./stream.rst
-    ./gencaster.rst
diff --git a/docs/back/api/gencaster.rst b/docs/back/gencaster.rst
similarity index 100%
rename from docs/back/api/gencaster.rst
rename to docs/back/gencaster.rst
diff --git a/docs/back/graphql.rst b/docs/back/graphql.rst
deleted file mode 100644
index 9b4c9b87..00000000
--- a/docs/back/graphql.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _graphql:
-
-GraphQL
-=======
-
-GraphQL is used as a communication protocol between *caster-back* and *caster-front* and *caster-editor*.
-
-Add queries
------------
-
-.. todo::
-
-    Describe the steps necessary to add additional queries
diff --git a/docs/back/index.rst b/docs/back/index.rst
index d5308a52..c854b72c 100644
--- a/docs/back/index.rst
+++ b/docs/back/index.rst
@@ -14,16 +14,15 @@ The communication with *caster-sound*, the sound generating and streaming servic
 Global model graph
 ------------------
 
-.. figure:: ../graphs/global.png
+.. figure:: ../graphs/global.svg
 
     Global model graph
 
 
-API
----
-
 .. toctree::
+    :hidden:
 
     osc_server.rst
-    graphql.rst
-    api/index.rst
+    story_graph.rst
+    stream.rst
+    gencaster.rst
diff --git a/docs/back/api/story_graph.rst b/docs/back/story_graph.rst
similarity index 100%
rename from docs/back/api/story_graph.rst
rename to docs/back/story_graph.rst
diff --git a/docs/back/api/stream.rst b/docs/back/stream.rst
similarity index 100%
rename from docs/back/api/stream.rst
rename to docs/back/stream.rst
diff --git a/docs/conf.py b/docs/conf.py
index 3d129e92..04b112c5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -88,3 +88,5 @@
 autodoc_default_options = {
     "exclude-members": "DoesNotExist,MultipleObjectsReturned",
 }
+
+graphviz_output_format = "svg"
diff --git a/docs/deployment.rst b/docs/deployment.rst
index 3e256db7..7ceb8d59 100644
--- a/docs/deployment.rst
+++ b/docs/deployment.rst
@@ -1,3 +1,5 @@
+.. _deployment:
+
 Deployment
 ==========
 
@@ -39,7 +41,7 @@ while a dev deployment can look like this
   SENTRY_DSN_CASTER_FRONT="https://changeMe.io"
 
 
-.. _services:
+.. _deployment-services:
 
 Services
 ^^^^^^^^
diff --git a/docs/editor.rst b/docs/editor.rst
index 46ee6f0d..d5c60a2d 100644
--- a/docs/editor.rst
+++ b/docs/editor.rst
@@ -9,10 +9,10 @@ Caster Editor
 
 .. seealso::
 
-    This documents covers the editing of a *story graph*.
-    For the concepts of such a graph see :ref:`Story Graph`.
+    This documents covers the editing of a :term:`Story Graph` through the editor.
+    For an introduction to the concepts of Gencaster, such as the editing and capabilities of the story graph, also take a look ot the :ref:`tutorial`.
 
-The editor is a website which allows to create and modify a :ref:`Story Graph`.
+The editor is a website which allows to create and modify a :term:`Story Graph`.
 It is possible that many users at once can collaboratively edit this story graph, and also the modifications will be applied in real time to an already running stream, which allows for live coding setups.
 
 .. figure:: ./assets/editor.png
@@ -49,6 +49,8 @@ There are multiple types of script cells for different contexts.
        e.g. PopUps on the :ref:`caster-front`.
        Anything that should be decided dynamically (e.g. day vs night) should be coded within Python.
 
+.. _editor_markdown:
+
 Markdown
 ^^^^^^^^
 
@@ -103,7 +105,7 @@ To use this ``name`` within a Markdown cell can be archived via
 
 .. code-block:: markdown
 
-    Hello ${var}`name`. I hope you are doing fine.
+    Hello {var}`name`. I hope you are doing fine.
 
 where the *${var}`name* will be replaced with the name provided through the popup, so for example *Hello Alice. I hope you are doing fine*.
 
@@ -120,6 +122,8 @@ The *volume* slider controls the volume of the audio on the stream.
 
 The *edit* button allows to change the associated audio file by uploading a new file or search through existing files.
 
+.. _editor_python:
+
 Python
 ^^^^^^
 
diff --git a/docs/front.rst b/docs/front.rst
deleted file mode 100644
index 60c2c3e0..00000000
--- a/docs/front.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. _caster-front:
-
-Caster Front
-============
-
-A Javascript frontend which gets data from *caster-back* and allows to build a connection to *caster-sound* to obtain a stream.
-
-The GraphQL documentation can be accessed at :ref:`graphql`.
-
-Connection flow
----------------
-
-
-Templates
----------
diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644
index 00000000..3c84cac8
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,145 @@
+Glossary
+========
+
+.. glossary::
+
+    Backend
+
+        See :term:`Services`.
+
+    Django
+
+        `Django <https://www.djangoproject.com/>`_ is used as the web server framework for Gencaster.
+        For example, it manages the database and wraps the :term:`Engine` into a :term:`GraphQL` connection.
+
+    Docker
+
+        Docker is a virtualization software which allows to specify the runtime of a service through code.
+        This helps to make the installation, deployment and management of Gencaster easier.
+
+    Edge
+    Connection
+
+        Connects an entry :term:`node door<Node door>` with an exit node door.
+
+        See :class:`story_graph.models.Edge`.
+
+    Editor
+
+        See :term:`Services`.
+
+    Engine
+
+        The story graph engine traverses the :term:`Story Graph` and manages any script cell executions and allocations.
+
+        See :class:`story_graph.engine.Engine`.
+
+    Frontend
+
+        See :term:`Services`.
+
+    Graph
+    Story Graph
+
+        A graph is a key component of Gencaster and is used to define the score of a story within Gencaster.
+        A graph stores the content, metadata and code statements which will control and influence the stream of the listener.
+        Each Graph consists of multiple :term:`nodes <Node>` which are connected through :term:`edges<Edge>`.
+
+        See :class:`story_graph.models.Graph`.
+
+    GraphQL
+
+        GraphQL has nothing to do with :term:`Story Graph`, but instead is a communication protocol used between :term:`Frontend` and :term:`Backend`.
+
+        See :ref:`schema`.
+
+    Janus
+
+        The WebRTC server used to distribute/broadcast the sonic output of :term:`scsynth` via :term:`WebRTC`.
+
+    Node
+
+        A node is an entity within the :term:`Story Graph` and consists of any number of :term:`script cells<Script Cell>` as well as any number of :term:`node doors<Node door>`.
+
+        See :class:`story_graph.models.Node`.
+
+    Node door
+
+        The entering and exiting of a :term:`node <Node>` is managed through *node doors*.
+        Each node has at least an default exit door, but can also have multiple exit nodes.
+        Additionally, each node also has an entry door which enforces the flow such that an *exit* door can be only connected to an *input* door of a node.
+
+        Also see :ref:`the node door tutorial<tutorial_node_door>` for further information.
+
+        See :class:`story_graph.models.NodeDoor`.
+
+    Pipewire
+
+        Used as a replacement for Jack within Gencaster, which manages the *piping* of the :term:`scsynth` output to :term:`Janus`.
+        Gencaster used to rely on Jack but the virtualization performance was very bad, which Pipewire fixed.
+
+    Services
+
+        See :ref:`services`.
+
+    Script cell
+
+        A script cell wrap code statements, see :ref:`tutorial_script_cell`.
+
+        See :class:`story_graph.models.ScriptCell`.
+
+    sclang
+
+        *sclang* is the programming language of the SuperCollider framework.
+        Within Gencaster it is used to control the content of the stream.
+
+    scsynth
+
+        scsyth is the synthesis enginge of SuperCollider and is responsible to generate sounds on the Gencaster stream.
+
+    Stream
+
+        A stream combines a listener with a :term:`Stream Point` and a :term:`Story Graph`.
+        There can be multiple listeners on a stream, determined by the :term:`Stream Assignment Policy`.
+        If the listener count becomes 0, the stream will be closed and the stream point will be available for the next listener.
+
+        See :class:`stream.models.Stream`.
+
+    Stream Assignment Policy
+
+        See :class:`story_graph.models.Graph.StreamAssignmentPolicy`.
+
+    Stream Point
+    Streaming Point
+
+
+        A stream point encapsules a combination of a :term:`Janus` `stream <https://janus.conf.meetecho.com/docs/streaming.html>`_, optional `audio bridge <https://janus.conf.meetecho.com/docs/audiobridge.html>`_ and a :term:`scsynth` instance.
+        Gencaster can only manage as many parallel streams as there are stream points available.
+
+        See :class:`stream.models.StreamPoint`.
+
+    Stream Variable
+
+        Stream variable allow to attach information on a :term:`stream<Stream>`.
+
+        See :class:`stream.models.StreamVariable`.
+
+        .. important::
+
+            A stream variable is **always** a string.
+            Even if a stream variable has been set to a number or boolean value through a Python cell, the stream variable will be a string in the next script cell.
+
+    SuperCollider
+
+        SuperCollider is a framework for algorithmic composition and beyond.
+        Gencaster uses :term:`scsynth` and :term:`sclang` in order to create sounds on the stream.
+
+    Vue
+
+        `Vue <https://vuejs.org/>`_ is a JavaScript framework which is used to build to :term:`Frontend` and the :term:`Editor`.
+
+    WebRTC
+
+        WebRTC is the streaming technology which is used by Gencaster.
+        It is supported by all major browsers and allows to distribute media in real time and in high quality.
+        The actually used WebRTC server is `Janus <https://janus.conf.meetecho.com/>`_.
diff --git a/docs/index.rst b/docs/index.rst
index d18279c2..7a13ed2d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,28 +1,28 @@
-.. GenCaster documentation master file, created by
-   sphinx-quickstart on Thu Mar 24 23:51:39 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Gencaster
 =========
 
-Gencaster is a non-linear audio streaming framework for real-time radiophonic experiences and live music and consists of multiple services.
+Gencaster is a non-linear audio streaming framework for real-time radiophonic experiences and live music.
+
+The audio streams created through Gencaster have a low latency (about 150ms) and can be listened to in any modern browser, and can dynamically render audio content based on a given story graph that can react to user input such as name, time, GPS position, or even microphone streaming after permissions have been granted.
 
-The audio streams have a low latency (about 150ms) and can be listened to in any modern browser, and can dynamically render audio content based on a given story graph that can react to user input such as name, time, GPS position, or even microphone streaming after permissions have been granted.
+Gencaster consists mainly ofthe following services.
 
-* :ref:`caster-sound` is a service that handles all streaming and audio rendering functionality, using SuperCollider to generate audio and Janus to distribute audio to listeners via WebRTC
+* :ref:`Caster sound<caster-sound>` is a service that handles all streaming and audio rendering functionality, using SuperCollider to generate audio and Janus to distribute audio to listeners via WebRTC
 
-* :ref:`caster-back` is a web backend to manage the streams of caster-sound, written in Django
+* :ref:`The backend<caster-back>` manages the streams of caster-sound, written in Django.
+  To communicate with :ref:`Caster sound<caster-sound>`, it uses the :ref:`OSC Server` service.
 
-* :ref:`caster-front` is a web frontend that allows users to listen to the streams of caster-sound, written in Vue
+* :ref:`The frontend<caster-front>` allows users to listen to the streams of :ref:`Caster sound <caster-sound>` and acts as a player.
+  It is written in Vue.
 
-* :ref:`caster-editor` is a web-editor in which the actions of a stream, called a :ref:`Story Graph`, can be created, edited and tweaked using Python or SuperCollider, and is also written in Vue
+* :ref:`The editor <caster-editor>` is a website in which the actions of a stream, called a :term:`Story Graph`, can be created, edited and tweaked using Python or SuperCollider, and is also written in Vue.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
 
-   quickstart.rst
-   story_graph.rst
+   tutorial.rst
    services.rst
    deployment.rst
+   glossary.rst
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
deleted file mode 100644
index 4d7b3fd4..00000000
--- a/docs/quickstart.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Quickstart
-==========
-
-.. todo::
-
-    todo
diff --git a/docs/services.rst b/docs/services.rst
index d8e5cfbc..8e19879a 100644
--- a/docs/services.rst
+++ b/docs/services.rst
@@ -5,27 +5,55 @@ Services
 
 Gencaster consists of multiple services which cover various tasks around the concept of a :ref:`Story Graph`.
 
+.. _caster-sound:
+.. _caster-front:
+
 .. list-table:: Services
    :header-rows: 1
    :widths: 10 30
 
    * - Name
      - Description
-   * - :ref:`Frontend <caster-front>`
-     - Interact and stream audio of a story graph
+   * - Frontend
+     - A Javascript frontend which is used to listen to a :term:`Stream`.
+       The frontend receives the data from the backend via :term:`GraphQL` (see :ref:`schema`).
+       When the backend assigned a :term:`Stream Point` to a listener, the frontend will take care of the connection procedure to the :term:`Stream`, such that the listener can listen to the stream.
    * - :ref:`Backend <caster-back>`
      - Stores information about streams and story graphs and manages their coordination
    * - :ref:`Editor <caster-editor>`
      - Create and edit story graphs within the browser
-   * - :ref:`Sound <caster-sound>`
-     - Creates an audio stream which gets distributed via WebRTC
+   * - Sound
+     - Wraps the output of :term:`scsynth` into a :term:`WebRTC` stream via :term:`Janus`.
+       This is the streaming server of Gencaster.
+
+.. graphviz::
+  :caption: The services of Gencaster
+
+    digraph Gencaster {
+        node [shape=box, fontname="Arial"]
+        edge [fontname="Arial"]
+
+        "Caster sound"
+        { rank = source; "Backend" }
+        "Frontend"
+        "Editor"
+        "OSC server"
+        { rank = sink; "Listener" [shape="signature", label="Listener" style="filled" color="#adff00"] }
+        "Database" [shape="cylinder"]
 
+        "Backend" -> "OSC server" [dir=both, label="OSC"]
+        "OSC server" -> "Caster sound" [dir=both, label="OSC"]
+        "Backend" -> "Frontend" [dir=both, label="GraphQL"]
+        "Listener" -> "Frontend" [label="http"]
+        "Caster sound" -> "Frontend" [dir=both, label="WebRTC"]
+        "Editor" -> "Backend" [dir=both, label="GraphQL"]
+        "Backend" -> "Database" [dir=both]
+    }
 
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
+   :hidden:
 
    back/index.rst
    editor.rst
-   front.rst
-   sound.rst
diff --git a/docs/sound.rst b/docs/sound.rst
deleted file mode 100644
index bf970462..00000000
--- a/docs/sound.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _caster-sound:
-
-Caster Sound
-============
diff --git a/docs/story_graph.rst b/docs/story_graph.rst
deleted file mode 100644
index 006f87dd..00000000
--- a/docs/story_graph.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-.. _Story Graph:
-
-Story Graph
-===========
-
-.. contents:: :local:
-    :depth: 2
-
-
-.. seealso::
-
-    This documents covers the concept behind a story graph.
-    The editing of such a graph can be found in :ref:`caster-editor`.
-
-
-The story graph acts as a central element of Gencaster to create non-linear storytelling experiences.
-In non-linearity the concept of a timeline is replaced by a tree of possibilities that the listener walks along.
-A story graph allows to construct such possibilities which cover
-
-* the playback of audio files
-* generating speech to text
-* triggering input dialogs
-
-and much more.
-
-Node
-----
-
-A *Node* represents a group of statements which will be executed for the listener upon visiting said node.
-Each node contains one or multiple *script cells*, which are described further at :ref:`editor script cells`.
-
-Each session of a listener starts on the *Start node*.
-
-.. graphviz::
-    :caption: A story graph at least consists of a start node
-
-    digraph StoryGraph {
-        "Start";
-    }
-
-
-Edge
-----
-
-In order to jump from one node to another one it is necessary to connect these two with an *edge*.
-This *edge* is directed, which means that the edge works only in one direction, from an outgoing *start node*
-to an incoming *end node*.
-
-.. graphviz::
-    :caption: A connection between two nodes can be established via an edge.
-        This connects the *Start* node to the *Play music* node.
-
-    digraph StoryGraph {
-        "Start" -> "Play music";
-    }
-
-.. todo::
-
-    If multiple *outgoing* edges are present it is currently determined by chance which node
-    will be taken.
-    This is about to change and is WIP.
-
-    .. graphviz::
-        :caption: Multiple outgoing connections from the *Start node*.
-            There is a 50/50 chance which following node will be selected.
-
-            digraph StoryGraph {
-                "Start" -> "Play music";
-                "Start" -> "Play podcast";
-            }
-
-It is possible to create loops within the story graph.
-
-.. graphviz::
-    :caption: A graph which loops indefinitely.
-
-    digraph StoryGraph {
-        "Start" -> "Play music";
-        "Play music" -> "Play podcast";
-        "Play podcast" -> "Start";
-    }
-
-.. _Node Door:
-
-Node Door
----------
-
-For a more technical description of a Node Door see :class:`story_graph.models.NodeDoor`.
-
-.. _Stream Variable:
-
-Stream Variable
----------------
-
-For a more technical description of a Stream Variable see :class:`stream.models.StreamVariable`.
-
-.. _Graph Meta:
-
-Graph Metadata
---------------
-
-Stream assignment policy
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-There are...
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
new file mode 100644
index 00000000..7f0b74ec
--- /dev/null
+++ b/docs/tutorial.rst
@@ -0,0 +1,47 @@
+.. _tutorial:
+
+Tutorial
+========
+
+..
+
+    Der Rundfunk ist aus einem Distributionsapparat in einen Kommunikationsapparat zu verwandeln. Der Rundfunk wäre der denkbar großartigste Kommunikationsapparat des öffentlichen Lebens, ein ungeheures Kanalsystem, das heißt, er wäre es, wenn er es verstünde, nicht nur auszusenden, sondern auch zu empfangen, also den Zuhörer nicht nur hören, sondern auch sprechen zu machen und ihn nicht zu isolieren, sondern ihn auch in Beziehung zu setzen.
+
+    -- Berthold Brecht
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+
+   tutorial/*
+
+
+Before explaining *how* Gencaster works, it might be useful to talk about the motivation behind Gencaster.
+The main idea behind Gencaster is to enrich the techniques of dynamic broadcasting by creating a framework for interactive audio streams, aiming to overcome the limitations of cueing a set of static sound files within the browser and instead provide a flexible setup that can be used in a variety of use cases and opening new sonic possibilities.
+
+Having previously worked on pieces that are driven by an interactive and dynamic rendering of sound (see `Social Score <https://socialscore.eu/>`_ or `Future Voices <https://futurevoices.radio/>`_), we wanted to build a framework that allows abstracting the building blocks of such broadcasting systems, inviting others to create pieces that rely on interaction through real-time information retrieval and dynamic response to it, without diving into the mechanics of setting up an audio stream environment.
+Gencaster is therefore a framework, but also a platform, since it is possible to use existing Gencaster instances or to set up your own.
+
+While *Social Score* already reacts to its environment in real time, it relies on two things we wanted to improve with Gencaster
+
+* All possible (inter)actions are stored in a single JSON file, which makes it easy to bundle for the user, but difficult to edit and build.
+* While the sound files were generated on the fly, they were sequenced through the browser, which limited its sonic compositing and reaction
+
+The first problem was solved by thinking about ways to construct possible paths, something common in programming.
+But instead of requiring people to *code* their possible stories, we wanted also people without programming skills to be able to use the framework, so we decided to build an editor that allows to create and edit a *story graph*, a key concept of Gencaster that will be discussed in the first chapter of the tutorial.
+A key element of a story graph is that it can lay out a possible path while still allowing for wildcards within that path, allowing for a dialog between sender and receiver.
+
+To improve the audio playback capabilities, we decided to abandon the Web Audio API of a browser and instead rely on the sonic capabilities of `SuperCollider <https://supercollider.github.io/>`_ which runs on a server and streams its output to the listener via WebRTC, which allows streaming media with high quality and low latency without the need for apps, simply relying on the capabilities of a smartphone browser.
+
+Gencaster therefore takes care of what a user will hear according to the *score* of the story graph, and takes care of any necessary communication.
+
+The presentation of the starting point and the direction of travel for Gencaster has hopefully provided a better understanding of what Gencaster wants to be: a platform for reactive audio content.
+
+.. note::
+
+   The tutorial tries to explain the basic concepts of Gencaster while giving some instructions and exercises to implement within Gencaster.
+   The instructions and exercises are wrapped in a layout box - make sure you deviate from it to experiment a bit and get familiar with it by stepping into the un-pathed territory.
+
+   Therefore, the tutorial assumes that you have access to a Gencaster instance to experiment with the examples.
+   If this is not the case, you can contact the Gencaster team to get access to an instance or simply deploy your own instance, see :ref:`deployment`.
diff --git a/docs/tutorial/01-story_graph.rst b/docs/tutorial/01-story_graph.rst
new file mode 100644
index 00000000..fcc388aa
--- /dev/null
+++ b/docs/tutorial/01-story_graph.rst
@@ -0,0 +1,130 @@
+.. _Story Graph:
+
+The story graph
+===============
+
+The story graph acts as a central element of Gencaster to create and control the non-linear storytelling experiences of Gencaster.
+It creates and negates possibilities through connections and statements within this graph.
+
+A Gencaster instance can store multiple graphs that are shared and identified by a name and a URL that can be used for listening or editing.
+When a user visits the URL of a story graph, a stream is assigned to the user and connected to the user.
+
+The graph itself consists of *nodes* connected by *connections* (or *edges*) and metadata such as a name for the graph.
+You can think of a graph as a web on which the listener lives and navigates.
+How this web looks like and what actions can happen is up to the author.
+The theoretical concept behind the story graph is motivated by a `*finite state machine* <https://www.youtube.com/watch?v=vhiiia1_hC4>`_, which defines all possible transitions between all possible states and is often used to model event-driven processes, allowing a clear visual representation of a complex system.
+
+.. admonition:: Action
+
+    * Visit the editor in your web browser
+    * Login with your credentials - you will be redirected to the list of all graphs of the Gencaster instance.
+    * Create a new graph by scrolling down the list of all existing graphs and clicking on the `+` symbol.
+      You will be asked for a name for the graph and after clicking *OK* you will be redirected to the new graph.
+
+Node
+----
+
+Each story graph consists of at least one *node*, the *start node*, which is used as the entry node for the listener.
+Upon connection, the user starts the journey on the graph with this node by executing its content.
+
+.. graphviz::
+    :caption: A story graph at least consists of a start node
+
+    digraph StoryGraph {
+        node [fontname="Arial"]
+        "Start" [fillcolor=lightgray style=filled];
+    }
+
+The content of each node consists of one or more *script cells* that control the actions on a stream.
+The order of the script cells is deterministic because they are ordered in a list.
+
+.. _tutorial_script_cell:
+
+Script cell
+-----------
+
+There are several types of script cells, each serving a different purpose by having a different handle on possible events.
+
+.. list-table:: Script cell types
+    :header-rows: 1
+    :widths: 15 30
+
+    * - Script cell type
+      - Comment
+    * - Markdown
+      - Markdown is a markup language used in Gencaster to speak on the stream.
+        A text-to-speech engine is used to convert the written text into spoken text.
+        There are several ways to dynamically control the content of the speech as well as the voice that speaks it.
+    * - Audio
+      - An audio cell is always associated with an audio file that is used for playback in the stream that can be uploaded through a dialog of the editor.
+        There are several ways to play the file, such as continuing to play in the background, or waiting for the file to finish playing before continuing with another action.
+    * - Python
+      - Python is a scripting language and can be used to implement custom logic or data retrieval.
+        It is also used to trigger dialogs for the listener, calculate and store information, access data from the internet or control the movement within the graph.
+
+        In fact, a large part of Gencaster is built with Python and every other cell is based on a Python cell in the Python cell in the background.
+    * - SuperCollider
+      - SuperCollider is used for the synthesis of sounds within Gencaster.
+        Via *sclang*, the scripting language of SuperCollider, commands can be executed within the sound generating server *scsynth*.
+
+        SuperCollider has many different kind of dialects (different ways of achieving the same results but with different tools or best practices), but Gencaster advocates the `JITLib <https://docs.supercollider.online/Classes/Ndef.html>`_ dialect.
+    * - Comment
+      - The comment cell is simply a way to annotate things without affecting the actions of a cell. It is more useful than it may sound at first.
+
+To summarize, a *node* is simply a collection of statements which are represented by *script cells*.
+
+
+.. admonition:: Action
+
+    * Double click on the start node - this will open the editor for the node in which you can
+      edit the content of the script cells - but currently this will be empty.
+    * Create a SuperCollider script cell and copy the following code into it.
+      If you are already familiar with SuperCollider you can also adjust the code to your liking
+
+      .. code:: supercollider
+
+        // clear any running sounds
+        Ndef.clear;
+
+        Ndef(\helloGencaster, {
+            // create a basic signal - a phase modulated sine oscillator
+            var sig = SinOsc.ar(
+                freq: LFDNoise0.kr(4.0!2).exprange(1000, 14000),
+                phase: SinOsc.ar(LFDNoise0.kr(0.5!2).exprange(10, 10000)).lag(0.5),
+            );
+            // create an amplitude envelope
+            var env = EnvGen.kr(
+                envelope: Env.perc(releaseTime: 0.1),
+                gate: Impulse.kr(8.0!2, phase: [0, pi]) + Dust.kr(4.0!2),
+            );
+            // a feedback signal
+            var oldSig = LocalIn.ar(2);
+            // randomly select between feedback and feedforward signal
+            sig = SelectX.ar(LFDNoise3.kr(4.0!2).range(0, 1), [sig, oldSig]);
+            // apply some pitch shifting and delay on the feedback signal
+            LocalOut.ar(
+                channelsArray: PitchShift.ar(
+                    in: CombC.ar(
+                        in: sig,
+                        decaytime: 0.2,
+                    ),
+                    windowSize: 0.4,
+                    pitchRatio: LFDNoise0.kr(10.2!2).range(0.25, 4),
+                    timeDispersion: 0.5,
+                )
+            );
+            // put sig and amp envelope together
+            sig = sig * env * \amp.kr(0.4);
+            sig.tanh;
+        }).play;
+
+        // we need to wait here because otherwise the
+        // graph is finished directly at the beginning
+        20.0.wait;
+
+    * Click *Save node* in the upper right corner in order to transmit the
+      content of the script cell to the server.
+
+    .. important::
+
+        It is not necessary to wrap the SuperCollider code into brackets ``()`` as each script cell will be automatically wrapped in it.
diff --git a/docs/tutorial/02-listening.rst b/docs/tutorial/02-listening.rst
new file mode 100644
index 00000000..103349a9
--- /dev/null
+++ b/docs/tutorial/02-listening.rst
@@ -0,0 +1,43 @@
+Listening to a graph
+====================
+
+Building a story graph is one thing, but just as important is listening to the graph.
+Gencaster provides a player for a story graph via a website, which makes it possible to distribute the content of the story graph via mobile devices to any place where there is mobile coverage.
+
+Gencaster can also manage not only one stream, but multiple streams at the same time, so that each listener gets his or her own stream.
+This allows for example to create new ways of cheap and interactive spatial setups.
+
+The frontend handles all necessary communication and streaming connection setup with the SuperCollider server using a technology called `WebRTC <https://webrtc.org/>`_.
+This allows you to listen to a Gencaster stream in your browser without the need to install any application.
+
+.. important::
+
+  Due to `playback limitations <https://developer.mozilla.org/en-US/docs/Web/Media/Autoplay_guide>`_ within the browser, it is still necessary for the user to interact with the website, e.g. by clicking a button in order to start playback of the stream.
+
+.. admonition:: Action
+
+    * Visit the frontend with your web browser
+    * In the list of all story graphs on the server, click on the one you just created
+    * Click on *Start*. You should hear a high pitched percussive sound.
+    * After around 20 seconds the screen will turn blank - we reached the end of the graph
+      and an ending message will be displayed.
+      As we have not defined it yet, it will be simply a blank screen.
+
+      Note that although we hit the end of a graph, we still hear its sound.
+      This is intentional as it allows for "never-ending" fade-outs.
+    * Do the same on another device, e.g. your smartphone.
+      Verify that both signals, although similar, are not the same.
+
+Graph metadata
+--------------
+
+To give a graph some context, it is possible to specify an intro text that is displayed above the start button, an about text that is available while the graph is being listened to, and an end text that is displayed when the graph is *finished*.
+A graph is *finished* when there are no nodes or script cells left to execute.
+
+The content of these text fields is formatted using `Markdown <https://www.markdownguide.org/basic-syntax/>`_ which also allows you to display images - either by referencing their URL or by copying and pasting them into the text field (but please not too large images).
+
+.. admonition:: Action
+
+    * In the graph editor, click on the *Meta* tab in the upper left corner
+    * Write something for the intro, about and end text
+    * Afterwards click on *Save* in the upper right corner
diff --git a/docs/tutorial/03-connecting-nodes.rst b/docs/tutorial/03-connecting-nodes.rst
new file mode 100644
index 00000000..fe36a468
--- /dev/null
+++ b/docs/tutorial/03-connecting-nodes.rst
@@ -0,0 +1,123 @@
+Connecting nodes
+================
+
+A single node in the graph will only get you so far.
+Although the sound is modulated, it sounds rather static over time, so it should change over time.
+SuperCollider implements several ways to sequence or modulate sounds over time (see e.g. `Tdef <https://docs.supercollider.online/Classes/Tdef.html>`_), but Gencaster also provides its own native way which aims more at an interaction between the listener, the stream and the database, represented by the graph already described.
+A key aspect of a graph is not only its nodes, but much more the connection between the nodes, which is represented by *edges*.
+
+Edge
+----
+
+In order to jump from a node :math:`A` to another node :math:`B`, it is necessary to connect these two nodes with an *edge*.
+An edge in Gencaster is *directed*, which means that the edge only provides a way from node :math:`A` to node :math:`B`, but not the other way around (unless there is an additional edge that goes from :math:`B` to :math:`A`).
+
+.. graphviz::
+    :caption: A connection between two nodes can be established via an edge.
+        This connects the *Start* node to the *Stop music* node.
+
+    digraph StoryGraph {
+        node [fontname="Arial"]
+        "Start" [fillcolor=lightgray style=filled];
+        "Start" -> "Stop music";
+    }
+
+A graph can contain an arbitrary number of nodes and edges, which allows complex structures to be built, and it is also allowed to build a graph that simply repeats itself, creating a loop by connecting a node to itself through another node.
+
+.. graphviz::
+    :caption: A graph which loops indefinitely.
+
+    digraph StoryGraph {
+        node [fontname="Arial"]
+        "Start" [fillcolor=lightgray style=filled];
+        "Start" -> "Stop music";
+        "Stop music" -> "Start";
+    }
+
+
+.. admonition:: Action
+
+    * In the build tab of the graph editor, create an additional node by clicking on *Add Node* on the upper left.
+      Give the new node a name, for example *Stop music*
+    * You can drag and drop the newly created node to a new position on the canvas with your mouse
+    * Double click on the new node to open the node editor of it
+    * Insert a SuperCollider cell with the following code (or something else)
+
+      .. code:: supercollider
+
+        Ndef.clear(fadeTime: 4.0);
+        // wait for fade
+        5.0.wait;
+
+    * Create an edge between the *Start* node and the new node by hovering the mouse
+      over the right *"circle"* on the Start node and drag the mouse pointer to the left
+      circle of the new node and release the mouse button.
+    * Do the same to create a connection from the new node to the start node.
+      Your graph should look a bit like the graphic above.
+    * Visit the frontend/player and listen what happens.
+    * Notice that the ending screen does not appear anymore as we now traverse the graph
+      indefinitely.
+
+Creating multiple paths
+-----------------------
+
+Having only one way to walk a path on a graph is not the most interesting, as it could also be represented by a single script cell inside a node.
+But Gencaster also allows to create more than one input and output edge on a node.
+If a node has multiple outgoing edges, a random edge will be chosen to traverse.
+
+.. graphviz::
+    :caption: Multiple outgoing connections from the *Start node*.
+        There is a 50/50 chance which following node will be selected.
+
+        digraph StoryGraph {
+            node [fontname="Arial"]
+            "Start" [fillcolor=lightgray style=filled];
+            "Start" -> "Play music";
+            "Start" -> "Play podcast";
+        }
+
+.. admonition:: Action
+
+    * Create another node, name it for example *Play other music*
+    * Double click on the node to open its editor and insert a new SuperCollider
+      script cell into it with the following code (or something else)
+
+      .. code:: supercollider
+
+        Ndef(\someOtherSound, {
+            var baseFreq = LFDNoise0.kr(0.5).exprange(100, 200);
+            var sig = 16.collect({|i|
+                VarSaw.ar(
+                    freq: (i*baseFreq) + (LFDNoise3.kr(i)*i),
+                    width: LFDNoise1.kr(i),
+                ) * EnvGen.kr(Env.perc(0.1, 0.01), gate: Dust.kr(2.0))
+            });
+            sig = Splay.ar(sig);
+            CombC.ar(sig, delaytime: LFDNoise0.kr(2.0).range(0.01, 0.02).lag(0.1), decaytime: 1.0) * \amp.kr(0.5);
+        }).play(fadeTime: 4.0);
+
+        // listen to it for 10 seconds
+        10.0.wait;
+
+      Remember to click *Save node*.
+    * Connect the output of the *stop music* node with the new node
+    * Connect the output of the new node with the input of *stop music*.
+      It should look something like the following graphic
+
+      .. graphviz::
+            :caption: Multiple outgoing connections from the *Stop music* node.
+                There is a 50/50 chance that the next node after *Stop music* is the
+                *Start* node or the *Play other music* node.
+
+                digraph StoryGraph {
+                    node [fontname="Arial"]
+                    "Start" [fillcolor=lightgray style=filled];
+                    "Start" -> "Stop music";
+                    "Stop music" -> "Start";
+                    "Stop music" -> "Play other music";
+                    "Play other music" -> "Stop music";
+                }
+
+    * Listen to the result
+    * Create additional edges - for example from "Start" to the new node in order
+      to allow for overlapping of sounds.
diff --git a/docs/tutorial/04-live-editing.rst b/docs/tutorial/04-live-editing.rst
new file mode 100644
index 00000000..b77d095c
--- /dev/null
+++ b/docs/tutorial/04-live-editing.rst
@@ -0,0 +1,42 @@
+Live editing
+============
+
+The relationship between the Gencaster editor and its player is much more direct than you might think at first.
+When a listener visits a graph via the frontend, Gencaster connects the listener to a stream and starts traversing the graph with the listener.
+
+But the graph can be changed while the listener is traversing it - this includes the topology of the graph as well as the statements within the script cells.
+So it is possible to add or delete new connections while the user is traversing the graph.
+All decisions are made as late as possible, so Gencaster only looks at all available outputs of a node when a node needs to be exited.
+The same applies to the code inside the script cells: The content of a script cell is only looked at when it is executed.
+
+Since Gencaster allows many listeners to traverse the graph independently, this feature can also be used to synchronize all listeners on the same graph by simply leading all nodes to the same *pause node*, which simply collects all listeners on the graph and redirects them to another node for further action.
+
+Of course, this also hopefully makes it easier to create a story graph, since you can listen to it as you create it.
+
+.. admonition:: Action
+
+    * Change the layout of the graph while listening to it.
+      Creating a dead end will stop the execution of the graph when a listener visits it.
+    * Change some parameters of the code while listening.
+      Simply change some numbers within the SuperCollider code and press *Save node* while listening to the graph.
+      You should be able to hear the updates the next time the script cell will be traversed.
+
+Collaboration
+-------------
+
+The synchronization of the graph exists not only between the editor and the listener, but also between multiple instances of the editor.
+Many people can edit and tweak the same graph through the editor, while their changes are synchronized by broadcasting them to everyone else.
+
+This allows new ways of collaboration, since not only listening to the graph is distributed, but also editing the graph.
+There can be :math:`n` listeners and :math:`m` editors on the same graph, interacting via sound or code.
+Of course, the set of listeners and editors can overlap, creating new possibilities for distributed live coding.
+
+.. admonition:: Action
+
+    * Open a second browser window and visit the graph editor
+    * Tweak the node in one of the graph editor windows and verify that the tweaks will be also synchronized with the other window.
+      The other window can also be on another computer.
+
+.. todo::
+
+    The synchronization of the script cell content with other editors does currently not work.
diff --git a/docs/tutorial/05-speaking.rst b/docs/tutorial/05-speaking.rst
new file mode 100644
index 00000000..e33a60cc
--- /dev/null
+++ b/docs/tutorial/05-speaking.rst
@@ -0,0 +1,87 @@
+Speaking
+========
+
+While radio is often used to distribute music, a common aspect of broadcasting is also the distribution of spoken content.
+Since Gencaster aims to be a two-way broadcasting platform, there are several ways to speak in a stream.
+
+Audio files
+-----------
+
+One way to speak on the stream is to record yourself or others with a microphone and save the content to an audio file.
+Gencaster allows you to play audio files in different formats, but common formats like mp3, wav, opus, AAC or FLAC are supported and recommended.
+
+Gencaster supports two types of playback styles
+
+.. list-table:: Script cell types
+    :header-rows: 1
+    :widths: 15 30
+
+    * - Playback type
+      - Comment
+    * - Sync playback
+      - The audio file is played in its entirety, and the progress of the graph execution is halted until the file is played in its entirety.
+        This is useful for spoken or other sonic content that requires focus from the listener, as it provides a more exclusive space on the stream.
+        Using an additional SuperCollider script cell or async audio playback it is possible to provide some background for this playback.
+    * - Async playback
+      - Once the playback of the file has been started, the execution of the graph will continue.
+        This is useful for sonic content which is intended for a background.
+
+        .. todo::
+
+            Currently there is no way to terminate the audio after playback, so once it is running it will be played back until the end.
+            At some point the async playback could be attached to a Node scope.
+
+
+.. admonition:: Action
+
+    * Open the node editor of the *Stop music* node
+    * Attach an audio file to it - you can upload one or choose on of the existing files on the server.
+      If you upload one, please provide meaningful name for it as you will need to identify the file through its name after the upload.
+    * Compare both kinds of playback styles.
+
+Speaking text
+-------------
+
+Another way to add a voice to the story graph is to use the text-to-speech engine.
+Using an external service that Gencaster can communicate with natively, it is possible to convert a written text into an audible spoken text through a variety of voices and variations.
+This allows for more dynamic or generative approaches to text, as the content of the written text can be generated dynamically, as shown in the following chapters.
+Also, the conversion of text to speech is very fast, so it is possible to create fast interactions with the listener through text as well.
+
+Any spoken content will block the execution of the graph until the audio file containing the spoken text has been fully played, mimicking the synchronized playback style of an audio file.
+
+.. admonition:: Action
+
+    * Open an arbitrary node of the graph and add a *Markdwon* script cell in it
+    * Write some text into it and save the node
+    * Listen to it
+
+By building upon `Markdown <https://www.markdownguide.org/basic-syntax/>`_ it is possible to not just declare what needs to be spoken, but also how it needs to be spoken and by whom.
+
+The default voice of Gencaster is ``DE_NEURAL2_C__FEMALE`` - to change the speaker of a section we can wrap the text we want to be spoken by a male person with a special kind of syntax:
+
+.. code:: markdown
+
+    {male}`Wir` müssen auch etwas gemeinsam {male}`sprechen`
+
+
+It is also possible to change the pronunciation of a word
+
+.. code:: markdown
+
+    Aber bitte, {chars}`bitte`, etwas gelassener.
+
+For a list of all available control statements for text to speech take a look at :ref:`Markdown script cell documentation of the editor<editor_markdown>` and at `SSML <https://cloud.google.com/text-to-speech/docs/ssml>`_.
+
+.. admonition:: Action
+
+    * Modify *how* your written text is spoken.
+    * Check the editor documentation and use ``break``
+
+.. note::
+
+    Note that an external service will be used to convert the written text to sound, so the text will have to be transferred to the service provider, who will also charge a fee.
+    Creating hours of spoken text is not a problem, as the services are not too expensive, but the mechanisms described can also be used to dynamically generate hundreds of hours of spoken text.
+
+    Since the same Markdown text will always result in the same audio file, we can *cache* the results by storing each result on the server's disk.
+    This makes running the graph much faster and cheaper.
+    Nevertheless, choose the allocation of your and our resources wisely.
diff --git a/docs/tutorial/06-interaction.rst b/docs/tutorial/06-interaction.rst
new file mode 100644
index 00000000..5628ef57
--- /dev/null
+++ b/docs/tutorial/06-interaction.rst
@@ -0,0 +1,150 @@
+Listener interaction
+====================
+
+After introducing the SuperCollider, Audio and Markdown cells, it is now time to take a look at what a Python script cell can offer.
+With Python script cells it is possible to
+
+* Interact with the listener by requesting some input
+* Generate or calculate some dynamic text
+* Control what is displayed on the listener's screen
+* request information from a database or the Internet, or
+* navigate the user through several possible paths
+
+This allows you to create more dynamic content within Gencaster, creating more of a dialog between the listener and the streamer.
+
+.. _stream variable:
+
+Stream variable
+---------------
+
+In order to respond to events or information from the user, it is necessary to have a way to pass information from the listener to the server that controls the sonic content of the stream.
+To attach information to a running stream, a stream variable is used.
+Each stream variable is stored as a string in the database under a *key*.
+It is possible to access and set this variable from different script cells throughout the graph.
+
+The native way of interacting and managing these streaming variables is through the Python script cells through the ``vars`` variable, which is a `dictionary <https://realpython.com/python-dicts/>`_ of all stream variables.
+There are several triggers and helper functions built into Gencaster, such as :func:`~story_graph.engine.Engine.wait_for_stream_variable`, which allows to wait for example a certain event which has been triggered by the user.
+
+In order to wait for the execution of the graph until a user presses the *Start* button in the frontend, it is possible to wait for the stream variable ``start`` which is set as soon as the listener presses the *Start* button.
+This is a common pattern within Gencaster as due browser restrictions it is not possible to playback any sound before any button is pressed.
+We can use a Python script cell to wait until this variable has been set by adding a Python script cell to a given node with the following code.
+
+.. code:: python
+
+    await wait_for_stream_variable("start")
+
+
+.. admonition:: Action
+
+    * Also wait for the press of *Start* from the user before playing any sound.
+      Note that it is possible to arrange the order of the script cells via drag and drop.
+
+.. note::
+
+    The code of a Python script cell is executed within an `async runtime  <https://realpython.com/async-io-python/>`_.
+    Also, for security reasons, the modules and functions which one can use within a Python script cell is limited and are stated explicitly.
+    The documentation and source code of :func:`~story_graph.engine.Engine.get_engine_global_vars` show all available functions and modules.
+
+
+Triggering dialogs
+------------------
+
+Gencaster not only allows to communicate with the listener through the sonic stream but also through the display of the device.
+Via a Python cell it is possible to construct a Dialog (e.g. its title, content and its button) and *yield* it to the frontend of the user.
+
+.. code:: python
+
+    yield Dialog(
+        title="Hello World",
+        content=[
+            Text(text="I was triggered from within a Python cell."),
+        ],
+        buttons=[Button.ok()],
+    )
+
+.. admonition:: Action
+
+    * Create a Python script cell in a node and paste the code above in it
+    * Save the node and try it out in the frontend
+    * Modify the text which should be displayed.
+    * Note that during each call of the code a dialog will be put on the stack of dialogs which needs to be displayed on the frontend.
+
+
+Storing user input in stream variables
+--------------------------------------
+
+While triggering a dialog on the listener's screen allows for more interaction with the listener and waiting for user-triggered events, it is also possible to use dialogs to retrieve text-based information from the listener and store that information in a stream variable.
+
+The following code creates a dialog that displays a text box where the listener can enter a name.
+The result is transferred and stored in a new stream variable called ``name`` and is available within Python.
+
+.. code:: python
+
+    yield Dialog(
+        title="Who are you?",
+        content=[
+            Text(text="Can we ask for your name?"),
+            # key will be used as the key for the stream variable name
+            Input(label="Name", key="name"),
+        ],
+        buttons=[Button.cancel(), Button.ok()],
+    )
+
+In order to use this variable within a Markdown/text-to-speech context, it is possible to access the stream variables via the ``var`` statement within a Markdown script cell.
+
+.. code:: markdown
+
+    Hello {var}`name`.
+
+If the listener stated *Italo* as a name, the listener will hear *Hello Italo* on the stream.
+There are also built in dialogs such as requesting the GPS address of the user, which are documented in :ref:`the python script cell documentation of the editor<editor_python>`.
+
+.. admonition:: Action
+
+    * Create a dialog which asks for a favorite pet - or something else, and store it in
+    * Wait for the user input.
+    * Use the pet within a Markdown cell.
+
+
+Conditional dialogs
+-------------------
+
+Creating endless or repeating (sub-)cycles within the story graph is a common pattern within Gencaster, but this can conflict with user information we want to ask only once.
+To ask for a name only once, it is possible to wrap the output of a dialog in an if condition, which checks if a stream variable for a certain key has already been set using the ``vars`` dictionary.
+
+.. code-block:: python
+
+    if vars.get("name") is None:
+        yield Dialog(
+            title="Who are you?",
+            content=[
+                Text(text="Can we ask for your name?"),
+                # key will be used as the key for the stream variable name
+                Input(label="Name", key="name"),
+            ],
+            buttons=[Button.cancel(), Button.ok()],
+        )
+        await wait_for_stream_variable("name")
+
+Creating streaming variables
+----------------------------
+
+We can also store the number of visits of a script cell, using the `*walrus operator* <https://docs.python.org/3/whatsnew/3.8.html#assignment-expressions>`_.
+Assigning a stream variable is as easy as declaring a new key for the ``vars`` variable.
+
+.. code-block:: python
+
+    if counter:=vars.get("counter"):
+        # streaming variables are always strings
+        # therefore we need to cast them e.g. to strings
+        counter = int(counter)+1
+    else:
+        vars["counter"] = 1
+
+
+.. note::
+
+    The SuperCollider and the Python script cell don't only serve different purposes, they also behave differently.
+    A Python script cell always starts *from scratch*, so functions declared in another script cell that may have already been evaluated are not available for execution.
+
+    On the other hand, SuperCollider script cells are executed in the context of the previous state of the SuperCollider interpreter - so variables and functions declared earlier are also available in the context of the script cell.
diff --git a/docs/tutorial/07-node_doors.rst b/docs/tutorial/07-node_doors.rst
new file mode 100644
index 00000000..0ff0ee5b
--- /dev/null
+++ b/docs/tutorial/07-node_doors.rst
@@ -0,0 +1,161 @@
+.. _tutorial_node_door:
+
+Node doors
+==========
+
+Until now, a listener's journey through a graph was either static (if each node of the graph had less than one successor node) or aleatory (if at least one node was connected to multiple successors).
+But Gencaster also allows to control the navigation through a story graph based on conditional Python statements that specify which successor node should be selected.
+This principle is called *node doors* in Python.
+
+Like each graph has at least one node, the start node, each node has at least one node door, called the default node door.
+In addition, each node has an *entry door* - this is the circle on the left side of each node, and for this document it is labeled as *Input* within the graphics.
+
+Default node door
+-----------------
+
+On closer inspection of the nodes, the most simple connection looks like the following graph.
+
+.. graphviz::
+    :caption: The most basic connection - the *default* exit node door of the *Start* node is connected with the *input* door of *Other node*.
+
+        digraph StoryGraph {
+            subgraph cluster_0 {
+                style=filled;
+                color=lightgrey;
+                node [style=filled,color=white, shape=box, fontname="Arial"];
+                "startInput" [color=grey, label="Input"];
+                "startDefault" [label="default"];
+                "startInput" -> "startDefault";
+                label = "Start";
+            }
+            subgraph cluster_1 {
+                style=filled;
+                color=lightgrey;
+                node [style=filled,color=white, shape=box, fontname="Arial"];
+                "mondayInput" [color=grey, label="Input"];
+                "mondayDefault" [label="default"]
+                "mondayInput" -> "mondayDefault"
+                label = "Other node";
+            }
+
+            startDefault -> mondayInput;
+        }
+
+An exit door can also be connected to multiple input node doors, in which case the next node is chosen randomly.
+
+.. graphviz::
+    :caption: Randomly select the next node when multiple nodes are connected to the same node door
+
+        digraph StoryGraph {
+            edge [fontname="Arial"]
+            subgraph cluster_0 {
+                style=filled;
+                color=lightgrey;
+                node [style=filled,color=white, shape=box, fontname="Arial"];
+                "startInput" [color=grey, label="Input"];
+                "startDefault" [label="default"];
+                "startInput" -> "startDefault";
+                label = "Start";
+            }
+            subgraph cluster_1 {
+                style=filled;
+                color=lightgrey;
+                node [style=filled,color=white, shape=box, fontname="Arial"];
+                "mondayInput" [color=grey, label="Input"];
+                "mondayDefault" [label="default"]
+                "mondayInput" -> "mondayDefault"
+                label = "Other Node";
+            }
+            subgraph cluster_2 {
+                style=filled;
+                color=lightgrey;
+                node [style=filled,color=white, shape=box, fontname="Arial"];
+                "otherDayInput" [color=grey, label="Input"];
+                "otherDayDefault" [label="default"];
+                "otherDayInput" -> "otherDayDefault";
+                label = "Another node";
+            }
+
+            startDefault -> mondayInput [xlabel="50%"];
+
+            startDefault -> otherDayInput [label="50%"];
+
+        }
+
+
+Additional node doors
+---------------------
+
+While the default node door does not check for any conditions, it is possible to add additional node doors to a node that will only be taken if a particular condition is met.
+If none of the criteria of the additional node doors is met, the default node door is taken as the fallback exit.
+
+The criteria can be a Python statement and has access.
+It should return a statement which can be evaluated to ``True`` or ``False``.
+If a criteria is too complex to be expressed within a single line of code, the value of the statement can be calculated in a Python script cell and stored within a stream variable.
+
+.. graphviz::
+    :caption: A graph which only enters the *monday* node if it is actually monday
+
+    digraph StoryGraph {
+        edge [fontname="Arial"]
+        subgraph cluster_0 {
+            style=filled;
+            color=lightgrey;
+            node [style=filled,color=white, shape=box, fontname="Arial"];
+            "startInput" [color=grey, label="Input"];
+            "startDefault" [label="default"];
+            "startIsMonday" [label="isMonday"];
+            "startInput" -> "startDefault";
+            "startInput" -> "startIsMonday"
+            label = "Start";
+        }
+        subgraph cluster_1 {
+            style=filled;
+            color=lightgrey;
+            node [style=filled,color=white, shape=box, fontname="Arial"];
+            "mondayInput" [color=grey, label="Input"];
+            "mondayDefault" [label="default"]
+            "mondayInput" -> "mondayDefault"
+            label = "Monday";
+        }
+        subgraph cluster_2 {
+            style=filled;
+            color=lightgrey;
+            node [style=filled,color=white, shape=box, fontname="Arial"];
+            "otherDayInput" [color=grey, label="Input"];
+            "otherDayDefault" [label="default"];
+            "otherDayInput" -> "otherDayDefault";
+            label = "otherDay";
+        }
+
+        startIsMonday -> mondayInput [label="today == 'monday'"];
+
+        startDefault -> otherDayInput;
+
+        otherDayDefault -> startInput;
+
+        mondayDefault -> startInput;
+    }
+
+Adding an additional Node Door to a node can be done using the Node Editor: Double click on a node and at the bottom of the appearing drawer there is a ``+`` sign under *Node Exit Doors* which allows to create additional node doors for this node.
+It may be necessary to scroll down if the contents of the script cells are long.
+Each node door consists of a name and a Python statement.
+For example, the statement to check if today is Monday is :code:`datetime.now().weekday() == 0`.
+The default node door is also listed there, but it cannot be edited.
+
+When all script cells of a node have been executed, each condition of each node door is evaluated in the order of their appearance (so it is possible to drag & drop the order of the node doors).
+As soon as one of the conditions is fulfilled, the door is taken as an exit, so the order of the node doors can be important.
+If none of the conditions returns ``True``, the node is exited through the default door.
+
+.. admonition:: Action
+
+    * Implement a dialog which asks the user to input a number.
+      If this number is bigger than 5 go to node *A*, else go to node *B*.
+
+      .. important::
+
+            Stream variables are stored as strings in the database.
+            When using numeric features of a stream variable, cast it to ``float`` or ``int``.
+
+    * What happens if the user does not input a number?
+      Can you come up with a graph which ensures that the listener inputs a number?
diff --git a/docs/tutorial/08-debugging.rst b/docs/tutorial/08-debugging.rst
new file mode 100644
index 00000000..8da4bc94
--- /dev/null
+++ b/docs/tutorial/08-debugging.rst
@@ -0,0 +1,23 @@
+Debugging
+=========
+
+After the tutorial introduced the major features of Gencaster, a last step is still missing which is how to figure what goes wrong in case something does not work as expected.
+
+Listening to a stream without attaching to a graph
+--------------------------------------------------
+
+In order to verify that streaming works or attach oneself to a running stream without triggering the execution of the story graph, it is possible to use the debug website of the frontend, which is available for example under `dev.gencaster/debug <https://dev.gencaster.org/debug>`_.
+
+Select the desired streaming point and use the player to tune into the stream.
+
+
+Debugging the graph execution
+-----------------------------
+
+To verify the graph execution, the editor provides a list of current and past streams via `editor.dev.gencaster.org/stream <https://editor.dev.gencaster.org/stream>`_.
+By clicking on a stream, the logs for the stream will be displayed and updating in real time.
+
+Admin view
+----------
+
+There also exists a backend admin menu under `backend.dev.gencaster.org/admin <https://backend.dev.gencaster.org/admin/>`_ which can be used to verify the data stored within the database.

From 1f1eebf00c4de9cbc3f58d5a46b8abbb2ba03d10 Mon Sep 17 00:00:00 2001
From: Dennis Scheiba <dennis.scheiba@gmx.de>
Date: Tue, 5 Dec 2023 09:54:00 +0100
Subject: [PATCH 2/2] rephrasing

---
 docs/tutorial/02-listening.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/tutorial/02-listening.rst b/docs/tutorial/02-listening.rst
index 103349a9..dedae43b 100644
--- a/docs/tutorial/02-listening.rst
+++ b/docs/tutorial/02-listening.rst
@@ -2,9 +2,9 @@ Listening to a graph
 ====================
 
 Building a story graph is one thing, but just as important is listening to the graph.
-Gencaster provides a player for a story graph via a website, which makes it possible to distribute the content of the story graph via mobile devices to any place where there is mobile coverage.
+Gencaster provides a player for a story graph via a website, which makes it possible to distribute the content of the story graph to any internet-enabled device.
 
-Gencaster can also manage not only one stream, but multiple streams at the same time, so that each listener gets his or her own stream.
+Gencaster can also manage not only one stream, but multiple streams at the same time, so that each listener gets their own stream.
 This allows for example to create new ways of cheap and interactive spatial setups.
 
 The frontend handles all necessary communication and streaming connection setup with the SuperCollider server using a technology called `WebRTC <https://webrtc.org/>`_.