linuxaudio
/
new-session-manager
mirror of https://github.com/linuxaudio/new-session-manager
1
0
Fork 0
Code Issues 0 Releases 17 Wiki Activity
Assists music production by grouping standalone programs into sessions. Community version of "Non Session Manager".
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1956 Commits
1 Branch
15MB
Tree: 3b311e7ed0
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '3b311e7ed0'
${ noResults }
new-session-manager/docs/api/index.html

1459 lines
70KB
Raw Blame History 

  1. <!DOCTYPE html>

  2. <html lang="en">

  3. <head>

  4. <meta charset="UTF-8">

  5. <meta http-equiv="X-UA-Compatible" content="IE=edge">

  6. <meta name="viewport" content="width=device-width, initial-scale=1.0">

  7. <meta name="generator" content="Asciidoctor 2.0.10">

  8. <meta name="author" content="Jonathan Moore Liles">

  9. <title>Non Session Manager - API</title>

  10. <style>

  11. /* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */

  12. /* Uncomment @import statement to use as custom stylesheet */

  13. /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/

  14. article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}

  15. audio,video{display:inline-block}

  16. audio:not([controls]){display:none;height:0}

  17. html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}

  18. a{background:none}

  19. a:focus{outline:thin dotted}

  20. a:active,a:hover{outline:0}

  21. h1{font-size:2em;margin:.67em 0}

  22. abbr[title]{border-bottom:1px dotted}

  23. b,strong{font-weight:bold}

  24. dfn{font-style:italic}

  25. hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}

  26. mark{background:#ff0;color:#000}

  27. code,kbd,pre,samp{font-family:monospace;font-size:1em}

  28. pre{white-space:pre-wrap}

  29. q{quotes:"\201C" "\201D" "\2018" "\2019"}

  30. small{font-size:80%}

  31. sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}

  32. sup{top:-.5em}

  33. sub{bottom:-.25em}

  34. img{border:0}

  35. svg:not(:root){overflow:hidden}

  36. figure{margin:0}

  37. fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}

  38. legend{border:0;padding:0}

  39. button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}

  40. button,input{line-height:normal}

  41. button,select{text-transform:none}

  42. button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}

  43. button[disabled],html input[disabled]{cursor:default}

  44. input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}

  45. button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}

  46. textarea{overflow:auto;vertical-align:top}

  47. table{border-collapse:collapse;border-spacing:0}

  48. *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}

  49. html,body{font-size:100%}

  50. body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}

  51. a:hover{cursor:pointer}

  52. img,object,embed{max-width:100%;height:auto}

  53. object,embed{height:100%}

  54. img{-ms-interpolation-mode:bicubic}

  55. .left{float:left!important}

  56. .right{float:right!important}

  57. .text-left{text-align:left!important}

  58. .text-right{text-align:right!important}

  59. .text-center{text-align:center!important}

  60. .text-justify{text-align:justify!important}

  61. .hide{display:none}

  62. img,object,svg{display:inline-block;vertical-align:middle}

  63. textarea{height:auto;min-height:50px}

  64. select{width:100%}

  65. .center{margin-left:auto;margin-right:auto}

  66. .stretch{width:100%}

  67. .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}

  68. div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}

  69. a{color:#2156a5;text-decoration:underline;line-height:inherit}

  70. a:hover,a:focus{color:#1d4b8f}

  71. a img{border:0}

  72. p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}

  73. p aside{font-size:.875em;line-height:1.35;font-style:italic}

  74. h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}

  75. h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}

  76. h1{font-size:2.125em}

  77. h2{font-size:1.6875em}

  78. h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}

  79. h4,h5{font-size:1.125em}

  80. h6{font-size:1em}

  81. hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}

  82. em,i{font-style:italic;line-height:inherit}

  83. strong,b{font-weight:bold;line-height:inherit}

  84. small{font-size:60%;line-height:inherit}

  85. code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}

  86. ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}

  87. ul,ol{margin-left:1.5em}

  88. ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}

  89. ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}

  90. ul.square{list-style-type:square}

  91. ul.circle{list-style-type:circle}

  92. ul.disc{list-style-type:disc}

  93. ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}

  94. dl dt{margin-bottom:.3125em;font-weight:bold}

  95. dl dd{margin-bottom:1.25em}

  96. abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}

  97. abbr{text-transform:none}

  98. blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}

  99. blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}

  100. blockquote cite::before{content:"\2014 \0020"}

  101. blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}

  102. blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}

  103. @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}

  104. h1{font-size:2.75em}

  105. h2{font-size:2.3125em}

  106. h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}

  107. h4{font-size:1.4375em}}

  108. table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}

  109. table thead,table tfoot{background:#f7f8f7}

  110. table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}

  111. table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}

  112. table tr.even,table tr.alt{background:#f8f8f7}

  113. table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}

  114. h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}

  115. h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}

  116. .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}

  117. .clearfix::after,.float-group::after{clear:both}

  118. :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}

  119. :not(pre)>code.nobreak{word-wrap:normal}

  120. :not(pre)>code.nowrap{white-space:nowrap}

  121. pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}

  122. pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}

  123. pre>code{display:block}

  124. pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}

  125. em em{font-style:normal}

  126. strong strong{font-weight:400}

  127. .keyseq{color:rgba(51,51,51,.8)}

  128. kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}

  129. .keyseq kbd:first-child{margin-left:0}

  130. .keyseq kbd:last-child{margin-right:0}

  131. .menuseq,.menuref{color:#000}

  132. .menuseq b:not(.caret),.menuref{font-weight:inherit}

  133. .menuseq{word-spacing:-.02em}

  134. .menuseq b.caret{font-size:1.25em;line-height:.8}

  135. .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}

  136. b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}

  137. b.button::before{content:"[";padding:0 3px 0 2px}

  138. b.button::after{content:"]";padding:0 2px 0 3px}

  139. p a>code:hover{color:rgba(0,0,0,.9)}

  140. #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}

  141. #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}

  142. #header::after,#content::after,#footnotes::after,#footer::after{clear:both}

  143. #content{margin-top:1.25em}

  144. #content::before{content:none}

  145. #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}

  146. #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}

  147. #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}

  148. #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}

  149. #header .details span:first-child{margin-left:-.125em}

  150. #header .details span.email a{color:rgba(0,0,0,.85)}

  151. #header .details br{display:none}

  152. #header .details br+span::before{content:"\00a0\2013\00a0"}

  153. #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}

  154. #header .details br+span#revremark::before{content:"\00a0|\00a0"}

  155. #header #revnumber{text-transform:capitalize}

  156. #header #revnumber::after{content:"\00a0"}

  157. #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}

  158. #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}

  159. #toc>ul{margin-left:.125em}

  160. #toc ul.sectlevel0>li>a{font-style:italic}

  161. #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}

  162. #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}

  163. #toc li{line-height:1.3334;margin-top:.3334em}

  164. #toc a{text-decoration:none}

  165. #toc a:active{text-decoration:underline}

  166. #toctitle{color:#7a2518;font-size:1.2em}

  167. @media screen and (min-width:768px){#toctitle{font-size:1.375em}

  168. body.toc2{padding-left:15em;padding-right:0}

  169. #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}

  170. #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}

  171. #toc.toc2>ul{font-size:.9em;margin-bottom:0}

  172. #toc.toc2 ul ul{margin-left:0;padding-left:1em}

  173. #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}

  174. body.toc2.toc-right{padding-left:0;padding-right:15em}

  175. body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}

  176. @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}

  177. #toc.toc2{width:20em}

  178. #toc.toc2 #toctitle{font-size:1.375em}

  179. #toc.toc2>ul{font-size:.95em}

  180. #toc.toc2 ul ul{padding-left:1.25em}

  181. body.toc2.toc-right{padding-left:0;padding-right:20em}}

  182. #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}

  183. #content #toc>:first-child{margin-top:0}

  184. #content #toc>:last-child{margin-bottom:0}

  185. #footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}

  186. #footer-text{color:rgba(255,255,255,.8);line-height:1.44}

  187. #content{margin-bottom:.625em}

  188. .sect1{padding-bottom:.625em}

  189. @media screen and (min-width:768px){#content{margin-bottom:1.25em}

  190. .sect1{padding-bottom:1.25em}}

  191. .sect1:last-child{padding-bottom:0}

  192. .sect1+.sect1{border-top:1px solid #e7e7e9}

  193. #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}

  194. #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}

  195. #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}

  196. #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}

  197. #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}

  198. details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}

  199. details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}

  200. .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}

  201. table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}

  202. .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}

  203. table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}

  204. .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}

  205. .admonitionblock>table td.icon{text-align:center;width:80px}

  206. .admonitionblock>table td.icon img{max-width:none}

  207. .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}

  208. .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}

  209. .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}

  210. .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}

  211. .exampleblock>.content>:first-child{margin-top:0}

  212. .exampleblock>.content>:last-child{margin-bottom:0}

  213. .sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}

  214. .sidebarblock>:first-child{margin-top:0}

  215. .sidebarblock>:last-child{margin-bottom:0}

  216. .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}

  217. .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}

  218. .literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}

  219. @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}

  220. @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}

  221. .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}

  222. .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}

  223. .listingblock>.content{position:relative}

  224. .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}

  225. .listingblock:hover code[data-lang]::before{display:block}

  226. .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}

  227. .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}

  228. .listingblock pre.highlightjs{padding:0}

  229. .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}

  230. .listingblock pre.prettyprint{border-width:0}

  231. .prettyprint{background:#f7f7f8}

  232. pre.prettyprint .linenums{line-height:1.45;margin-left:2em}

  233. pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}

  234. pre.prettyprint li code[data-lang]::before{opacity:1}

  235. pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}

  236. table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}

  237. table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}

  238. table.linenotable td.code{padding-left:.75em}

  239. table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}

  240. pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}

  241. pre.pygments .lineno::before{content:"";margin-right:-.125em}

  242. .quoteblock{margin:0 1em 1.25em 1.5em;display:table}

  243. .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}

  244. .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}

  245. .quoteblock blockquote{margin:0;padding:0;border:0}

  246. .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}

  247. .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}

  248. .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}

  249. .verseblock{margin:0 1em 1.25em}

  250. .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}

  251. .verseblock pre strong{font-weight:400}

  252. .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}

  253. .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}

  254. .quoteblock .attribution br,.verseblock .attribution br{display:none}

  255. .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}

  256. .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}

  257. .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}

  258. .quoteblock.abstract{margin:0 1em 1.25em;display:block}

  259. .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}

  260. .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}

  261. .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}

  262. .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}

  263. .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}

  264. table.tableblock{max-width:100%;border-collapse:separate}

  265. p.tableblock:last-child{margin-bottom:0}

  266. td.tableblock>.content>:last-child{margin-bottom:-1.25em}

  267. td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0}

  268. table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}

  269. table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}

  270. table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}

  271. table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}

  272. table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}

  273. table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}

  274. table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}

  275. table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}

  276. table.frame-all{border-width:1px}

  277. table.frame-sides{border-width:0 1px}

  278. table.frame-topbot,table.frame-ends{border-width:1px 0}

  279. table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}

  280. th.halign-left,td.halign-left{text-align:left}

  281. th.halign-right,td.halign-right{text-align:right}

  282. th.halign-center,td.halign-center{text-align:center}

  283. th.valign-top,td.valign-top{vertical-align:top}

  284. th.valign-bottom,td.valign-bottom{vertical-align:bottom}

  285. th.valign-middle,td.valign-middle{vertical-align:middle}

  286. table thead th,table tfoot th{font-weight:bold}

  287. tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}

  288. tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}

  289. p.tableblock>code:only-child{background:none;padding:0}

  290. p.tableblock{font-size:1em}

  291. ol{margin-left:1.75em}

  292. ul li ol{margin-left:1.5em}

  293. dl dd{margin-left:1.125em}

  294. dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}

  295. ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}

  296. ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}

  297. ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}

  298. ul.unstyled,ol.unstyled{margin-left:0}

  299. ul.checklist{margin-left:.625em}

  300. ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}

  301. ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}

  302. ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}

  303. ul.inline>li{margin-left:1.25em}

  304. .unstyled dl dt{font-weight:400;font-style:normal}

  305. ol.arabic{list-style-type:decimal}

  306. ol.decimal{list-style-type:decimal-leading-zero}

  307. ol.loweralpha{list-style-type:lower-alpha}

  308. ol.upperalpha{list-style-type:upper-alpha}

  309. ol.lowerroman{list-style-type:lower-roman}

  310. ol.upperroman{list-style-type:upper-roman}

  311. ol.lowergreek{list-style-type:lower-greek}

  312. .hdlist>table,.colist>table{border:0;background:none}

  313. .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}

  314. td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}

  315. td.hdlist1{font-weight:bold;padding-bottom:1.25em}

  316. .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}

  317. .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}

  318. .colist td:not([class]):first-child img{max-width:none}

  319. .colist td:not([class]):last-child{padding:.25em 0}

  320. .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}

  321. .imageblock.left{margin:.25em .625em 1.25em 0}

  322. .imageblock.right{margin:.25em 0 1.25em .625em}

  323. .imageblock>.title{margin-bottom:0}

  324. .imageblock.thumb,.imageblock.th{border-width:6px}

  325. .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}

  326. .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}

  327. .image.left{margin-right:.625em}

  328. .image.right{margin-left:.625em}

  329. a.image{text-decoration:none;display:inline-block}

  330. a.image object{pointer-events:none}

  331. sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}

  332. sup.footnote a,sup.footnoteref a{text-decoration:none}

  333. sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}

  334. #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}

  335. #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}

  336. #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}

  337. #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}

  338. #footnotes .footnote:last-of-type{margin-bottom:0}

  339. #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}

  340. .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}

  341. .gist .file-data>table td.line-data{width:99%}

  342. div.unbreakable{page-break-inside:avoid}

  343. .big{font-size:larger}

  344. .small{font-size:smaller}

  345. .underline{text-decoration:underline}

  346. .overline{text-decoration:overline}

  347. .line-through{text-decoration:line-through}

  348. .aqua{color:#00bfbf}

  349. .aqua-background{background:#00fafa}

  350. .black{color:#000}

  351. .black-background{background:#000}

  352. .blue{color:#0000bf}

  353. .blue-background{background:#0000fa}

  354. .fuchsia{color:#bf00bf}

  355. .fuchsia-background{background:#fa00fa}

  356. .gray{color:#606060}

  357. .gray-background{background:#7d7d7d}

  358. .green{color:#006000}

  359. .green-background{background:#007d00}

  360. .lime{color:#00bf00}

  361. .lime-background{background:#00fa00}

  362. .maroon{color:#600000}

  363. .maroon-background{background:#7d0000}

  364. .navy{color:#000060}

  365. .navy-background{background:#00007d}

  366. .olive{color:#606000}

  367. .olive-background{background:#7d7d00}

  368. .purple{color:#600060}

  369. .purple-background{background:#7d007d}

  370. .red{color:#bf0000}

  371. .red-background{background:#fa0000}

  372. .silver{color:#909090}

  373. .silver-background{background:#bcbcbc}

  374. .teal{color:#006060}

  375. .teal-background{background:#007d7d}

  376. .white{color:#bfbfbf}

  377. .white-background{background:#fafafa}

  378. .yellow{color:#bfbf00}

  379. .yellow-background{background:#fafa00}

  380. span.icon>.fa{cursor:default}

  381. a span.icon>.fa{cursor:inherit}

  382. .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}

  383. .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}

  384. .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}

  385. .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}

  386. .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}

  387. .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}

  388. .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}

  389. .conum[data-value] *{color:#fff!important}

  390. .conum[data-value]+b{display:none}

  391. .conum[data-value]::after{content:attr(data-value)}

  392. pre .conum[data-value]{position:relative;top:-.125em}

  393. b.conum *{color:inherit!important}

  394. .conum:not([data-value]):empty{display:none}

  395. dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}

  396. h1,h2,p,td.content,span.alt{letter-spacing:-.01em}

  397. p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}

  398. p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}

  399. p{margin-bottom:1.25rem}

  400. .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}

  401. .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}

  402. .print-only{display:none!important}

  403. @page{margin:1.25cm .75cm}

  404. @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}

  405. html{font-size:80%}

  406. a{color:inherit!important;text-decoration:underline!important}

  407. a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}

  408. a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}

  409. abbr[title]::after{content:" (" attr(title) ")"}

  410. pre,blockquote,tr,img,object,svg{page-break-inside:avoid}

  411. thead{display:table-header-group}

  412. svg{max-width:100%}

  413. p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}

  414. h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}

  415. #toc,.sidebarblock,.exampleblock>.content{background:none!important}

  416. #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}

  417. body.book #header{text-align:center}

  418. body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}

  419. body.book #header .details{border:0!important;display:block;padding:0!important}

  420. body.book #header .details span:first-child{margin-left:0!important}

  421. body.book #header .details br{display:block}

  422. body.book #header .details br+span::before{content:none!important}

  423. body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}

  424. body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}

  425. .listingblock code[data-lang]::before{display:block}

  426. #footer{padding:0 .9375em}

  427. .hide-on-print{display:none!important}

  428. .print-only{display:block!important}

  429. .hide-for-print{display:none!important}

  430. .show-for-print{display:inherit!important}}

  431. @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}

  432. .sect1{padding:0!important}

  433. .sect1+.sect1{border:0}

  434. #footer{background:none}

  435. #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}

  436. @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}

  437. </style>

  438. </head>

  439. <body class="article">

  440. <div id="header">

  441. <h1>Non Session Manager - API</h1>

  442. <div class="details">

  443. <span id="author" class="author">Jonathan Moore Liles</span><br>

  444. <span id="email" class="email">&lt;<a href="mailto:male@tuxfamily.org">male@tuxfamily.org</a>&gt;</span><br>

  445. <span id="revnumber">version 1.2</span>

  446. </div>

  447. <div id="toc" class="toc">

  448. <div id="toctitle">Table of Contents</div>

  449. <ul class="sectlevel1">

  450. <li><a href="#_client_behavior_under_session_management">1. Client Behavior Under Session Management</a>

  451. <ul class="sectlevel2">

  452. <li><a href="#_file_menu">1.1. File Menu</a>

  453. <ul class="sectlevel3">

  454. <li><a href="#_new">1.1.1. New</a></li>

  455. <li><a href="#_open">1.1.2. Open</a></li>

  456. <li><a href="#_save">1.1.3. Save</a></li>

  457. <li><a href="#_save_as">1.1.4. Save As</a></li>

  458. <li><a href="#_close_as_distinguished_from_quit_or_exit">1.1.5. Close (as distinguished from Quit or Exit)</a></li>

  459. <li><a href="#_quit_or_exit">1.1.6. Quit or Exit</a></li>

  460. </ul>

  461. </li>

  462. <li><a href="#_data_storage">1.2. Data Storage</a>

  463. <ul class="sectlevel3">

  464. <li><a href="#_internal_files">1.2.1. Internal Files</a></li>

  465. <li><a href="#_external_files">1.2.2. External Files</a></li>

  466. </ul>

  467. </li>

  468. </ul>

  469. </li>

  470. <li><a href="#_nsm_osc_protocol">2. NSM OSC Protocol</a>

  471. <ul class="sectlevel2">

  472. <li><a href="#_establishing_a_connection">2.1. Establishing a Connection</a>

  473. <ul class="sectlevel3">

  474. <li><a href="#_announce">2.1.1. Announce</a></li>

  475. <li><a href="#_response">2.1.2. Response</a></li>

  476. </ul>

  477. </li>

  478. <li><a href="#_server_to_client_control_messages">2.2. Server to Client Control Messages</a>

  479. <ul class="sectlevel3">

  480. <li><a href="#_quit">2.2.1. Quit</a></li>

  481. <li><a href="#_open_2">2.2.2. Open</a>

  482. <ul class="sectlevel4">

  483. <li><a href="#_response_2">2.2.2.1. Response</a></li>

  484. </ul>

  485. </li>

  486. <li><a href="#_save_2">2.2.3. Save</a>

  487. <ul class="sectlevel4">

  488. <li><a href="#_response_3">2.2.3.1. Response</a></li>

  489. </ul>

  490. </li>

  491. </ul>

  492. </li>

  493. <li><a href="#_server_to_client_informational_messages">2.3. Server to Client Informational Messages</a>

  494. <ul class="sectlevel3">

  495. <li><a href="#_session_is_loaded">2.3.1. Session is Loaded</a></li>

  496. <li><a href="#_show_optional_gui">2.3.2. Show Optional Gui</a></li>

  497. </ul>

  498. </li>

  499. <li><a href="#_client_to_server_informational_messages">2.4. Client to Server Informational Messages</a>

  500. <ul class="sectlevel3">

  501. <li><a href="#_optional_gui">2.4.1. Optional GUI</a></li>

  502. <li><a href="#_progress">2.4.2. Progress</a></li>

  503. <li><a href="#_dirtiness">2.4.3. Dirtiness</a></li>

  504. <li><a href="#_status_messsages">2.4.4. Status Messsages</a></li>

  505. </ul>

  506. </li>

  507. <li><a href="#_error_code_definitions">2.5. Error Code Definitions</a></li>

  508. <li><a href="#_client_to_server_control">2.6. Client to Server Control</a></li>

  509. <li><a href="#_server_control_api">2.7. Server Control API</a>

  510. <ul class="sectlevel3">

  511. <li><a href="#_client_to_client_communication">2.7.1. Client to Client Communication</a></li>

  512. </ul>

  513. </li>

  514. </ul>

  515. </li>

  516. </ul>

  517. </div>

  518. </div>

  519. <div id="content">

  520. <div id="preamble">

  521. <div class="sectionbody">

  522. <div class="paragraph">

  523. <p>The Non Session Management API is used by the various components of the Non audio production suite

  524. to allow any number of independent programs to be managed together as part of a logical session

  525. (i.e. a song). Thus, operations such as loading and saving are synchronized.</p>

  526. </div>

  527. <div class="paragraph">

  528. <p>The API comprises a simple Open Sound Control (OSC) based protocol, along with some behavioral

  529. guidelines, which can easily be implemented by various applications.</p>

  530. </div>

  531. <div class="paragraph">

  532. <p>The Non project contains an program called <code>nsmd</code> which is an implementation of the server side of

  533. the NSM API. <code>nsmd</code> is controlled by the <code>non-session-manager</code> GUI. However, the same server-side

  534. API can also be implemented by other session managers (such as LADISH), although consistency and

  535. robustness will likely suffer if non-NSM compliant clients are allowed to participate in a session.

  536. The only dependency for client implementations <code>liblo</code> (the OSC library), which several Linux audio

  537. applications already link to or plan to link to in the future.b</p>

  538. </div>

  539. <div class="paragraph">

  540. <p>The aim of this project is to thoroughly define the behavior required of clients. This is an area

  541. where other attempts at session management (LASH and JACK-Session) have failed. Often the

  542. difficulty with these systems has been not in implementing support for them, but in attempting to

  543. interpret the confusing, ambiguous, or ill-conceived API documentation. For these reasons and more

  544. all previous attempts at Linux audio session management protocols are considered harmful.</p>

  545. </div>

  546. <div class="paragraph">

  547. <p>You WILL see some unambiguous and emphatic language in this document. For the good of the user,

  548. these rules are meant to be followed and are non-negotiable. If an application does not conform to

  549. this specification it should be considered broken. Consistency across applications under session

  550. management is very important for a good user experience.</p>

  551. </div>

  552. </div>

  553. </div>

  554. <div class="sect1">

  555. <h2 id="_client_behavior_under_session_management">1. Client Behavior Under Session Management</h2>

  556. <div class="sectionbody">

  557. <div class="paragraph">

  558. <p>Most graphical applications make available to the user a common set of file operations, typically

  559. presented under a File or Project menu.</p>

  560. </div>

  561. <div class="paragraph">

  562. <p>These are: New, Open, Save, Save As, Close and Quit or Exit.</p>

  563. </div>

  564. <div class="paragraph">

  565. <p>The following sub-sections describe how these options should behave when the application is part of

  566. an NSM session. These rules only apply when session management is active (that is, after the

  567. <code>announce</code> handshake described in the <a href="#_nsm_osc_protocol">NSM OSC Protocol</a> section. In order to provide a

  568. consistent and predictable user experience, it is critically important for applications to adhere

  569. to these guidelines.</p>

  570. </div>

  571. <div class="sect2">

  572. <h3 id="_file_menu">1.1. File Menu</h3>

  573. <div class="sect3">

  574. <h4 id="_new">1.1.1. New</h4>

  575. <div class="paragraph">

  576. <p>This option may empty/reset the current file or project (possibly after user confirmation). UNDER

  577. NO CIRCUMSTANCES should it allow the user to create a new project/file in another location.</p>

  578. </div>

  579. </div>

  580. <div class="sect3">

  581. <h4 id="_open">1.1.2. Open</h4>

  582. <div class="paragraph">

  583. <p>This option MUST be disabled.</p>

  584. </div>

  585. <div class="paragraph">

  586. <p>The application may, however, elect to implement an option called 'Import into Session', creates a

  587. copy of a file/project which is then saved at the session path provided by NSM.</p>

  588. </div>

  589. </div>

  590. <div class="sect3">

  591. <h4 id="_save">1.1.3. Save</h4>

  592. <div class="paragraph">

  593. <p>This option should behave as normal, saving the current file/project as established by the NSM

  594. <code>open</code> message.</p>

  595. </div>

  596. <div class="paragraph">

  597. <p>UNDER NO CIRCUMSTANCES should this option present the user with a choice of where to save the file.</p>

  598. </div>

  599. </div>

  600. <div class="sect3">

  601. <h4 id="_save_as">1.1.4. Save As</h4>

  602. <div class="paragraph">

  603. <p>This option MUST be disabled.</p>

  604. </div>

  605. <div class="paragraph">

  606. <p>The application may, however, elect to implement an option called 'Export from Session', which

  607. creates a copy of the current file/project which is then saved in a user-specified location outside

  608. of the session path provided by NSM.</p>

  609. </div>

  610. </div>

  611. <div class="sect3">

  612. <h4 id="_close_as_distinguished_from_quit_or_exit">1.1.5. Close (as distinguished from Quit or Exit)</h4>

  613. <div class="paragraph">

  614. <p>This option MUST be disabled unless its meaning is to disconnect the application from session

  615. management.</p>

  616. </div>

  617. </div>

  618. <div class="sect3">

  619. <h4 id="_quit_or_exit">1.1.6. Quit or Exit</h4>

  620. <div class="paragraph">

  621. <p>This option may behave as normal (possibly asking the user to confirm exiting).</p>

  622. </div>

  623. </div>

  624. </div>

  625. <div class="sect2">

  626. <h3 id="_data_storage">1.2. Data Storage</h3>

  627. <div class="sect3">

  628. <h4 id="_internal_files">1.2.1. Internal Files</h4>

  629. <div class="paragraph">

  630. <p>All project specific data created by a client MUST be stored in the per-client storage area

  631. provided by NSM. This includes all recorded audio and MIDI files, snapshots, etc. Only global

  632. configuration items, exports, and renders of the project may be stored elsewhere (wherever the user

  633. specifies).</p>

  634. </div>

  635. </div>

  636. <div class="sect3">

  637. <h4 id="_external_files">1.2.2. External Files</h4>

  638. <div class="paragraph">

  639. <p>Files required by the project but external to it (typically read-only data such as audio samples)

  640. SHOULD be referenced by creating a symbolic link within the assigned session area, and then

  641. referring to the symlink. This allows sessions to be archived and transported simply (e.g. with

  642. "tar -h") by tools that have no knowledge of the project formats of the various clients in the

  643. session. The symlinks thus created should, at the very least, be named after the files they refer

  644. to (some unique component may be required to prevent collisions)</p>

  645. </div>

  646. </div>

  647. </div>

  648. </div>

  649. </div>

  650. <div class="sect1">

  651. <h2 id="_nsm_osc_protocol">2. NSM OSC Protocol</h2>

  652. <div class="sectionbody">

  653. <div class="paragraph">

  654. <p>All message parameters are REQUIRED. All messages MUST be sent from the same socket as the <code>announce</code>

  655. message, using the <code>lo_send_from</code> method of liblo or its equivalent, as the server uses the return

  656. addresses to distinguish between clients.</p>

  657. </div>

  658. <div class="paragraph">

  659. <p>Clients MUST create thier OSC servers using the same protocol (UDP,TCP) as found in <code>NSM_URL</code>. liblo

  660. is lacking a robust TCP implementation at the time of writing, but in the future it may be useful.</p>

  661. </div>

  662. <div class="sect2">

  663. <h3 id="_establishing_a_connection">2.1. Establishing a Connection</h3>

  664. <div class="sect3">

  665. <h4 id="_announce">2.1.1. Announce</h4>

  666. <div class="paragraph">

  667. <p>At launch, the client MUST check the environment for the value of <code>NSM_URL</code>. If present, the client

  668. MUST send the following message to the provided address as soon as it is ready to respond to the

  669. <code>/nsm/client/open</code> event:</p>

  670. </div>

  671. <div class="listingblock">

  672. <div class="content">

  673. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/server/announce s:application_name s:capabilities s:executable_name i:api_version_major i:api_version_minor i:pid</code></pre>

  674. </div>

  675. </div>

  676. <div class="paragraph">

  677. <p>If <code>NSM_URL</code> is undefined, invalid, or unreachable, then the client should proceed assuming that

  678. session management is unavailable.</p>

  679. </div>

  680. <div class="paragraph">

  681. <p><code>api_version_major</code> and <code>api_version_minor</code> must be the two parts of the version number of the NSM API

  682. as defined by this document.</p>

  683. </div>

  684. <div class="paragraph">

  685. <p>Note that if the application intends to register JACK clients, <code>application_name</code> MUST be the same as

  686. the name that would normally be passed to <code>jack_client_open</code>. For example, Non-Mixer sends

  687. "Non-Mixer" as its <code>application_name</code>. Applications MUST NOT register their JACK clients until

  688. receiving an <code>open</code> message; the <code>open</code> message will provide a unique client name prefix suitable for

  689. passing to JACK. This is probably the most complex requirement of the NSM API, but it isn&#8217;t

  690. difficult to implement, especially if the application simply wishes to delay its initialization

  691. process breifly while awaiting the <code>announce</code> reply and subsequent <code>open</code> message.</p>

  692. </div>

  693. <div class="paragraph">

  694. <p><code>capabilities</code> MUST be a string containing a colon separated list of the special capabilities the

  695. client possesses. e.g. <code>:dirty:switch:progress:</code></p>

  696. </div>

  697. <div class="paragraph">

  698. <p><code>executable_name</code> MUST be the executable name that the program was launched with. For C programs,

  699. this is simply the value of <code>argv[0]</code>. Note that hardcoding the name of the program here is not the

  700. same as using, as the user may have launched the program from a script with a different name using

  701. exec, or have created a symlink to the program. Getting the correct value in scripting languages

  702. like Python can be more challenging.</p>

  703. </div>

  704. <table class="tableblock frame-all grid-all stripes-even stretch">

  705. <caption class="title">Table 1. Available Client Capabilities</caption>

  706. <colgroup>

  707. <col style="width: 50%;">

  708. <col style="width: 50%;">

  709. </colgroup>

  710. <thead>

  711. <tr>

  712. <th class="tableblock halign-left valign-top">Name</th>

  713. <th class="tableblock halign-left valign-top">Description</th>

  714. </tr>

  715. </thead>

  716. <tbody>

  717. <tr>

  718. <td class="tableblock halign-left valign-top"><p class="tableblock">switch</p></td>

  719. <td class="tableblock halign-left valign-top"><p class="tableblock">client is capable of responding to multiple <code>open</code> messages without restarting</p></td>

  720. </tr>

  721. <tr>

  722. <td class="tableblock halign-left valign-top"><p class="tableblock">dirty</p></td>

  723. <td class="tableblock halign-left valign-top"><p class="tableblock">client knows when it has unsaved changes</p></td>

  724. </tr>

  725. <tr>

  726. <td class="tableblock halign-left valign-top"><p class="tableblock">progress</p></td>

  727. <td class="tableblock halign-left valign-top"><p class="tableblock">client can send progress updates during time-consuming operations</p></td>

  728. </tr>

  729. <tr>

  730. <td class="tableblock halign-left valign-top"><p class="tableblock">message</p></td>

  731. <td class="tableblock halign-left valign-top"><p class="tableblock">client can send textual status updates</p></td>

  732. </tr>

  733. <tr>

  734. <td class="tableblock halign-left valign-top"><p class="tableblock">optional-gui</p></td>

  735. <td class="tableblock halign-left valign-top"><p class="tableblock">client has an optional GUI</p></td>

  736. </tr>

  737. </tbody>

  738. </table>

  739. </div>

  740. <div class="sect3">

  741. <h4 id="_response">2.1.2. Response</h4>

  742. <div class="paragraph">

  743. <p>The server will respond to the client&#8217;s announce message with the following message:</p>

  744. </div>

  745. <div class="listingblock">

  746. <div class="content">

  747. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/reply "/nsm/server/announce" s:message s:name_of_session_manager s:capabilities</code></pre>

  748. </div>

  749. </div>

  750. <div class="paragraph">

  751. <p><code>message</code> is a welcome message.</p>

  752. </div>

  753. <div class="paragraph">

  754. <p>The value of <code>name_of_session_manager</code> will depend on the implementation of the NSM server. It might

  755. say "Non Session Manager", or it might say "LADISH". This is for display to the user.</p>

  756. </div>

  757. <div class="paragraph">

  758. <p><code>capabilities</code> will be a string containing a colon separated list of special server capabilities.</p>

  759. </div>

  760. <div class="paragraph">

  761. <p>Presently, the server <code>capabilities</code> are:</p>

  762. </div>

  763. <table class="tableblock frame-all grid-all stripes-even stretch">

  764. <caption class="title">Table 2. Available Server Capabilities</caption>

  765. <colgroup>

  766. <col style="width: 50%;">

  767. <col style="width: 50%;">

  768. </colgroup>

  769. <thead>

  770. <tr>

  771. <th class="tableblock halign-left valign-top">Name</th>

  772. <th class="tableblock halign-left valign-top">Description</th>

  773. </tr>

  774. </thead>

  775. <tbody>

  776. <tr>

  777. <td class="tableblock halign-left valign-top"><p class="tableblock">server_control</p></td>

  778. <td class="tableblock halign-left valign-top"><p class="tableblock">client-to-server control</p></td>

  779. </tr>

  780. <tr>

  781. <td class="tableblock halign-left valign-top"><p class="tableblock">broadcast</p></td>

  782. <td class="tableblock halign-left valign-top"><p class="tableblock">server responds to /nsm/server/broadcast message</p></td>

  783. </tr>

  784. <tr>

  785. <td class="tableblock halign-left valign-top"><p class="tableblock">optional-gui</p></td>

  786. <td class="tableblock halign-left valign-top"><p class="tableblock">server responds to optional-gui messages&#8212;&#8203;if this capability is not present then clients with optional-guis MUST always keep them visible</p></td>

  787. </tr>

  788. </tbody>

  789. </table>

  790. <div class="paragraph">

  791. <p>A client should not consider itself to be under session management until it receives this response.

  792. For example, the Non applications activate their "SM" blinkers at this time.</p>

  793. </div>

  794. <div class="paragraph">

  795. <p>If there is an error, a reply of the following form will be sent to the client:</p>

  796. </div>

  797. <div class="listingblock">

  798. <div class="content">

  799. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/error "/nsm/server/announce" i:error_code s:error_message</code></pre>

  800. </div>

  801. </div>

  802. <div class="paragraph">

  803. <p>The following table defines possible values of <code>error_code</code>:</p>

  804. </div>

  805. <table class="tableblock frame-all grid-all stripes-even stretch">

  806. <caption class="title">Table 3. Response codes</caption>

  807. <colgroup>

  808. <col style="width: 50%;">

  809. <col style="width: 50%;">

  810. </colgroup>

  811. <thead>

  812. <tr>

  813. <th class="tableblock halign-left valign-top">Code</th>

  814. <th class="tableblock halign-left valign-top">Meaning</th>

  815. </tr>

  816. </thead>

  817. <tbody>

  818. <tr>

  819. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_GENERAL</p></td>

  820. <td class="tableblock halign-left valign-top"><p class="tableblock">General Error</p></td>

  821. </tr>

  822. <tr>

  823. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_INCOMPATIBLE_API</p></td>

  824. <td class="tableblock halign-left valign-top"><p class="tableblock">Incompatible API version</p></td>

  825. </tr>

  826. <tr>

  827. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_BLACKLISTED</p></td>

  828. <td class="tableblock halign-left valign-top"><p class="tableblock">Client has been blacklisted.</p></td>

  829. </tr>

  830. </tbody>

  831. </table>

  832. </div>

  833. </div>

  834. <div class="sect2">

  835. <h3 id="_server_to_client_control_messages">2.2. Server to Client Control Messages</h3>

  836. <div class="paragraph">

  837. <p>Compliant clients MUST accept the client control messages described in this section. All client

  838. control messages REQUIRE a response. Responses MUST be delivered back to the sender (NSM) from the

  839. same socket used by the client in its <code>announce</code> message (by using <code>lo_send_from</code>) AFTER the action has

  840. been completed or if an error is encountered. The required response is described in the subsection

  841. for each message.</p>

  842. </div>

  843. <div class="paragraph">

  844. <p>If there is an error and the action cannot be completed, then <code>error_code</code> MUST be set to a valid

  845. error code (see <a href="#_error_code_definitions">Error Code Definitions</a>) and <code>message</code> to a string describing the problem

  846. (suitable for display to the user).</p>

  847. </div>

  848. <div class="paragraph">

  849. <p>The reply can take one of the following two forms, where path MUST be the <code>path</code> of the message being

  850. replied to (e.g. "nsm/client/save":</p>

  851. </div>

  852. <div class="listingblock">

  853. <div class="content">

  854. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/reply s:path s:message</code></pre>

  855. </div>

  856. </div>

  857. <div class="listingblock">

  858. <div class="content">

  859. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/error s:path i:error_code s:message</code></pre>

  860. </div>

  861. </div>

  862. <div class="sect3">

  863. <h4 id="_quit">2.2.1. Quit</h4>

  864. <div class="paragraph">

  865. <p>There is no message for this. Clients will receive the Unix SIGTERM signal and MUST close cleanly

  866. IMMEDIATELY, without displaying any kind of dialog to the user and regardless of whether or not

  867. unsaved changes would be lost. When a session is closed the application will receive this signal

  868. soon after having responded to a <code>save</code> message.</p>

  869. </div>

  870. </div>

  871. <div class="sect3">

  872. <h4 id="_open_2">2.2.2. Open</h4>

  873. <div class="listingblock">

  874. <div class="content">

  875. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/open s:path_to_instance_specific_project s:display_name s:client_id</code></pre>

  876. </div>

  877. </div>

  878. <div class="paragraph">

  879. <p><code>path_to_instance_specific_project</code> is a path name assigned to the client for storing its project

  880. data.</p>

  881. </div>

  882. <div class="paragraph">

  883. <p>The client may append to the path, creating a sub-directory, e.g. '/song.foo' or simply append the

  884. client&#8217;s native file extension (e.g. '.non' or '.XML'). The same transformation MUST be applied to

  885. the name when opening an existing project, as NSM will only provide the instance specific part of

  886. the path.</p>

  887. </div>

  888. <div class="paragraph">

  889. <p>If a project exists at the path, the client MUST immediately open it.</p>

  890. </div>

  891. <div class="paragraph">

  892. <p>If a project does not exist at the path, then the client MUST immediately create and open a new one

  893. at the specified path or, for clients which hold all their state in memory, store the path for

  894. later use when responding to the <code>save</code> message.</p>

  895. </div>

  896. <div class="paragraph">

  897. <p>No file or directory will be created at the specified path by the server. It is up to the client to

  898. create what it needs.</p>

  899. </div>

  900. <div class="paragraph">

  901. <p>For clients which HAVE NOT specified the <code>:switch:</code> capability, the <code>open</code> message will only be

  902. delivered once, immediately following the <code>announce</code> response.</p>

  903. </div>

  904. <div class="paragraph">

  905. <p>For clients which HAVE specified the <code>:switch:</code> capability, the client MUST immediately switch to the

  906. specified project or create a new one if it doesn&#8217;t exist.</p>

  907. </div>

  908. <div class="paragraph">

  909. <p>Clients which are incapable of switching projects or are prone to crashing upon switching MUST NOT

  910. include <code>:switch:</code> in their capability string.</p>

  911. </div>

  912. <div class="paragraph">

  913. <p>If the user the is allowed to run two or more instances of the application simultaneously (that is

  914. to say, there is no technical limitation preventing them from doing so, even if it doesn&#8217;t make

  915. sense to the author), then such an application MUST PRE-PEND the provided <code>client_id</code> string to any

  916. names it registers with common subsystems (e.g. JACK client names). This ensures that multiple

  917. instances of the same application can be restored in any order without scrambling the JACK

  918. connections or causing other conflicts. The provided <code>client_id</code> will be a concatenation of the value

  919. of <code>application_name</code> sent by the client in its <code>announce</code> message and a unique identifier. Therefore,

  920. applications which create single JACK clients can use the value of <code>client_id</code> directly as their JACK

  921. client name. Applications which register multiple JACK clients (e.g. Non-Mixer) MUST PRE-PEND

  922. <code>client_id</code> value to the client names they register with JACK and the application determined part

  923. MUST be unique for that (JACK) client.</p>

  924. </div>

  925. <div class="paragraph">

  926. <p>For example, a suitable JACK client name would be:  <code>$CLIENT_ID/track-1</code></p>

  927. </div>

  928. <div class="paragraph">

  929. <p>Note that this means that the application MUST NOT register with JACK (or any

  930. other subsystem requiring unique names) until it receives an <code>open</code> message from NSM. Likewise,

  931. applications with the <code>:switch:</code> capability should close their JACK clients and re-create them with

  932. using the new <code>client_id</code>. Re-registering is necessary because the JACK API does currently support

  933. renaming existing clients, although this is a sorely needed addition.</p>

  934. </div>

  935. <div class="paragraph">

  936. <p>A response is REQUIRED as soon as the open operation has been completed. Ongoing progress may be

  937. indicated by sending messages to <code>/nsm/client/progress</code>.</p>

  938. </div>

  939. <div class="sect4">

  940. <h5 id="_response_2">2.2.2.1. Response</h5>

  941. <div class="paragraph">

  942. <p>The client MUST respond to the 'open' message with:</p>

  943. </div>

  944. <div class="listingblock">

  945. <div class="content">

  946. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/reply "/nsm/client/open" s:message</code></pre>

  947. </div>

  948. </div>

  949. <div class="paragraph">

  950. <p>Or</p>

  951. </div>

  952. <div class="listingblock">

  953. <div class="content">

  954. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/error "/nsm/client/open" i:error_code s:message</code></pre>

  955. </div>

  956. </div>

  957. <table class="tableblock frame-all grid-all stripes-even stretch">

  958. <caption class="title">Table 4. Response codes</caption>

  959. <colgroup>

  960. <col style="width: 50%;">

  961. <col style="width: 50%;">

  962. </colgroup>

  963. <thead>

  964. <tr>

  965. <th class="tableblock halign-left valign-top">Code</th>

  966. <th class="tableblock halign-left valign-top">Meaning</th>

  967. </tr>

  968. </thead>

  969. <tbody>

  970. <tr>

  971. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR</p></td>

  972. <td class="tableblock halign-left valign-top"><p class="tableblock">General Error</p></td>

  973. </tr>

  974. <tr>

  975. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_BAD_PROJECT</p></td>

  976. <td class="tableblock halign-left valign-top"><p class="tableblock">An existing project file was found to be corrupt</p></td>

  977. </tr>

  978. <tr>

  979. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_CREATE_FAILED</p></td>

  980. <td class="tableblock halign-left valign-top"><p class="tableblock">A new project could not be created</p></td>

  981. </tr>

  982. <tr>

  983. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_UNSAVED_CHANGES</p></td>

  984. <td class="tableblock halign-left valign-top"><p class="tableblock">Unsaved changes would be lost</p></td>

  985. </tr>

  986. <tr>

  987. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NOT_NOW</p></td>

  988. <td class="tableblock halign-left valign-top"><p class="tableblock">Operation cannot be completed at this time</p></td>

  989. </tr>

  990. </tbody>

  991. </table>

  992. </div>

  993. </div>

  994. <div class="sect3">

  995. <h4 id="_save_2">2.2.3. Save</h4>

  996. <div class="listingblock">

  997. <div class="content">

  998. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/save</code></pre>

  999. </div>

  1000. </div>

  1001. <div class="paragraph">

  1002. <p>This message will only be delivered after a previous <code>open</code> message, and may be sent any number of

  1003. times within the course of a session (including zero, if the user aborts the session).</p>

  1004. </div>

  1005. <div class="sect4">

  1006. <h5 id="_response_3">2.2.3.1. Response</h5>

  1007. <div class="listingblock">

  1008. <div class="content">

  1009. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/reply "/nsm/client/save" s:message</code></pre>

  1010. </div>

  1011. </div>

  1012. <div class="paragraph">

  1013. <p>Or</p>

  1014. </div>

  1015. <div class="listingblock">

  1016. <div class="content">

  1017. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/error "/nsm/client/save" i:error_code s:message</code></pre>

  1018. </div>

  1019. </div>

  1020. <table class="tableblock frame-all grid-all stripes-even stretch">

  1021. <caption class="title">Table 5. Response codes</caption>

  1022. <colgroup>

  1023. <col style="width: 50%;">

  1024. <col style="width: 50%;">

  1025. </colgroup>

  1026. <thead>

  1027. <tr>

  1028. <th class="tableblock halign-left valign-top">Code</th>

  1029. <th class="tableblock halign-left valign-top">Meaning</th>

  1030. </tr>

  1031. </thead>

  1032. <tbody>

  1033. <tr>

  1034. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR</p></td>

  1035. <td class="tableblock halign-left valign-top"><p class="tableblock">General Error</p></td>

  1036. </tr>

  1037. <tr>

  1038. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_SAVE_FAILED</p></td>

  1039. <td class="tableblock halign-left valign-top"><p class="tableblock">Project could not be saved</p></td>

  1040. </tr>

  1041. <tr>

  1042. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NOT_NOW</p></td>

  1043. <td class="tableblock halign-left valign-top"><p class="tableblock">Operation cannot be completed at this time</p></td>

  1044. </tr>

  1045. </tbody>

  1046. </table>

  1047. </div>

  1048. </div>

  1049. </div>

  1050. <div class="sect2">

  1051. <h3 id="_server_to_client_informational_messages">2.3. Server to Client Informational Messages</h3>

  1052. <div class="sect3">

  1053. <h4 id="_session_is_loaded">2.3.1. Session is Loaded</h4>

  1054. <div class="paragraph">

  1055. <p>Accepting this message is optional. The intent is to signal to clients which may have some

  1056. interdependence (say, peer to peer OSC connections) that the session is fully loaded and all their

  1057. peers are available. Most clients will not need to act on this message. This message has no meaning

  1058. when a session is being built or run&#8212;&#8203;only when it is initially loaded. Clients who intend to act

  1059. on this message MUST not do so by delaying initialization waiting for it.</p>

  1060. </div>

  1061. <div class="listingblock">

  1062. <div class="content">

  1063. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/session_is_loaded</code></pre>

  1064. </div>

  1065. </div>

  1066. <div class="paragraph">

  1067. <p>This message does not require a response.</p>

  1068. </div>

  1069. </div>

  1070. <div class="sect3">

  1071. <h4 id="_show_optional_gui">2.3.2. Show Optional Gui</h4>

  1072. <div class="paragraph">

  1073. <p>If the client has specified the <code>optional-gui</code> capability, then it may receive this message from the

  1074. server when the user wishes to change the visibility state of the GUI. It doesn&#8217;t matter if the

  1075. optional GUI is integrated with the program or if it is a separate program \(as is the case with

  1076. SooperLooper\). When the GUI is hidden, there should be no window mapped and if the GUI is a

  1077. separate program, it should be killed.</p>

  1078. </div>

  1079. <div class="listingblock">

  1080. <div class="content">

  1081. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/show_optional_gui</code></pre>

  1082. </div>

  1083. </div>

  1084. <div class="listingblock">

  1085. <div class="content">

  1086. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/hide_optional_gui</code></pre>

  1087. </div>

  1088. </div>

  1089. <div class="paragraph">

  1090. <p>No response is message is required.</p>

  1091. </div>

  1092. </div>

  1093. </div>

  1094. <div class="sect2">

  1095. <h3 id="_client_to_server_informational_messages">2.4. Client to Server Informational Messages</h3>

  1096. <div class="sect3">

  1097. <h4 id="_optional_gui">2.4.1. Optional GUI</h4>

  1098. <div class="paragraph">

  1099. <p>If the client has specified the <code>optional-gui</code> capability, then it MUST send this message whenever

  1100. the state of visibility of the optional GUI has changed. It also MUST send this message after it&#8217;s

  1101. announce message to indicate the initial visibility state of the optional GUI.</p>

  1102. </div>

  1103. <div class="paragraph">

  1104. <p>It is the responsibility of the client to remember the visibility state of its GUI across session

  1105. loads.</p>

  1106. </div>

  1107. <div class="listingblock">

  1108. <div class="content">

  1109. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/gui_is_hidden</code></pre>

  1110. </div>

  1111. </div>

  1112. <div class="listingblock">

  1113. <div class="content">

  1114. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/gui_is_shown</code></pre>

  1115. </div>

  1116. </div>

  1117. <div class="paragraph">

  1118. <p>No response will be delivered.</p>

  1119. </div>

  1120. </div>

  1121. <div class="sect3">

  1122. <h4 id="_progress">2.4.2. Progress</h4>

  1123. <div class="listingblock">

  1124. <div class="content">

  1125. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/progress f:progress</code></pre>

  1126. </div>

  1127. </div>

  1128. <div class="paragraph">

  1129. <p>For potentially time-consuming operations, such as <code>save</code> and <code>open</code>, progress updates may be

  1130. indicated throughout the duration by sending a floating point value between 0.0 and 1.0, 1.0

  1131. indicating completion, to the NSM server.</p>

  1132. </div>

  1133. <div class="paragraph">

  1134. <p>The server will not send a response to these messages, but will relay the information to the user.</p>

  1135. </div>

  1136. <div class="paragraph">

  1137. <p>Note that even when using the <code>progress</code> feature, the final response to the <code>save</code> or <code>open</code>

  1138. message is still REQUIRED.</p>

  1139. </div>

  1140. <div class="paragraph">

  1141. <p>Clients which intend to send progress messages should include <code>:progress:</code> in their <code>announce</code>

  1142. capability string.</p>

  1143. </div>

  1144. </div>

  1145. <div class="sect3">

  1146. <h4 id="_dirtiness">2.4.3. Dirtiness</h4>

  1147. <div class="listingblock">

  1148. <div class="content">

  1149. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/is_dirty</code></pre>

  1150. </div>

  1151. </div>

  1152. <div class="listingblock">

  1153. <div class="content">

  1154. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/is_clean</code></pre>

  1155. </div>

  1156. </div>

  1157. <div class="paragraph">

  1158. <p>Some clients may be able to inform the server when they have unsaved changes pending. Such clients

  1159. may optionally send <code>is_dirty</code> and <code>is_clean</code> messages.</p>

  1160. </div>

  1161. <div class="paragraph">

  1162. <p>Clients which have this capability should include <code>:dirty:</code> in their <code>announce</code> capability string.</p>

  1163. </div>

  1164. </div>

  1165. <div class="sect3">

  1166. <h4 id="_status_messsages">2.4.4. Status Messsages</h4>

  1167. <div class="listingblock">

  1168. <div class="content">

  1169. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/client/message i:priority s:message</code></pre>

  1170. </div>

  1171. </div>

  1172. <div class="paragraph">

  1173. <p>Clients may send miscellaneous status updates to the server for possible display to the user. This

  1174. may simply be chatter that is normally written to the console. <code>priority</code> should be a number from 0

  1175. to 3, 3 being the most important.</p>

  1176. </div>

  1177. <div class="paragraph">

  1178. <p>Clients which have this capability should include <code>:message:</code> in their <code>announce</code> capability

  1179. string.</p>

  1180. </div>

  1181. </div>

  1182. </div>

  1183. <div class="sect2">

  1184. <h3 id="_error_code_definitions">2.5. Error Code Definitions</h3>

  1185. <table class="tableblock frame-all grid-all stripes-even stretch">

  1186. <caption class="title">Table 6. Error Code Definitions</caption>

  1187. <colgroup>

  1188. <col style="width: 50%;">

  1189. <col style="width: 50%;">

  1190. </colgroup>

  1191. <thead>

  1192. <tr>

  1193. <th class="tableblock halign-left valign-top">Symbolic Name</th>

  1194. <th class="tableblock halign-left valign-top">Integer Value</th>

  1195. </tr>

  1196. </thead>

  1197. <tbody>

  1198. <tr>

  1199. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_GENERAL</p></td>

  1200. <td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td>

  1201. </tr>

  1202. <tr>

  1203. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_INCOMPATIBLE_API</p></td>

  1204. <td class="tableblock halign-left valign-top"><p class="tableblock">-2</p></td>

  1205. </tr>

  1206. <tr>

  1207. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_BLACKLISTED</p></td>

  1208. <td class="tableblock halign-left valign-top"><p class="tableblock">-3</p></td>

  1209. </tr>

  1210. <tr>

  1211. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_LAUNCH_FAILED</p></td>

  1212. <td class="tableblock halign-left valign-top"><p class="tableblock">-4</p></td>

  1213. </tr>

  1214. <tr>

  1215. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NO_SUCH_FILE</p></td>

  1216. <td class="tableblock halign-left valign-top"><p class="tableblock">-5</p></td>

  1217. </tr>

  1218. <tr>

  1219. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NO_SESSION_OPEN</p></td>

  1220. <td class="tableblock halign-left valign-top"><p class="tableblock">-6</p></td>

  1221. </tr>

  1222. <tr>

  1223. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_UNSAVED_CHANGES</p></td>

  1224. <td class="tableblock halign-left valign-top"><p class="tableblock">-7</p></td>

  1225. </tr>

  1226. <tr>

  1227. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NOT_NOW</p></td>

  1228. <td class="tableblock halign-left valign-top"><p class="tableblock">-8</p></td>

  1229. </tr>

  1230. <tr>

  1231. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_BAD_PROJECT</p></td>

  1232. <td class="tableblock halign-left valign-top"><p class="tableblock">-9</p></td>

  1233. </tr>

  1234. <tr>

  1235. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_CREATE_FAILED</p></td>

  1236. <td class="tableblock halign-left valign-top"><p class="tableblock">-10</p></td>

  1237. </tr>

  1238. </tbody>

  1239. </table>

  1240. </div>

  1241. <div class="sect2">

  1242. <h3 id="_client_to_server_control">2.6. Client to Server Control</h3>

  1243. <div class="paragraph">

  1244. <p>If the server publishes the <code>:server_control:</code> capability, then clients can also initiate action by

  1245. the server. For example, a client might implement a 'Save All' option which sends a

  1246. <code>/nsm/server/save</code> message to the server, rather than requiring the user to switch to the session

  1247. management interface to effect the save.</p>

  1248. </div>

  1249. </div>

  1250. <div class="sect2">

  1251. <h3 id="_server_control_api">2.7. Server Control API</h3>

  1252. <div class="paragraph">

  1253. <p>The session manager not only manages clients via OSC, but it is itself controlled via OSC messages.

  1254. The server responds to the following messages.</p>

  1255. </div>

  1256. <div class="paragraph">

  1257. <p>All of the following messages will be responded to, at the sender&#8217;s address, with one of the two

  1258. following messages:</p>

  1259. </div>

  1260. <div class="listingblock">

  1261. <div class="content">

  1262. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/reply s:path s:message</code></pre>

  1263. </div>

  1264. </div>

  1265. <div class="listingblock">

  1266. <div class="content">

  1267. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/error s:path i:error_code s:message</code></pre>

  1268. </div>

  1269. </div>

  1270. <div class="paragraph">

  1271. <p>The first parameter of the reply is the path to the message being replied to. The <code>/error</code> reply

  1272. includes an integer error code (non-zero indicates error). <code>message</code> will be a description of the

  1273. error.</p>

  1274. </div>

  1275. <div class="paragraph">

  1276. <p>The possible errors are:</p>

  1277. </div>

  1278. <table class="tableblock frame-all grid-all stripes-even stretch">

  1279. <caption class="title">Table 7. Responses</caption>

  1280. <colgroup>

  1281. <col style="width: 50%;">

  1282. <col style="width: 50%;">

  1283. </colgroup>

  1284. <thead>

  1285. <tr>

  1286. <th class="tableblock halign-left valign-top">Code</th>

  1287. <th class="tableblock halign-left valign-top">Meaning</th>

  1288. </tr>

  1289. </thead>

  1290. <tbody>

  1291. <tr>

  1292. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_GENERAL</p></td>

  1293. <td class="tableblock halign-left valign-top"><p class="tableblock">General Error</p></td>

  1294. </tr>

  1295. <tr>

  1296. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_LAUNCH_FAILED</p></td>

  1297. <td class="tableblock halign-left valign-top"><p class="tableblock">Launch failed</p></td>

  1298. </tr>

  1299. <tr>

  1300. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NO_SUCH_FILE</p></td>

  1301. <td class="tableblock halign-left valign-top"><p class="tableblock">No such file</p></td>

  1302. </tr>

  1303. <tr>

  1304. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_NO_SESSION</p></td>

  1305. <td class="tableblock halign-left valign-top"><p class="tableblock">No session is open</p></td>

  1306. </tr>

  1307. <tr>

  1308. <td class="tableblock halign-left valign-top"><p class="tableblock">ERR_UNSAVED_CHANGES</p></td>

  1309. <td class="tableblock halign-left valign-top"><p class="tableblock">Unsaved changes would be lost</p></td>

  1310. </tr>

  1311. </tbody>

  1312. </table>

  1313. <div class="ulist">

  1314. <ul>

  1315. <li>

  1316. <p><code>/nsm/server/add s:executable_name</code></p>

  1317. <div class="ulist">

  1318. <ul>

  1319. <li>

  1320. <p>Adds a client to the current session.</p>

  1321. </li>

  1322. </ul>

  1323. </div>

  1324. </li>

  1325. <li>

  1326. <p><code>/nsm/server/save</code></p>

  1327. <div class="ulist">

  1328. <ul>

  1329. <li>

  1330. <p>Saves the current session.</p>

  1331. </li>

  1332. </ul>

  1333. </div>

  1334. </li>

  1335. <li>

  1336. <p><code>/nsm/server/open s:project_name</code></p>

  1337. <div class="ulist">

  1338. <ul>

  1339. <li>

  1340. <p>Saves the current session and loads a new session.</p>

  1341. </li>

  1342. </ul>

  1343. </div>

  1344. </li>

  1345. <li>

  1346. <p><code>/nsm/server/new s:project_name</code></p>

  1347. <div class="ulist">

  1348. <ul>

  1349. <li>

  1350. <p>Saves the current session and creates a new session.</p>

  1351. </li>

  1352. </ul>

  1353. </div>

  1354. </li>

  1355. <li>

  1356. <p><code>/nsm/server/duplicate s:new_project</code></p>

  1357. <div class="ulist">

  1358. <ul>

  1359. <li>

  1360. <p>Saves and closes the current session, makes a copy, and opens it.</p>

  1361. </li>

  1362. </ul>

  1363. </div>

  1364. </li>

  1365. <li>

  1366. <p><code>/nsm/server/close</code></p>

  1367. <div class="ulist">

  1368. <ul>

  1369. <li>

  1370. <p>Saves and closes the current session.</p>

  1371. </li>

  1372. </ul>

  1373. </div>

  1374. </li>

  1375. <li>

  1376. <p><code>/nsm/server/abort</code></p>

  1377. <div class="ulist">

  1378. <ul>

  1379. <li>

  1380. <p>Closes the current session WITHOUT SAVING</p>

  1381. </li>

  1382. </ul>

  1383. </div>

  1384. </li>

  1385. <li>

  1386. <p><code>/nsm/server/quit</code></p>

  1387. <div class="ulist">

  1388. <ul>

  1389. <li>

  1390. <p>Saves and closes the current session and terminates the server.</p>

  1391. </li>

  1392. </ul>

  1393. </div>

  1394. </li>

  1395. <li>

  1396. <p><code>/nsm/server/list</code></p>

  1397. <div class="ulist">

  1398. <ul>

  1399. <li>

  1400. <p>Lists available projects. One <code>/reply</code> message will be sent for each existing project.</p>

  1401. </li>

  1402. </ul>

  1403. </div>

  1404. </li>

  1405. </ul>

  1406. </div>

  1407. <div class="sect3">

  1408. <h4 id="_client_to_client_communication">2.7.1. Client to Client Communication</h4>

  1409. <div class="paragraph">

  1410. <p>If the server includes <code>:broadcast:</code> in its capability string, then clients may send broadcast

  1411. messages to each other through the NSM server. Clients may send messages to the server at the path

  1412. <code>/nsm/server/broadcast</code>.</p>

  1413. </div>

  1414. <div class="paragraph">

  1415. <p>The format of this message is as follows:</p>

  1416. </div>

  1417. <div class="listingblock">

  1418. <div class="content">

  1419. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/server/broadcast s:path [arguments...]</code></pre>

  1420. </div>

  1421. </div>

  1422. <div class="paragraph">

  1423. <p>The message will then be relayed to all clients in the session at the path <code>path</code> (with the

  1424. arguments shifted by one).</p>

  1425. </div>

  1426. <div class="paragraph">

  1427. <p>For example the message:</p>

  1428. </div>

  1429. <div class="listingblock">

  1430. <div class="content">

  1431. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/nsm/server/broadcast /tempomap/update "0,120,4/4:12351234,240,4/4"</code></pre>

  1432. </div>

  1433. </div>

  1434. <div class="paragraph">

  1435. <p>Would broadcast the following message to all clients in the session (except for the sender), some

  1436. of which might respond to the message by updating their own tempo maps.</p>

  1437. </div>

  1438. <div class="listingblock">

  1439. <div class="content">

  1440. <pre class="highlight nowrap"><code class="language-OSC" data-lang="OSC">/tempomap/update "0,120,4/4:12351234,240,4/4"</code></pre>

  1441. </div>

  1442. </div>

  1443. <div class="paragraph">

  1444. <p>The Non programs use this feature to establish peer to peer OSC communication by symbolic names

  1445. (client IDs) without having to remember the OSC URLs of peers across sessions.</p>

  1446. </div>

  1447. </div>

  1448. </div>

  1449. </div>

  1450. </div>

  1451. </div>

  1452. <div id="footer">

  1453. <div id="footer-text">

  1454. Version 1.2<br>

  1455. Last updated 2020-07-07 12:43:32 +0200

  1456. </div>

  1457. </div>

  1458. </body>

  1459. </html>