thesis/thesis.tex: Moving information on OSC protocol tu subsubsection of OSC interface. Ading information on Starting the SSR as client and server.

1 files changed, 128 insertions, 70 deletions

diff --git a/thesis/thesis.tex b/thesis/thesis.tex
index 86ecd0d..b3cf61b 100644
--- a/thesis/thesis.tex
+++ b/thesis/thesis.tex
@@ -498,74 +498,77 @@ parskip=never]{paper}
     \label{sec:results}
     \subsection{Open Sound Control interface}
       \label{subsec:osc-interface}
-      \gls{osc} is an “open, transport-independent, message-based protocol
-      developed for communication among computers, sound synthesizers, and
-      other multimedia devices” \citep{website:oscv1.0} developed at the
-      \gls{cnmat}.  Its 1.0 specification was published by Matthew Wright in
-      2002 \citep{website:oscv1.0} and the protocol has found widespread
-      implementations (as libraries) in several programming languages and
-      through that many use-cases in free and closed audio and video related
-      applications (e.g. Ardour \citep{website:ardour}, Cubase
-      \citep{website:steinberg}, Max/MSP \citep{website:cycling74},
-      SuperCollider \citep{website:supercollider}) since then.\\
-      \gls{osc}'s syntax is defined by several parts, which are discussed
-      briefly in this section.\\
-      \begin{itemize}
-        \item Atomic data types, which are also reflected in type tags (see
-          Table~\ref{tab:ssr-osc-data-type-acronyms} for details)
-        \item Address patterns (a \gls{osc}-string starting with a “/”)
-        \item Type tag string (a string, beginning with a “,”, holding a set of
-          type tags, describing a collection of atomic data types)
-        \item Arguments, a set of binary representations of each argument
-        \item Messages, consisting (in sequence) of an address pattern, a type
-          tag string and \textit{n} \gls{osc} arguments.
-        \item Bundles, consisting of a set of Messages.
-        \item Packets, the unit of transmission (sent over \gls{udp} or
-          \gls{tcp}), consisting of a message or a bundle.
-      \end{itemize}
-      According to the specification, applications sending \gls{osc} packets
-      are considered a client and the ones receiving packets a server.
-      Applications can therefore be client and server at the same time.
-      \begin{table}[!htb]
-        \scriptsize
-        \centering
-        \rowcolors{2}{table-background-one}{table-background-two}
-        \begin{tabular}{ p{2cm} | p{8cm} }
-          \textbf{\gls{osc} type tag} & \textbf{Type} \\
-          \hline
-          \texttt{i} & int32 \\
-          \texttt{f} & float32 \\
-          \texttt{s} & \gls{osc}-string \\
-          \texttt{b} & \gls{osc}-blob \\
-          \hline
-          \hline
-          \texttt{h} & 64 bit big-endian two's complement integer\\
-          \texttt{t} & \gls{osc}-timetag\\
-          \texttt{d} & 64 bit (“double”) IEEE 754 floating point number\\
-          \texttt{S} & Alternate type represented as an \gls{osc}-string (for
-          example, for systems that differentiate “symbols” from “strings”)\\
-          \texttt{c} & an ascii character, sent as 32 bits\\
-          \texttt{r} & 32 bit RGBA color\\
-          \texttt{m} & 4 byte MIDI message. Bytes from MSB to LSB are: port id,
-          status byte, data1, data2\\
-          \texttt{T} & True. No bytes are allocated in the argument data.\\
-          \texttt{F} & False. No bytes are allocated in the argument data.\\
-          \texttt{N} & Nil. No bytes are allocated in the argument data.\\
-          \texttt{I} & Infinitum. No bytes are allocated in the argument
-          data.\\
-          \texttt{[} & Indicates the beginning of an array. The tags following
-            are for data in the Array until a close brace tag is reached.\\
-          \texttt{]} & Indicates the end of an array.\\
-        \end{tabular}
-        \caption{Acronyms (type tags) for atomic data types, used in \gls{osc}
-        messages and bundles \citep{website:oscv1.0}.}\\
-        The first four types define the standard \gls{osc} type tags, which
-        should be understood by all implementations. The remaining are
-        non-standard types, that are implemented by most (e.g.
-        \nameref{subsubsec:liblo} implements all but array and RGBA color
-        type).
-        \label{tab:ssr-osc-data-type-acronyms}
-      \end{table}
+      \subsubsection{Open Sound Control}
+        \label{subsubsec:open-sound-control}
+        \gls{osc} is an “open, transport-independent, message-based protocol
+        developed for communication among computers, sound synthesizers, and
+        other multimedia devices” \citep{website:oscv1.0} developed at the
+        \gls{cnmat}.  Its 1.0 specification was published by Matthew Wright in
+        2002 \citep{website:oscv1.0} and the protocol has found widespread
+        implementations (as libraries) in several programming languages and
+        through that many use-cases in free and closed audio and video related
+        applications (e.g. Ardour \citep{website:ardour}, Cubase
+        \citep{website:steinberg}, Max/MSP \citep{website:cycling74},
+        SuperCollider \citep{website:supercollider}) since then.\\
+        \gls{osc}'s syntax is defined by several parts, which are discussed
+        briefly in this section.\\
+        \begin{itemize}
+          \item Atomic data types, which are also reflected in type tags (see
+            Table~\ref{tab:ssr-osc-data-type-acronyms} for details)
+          \item Address patterns (a \gls{osc}-string starting with a “/”)
+          \item Type tag string (a string, beginning with a “,”, holding a set
+            of type tags, describing a collection of atomic data types)
+          \item Arguments, a set of binary representations of each argument
+          \item Messages, consisting (in sequence) of an address pattern, a
+            type tag string and \textit{n} \gls{osc} arguments.
+          \item Bundles, consisting of a set of Messages.
+          \item Packets, the unit of transmission (sent over \gls{udp} or
+            \gls{tcp}), consisting of a message or a bundle.
+        \end{itemize}
+        According to the specification, applications sending \gls{osc} packets
+        are considered a client and the ones receiving packets a server.
+        Applications can therefore be client and server at the same time.
+        \begin{table}[!htb]
+          \scriptsize
+          \centering
+          \rowcolors{2}{table-background-one}{table-background-two}
+          \begin{tabular}{ p{2cm} | p{8cm} }
+            \textbf{\gls{osc} type tag} & \textbf{Type} \\
+            \hline
+            \texttt{i} & int32 \\
+            \texttt{f} & float32 \\
+            \texttt{s} & \gls{osc}-string \\
+            \texttt{b} & \gls{osc}-blob \\
+            \hline
+            \hline
+            \texttt{h} & 64 bit big-endian two's complement integer\\
+            \texttt{t} & \gls{osc}-timetag\\
+            \texttt{d} & 64 bit (“double”) IEEE 754 floating point number\\
+            \texttt{S} & Alternate type represented as an \gls{osc}-string (for
+            example, for systems that differentiate “symbols” from “strings”)\\
+            \texttt{c} & an ascii character, sent as 32 bits\\
+            \texttt{r} & 32 bit RGBA color\\
+            \texttt{m} & 4 byte MIDI message. Bytes from MSB to LSB are: port
+            id, status byte, data1, data2\\
+            \texttt{T} & True. No bytes are allocated in the argument data.\\
+            \texttt{F} & False. No bytes are allocated in the argument data.\\
+            \texttt{N} & Nil. No bytes are allocated in the argument data.\\
+            \texttt{I} & Infinitum. No bytes are allocated in the argument
+            data.\\
+            \texttt{[} & Indicates the beginning of an array. The tags
+              following are for data in the Array until a close brace tag is
+              reached.\\
+            \texttt{]} & Indicates the end of an array.\\
+          \end{tabular}
+          \caption{Acronyms (type tags) for atomic data types, used in
+          \gls{osc} messages and bundles \citep{website:oscv1.0}.}\\
+          The first four types define the standard \gls{osc} type tags, which
+          should be understood by all implementations. The remaining are
+          non-standard types, that are implemented by most (e.g.
+          \nameref{subsubsec:liblo} implements all but array and RGBA color
+          type).
+          \label{tab:ssr-osc-data-type-acronyms}
+        \end{table}
 
       \subsubsection{liblo}
         \label{subsubsec:liblo}
