From 2f8d86703c0ab1c964cada13ef0b7a9a410df7dc Mon Sep 17 00:00:00 2001 From: David Runge Date: Tue, 20 Jun 2017 00:38:28 +0200 Subject: thesis/thesis.tex: Moving information on OSC protocol tu subsubsection of OSC interface. Ading information on Starting the SSR as client and server. --- thesis/thesis.tex | 198 +++++++++++++++++++++++++++++++++++------------------- 1 file 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} -- cgit v1.2.3-54-g00ecf