annotate SMC2015latex/section/framework.tex @ 54:0dd1b89b5943

updating images and framework tex

\section{Framework}

\begin{figure}[t]
\centering
\includegraphics[width=0.6\columnwidth]{images/framework.pdf}
\caption{Module hierarchy in the synpy toolkit: The top-level module provides a simple interface for the user to test different syncopation models. Musical constructs such as bars, velocity and note sequences, notes and time signatures are defined in the `music objects' module while support for common procedures such as sequence concatenation and subdivision is provided in `basic functions'. Models and file reading components can be interchanged as required by the user.\label{fig:framework}}
\end{figure}

The architecture of the toolkit is relatively simple (see Figure~\ref{fig:framework}). At the top level, syncopation values can be calculated for each bar in a given source of rhythm data; the user specifies which model to use and supplies any special parameters that are required.  Sources of rhythm data can be a bar object or a list of bars (detailed below in section\ref{sec:musicobjects}) or, alternatively, the name of a file containing music data. Where a model is unable to calculate a value for a given rhythm pattern, a “None” value is recorded for that bar and the indices of unmeasured bars reported in the output.  Output can optionally be saved directly to XML or JSON files. 

\subsection{Music objects}
\label{sec:musicobjects}
The `music objects' module provides classes to represent musical constructs such as bars, velocity and note sequences, time signatures, and individual notes.  A \code{Bar} object holds the rhythm information for a single bar of music along with its associated time signature and optional tempo and ticks-per-quarternote values. \code{Bar} objects may be initialised with either a note sequence or velocity sequence and can be chained together in the form of a doubly-linked \code{BarList} allowing syncopation models to access next and previous bars where appropriate\footnote{Several models \cite{LHL84,Keith91,Pressing97,Gomez05} implemented in the toolkit require knowledge of the contents of previous and/or next bars in order to calculate the syncopation of the current bar.}. The note sequence and velocity sequence classes are direct implementations of the sequences described in section~\ref{sec:background}.    Common low-level procedures such as sequence concatenation and subdivision are provided in `basic functions'.

\subsection{File Input}
\label{sec:fileinput}
Two file reader modules are currently provided: one for for reading plain text rhythm annotation (\code{.rhy}) files and one for reading standard MIDI files (\code{.mid}). These modules open their respective file types and return a \code{BarList} object ready for processing.  

\begin{figure}
\footnotesize{
\begin{minted}[frame=single,framesep=10pt]{python}
T{4/4} # time signature
TPQ{4} # ticks per quarternote
# Bar 1
Y{(0,3,2),(3,1,1),(6,2,2),(10,2,1),(12,4,1)}
# Bar 2
V{1,0,0,0.5,0,0,1,0,0,0,0.5,0,0.5,0,0,0}
\end{minted}
}
\caption{Example rhythm annotation \code{.rhy} file containing two bars of the Son Clave rhythm. The first is expressed as a note sequence with resolution of four ticks per quarternote; the second is the same rhythm expressed as a velocity sequence (see section~\ref{sec:background}).}
\label{ta:clave} 
\end{figure}
Our \code{.rhy} annotation format is a light text syntax for descibing rhtyhm patterns directly in terms of note and velocity sequences (see Figure~\ref{ta:clave}). 

\subsection{Plugin architecture}
The system architecture has been designed to allow new models to be added easily.   Models have a common interface, exposing a single function that will return the syncopation value for a bar of music.  Optional parameters may be supplied as a Python dictionary if the user wishes to specify settings different from the those given in the literature for a specific model.

\begin{figure}
\footnotesize{
\begin{minted}[frame=single,framesep=10pt]{python}
>>>from synpy import *
>>>import synpy.PRS as model
>>>calculate_syncopation(model, "clave.rhy")
{'bars_with_valid_output': [0, 1],
 'mean_syncopation_per_bar': 8.625,
 'model_name': 'PRS',
 'number_of_bars': 2,
 'number_of_bars_not_measured': 0,
 'source': 'clave.rhy',
 'summed_syncopation': 17.25,
 'syncopation_by_bar': [8.625, 8.625]}
\end{minted}
}
\caption{To use the toolkit, the top level \code{synpy} module is imported along with a model (in this example Pressing \cite{Pressing97}); calling \code{calculate\_syncopation()} gives the syncopation results as shown. 
\label{ta:example} }
\end{figure}






% \section{MIDI Input}\label{sec:midi}

% \cite{Taylor89MusicTheory}

% \section{Text Input}\label{sec:textinput}

% \begin{table*}
% \small{
% \begin{minted}[frame=single,framesep=10pt]{console}
% <piece>             ::=  [<comment-lines>] <timesig> <line> | <piece> <line>

% <comment-lines>     ::= <comment> "\n" | <comment-lines> <comment> "\n"

% <line>              ::= [<barlist>] [<comment>] "\n"

% <comment>           ::= "#" <comment-text>

% <barlist>           ::= <time-info> | [<time-info>] <bar> | <barlist> <bar>

% <time-info>         ::= [<timesig>] [<ticks-per-quarter>] [<tempo>] 

% <tempo>             ::= "QPM{" <digits> "}"

% <ticks-per-quarter> ::= "TPQ{" <digits> "}"

% <timesig>           ::= "T{" <digit> "/" <digit> "}"

% <bar>               ::= "V{" <velocity-sequence> "}" | "Y{" <note-sequence> "}"

% <note-sequence>     ::= <note> | <note-sequence> "," <note>

% <note>              ::= "(" <digits> "," <digits> "," <digits> ")"

% <velocity-sequence> ::= <decimal> | <velocity-sequence> "," <decimal>

% <decimal>           ::= "0" | "1" | "0." <digits>

% <digits>            ::= <digit> | <digits> <digit>

% <digit>             ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
% \end{minted}
% }
% \caption{Syntax of rhythm text format Backus-Naur Form}
% \label{ta:BNF} 
% \end{table*}