@@ -603,15 +606,70 @@ parskip=never]{paper}
       \subsubsection{Starting the SSR}
         \label{subsubsec:starting-the-ssr}
         The \gls{ssr} can be started with a rendering engine preselected (an
-        executable postfixed by the rendering acronym), or by selecting one
-        through the configuration file, when using the executable named
+          executable postfixed by the supported rendering algorithm is provided
+        by the software - e.g. \textbf{ssr-wfs}), or by selecting one through
+        the configuration file, when using the standard executable named
         \textbf{ssr}. This way \gls{aap}, \gls{bs}, \gls{brs}, generic,
         \gls{nfc-hoa}, \gls{vbap}, \gls{wfs} renderers become available.\\
+        Additional features can be activated with the help of several flags to
+        the executables. The customized ones, belonging to the \gls{osc}
+        interface will be discussed in the following paragraphs. More
+        information on the interplay between \gls{osc} messaging and the
+        \nameref{subsec:publisher_subscriber_interface} can be found in
+        \textbf{\nameref{subsubsec:message_interface}}.
 
         \paragraph{Client instance}
           \label{para:client-instance}
+          By default the \gls{ssr} is started as an \gls{osc} client on port
+          50001. As shown in Listing~\ref{lst:ssr-binaural-client-start}, it is
+          possible to use a different port, by defining it with the help of the
+          \textbf{-p} flag.\\
+
+          \begin{listing}[!htb]
+            \begin{mdframed}
+              \begin{minted}[fontsize=\footnotesize]{console}
+ssr-binaural -p “50002”
+              \end{minted}
+            \end{mdframed}
+            \caption{Starting the \gls{ssr} using the \gls{bs} renderer as an
+            \gls{osc} client (default) on the non-standard port 50002.}
+            \label{lst:ssr-binaural-client-start}
+          \end{listing}
+
+          Once started, the client instance waits to receive a poll message
+          from a server instance (or an application, mimicing one), upon which
+          it will subscribe to it. Only then it is possible for the server
+          application to control the client instance to the full extent.
+
         \paragraph{Server instance}
           \label{para:server-instance}
