1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
|
\documentclass[12pt, a4paper, oneside, titlepage, listof=totoc, headinclude,
open=right, glossaries=totoc, captions=tableheading, final, BCOR=10mm,
parskip=never]{paper}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[usenames,dvipsnames,rgb,svgnames,table]{xcolor}
\definecolor{osc-out}{RGB}{150,0,255}
\definecolor{osc-in}{RGB}{0,0,255}
\definecolor{audio-in}{RGB}{255,0,0}
\definecolor{audio-out}{RGB}{0,206,0}
\definecolor{pubsub-in}{RGB}{128,0,0}
\definecolor{controller-in}{RGB}{0,128,0}
\definecolor{table-background-one}{RGB}{194,195,194}
\definecolor{table-background-two}{RGB}{210,213,210}
\usepackage[newfloat=true]{minted}
\usepackage{mdframed}
\usepackage{fancyhdr}
%\usepackage{ulem}
%\usepackage{lmodern}
\usepackage{url}
\usepackage{graphicx}
\usepackage{pdfpages}
\usepackage[author={David Runge}]{pdfcomment}
\usepackage{mathtools}
\usepackage{float}
\floatstyle{boxed}
\restylefloat{figure}
\usepackage{tocloft}
\setcounter{secnumdepth}{4}
\usepackage{hyperref}
\hypersetup{hidelinks, colorlinks = false}
\usepackage[font=scriptsize]{caption}
\usepackage[authoryear]{natbib}
% glossary
\usepackage[acronym,nonumberlist,toc,xindy]{glossaries}
\newacronym{aap}{AAP}{Ambisonics Amplitude Panning}
\newacronym{adat}{ADAT}{Alesis Digital Audio Tape}
\newacronym{alsa}{ALSA}{Advanced Linux Sound Architecture}
\newacronym{apf}{APF}{Audio Processing Framework}
\newacronym{api}{API}{Application programming interface}
\newacronym{asdf}{ASDF}{Audio Scene Description Format}
\newacronym{bs}{BS}{Binaural Synthesis}
\newacronym{brir}{BRIR}{Binaural Room Impulse Response}
\newacronym{brs}{BRS}{Binaural Room Synthesis}
\newacronym{cc}{CC}{Creative Commons}
\newacronym{cicm}{CICM}{Centre de recherche Informatique et Création Musicale}
\newacronym{cnmat}{CNMAT}{Center for New Music and Audio Technologies}
\newacronym{cpu}{CPU}{Central Processing Unit}
\newacronym{fdl}{FDL}{GNU Free Documentation License}
\newacronym{gpl}{GPL}{GNU General Public License}
\newacronym{gui}{GUI}{Graphical user interface}
\newacronym{hrir}{HRIR}{Head Related Impulse Response}
\newacronym{hrtf}{HRTF}{Head Related Transfer Function}
\newacronym{ide}{IDE}{Integrated Development Environment}
\newacronym{lgpl}{LGPL}{GNU Lesser General Public License}
\newacronym{lts}{LTS}{Long Term Support}
\newacronym{hoa}{HOA}{Higher Order Ambisonics}
\newacronym{ip}{IP}{Internet Protocol}
\newacronym{jack}{JACK}{JACK Audio Connection Kit}
\newacronym{madi}{MADI}{Multichannel Audio Digital Interface}
\newacronym{nfc-hoa}{NFC-HOA}{Near-field-compensated Higher Order Ambisonics}
\newacronym{oop}{OOP}{Object-oriented Programming}
\newacronym{os}{OS}{Operating System}
\newacronym{osc}{OSC}{Open Sound Control}
\newacronym{posix}{POSIX}{Portable Operating System Interface}
\newacronym{pubsub}{PubSub}{Publish-subscribe message pattern}
\newacronym{pd}{Pd}{PureData}
\newacronym{raii}{RAII}{Ressource acquisition is initialization}
\newacronym{ssr}{SSR}{SoundScape Renderer}
\newacronym{tcp}{TCP}{Transmission Control Protocol}
\newacronym{udp}{UDP}{User Datagram Protocol}
\newacronym{vbap}{VBAP}{Vector Based Amplitude Panning}
\newacronym{wfs}{WFS}{Wave Field Synthesis}
\newacronym{xml}{XML}{Extensible Markup Language}
\newglossaryentry{sclang}{
name={sclang},
description={Name of the SuperCollider programming language and the
interpreter executable of the SuperCollider programming language}
}
\newglossaryentry{id}{
name={ID},
description={A name or number, that identifies an object},
plural=IDs
}
\newglossaryentry{stdout}{
name={stdout},
description={The standard output is a stream where a program writes its
output data to. This can be a log file or a terminal}
}
\newglossaryentry{faust}{
name={FAUST},
description={Functional Audio Stream is a functional programming language
specifically designed for realtime signal processing and synthesis}
}
\newglossaryentry{quark}{
name={Quark},
description={Name for Classes extending the SuperCollider programming
language, usually developed in a separate version controlled code
repository},
plural=Quarks
}
\newglossaryentry{supercollider}{
name={SuperCollider},
description={A programming language, \gls{ide} and synthesis server for
realtime audio processing and synthesis}
}
\newglossaryentry{qt4}{
name={Qt4},
description={Version 4 (legacy) of the cross-platform application framework
for creating desktop applications.}
}
\makeglossaries
\graphicspath{{../images//}}
\begin{document}
\pagenumbering{Roman}
\pagestyle{empty}
\begin{titlepage}
\centering
\includegraphics[width=0.3\textwidth]{tu-berlin-logo.pdf}\par\vspace{1cm}
{\scshape\LARGE Technische Universität Berlin\par}
\vspace{1cm}
{\scshape\Large Master Thesis\par}
\vspace{1.5cm}
{\huge\bfseries A Networking Extension for the SoundScape Renderer\par}
\vspace{2cm}
{\Large\itshape David Runge\par}
\vspace{1.5cm}
{\large (340592)}\\
\href{dave@sleepmap.de}{dave@sleepmap.de}\\
\vfill
supervised by\par
Henrik von Coler and Stefan Weinzierl
\vfill
{\large \today\par}
\end{titlepage}
\section*{Eidesstattliche Erklärung}
\vspace{1cm}
Hiermit erkläre ich, dass ich die vorliegende Arbeit selbstständig und
eigenhändig sowie ohne unerlaubte fremde Hilfe und ausschließlich unter
Verwendung der aufgeführten Quellen und Hilfsmittel angefertigt habe.\\
Berlin, den \today\par\\
\vspace{2cm}
\noindent\ldots\ldots\ldots\ldots\ldots\ldots\ldots\ldots\ldots\ldots\ldots\\
David Runge
\newpage
Thanks
\newpage
\begin{abstract}
\gls{wfs} as a technological concept has been around for
many years now and all over the world several institutions run small and
some even large scale setups ranging from single speaker lines to those
facilitating a couple of hundred loudspeakers respectively.\\
The still evolving implementations are driven by several rendering
engines, of which two free and open-source ones, namely sWONDER and
SoundScape Renderer, have (partially) been developed at TU Berlin.\\
The latter due to its current design is not yet able to render for large
scale setups, ie.\ those using several computers to render audio on a
loudspeaker setup, due to the high amount of channels.\\
Its solid codebase however, which additionally offers a framework for many
more renderering types, and the ongoing development, deems further work on
this application a good future investment.\\
This work is about the extension of the SoundScape Renderer's functionality
to turn it into a networking application for large scale \gls{wfs} setups.
\end{abstract}
\newpage
\renewcommand{\abstractname}{Zusammenfassung}
\begin{abstract}
\gls{wfs} as a technological concept has been around for
many years now and all over the world several institutions run small and
some even large scale setups ranging from single speaker lines to those
facilitating a couple of hundred loudspeakers respectively.\\
The still evolving implementations are driven by several rendering
engines, of which two free and open-source ones, namely sWONDER and
SoundScape Renderer, have (partially) been developed at TU Berlin.\\
The latter due to its current design is not yet able to render for large
scale setups, ie.\ those using several computers to render audio on a
loudspeaker setup, due to the high amount of channels.\\
Its solid codebase however, which additionally offers a framework for many
more renderering types, and the ongoing development, deems further work on
this application a good future investment.\\
This work is about the extension of the SoundScape Renderer's functionality
to turn it into a networking application for large scale \gls{wfs} setups.
\end{abstract}
\newpage
\setcounter{page}{1}
\pagestyle{plain}
\printglossaries
\newpage
\phantomsection
\addcontentsline{toc}{section}{\listtablename}
\listoftables
\newpage
\phantomsection
\addcontentsline{toc}{section}{\listfigurename}
\listoffigures
\newpage
\phantomsection
\addcontentsline{toc}{section}{\listlistingname}
\listoflistings
\newpage
\pagestyle{empty}
{
\setcounter{tocdepth}{4}
\renewcommand{\thispagestyle}[1]{}
\tableofcontents
\newpage
}
\pagestyle{headings}
\setcounter{page}{1}
\pagenumbering{arabic}
\renewcommand{\theFancyVerbLine}{\textcolor{gray}{\scriptsize\arabic{FancyVerbLine}}}
\RecustomVerbatimEnvironment{Verbatim}{Verbatim}{xleftmargin=5mm}
\section{Introduction}
\label{sec:introduction}
\cleardoublepage
\section{Free and open-source spatial audio renderers}
\label{sec:freespatialaudiorenderers}
To date there exist five (known of) free and open-source spatial audio
renderers, which are all \gls{jack} \citep{website:jackaudio2016} clients:
\begin{itemize}
\item sWONDER \citep{website:swonder2016}, developed by Technische
Universität Berlin, Germany
\item WFSCollider \citep{website:wfscollider}, developed by the Game Of
Life Foundation \citep{website:gameoflife}, The Hague, Netherlands
\item HoaLibrary for \gls{pd} \citep{github:hoalibraryforpd} developed at
\gls{cicm}, Paris, France
\item 3Dj for \gls{supercollider} \citep{thesis:perezlopez3dj2014},
developed at Universitat Pompeu Fabra, Barcelona
\item \gls{ssr} \citep{website:ssr2016}, developed by Quality \&
Usability Lab, Telekom Innovation Laboratories, TU Berlin and Institut
für Nachrichtentechnik, Universität Rostock and Division of Applied
Acoustics, Chalmers University of Technology
\end{itemize}
Different concepts and contexts apply to all of the renderers, which are
about to be explained briefly in the following sections, prefixed by a
section about spatial audio renderer appliances and followed by one about
free software and its pitfalls.
\subsection{Spatial audio rendering algorithms and their appliances}
\label{subsec:spatialaudiorenderersandtheirappliance}
In the following subsubsections several spatial audio rendering
algorithms are introduced briefly.
As they serve as a mere introductory, they are merged where applicable.
\subsubsection{Dynamic Binaural Synthesis and Dynamic Binaural Room
Synthesis}
\label{subsubsec:binaural}
\gls{bs} describes a stereophonic audio reproduction, in which -
usually using headphones - acoustic signals are recreated at the ears
of the listener.\\
For humans, sound source localization and distance estimation takes
place according to auditory cues from each ear. The signals perceived
by inner and outer ear, are correlated by the brain, to account for
locations in all three dimensions and their distances from the
listener.\\
The differences between the cues perceived by each ear can be measured
as a \gls{hrir} for every human individually (as it is dependant on
physiology). Its Fourier transform, the \gls{hrtf}, can then be used
to modify audio signals to become a directional audio source, perceived
as in free field conditions.\\
\gls{brs} is a special form of \gls{bs}, in which \glspl{brir}, encode
all of the virtual source's characteristics, such as position,
alongside the room's acoustic characteristics.
This way, recordings from real rooms can be reproduced authentically.\\
\glspl{hrir} and \glspl{brir} are by default applied seperately for
each ear, therefore, if a resolution of 1\textdegree~is desired, it
can only be achieved by a set of 720 impulse responses.
\subsubsection{(Higher Order) Ambisonics Amplitude Panning and
Near-field-compensated Higher Order Ambisonics}
\label{subsubsec:aapandnfchoa}
\gls{aap} and \gls{hoa} are spatial rendering algorithms, that
reproduce audio on multi-speaker setups. Those are usually circular or
spherical.\\
Depending on a loudspeaker's position in the setup, relative to the
spheres's center (the listening area or \textit{sweet spot}), a linear
combination of all loudspeakers is used to achieve a localized
representation of a virtual sound source.\\
The relatively small listening area can be extended by using additional
sets of loudspeakers, which in turn lead to more spatial aliasing.\\
Due to the perceptebility of localization cues, mentioned in
\rer{subsubsec:binaural}, it is required to apply spatial equalization
for the rendered sources, to account for differences in low- and
high-frequency localization capabilities of the human ear.\\
For ambisonics, plane-wave sources are assumed. Due to the proximity
effect, this leads to a bass boost in the listening area. \gls{nfc-hoa}
accounts for this by a set of driving functions, applying a per speaker
near-field compensation.\\
\subsubsection{Vector Based Amplitude Panning}
\label{subsubsec:vbap}
\subsubsection{Wave Field Synthesis}
\label{subsubsec:wavefieldsynthesis}
\gls{wfs} describes a spatial technique for rendering audio. As such it
aims at synthesizing a sound field of desired acoustic preference in a
given listening area, assuming a planar reproduction to be most
suitable for most applications.\\
\gls{wfs} is typically implemented using a circular, rectangular or
linear loudspeaker array surrounding or fronting the listening area.\\
Several free and open-source renderer applications exist for \gls{wfs}
environments, with varying stages of feature richness.\\
\subsection{sWONDER}
\label{subsec:swonder}
sWONDER \citep{baalman2007} consists of a set of C++ applications that
provide \gls{bs} and \gls{wfs} rendering. In 2007 it was specifically
redesigned \citep{baalmanetal2007} to cope with large scale \gls{wfs}
setups in which several (computer) nodes, providing several speakers
each, drive a system together.\\
In these setups each node receives all available audio streams (which
represent one virtual audio source respectively) redundantly and a master
application signals which node is responsible for rendering what source
on which speaker.\\
It uses \gls{osc} for messaging between its components and for setting
its controls. Additionally, it can be controlled through a \gls{gui},
that was specifically designed for it.\\
Sound sources can be moved dynamically, or according to a \gls{xml} based
score.\\
sWONDER has been in use for the medium and large scale \gls{wfs} systems
in the Electronic Music Studio \citep{website:tu-electronic_studio} and
lecture hall H0103 \citep{website:tu-wfs} at Technical University of
Berlin and a medium scale system at the Wave Field Synthesis Lab at HAW
in Hamburg \citep{Fohl2013}.\\
The included convolution engine fWonder has found application in
“Assessing the Authenticity of Individual Dynamic Binaural Synthesis”
\citep[pp. 223-246]{lindau2014}.\\
Unfortunately, the spatial audio renderer has not been actively
maintained for several years, is limited to its two rendering algorithms
and has many bugs, that are not likely to get fixed in the future.\\
\subsection{HoaLibrary (PureData extension)}
\label{subsec:hoalibrary_puredata_extension}
The HoaLibrary is “a collection of C++ and \gls{faust} classes and
objects for Max, PureData and VST destined to high order ambisonics sound
reproduction” \citep{website:hoalibrary}. By using its \gls{pd}
extension, it enables for \gls{hoa} reproduction, while harnessing the
rich feature set of the audio programming language still enables for
implementing other forms of spatial rendering alongside the HoaLibrary.\\
\gls{pd} is \gls{osc} capable with the help of extensions, such as
\textit{mrpeach}\footnote{ \href{https://puredata.info/downloads/mrpeach}
{https://puredata.info/downloads/mrpeach}} or \textit{IEMnet}\footnote{
\href{https://puredata.info/downloads/iemnet}
{https://puredata.info/downloads/iemnet}}.\\
\subsection{3Dj (SuperCollider Quark)}
\label{subsec:3dj_supercollider_quark}
3Dj is a \gls{supercollider} \gls{quark} conceived in the course of a Master
Thesis at Universitat Pompeu Fabra, Barcelona
\citep{thesis:perezlopez3dj2014} for interactive performance live
spatialization purposes. It implements \gls{hoa} and \gls{vbap} rendering
\citep[p 45]{thesis:perezlopez3dj2014} and uses a specific scene format
\citep[pp. 45-46]{thesis:perezlopez3dj2014} to allow sound sources to
have static, linear, random, brownian, simple harmonic and orbital
motion.\\
Due to being a language extension to \gls{sclang}, 3Dj can be used in
conjunction with other spatial rendering algorithms provided by
\gls{supercollider} or any of its \glspl{quark}.\\
\gls{supercollider} is \gls{osc} enabled by default, which renders 3Dj a
dynamically accessible solution.
\subsection{WFSCollider}
\label{subsec:wfscollider}
WFSCollider was built on top of
\href{https://supercollider.github.io}{SuperCollider} 3.5
\citep{website:supercollider} and as its name suggests, is an application
for \gls{wfs} reproduction. It “allows soundfiles, live input and
synthesis processes to be placed in a score editor where start times, and
durations can be set and trajectories or positions assigned to each
event. It also allows realtime changement of parameters and on the fly
starting and stopping of events via \gls{gui} or \gls{osc} control. Each
event can be composed of varous objects (“units”) in a processing chain“
\citep{website:wfscollider}. According to its current manual, it is
also capable of using a \gls{vbap} renderer for other multi-speaker
setups \citep[p. 8]{manual:wfscollider}.\\
”WFSCollider is the driving software of the Wave Field Synthesis system
of the Game Of Life Foundation“ \citep{website:gameoflife}. In
multi-computer setups, it can synchronize the involved processes and a
dynamic latency can be introduced to account for high network throughput
\citep[p. 22]{manual:wfscollider}. WFSCollider by nature is \gls{osc}
capable and extendable by what \gls{sclang} has to offer. Its scores are
saved as \gls{supercollider} code, as well.\\
It is currently only tested on MacOSX and is based upon a several year
old version of \href{https://supercollider.github.io}{SuperCollider}.
\subsection{SoundScape Renderer}
\label{subsec:soundscaperenderer}
The \gls{ssr}, written in C++, is a multi-purpose spatial audio renderer,
that runs on Linux and MacOSX\@. Based on its underlying \gls{apf}
\citep{MatthiasGeierTorbenHohn1890}, it is able to use \gls{bs},
\gls{brs}, \gls{aap}, \gls{wfs}, \gls{hoa} and \gls{vbap}.\\
It can be used with a \gls{qt4} based \gls{gui} or headless (without
one), depicting the virtual sources, their volumes and positions. If a
loudspeaker based renderer is chosen, the \gls{gui} also illustrates
which speakers are currently used for rendering a selected source.\\
The \gls{bs} and \gls{brs} renderers are frequently used in scientific
research, such as \citep{DavidAckermann1895} or
\citep{DmitryGrigoriev1896}. The \gls{wfs} renderer has been improved by
the work of several research papers, dealing with enhancements of spatial
aliasing, active listening room and loudspeaker compensation and active
noise control \citep{SaschaSporsRudolfRabensteinJensAhrens1822} and
analyzing and pre-equalizing in 2.5-dimensional \gls{wfs}
\citep{SaschaSporsJensAhrens1821}.\\
The \gls{ssr} uses \gls{xml} based configuration files for reproduction
(i.e.\ how something is played back) and scene (i.e.\ what is played
back). The \gls{asdf} however is not (yet) able to represent dynamic
setups.\\
The application can be controlled through a \gls{tcp}/\gls{ip} socket.
\gls{osc} functionality can only be achieved using the capapilities of
other applications such as \gls{pd} \citep{website:puredata2016} in
combination with it.\\
Unlike \nameref{subsec:swonder} or \nameref{subsec:wfscollider}, the
\gls{ssr} is not able to run medium or large-scale \gls{wfs} setups, as
it lacks the features to communicate between instances of itself on
several computers, while these instances serve a subset of the
available loudspeakers.
\subsection{Why free software matters and what its pitfalls are}
\label{subsec:whyfreesoftwarematters}
Free software is the terminology for software published under a free
license. Licenses, such as the \gls{gpl} are considered free, because
they allow for anyone to copy, modify and redistribute the source code
(under the same license).\\
Research is a field of work, in which reproducability is very important,
as findings need to be independently verifiable. Scientific work is
published and shared (sometimes also under free licenses, such as
\gls{cc}) amongst research groups of institutions all around the world.
In an ideal world, all scientific research would be published under a
free documentation license, such as the \gls{fdl}, allowing access to
anyone.\\
The software used in scientific institutions is unfortunately rarely free
(e.g. Microsoft Exchange, Microsoft Office, Adobe Photoshop in general
and Steinberg's Cubase, Cycling '74's Max/MSP, Avid's ProTools or
Ableton Live in the audio production field) and additionally mostly bound
to proprietary \glspl{os}, such as Microsoft Windows or Apple's MacOS,
preventing interoperability, development and an open society.\\
Free software however enables students and researchers to learn from the
source code directly (if they can and want to), to modify (and improve)
it and to share their findings. More than with proprietary software, it
is possible to have a community develop around it, that takes care of the
project for a long time.\\
Free software nonetheless can not be considered a silver bullet. It is
after all only a way of developing software and not a way to grade its
efficiency or code quality. Additionally, especially in a scientific
context it can happen, that software is conceived by an institution, put
to use, but afterwards not developed any further, as the programmers go
their way (e.g. \nameref{subsec:swonder}).
This way a high responsibility weighs on these institutions, as they
need to ensure further development on systems, not easily accessible to
the public, or not feasible for home use (e.g. \gls{wfs}). This situation
however also holds a great opportunity for coorporation.
\cleardoublepage
\section{Implementation}
\label{sec:implementation}
This section covers the implementation of a networking interface for the
\gls{ssr} and the considerations leading to it.
The application was chosen to be extended by a \gls{osc} based networking
interface, because it runs on multiple \glspl{os}, offers a wide set of
rendering algorithms (in various stages of completion) by using the
\gls{apf} \citep{MatthiasGeierTorbenHohn1890}, is used extensively in
scientific research, has the future possibility to run medium and large
scale \gls{wfs} setups and was still actively maintained by its creators at
the time of writing.\\
\subsection{Outline}
\label{subsec:outline}
Initially it was aimed at extending the \gls{ssr}'s features in the scope
of creating a replacement for the aging sWONDER software, enabling it to
run networked instances to drive a medium or large scale \gls{wfs} setup.
The approach appeared too narrow however, as the application offers many
different rendering algorithms. A networking extension therefore would
have to be available to all of them with an equal feature set.
Additionally, extending a rendering framework by a networking feature,
with the help of only one of its engines proved to be linked to a
massive, but avoidable overhead (see~\ref{subsubsec:preliminaries}).\\
The \gls{ssr}, being a multi-purpose spatial audio renderer, can be used
in diverse setup scenarios (see~\ref{subsubsec:setups}). Therefore not
only classic server-client relationships
(see~\ref{subsubsec:remote_controlling_a_server}), but also client-only
and local (see~\ref{subsubsec:remote_controlling_a_client}) setups had to
be taken account of. In addition the case of medium and
large scale loudspeaker based rendering setups and their specifics had to
be considered (see~\ref{subsubsec:rendering_on_dedicated_speakers}).
\subsubsection{Prelimenaries}
\label{subsubsec:preliminaries}
In preparation to this work, an implemention of a side-by-side
installation to the \gls{os} currently driving the \gls{wfs} system
setup of the Electronic Studio at TU Berlin
\citep{website:tu-electronic_studio} was attempted for testing
purposes.\\
Arch Linux \citep{website:archlinux} was installed and configured to
run the medium scale setup. Unfortunately the proprietary Dante
\citep{website:audinate} driver for Linux, offered by Four Audio
\citep{website:fouraudio}, creates non-trivial circumstances for using
it on an up-to-date Linux kernel, due to \gls{alsa} \gls{api} changes
not accounted for.\\
While the current \gls{os} - an Ubuntu \citep{website:ubuntu} Studio
2012 \gls{lts} - still runs well in its own parameters, its support has
run out and it is therefore becoming harder, if not impossible, to
build newer software on it, using newer versions of free software
compilers.\\
For research purposes however, it is desirable to be able to try new
kernel and software features, finding the most stable and secure setup
possible involving realtime enabled kernels and building new versions
of (spatialisation) software on a regular basis.\\
The hardware of the large scale setup at TU Berlin in room H0104 was
being updated and unusable at the time of writing. In the future it
will however become a valuable candidate for testing of the sought
after \gls{ssr} features, as its setup involves no Dante network, but
is instead run by several rendering computers connected to \gls{madi}
and \gls{adat} lightpipe enabled speaker systems.\\
Although a \gls{wfs} setup for testing purposes was eligible, it
generally is not needed for implementing the features described in
the following sections and subsections, as they can be tested using two
machines running Linux, \gls{jack} and a development version of the
\gls{ssr}.\\
\subsubsection{Remote controlling a server}
\label{subsubsec:remote_controlling_a_server}
A \gls{ssr} server instance in the notion of a medium to large scale
reproduction setup is supposed to have a set of \textit{n}
(pre-)assigned clients. Generally, controlling it should be possible
through either \gls{udp} or \gls{tcp}.
Every message sent to it, should be distributed to all of its clients
(if applicable), preferably using the same protocol used to communicate
with the server. The messaging system should be flexible and
scriptable.\\
All audio inputs available to the server should be available to its
clients as well. A server instance should be able to render audio just
as a client would. It should be able to receive messages from its
clients and act upon them (e.g.\ updating \gls{gui} elements).
\subsubsection{Remote controlling clients}
\label{subsubsec:remote_controlling_a_client}
A \gls{ssr} client can either be local (on the same machine) or
somewhere on the same network, as the server or application controlling
it. It should not make a difference, if the client instance is
controlled by a server instance or any other application, implementing
the messaging system it uses. A client should send an update to its
server or the application controlling it, upon receiving a valid
message.
\subsubsection{Rendering on dedicated speakers}
\label{subsubsec:rendering_on_dedicated_speakers}
In a medium or large scale setup, \textit{n} clients collectively
render audio on \textit{l} loudspeakers, while all should be using the
same \textit{i} inputs and each have \textit{c} hardware outputs.
\textit{l} is preferably a multiple of \textit{c}, but definitely
larger than \textit{c}.\\
As the described setups usually have too many loudspeakers for only one
machine (i.e.\ a client), a system has to be conceived, by which each
client will only render on its specifically assigned subset of size
\textit{c} of the \textit{n} loudspeakers.
\subsection{Publisher/Subscriber interface}
\label{subsec:publisher_subscriber_interface}
The \gls{ssr} internally uses a \gls{pubsub}, which is a design pattern,
to implement control through and over several parts of its components.\\
In \gls{oop} \gls{pubsub} - also called observer, listener messaging - is
usually comprised of a publisher class, handling the messages, without
explicitely implementing how they will be used and a subscriber class,
that allows for its implementations to subscribe to the messages
provided. Filtering takes place to enable subscribers to only receive a
certain subset of the messages.\\
The \gls{ssr} implements a content-based filtering system, in which each
subscriber evaluates the messages received and acts depending on its own
constraints to implement further actions upon it.\\
\begin{figure}[!htb]
\centering
\includegraphics[scale=0.6, trim = 6mm 130mm 12mm 4mm, clip]
{ssr-publisher-with-legacy-subscribers.pdf}
\caption{A diagram depicting a simplified version of the \gls{pubsub}
used within the \gls{ssr}.\\
{\color{pubsub-in}\textbf{--}} Calls from Publisher to Subscriber
{\color{controller-in}\textbf{--}} Calls from Subscribers to
Controller (Publisher)
}
\label{fig:ssr-publisher-with-legacy-subscribers}
\end{figure}
The abstract class \mintinline{c++}{Publisher} defines the messages
possible to send and provides means to subscribe to them. The global
\mintinline{c++}{Controller} class is its only implementation within the
\gls{ssr}.\\
The abstract class \mintinline{c++}{Subscriber} in turn defines the
messages understood, while its implementations in
\mintinline{c++}{RenderSubscriber}, \mintinline{c++}{Scene},
\mintinline{c++}{OscSender} and \mintinline{c++}{NetworkSubscriber} take
care of how they are used.\\
This system enables a versatile messaging layout, in which components can
call the \mintinline{c++}{Publisher} functionality in
\mintinline{c++}{Controller}, which in turn will send out messages to all
of its subscribers.\\
Depending on the design of an application, \gls{pubsub} is not
necessarily a one-way-road. As shown in
Figure~\ref{fig:ssr-publisher-with-legacy-subscribers}, subscribers can
also be able to call functions of the \mintinline{c++}{Publisher}, if the
implementation permits it.\\
In the \gls{ssr} this is possible, because each
\mintinline{c++}{Subscriber} holds a reference to the
\mintinline{c++}{Controller} instance and is therefore able to call its
public functions.\\
According to the principle of encapsulation in \gls{oop}, this type of
functionality is handled by a separate class. In
Figure~\ref{fig:ssr-publisher-with-all-subscribers}, the
\mintinline{c++}{OscHandler} and \mintinline{c++}{Server} instances
delegate calls to \mintinline{c++}{Controller} functionality to their
utilities \mintinline{c++}{OscReceiver} and
\mintinline{c++}{CommandParser} (respectively).
\subsection{IP interface}
\label{subsec:ip-interface}
The \gls{ssr} from early on incorporated a network interface, that
accepts specially terminated \gls{xml}-formatted strings over a \gls{tcp}
port, called “\gls{ip} interface”. This has the benefit of reusing the
same \gls{xml} parser code in use for scene and reproduction
description.\\
A downside is however, that - from the perspective of other software - it
is complicated to use, as a conversion to \gls{xml} has to be attempted
before sending a message to the \gls{ssr}. Additionally the message has
to be linted (error checked) before sending and again parsed, after
receiving an answer from the application.\\
The \gls{ip} interface achieves to offer more or less direct access to
the \nameref{subsec:publisher_subscriber_interface}. However, it has no
notion of a networked setup and could therefore be described as a
two-directional message system between two destinations. With it, only
setups with up to \textit{n} clients are possible.
\subsubsection{OSC through PureData}
\label{subsubsec:osc_through_puredata}
To allow \gls{osc} communication, the \gls{ssr} incorporates a Lua
based \gls{pd} external. It uses two externals
(\textit{IEMnet}\footnote{
\href{https://puredata.info/downloads/iemnet}
{https://puredata.info/downloads/iemnet}} and
\textit{pdlua}\footnote{\href{https://puredata.info/downloads/pdlua}
{https://puredata.info/downloads/pdlua}}) alongside a Lua library for
parsing and creating \gls{xml}
(\textit{SLAXML}\footnote{\href{https://github.com/Phrogz/SLAXML}
{https://github.com/Phrogz/SLAXML}}).
\subsubsection{Sending and receiving}
\label{subsubsec:sending_and_receiving}
As mentioned in
section~\nameref{subsec:publisher_subscriber_interface}, the
\mintinline{c++}{NetworkSubscriber} class (part of the \gls{ip}
interface) implements the \mintinline{c++}{Subscriber} interface. This
means: The network interface subscribes to the messages the
\mintinline{c++}{Publisher} (the \mintinline{c++}{Controller} instance)
has to offer. Every time a function of the \gls{ssr}'s
\mintinline{c++}{Controller} instance, that was inherited from
\mintinline{c++}{Publisher}, is called, it will issue the call on all
of its subscribers, too.\\
\cleardoublepage
\subsection{Open Sound Control interface}
\label{subsec:osc-interface}
The networking interface conceived in the course of this work was
developed in several branches, using the git version control system
(written by Linus Torvalds, now maintained by Junio
Hamano\footnote{\href{https://git-scm.com}{https://git-scm.com}}),
publicly on Github\footnote{\href{https://github.com/dvzrv/ssr}
{https://github.com/dvzrv/ssr}}. Internally the liblo library (further
explained in~\ref{subsubsec:liblo}) was harnessed to implement \gls{osc}
functionality (see~\ref{subsubsec:open-sound-control}) for the
\gls{ssr}.\\
After initial conversations with the current maintainer Matthias Geier
through the project's Github issue
tracker\footnote{ \href{https://github.com/soundscaperenderer/ssr}
{https://github.com/soundscaperenderer/ssr}}, different ideas were worked
out to achieve a broad solution to the server-client and client-only
setups and get a better understanding of the underlying design. Initial
attempts, such as the mapping of a networking setup in the scene
description\footnote{
\href{https://github.com/dvzrv/ssr/tree/distributed\_reproduction}
{https://github.com/dvzrv/ssr/tree/distributed\_reproduction}}
proved too restrictive though, as it would allow the networking
functionality only to renderers, that use loudspeakers and mix scene
description with networking description.\\
A nearly configuration-less approach, based on subscribing clients on
sending poll messages to them proved more open (in the sense that it can
be interfaced with by any \gls{osc}-capable application or programming
language) and have less configuration overhead. With it, a diverse set of
setups can be achieved (further described in~\ref{subsubsec:setups}),
which at the same time remain dynamically configurable (using a plethora
of \gls{osc} implementations) and debuggable using tests (further
explored in~\ref{subsec:automated_tests}).
\begin{figure}[!htb]
\centering
\includegraphics[scale=0.6, trim = 6mm 91mm 12mm 10mm, clip]
{ssr-publisher-with-all-subscribers.pdf}
\caption{A diagram depicting a simplified version of the \gls{pubsub}
used within the \gls{ssr}.\\
{\color{pubsub-in}\textbf{--}} Calls from \mintinline{c++}{Publisher}
to \mintinline{c++}{Subscriber} {\color{controller-in}\textbf{--}}
Calls from \mintinline{c++}{Subscribers} to
\mintinline{c++}{Controller} (\mintinline{c++}{Publisher})
}
\label{fig:ssr-publisher-with-all-subscribers}
\end{figure}
The main implementations of the interface, further described in the
following subsections, can be found in the classes
\mintinline{c++}{OscHandler} (handling the \gls{osc} server),
\mintinline{c++}{OscReceiver} (handling incoming \gls{osc} messages and
acting upon them in the context of the \gls{ssr} instance) and
\mintinline{c++}{OscSender} (responsible for reacting to calls from the
\textbf{\nameref{subsec:publisher_subscriber_interface}} and sending of
\gls{osc} messages to clients and server).\\
As shown in Figure~\ref{fig:ssr-publisher-with-all-subscribers}, the
\mintinline{c++}{OscSender} is another implementation of the
\mintinline{c++}{Subscriber} interface. This way, every call made through
the \mintinline{c++}{Publisher} (i.e.\ the \mintinline{c++}{Controller}),
will be made on the corresponding function in \mintinline{c++}{OscSender}
as well. With \mintinline{c++}{OscReceiver} the \gls{osc} interface has
direct access to the \mintinline{c++}{Controller} and can make calls to
it, on receiving a message.\\
In its implementation approach the \gls{osc} interface therefore follows
that of the \textbf{\nameref{subsec:ip-interface}}, expanding however in
creating a client-server architecture, controlled by
\textbf{\nameref{subsubsec:message_levels}}, using a unified
\textbf{\nameref{subsubsec:message_interface}}.\\
\gls{ssr} client instances only evaluate messages of server instances
they are subscribed to. Server instances only evaluate messages of client
instances, that are subscribed to them.
\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},
\gls{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]
\renewcommand{\arraystretch}{1.2}
\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} & \mintinline{c++}{int32} \\
\texttt{f} & \mintinline{c++}{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}
As shown in Table~\ref{tab:ssr-osc-data-type-acronyms}, only
\mintinline{c++}{int32}, \mintinline{c++}{float32}, \gls{osc}-string
and \gls{osc}-blob are considered standardized. Most of the remaining
non-standard types are however implemented and used by many different
clients. For implementing the \gls{ssr} \gls{osc} interface, described
in the following subsubsections, it was necessary to use the
non-standard types \textit{True} and \textit{False} alongside the
standard-types.
\subsubsection{liblo}
\label{subsubsec:liblo}
Liblo \citep{website:liblo2017} is an implementation of the \gls{osc}
protocol for \gls{posix} systems. It was initially developed by Steve
Harris and is now actively maintained by Stephen Sinclair.\\
The library, written in C, offers a C++ abstraction layer and is
released under the \gls{lgpl} v2.1 or greater. Additionally there are
wrappers for the Perl and Python programming languages.\\
Due to its long standing availability and usage in many small and
large-scale software projects, alongside its fairly straight forward
implementability, it was chosen as the candidate for establishing a
\gls{osc} interface for the \gls{ssr}.\\
At the time of writing liblo's lastet stable release (0.28) was issued
on 27th January 2014. Many changes and improvements have been applied
to the codebase since then. One of them is the implementation of a
\mintinline{c++}{ServerThread} for the C++ abstraction layer, which
runs a \mintinline{c++}{Server} instance on a separate thread
automatically.\\
In programming, threads are a way to implement simultaneous and/ or
asynchroneous execution of code. The liblo \mintinline{c++}{Server}
class, at the core of the C++ side of the library, is responsible for
assigning a network port to listen to for incoming messages, listening
for messages, executing code on their arrival (i.e.\ callback handling)
and sending messages to clients. As most applications, facilitating
liblo, use \gls{osc} only as a messaging system, it usually means, that
the application itself is not single-purpose and is busy computing
something else most of the time. Therefore it makes sense to run a
Server instance on a separate background thread, to not interfere with
the executional flow of the rest of the program.\\
The \mintinline{c++}{ServerThread} class is able to free its ressources
upon going ot of scope, known as \gls{raii}. For this reason, the
latest development version, instead of the current stable version of
liblo was chosen for the implementation.
\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 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\pdfcomment[color=red,icon=Note]{Handle failure to startup the
liblo ServerThread more gracefully. Instead of segfaulting in case of
port in use, throw error message and exit.}. 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]{shell}
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, mimicking 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 via
\gls{osc}.
\paragraph{Server instance}
\label{para:server-instance}
With the help of the \textbf{-N} flag
\pdfcomment[color=red,icon=Note]{Make -N start server, client is
default anyways}, 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).\\
The \textbf{-p} flag, for setting a specific port is also available,
when starting a server instance.
\begin{listing}[!htb]
\begin{mdframed}
\begin{minted}[fontsize=\footnotesize]{shell}
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, using a message
level system further explained in~\ref{subsubsec:message_levels}.
Every valid \gls{osc} message sent to the server instance will be
delegated to all of its clients upon evaluation, again according to
the aforementioned message level system.
\paragraph{Verbosity}
\label{para:verbosity}
The \gls{ssr} can be started with several levels of verbosity. These
are accessed by using the flag \textbf{-v}, up to three times (i.e.
\textbf{-vvv}).\\
The higher the level of verbosity, the more messages will be printed
by the application. This especially applies to the \gls{osc}
interface part of the \gls{ssr}, as most incoming and outgoing
messages will be printed to \gls{stdout} at a level of \textbf{-vv}.
At a level of \textbf{-vvv}, additionally all incoming and outgoing
messages, that are issued in very short intervals per default
(see~\ref{subsubsec:message_levels} for details) will be printed.
\subsubsection{Setups}
\label{subsubsec:setups}
The \gls{ssr} offers the possibility for many different \gls{osc}
enabled client-server and client-only setups. They will be explained in
the following paragraphs.\\
All examples provide audio input via a \gls{jack} client, which can be
local (on each client's or server's host computer) or provided through
external audio inputs from another host computer (e.g.\ through
\gls{adat} or \gls{madi}). This however is not mandatory, as the
\gls{ssr} is capable of playing back audio files directly.\\
The differences between server and client messaging is further
elaborated upon in \textbf{\nameref{subsubsec:message_interface}}.\\
A special networked setup, in which the server instance is not
rendering any audio, is discussed in
\textbf{\nameref{subsec:implementing_a_nullrenderer}}.
\paragraph{Client-Server, shared rendering}
\label{para:client_server_shared_rendering}
In Figure~\ref{fig:ssr-client-server-shared-output}, the setup shows
\textit{1} to \textit{n} client instances, controlled by a server
instance. All instances are receiving audio from an external
\gls{jack} client or from reading local files. Collectively, the
\textit{n} clients and the server are rendering audio on a shared
output system (e.g. \gls{wfs} or \gls{hoa}).\\
The server instance is controlled through its \gls{gui}, sends out
\gls{osc} messages to all \textit{n} clients and receives their
updated information (again through \gls{osc}).
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-client-server-shared-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in
which the server and the clients render audio collectively (e.g.
\gls{wfs}). The server instance is not controlled via \gls{osc},
but controls its clients through it.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-client-server-shared-output}
\end{figure}
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-external-client-server-shared-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in
which the server and the clients render audio collectively (e.g.
\gls{wfs}). The server instance is controlled by an \gls{osc}
capable application (acting as another client) and controls its
clients through \gls{osc} as well.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-external-client-server-shared-output}
\end{figure}
The setup shown in
Figure~\ref{fig:ssr-external-client-server-shared-output} is similar
to the previous one, with the exception, that the server instance is
controlled by an external \gls{osc} capable application. This way,
the server instance can also be run headless (without a \gls{gui}).\\
The set of \textit{n} clients report back to the server instance,
which in turn reports back to the \gls{osc} enabled application
(acting as another client).
\cleardoublepage
\paragraph{Client-Server, separate rendering}
\label{para:client_server_separate_rendering}
As shown in Figure~\ref{fig:ssr-client-server-separate-output}, it is
possible to have a setup, in which, similar to the one described in
Figure~\ref{fig:ssr-client-server-shared-output}, server and
\textit{n} clients render the same sources, but on separate output
systems (e.g.\ several \gls{bs}/\gls{brs} renderers or even a mixture
of a \gls{wfs}/\gls{hoa} system and several \gls{bs}/\gls{brs}
renderers).\\
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-client-server-separate-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in
which the server and the clients render audio to separate outputs
(e.g.\ multiple \gls{bs} renderers). The server instance is not
controlled via \gls{osc}, but controls its clients through it.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-client-server-separate-output}
\end{figure}
Figure~\ref{fig:ssr-external-client-server-separate-output} is an
example of a similar setup, but again using an external \gls{osc}
capable application to control the server instance.\\
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-external-client-server-separate-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in
which the server and the clients render audio separately (e.g.\
multiple \gls{bs} renderers). The server instance is controlled
by an \gls{osc} capable application (acting as another client)
and controls its clients through \gls{osc} as well.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-external-client-server-separate-output}
\end{figure}
\cleardoublepage
\paragraph{Clients only}
\label{para:clients_only}
Using the new \gls{osc} interface, it is also possible to have
client-only setups, in which an \gls{osc} capable application mimics
a \gls{ssr} server. This way a set of \textit{n} clients can
collectively (see
Figure~\ref{fig:ssr-external-clients-only-shared-output}) or
separately (see
Figure~\ref{fig:ssr-external-clients-only-separate-output}) render
audio, without the specific need of a \gls{ssr} server instance
controlling them. The clients send their update information back to
the controlling application.\\
Much of the functionality implemented in the server-side of the
\gls{osc} interface however has to be reapplied to the controlling
software and its behavior, when dealing with \gls{ssr} clients.
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-external-clients-only-shared-output.pdf}
\caption{A diagram displaying a \gls{ssr} client cluster setup, in
which a set of clients render audio collectively (e.g.\ medium or
large-scale \gls{wfs} setup). An \gls{osc} capable application
acts as a \gls{ssr} server instance and controls the clients.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-external-clients-only-shared-output}
\end{figure}
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-external-clients-only-separate-output.pdf}
\caption{A diagram displaying a \gls{ssr} client cluster setup, in
which a set of clients render audio separately (e.g.\ multiple
\gls{bs} renderers). An \gls{osc} capable application acts as a
\gls{ssr} server instance and controls the clients.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-external-clients-only-separate-output}
\end{figure}
\cleardoublepage
\subsubsection{Message levels}
\label{subsubsec:message_levels}
To be able to distinguish between types of
clients and servers, several message levels were implemented for the
\gls{osc} interface conceived in the course of this work.\\
The \mintinline{c++}{enumeration class MessageLevel}
\pdfcomment[color=red,icon=Note]{Don't allow static\_casts above
MessageLevel::GUI\_SERVER} (see Listing~\ref{lst:ssr_global.h}) defines
the four types \mintinline{c++}{CLIENT}, \mintinline{c++}{GUI_CLIENT},
\mintinline{c++}{SERVER}, \mintinline{c++}{GUI_SERVER}, which are
represented as non-negative integers (in ascending order), starting
from 0.\\
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=54, lastline=60,
fontsize=\footnotesize]{c++}{../../ssr/src/ssr_global.h}
\end{mdframed}
\caption{src/ssr\_global.h: \mintinline{c++}{enum class
MessageLevel}}
\label{lst:ssr_global.h}
\end{listing}\\
\noindent\gls{ssr} client instances subscribe to (\gls{ssr}) server instances
with the \mintinline{c++}{MessageLevel} \mintinline{c++}{CLIENT} by
default. Server instances get the \mintinline{c++}{MessageLevel}
\mintinline{c++}{SERVER} assigned to by each client on subscribing to
it.\\
In the \gls{osc} interface it is implemented as follows: A (recycable
and reconfigurable) list of clients is held by a server instance, which
enables for the \mintinline{c++}{MessageLevel} to change for each
client. Every client instance holds a (reconfigurable) server
representation, that enables for the \mintinline{c++}{MessageLevel} to
change for each client towards its server.\\
Several messages, such as information related to \gls{cpu} load or
master signal level are not useful for a rendering client (additionally
they are issued in very short intervals, which can lead to performance
issues), which is why they are only sent to clients with a
\mintinline{c++}{MessageLevel} \mintinline{c++}{GUI_CLIENT} or servers
with a \mintinline{c++}{MessageLevel} \mintinline{c++}{GUI_SERVER}.\\
Lightweight \gls{osc} capable applications used to control a \gls{ssr}
server instance are clients to said server instance. An elevated
\mintinline{c++}{MessageLevel} of \mintinline{c++}{SERVER} (instead of
\mintinline{c++}{CLIENT}) enables them to send messages to the server
and have them evaluated.\\
Analogous to a server instance holding a \mintinline{c++}{MessageLevel}
of \mintinline{c++}{GUI_SERVER} towards its clients, a client instance
can hold the same \mintinline{c++}{MessageLevel} towards a server
instance to receive the above mentioned performance heavy \gls{osc}
messages.
How the setting up of message levels is achieved, is further elaborated
upon in the following section.
\subsubsection{Message interface}
\label{subsubsec:message_interface}
\gls{osc} offers the possibility of a hierarchical path tree, that can
be used to group messages by type (i.e.\ context). In conjunction with
messages only understood by client or server (or a context dependant
meaning), most of the messages understood by the
\nameref{subsec:ip-interface} are implemented. Additional features,
related to server-client and client-only functionality were integrated
as well.\\
Generally it can be distinguished between \textit{direct} messages -
sent from a server (or an application mimicking one) to a client or a
server to trigger processing (see
Table~\ref{tab:ssr-osc-processing-tracker-transport}), reference (see
Table~\ref{tab:ssr-osc-reference}), scene (see
Table~\ref{tab:ssr-osc-scene}), source (see
Table~\ref{tab:ssr-osc-source}), tracker (see
Table~\ref{tab:ssr-osc-processing-tracker-transport}) or transport (see
Table~\ref{tab:ssr-osc-processing-tracker-transport}) related
operations in the \gls{ssr} - and \textit{update} messages (see
Table~\ref{tab:ssr-osc-update}) - sent from a client to a server upon
successful processing an operation related to a \textit{direct}
message.\\
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{2cm} | p{1cm} | p{3.5cm} | p{3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example}\\
\hline
\texttt{/message\_level} & i & Set message level of sender &
\texttt{[/message\_level, 1]} \\
\texttt{/message\_level} & ssi & Set message level of a specific
client & \texttt{[/message\_level, “127.0.0.1”,
“50002”, 1]} \\
\texttt{/subscribe} & F & Unsubscribe sender & \texttt{[/subscribe,
false]} \\
\texttt{/subscribe} & Fss & Unsubscribe specific client &
\texttt{[/subscribe, false, “127.0.0.1”, “50002”]}\\
\texttt{/subscribe} & T & Subscribe sender & \texttt{[/subscribe,
true]} \\
\texttt{/subscribe} & Ti & Subscribe sender with specific message
level & \texttt{[/subscribe, true, 1]} \\
\texttt{/subscribe} & Tssi & Subscribe specific client with
specific message level & \texttt{[/subscribe, true, “127.0.0.1”,
“50002”, 1]} \\
\end{tabular}
\caption{\gls{osc} messages relevant for subscribing and setting of
message levels for clients.\\
}
\caption*{Understood by server.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-subscribe}
\end{table}
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{2cm} | p{1cm} | p{3.5cm} | p{3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example}\\
\hline
\texttt{/message\_level} & i & Set message level of sender (the
server) & \texttt{[/message\_level, 1]} \\
\texttt{/poll} & & Poll client (continously sent), triggering
subscribe (see Table~\ref{tab:ssr-osc-subscribe}) &
\texttt{[/poll]} \\
\end{tabular}
\caption{\gls{osc} messages relevant for polling and setting of
message levels for servers subscribed to.\\
}
\caption*{Understood by client.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-client-poll-message-level}
\end{table}
A special set of \textit{direct} message are the \textit{subscribe} and
\textit{message level} (see Table~\ref{tab:ssr-osc-subscribe}) and
\textit{poll} and \textit{message level} (see
Table~\ref{tab:ssr-osc-client-poll-message-level}) messages. The former
- understood only by \gls{ssr} server instances - enable clients to
subscribe (with a certain message level) or subscribe other clients
(with a predefined message level) and set their own message level or
that of another client. The latter set - only understood by clients -
enables servers (or applications mimicking one) to poll yet
unsubscribed clients to have them subscribe and subscribed clients to
reply with an alive message. Similar to the \textit{message level}
message understood by server instances, the one understood by clients
sets the message level (of the server representation in the client).\\
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{3cm} | p{1.2cm} | p{3.5cm} | p{3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example}\\
\hline
\texttt{/processing/state} & F & Unset processing state &
\texttt{[/processing/state, false]} \\
\texttt{/processing/state} & T & Set processing state &
\texttt{[/processing/state, true]} \\
\texttt{/tracker/reset} & & Reset tracker &
\texttt{[/tracker/reset]} \\
\texttt{/transport/rewind} & & Rewind the \gls{jack} transport &
\texttt{[/transport/rewind]} \\
\texttt{/transport/seek} & s & Seek to time code in
\gls{jack} transport & \texttt{[/transport/seek, “42:00:00”]} \\
\texttt{/transport/state} & F & Unset \gls{jack} transport
state & \texttt{[/transport/state, false]} \\
\texttt{/transport/state} & T & Set \gls{jack} transport
state & \texttt{[/transport/state, true]} \\
\end{tabular}
\caption{\gls{osc} messages relevant for processing, tracker and
(\gls{jack}) transport related settings.\\
}
\caption*{Understood by server and client.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-processing-tracker-transport}
\end{table}
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{4.3cm} | p{1cm} | p{2.5cm} | p{4.4cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example}\\
\hline
\texttt{/reference/orientation} & f & Set azimuth of reference
point & \texttt{[/reference/orientation, -90.0]} \\
\texttt{/reference/position} & ff & Set position of reference &
\texttt{[/reference/position, 1.5, 2.0]} \\
\texttt{/reference\_offset/orientation} & f & Set azimuth of
reference offset position &
\texttt{[/reference\_offset/orientation, -90.0]} \\
\texttt{/reference\_offset/position} & ff & Set position of
reference offset & \texttt{[/reference\_offset/position, 1.5,
2.0]}\\
\end{tabular}
\caption{\gls{osc} messages relevant for reference management.\\
}
\caption*{Understood by server and client.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-reference}
\end{table}
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{4.5cm} | p{0.9cm} | p{2.5cm} | p{4.3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example} \\
\hline
\texttt{/scene/amplitude\_reference
\_distance} & f & Set amplitude
reference distance. &
\texttt{[/scene/amplitude\_reference
\_distance, 6.0]}\\
\texttt{/scene/auto\_rotate\_sources} & F & Disable automatic
rotation of sources. & \texttt{[/scene/auto\_rotate\_sources,
false]}\\
\texttt{/scene/auto\_rotate\_sources} & T & Enable automatic
rotation of sources. & \texttt{[/scene/auto\_rotate\_sources,
true]}\\
\texttt{/scene/clear} & & Delete all sources &
\texttt{[/scene/clear]}\\
\texttt{/scene/decay\_exponent} & f & Set amplitude decay exponent
in virtual space ($1/r^{exp}$). & \texttt{[/scene/decay\_exponent,
2.0]}\\
\texttt{/scene/load} & s & Load scene from \gls{asdf} file. &
\texttt{[/scene/load, “example.asd”]}\\
\texttt{/scene/master\_signal\_level} & f & Set the renderers
signal level. & \texttt{[/scene/master\_signal\_level, -20]}\\
\texttt{/scene/save} & s & Save scene to \gls{asdf} file. &
\texttt{[/scene/save, “example.asd”]}\\
\texttt{/scene/volume} & f & Set scene master volume. &
\texttt{[/scene/volume, 0.23]}\\
\end{tabular}
\caption{\gls{osc} messages relevant for scene management.\\
}
\caption*{Understood by server and client.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-scene}
\end{table}
When starting a \gls{ssr} server instance
(see~\ref{para:server-instance}), it responds to the messages shown in
Table~\ref{tab:ssr-osc-subscribe}
,~\ref{tab:ssr-osc-scene}
,~\ref{tab:ssr-osc-source}
,~\ref{tab:ssr-osc-processing-tracker-transport}
,~\ref{tab:ssr-osc-reference} and~\ref{tab:ssr-osc-update}.
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{3.5cm} | p{1.5cm} | p{2.5cm} | p{4.3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} &
\textbf{Example} \\
\hline
\texttt{/source/delete} & i & Delete source with given id &
\texttt{[/source/delete, 1]}\\
\texttt{/source/file\_channel} & ii & Set a source's file channel &
\texttt{[/source/file\_channel, 1, 2]}\\
\texttt{/source/file\_name\_ or\_port\_number} & is & Set a source's
file name or port number &
\texttt{[/source/file\_name\_ or\_port\_number, 1, “1”]}\\
\texttt{/source/port\_name } & is & Set a source's \gls{jack} input
port name & \texttt{[/source/port\_name, 1, “system:capture\_2”]}\\
\texttt{/source/gain} & if & Set a source's gain &
\texttt{[/source/gain, 1, 0.2]}\\
\texttt{/source/model} & is & Set a source's model &
\texttt{[/source/model, 1, “point”]}\\
\texttt{/source/mute} & iF & Unmute a source &
\texttt{[/source/mute, 1, false]}\\
\texttt{/source/mute} & iT & Mute a source &
\texttt{[/source/mute, 1, true]}\\
\texttt{/source/name} & is & Set a source's name &
\texttt{[/source/name, 1, “Daisy”]}\\
\texttt{/source/new} & i & Create a new source stub using id &
\texttt{[/source/new, 1]}\\
\texttt{/source/new} & sssffffTFF & Create a new source
(auto-generated id) with name, model, port number, X-coordinate,
Y-coordinate, orientation, gain, movability, orientation movability
and mute status & \texttt{[/source/new, “Daisy”, “point”, “1”, 1.0,
2.5, 90.0, 0.2, true, false, false]} \\
\texttt{/source/new} & sssffffisTFF & Create a new source
(auto-generated id) with name, model, port number, X-coordinate,
Y-coordinate, orientation, gain, file channel, properties file,
movability, orientation movability and mute status &
\texttt{[/source/new, “Daisy”, “point”, “1”, 1.0, 2.5, 90.0, 0.2,
2, “properties.xml”, true, false, false]} \\
\texttt{/source/orientation} & if & Set a source's orientation &
\texttt{[/source/orientation, 1, -90.0]}\\
\texttt{/source/position} & iff & Set a source's position &
\texttt{[/source/position, 1, 1.5, 2.0]}\\
\texttt{/source/position\_fixed} & iF & Set a source movable &
\texttt{[/source/position\_fixed, 1, false]}\\
\texttt{/source/position\_fixed} & iT & Set a source immovable &
\texttt{[/source/position\_fixed, 1, true]}\\
\texttt{/source/properties\_file} & is & Set a source's properties
file & \texttt{[/source/properties\_file, 1,
“source-properties.xml”]}\\
\end{tabular}
\caption{\gls{osc} messages relevant for source management.\\
}
\caption*{Understood by server and client.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-source}
\end{table}
\noindent A client instance (see~\ref{para:client-instance}) will only
respond to the \textit{direct} messages listed in
Table~\ref{tab:ssr-osc-client-poll-message-level}
,~\ref{tab:ssr-osc-scene} ,~\ref{tab:ssr-osc-source}
,~\ref{tab:ssr-osc-processing-tracker-transport}
and~\ref{tab:ssr-osc-reference}, but is able to send \textit{update}
messages.
\begin{table}[!htb]
\renewcommand{\arraystretch}{1.2}
\scriptsize
\centering
\rowcolors{2}{table-background-one}{table-background-two}
\begin{tabular}{ p{6.5cm} | p{0.9cm} | p{4.3cm} }
\textbf{Path} & \textbf{Types} & \textbf{Description} \\
\hline
\texttt{/update/cpu\_load} & f & \gls{cpu} load changes.\\
\texttt{/update/processing/state} & T & Processing state is set.\\
\texttt{/update/processing/state} & F & Processing state is
unset.\\
\texttt{/update/reference/orientation} & f & Reference orientation
changes.\\
\texttt{/update/reference/position} & ff & Reference position
changes.\\
\texttt{/update/reference\_offset/orientation} & f & Reference
offset orientation changes.\\
\texttt{/update/reference\_offset/position} & ff & Reference offset
position changes.\\
\texttt{/update/scene/amplitude\_reference\_distance} & f &
Amplitude reference distance changes.\\
\texttt{/update/scene/auto\_rotate\_sources} & T & Auto rotation of
sources is set.\\
\texttt{/update/scene/auto\_rotate\_sources} & F & Auto rotation of
sources is unset.\\
\texttt{/update/scene/decay\_exponent} & f & The scene's decay
exponent has changed.\\
\texttt{/update/scene/master\_signal\_level} & f & Master signal
level has changed.\\
\texttt{/update/scene/sample\_rate} & i & Sample rate of the scene
changed.\\
\texttt{/update/scene/volume} & f & Volume of the scene has
changed.\\
\texttt{/update/source/delete} & i & A source with given id was
deleted. \\
\texttt{/update/source/file\_channel} & ii & A source's file
channel was set.\\
\texttt{/update/source/file\_name\_or\_port\_number} & is & A
source's file name or port number was set.\\
\texttt{/update/source/gain} & if & A source's gain was set.\\
\texttt{/update/source/length} & ii & A source's length was set.\\
\texttt{/update/source/level} & if & A source's output level has
changed.\\
\texttt{/update/source/model} & is & A source's model was set.\\
\texttt{/update/source/mute} & iF & A source was unmuted.\\
\texttt{/update/source/mute} & iT & A source was muted.\\
\texttt{/update/source/name} & is & A source's name was set.\\
\texttt{/update/source/orientation} & if & A source's orientation
was set. \\
\texttt{/update/source/new} & i & A new source with given id was
created. \\
\texttt{/update/source/port\_name} & is & A source's \gls{jack}
port\_name was set. \\
\texttt{/update/source/position} & iff & A source's position was
set. \\
\texttt{/update/source/position\_fixed} & iF & A source was set to
be movable. \\
\texttt{/update/source/position\_fixed} & iT & A source was set to
be immovable. \\
\texttt{/update/source/properties\_file} & is & A source's
properties\_file was set.\\
\texttt{/update/transport/seek} & s & \gls{jack} transport seeked
to a timecode position.\\
\texttt{/update/transport/state} & F & \gls{jack} transport was
stopped.\\
\texttt{/update/transport/state} & T & \gls{jack} transport was
started.\\
\end{tabular}
\caption{\gls{osc} messages for updating information on \gls{cpu} load,
processing, reference, scene, source, and transport of clients on a
server.\\
No examples are given, as they are mostly analogous to the ones in
Table~\ref{tab:ssr-osc-processing-tracker-transport}
,~\ref{tab:ssr-osc-scene} and~\ref{tab:ssr-osc-source}.
}
\caption*{Understood by server.\\
Data types and their acronyms are listed in
Table~\ref{tab:ssr-osc-data-type-acronyms}.
}
\label{tab:ssr-osc-update}
\end{table}
\cleardoublepage
\subsubsection{Workflow Examples}
\label{subsubsec:workflow_examples}
Using any \gls{osc} capable programming language or application enables
for communication with the \gls{ssr}. The following examples illustrate
simple workflows using \gls{sclang} and should therefore be \gls{os}
agnostic.\\
\paragraph{Controlling a server}
\label{para:controlling_a_server}
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=3, lastline=29,
fontsize=\footnotesize]{supercollider}{../../ssr/supercollider/workflows.scd}
\end{mdframed}
\caption{supercollider/workflows.scd: \gls{sclang} as client
controlling a \gls{ssr} server instance}
\label{lst:ssr-workflow-sclang-controls-server}
\end{listing}\\
As shown in Listing~\ref{lst:ssr-workflow-sclang-controls-server}, it
is necessary to subscribe to the server instance with a
\mintinline{c++}{MessageLevel} of \mintinline{c++}{SERVER} or higher.\\
After doing so, also all \textit{direct} \gls{osc} messages (i.e.
Table~\ref{tab:ssr-osc-source},~\ref{tab:ssr-osc-scene}
,~\ref{tab:ssr-osc-reference},~\ref{tab:ssr-osc-subscribe}) are
evaluated when sent to the \gls{ssr}.\\
The server instance will relay valid messages to all of its active
clients.
\paragraph{Server mimicry}
\label{para:server_mimicry}
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=31, lastline=61,
fontsize=\footnotesize]{supercollider}{../../ssr/supercollider/workflows.scd}
\end{mdframed}
\caption{supercollider/workflows.scd: \gls{sclang} mimics server,
controlling a \gls{ssr} client instance}
\label{lst:ssr-workflow-sclang-is-server-controls-client}
\end{listing}\\
When mimicking a \gls{ssr} server instance in a client-only setup
(e.g.\ Figure~\ref{fig:ssr-external-clients-only-shared-output} or
Figure~\ref{fig:ssr-external-clients-only-separate-output}), it is
necessary to send a poll message to the client instance to make it
subscribe (which sets the server's address and port up internally).\\
Afterwards - similar to the example in the paragraph
\nameref{para:clients_only} - all \textit{direct} \gls{osc} messages
are accepted by the client instance, when coming from the server
address and port.\\
An interesting concept here is to (temporarily) set a different
\mintinline{c++}{MessageLevel} for the application acting as a server
(e.g.\ to \mintinline{c++}{GUI_SERVER}), to receive \gls{gui}
relevant messages, as explained in
\nameref{subsubsec:message_interface}.\\
\subsection{Automated tests}
\label{subsec:automated_tests}
The \gls{ssr} was developed without the help of a test framework, which
is responsible to test its components, after they have been changed.
This means, that internal (e.g.\ the \gls{pubsub} interface), or external
(e.g.\ the \gls{ip} or \gls{osc} interface) functionality might or might
not work as expected. To test the \gls{osc} interface's logical coherency
and robustness automatically, a set of tests were written in
\gls{sclang}.\\
The tests are divided into those probing robustness of the \gls{osc}
interface and others probing its functionality. The robustness tests
further divide into server and client specific tests, where authorized
and unauthorized access is tried. The functionality tests are grouped by
tests for general operability, i.e.\ testing certain features or
workflows once and long-running tests, where features are tried
repeatedly.\\
\subsubsection{Robustness}
\label{subsubsec:robustness}
Listing~\ref{lst:ssr-tests-sclang-unsubscribed-controls-server}
and~\ref{lst:ssr-tests-sclang-subscribed-controls-server} describe
server-side tests for robustness. While the first will not lead to any
processed action by the server, the latter will. This is explained by
\gls{sclang} not being a subscribed client with a
\mintinline{c++}{MessageLevel} of \mintinline{c++}{SERVER} or higher in
the first case. In the second test however \gls{sclang} subscribes to
the \gls{ssr} server instance, which is why the \gls{osc} messages are
evaluated in this case.\\
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=145, lastline=158,
fontsize=\footnotesize]{supercollider}
{../../ssr/supercollider/tests.scd}
\end{mdframed}
\caption{supercollider/tests.scd: \gls{sclang} (unsubscribed) tries
to control a \gls{ssr} server}
\label{lst:ssr-tests-sclang-unsubscribed-controls-server}
\end{listing}\\
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=160, lastline=183,
fontsize=\footnotesize]{supercollider}
{../../ssr/supercollider/tests.scd}
\end{mdframed}
\caption{supercollider/tests.scd: \gls{sclang} (subscribed) tries to
control a \gls{ssr} server}
\label{lst:ssr-tests-sclang-subscribed-controls-server}
\end{listing}\\
The tests described in
Listing~\ref{lst:ssr-tests-sclang-controls-client-unpolled}
and~\ref{lst:ssr-tests-sclang-controls-client-polled} are client-side
tests for robustness, that work in a similar fashion to the
aforementioned server-side tests. While in the first case, the sent
\gls{osc} messages are not evaluated, because \gls{sclang}, mimicking a
server instance (see~\ref{para:server_mimicry}), did not poll the
\gls{ssr} client instance up front, in the second case the messages are
evaluated, because it did poll the client first.
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=185, lastline=197,
fontsize=\footnotesize]{supercollider}
{../../ssr/supercollider/tests.scd}
\end{mdframed}
\caption{supercollider/tests.scd: \gls{sclang} tries to control a
\gls{ssr} client (without polling it)}
\label{lst:ssr-tests-sclang-controls-client-unpolled}
\end{listing}\\
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=199, lastline=214,
fontsize=\footnotesize]{supercollider}
{../../ssr/supercollider/tests.scd}
\end{mdframed}
\caption{supercollider/tests.scd: \gls{sclang} tries to control a
\gls{ssr} client (with previously polling it)}
\label{lst:ssr-tests-sclang-controls-client-polled}
\end{listing}\\
In all tests for robustness, the attempt is made to break the
implementation of the \nameref{subsubsec:message_interface}. This is
achieved by purposely using ranges of data types for messages, that are
not allowed, or not defined in the \gls{ssr}'s internal
implementation.\\
Two examples for weak spot exploitations are the use of negative
integers for \glspl{id} in source related messages (only non-zero,
non-negative \glspl{id} are allowed internally) or supplying an empty
string as hostname or port number for subscription messages.\\
The first example will lead to undefined behavior, if the range is not
checked in the implementation, as a \textit{static\_cast} is used
internally to cast the value of the message data type (\textit{unsigned
int}) to the one expected by the \gls{ssr}'s Controller implementation
(\textit{signed int}) and the outcome of said operation is
implementation dependant (depending on the \gls{os} in use).\\
The second example, if not checked for empty string, would lead to the
\gls{osc} interface trying to create a possibly defective address and
send poll messages out to it.\\
While only some of the above mentioned scenarios could lead to a crash
of the program (under certain circumstances), unhandled all of them
waste ressources, which is undesired.
To circumvent possibly harmful input using the \gls{osc} interface, a
set of sanity checks were implemented, that only allow for a received
message to be processed, if all of its components fit the requirements.
\subsubsection{Functionality and operability}
\label{subsubsec:functionality_and_operability}
\begin{listing}[!htb]
\begin{mdframed}
\inputminted[numbers=left, firstline=216, lastline=225,
fontsize=\footnotesize]{supercollider}
{../../ssr/supercollider/tests.scd}
\end{mdframed}
\caption{supercollider/tests.scd: \gls{sclang} controls a \gls{ssr}
client (with previously polling it), creating several sources and
moving them}
\label{lst:ssr-tests-sclang-sources}
\end{listing}\\
The test described in Listing~\ref{lst:ssr-tests-sclang-sources} is a
test for functionality, which also serves as a long-running stress test
for the \gls{ssr}. It creates 20 sources, that are then moved around
randomly, every 100ms, for 100 seconds, which on a Lenovo W540, with an
Intel i7-4700MQ and 16Gb RAM created less than 50\% of \gls{cpu}
load.\\
Based on the above mentioned tests, the basic functionality of the
\gls{osc} interface can be guaranteed and depending on the host's
hardware also a maximum degree of capacity utilization can be
estimated, when observing the \gls{ssr}'s workload towards the system,
while using the long-running tests.\\
It has to be mentioned, that a higher load can be observed, when using
higher levels of verbosity (especially above \textbf{-vv}). This is
explained by the fact, that the \gls{ssr} will print out every
\gls{osc} message received and sent above the aforementioned verbosity
level.
\cleardoublepage
\section{Discussion}
\label{sec:discussion}
\cleardoublepage
\subsection{Implementing a NullRenderer}
\label{subsec:implementing_a_nullrenderer}
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-client-server-clients-only-shared-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in which
only the clients render audio collectively (e.g.\ medium or
large-scale \gls{wfs}). The server instance is not controlled via
\gls{osc}, but controls its clients through it. Additionally its
rendering engine does not have any outputs.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-client-server-clients-only-shared-output}
\end{figure}
\begin{figure}[!htb]
\centering
\includegraphics[scale=1.0, trim = 20mm 204mm 10mm 10mm, clip]
{ssr-client-server-clients-only-separate-output.pdf}
\caption{A diagram displaying a \gls{ssr} client/server setup, in
which only the clients render audio to separate outputs (e.g.\
multiple \glspl{bs} renderers). The server instance is not controlled
via \gls{osc}, but controls its clients through it. Additionally its
rendering engine does not have any outputs.\\
{\color{osc-in}\textbf{--}} \gls{osc} input
{\color{osc-out}\textbf{--}} \gls{osc} output
{\color{audio-in}\textbf{--}} Audio input
{\color{audio-out}\textbf{--}} Audio output
}
\label{fig:ssr-client-server-clients-only-separate-output}
\end{figure}
\cleardoublepage
\subsection{Implementing AlienLoudspeaker}
\label{subsec:implementing_alienloudspeaker}
\subsection{Implementing automatic client discarding}
\label{subsec:implementing_automatic_client_discarding}
\subsection{Status messages}
\label{subsec:status_messages}
\subsection{Assigning inputs on the fly}
\label{subsec:assigning_inputs_on_the_fly}
\subsection{Interpolation of moving sources}
\label{subsec:interpolation_of_moving_sources}
\pagestyle{empty}
\cleardoublepage
\appendix
\cleardoublepage
\bibliographystyle{plainnat}
\bibliography{../bib/ssr-networking}
\end{document}
|