+          With the help of the \textbf{-N} flag, it is possible to start the
+          \gls{ssr} as an \gls{osc} server. In
+          Listing~\ref{lst:ssr-binaural-server-start} additionally flag
+          \textbf{-C} is used to specify an initial client \gls{ip} and its
+          port (the flag actually accepts a comma-separated list of
+          \gls{ip}-port pairs).\\
+
+          \begin{listing}[!htb]
+            \begin{mdframed}
+              \begin{minted}[fontsize=\footnotesize]{console}
+ssr-aap -N “server” -C “127.0.0.1:50002”
+              \end{minted}
+            \end{mdframed}
+            \caption{Starting the \gls{ssr} using the \gls{aap} renderer as an
+              \gls{osc} server, with an initial client on localhost, port 50002
+            provided. }
+            \label{lst:ssr-binaural-server-start}
+          \end{listing}
+
+          When the server instance starts, it instantly starts sending out poll
+          messages to all of its active clients. Clients provided by the
+          \textbf{-C} flag are considered instantly active.\\
+          Additionally it's possible for clients (\gls{ssr} client instances,
+          or \gls{osc} capable applications) to subscribe to the server
+          instance, or be subscribed to it by another client.
+          Every valid \gls{osc} message sent to the server instance will be
+          delegated to all of its clients upon evaluation.
 
       \subsubsection{Setups}
         \label{subsubsec:setups}