n4dir
/
ray_manual


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662
							<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.8">
<title>RaySession Manual</title>
<link rel="stylesheet" href="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">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Uncomment @import statement below to use as custom stylesheet */
/*@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";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
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}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.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}
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}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
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}
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}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
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}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
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}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
*:not(pre)>code.nobreak{word-wrap:normal}
*:not(pre)>code.nowrap{white-space:nowrap}
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
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-color:#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}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#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}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#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}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#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}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#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}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#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}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#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}
#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}
#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}
#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}
#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}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.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}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.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)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.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}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{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}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.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}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.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:#999}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.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}
.quoteblock blockquote{margin:0;padding:0;border:0}
.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)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.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}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.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}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
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}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
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}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
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}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.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}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color: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}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>RaySession Manual</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_introduction">Introduction</a></li>
<li><a href="#_simple_use_example">Simple use example</a></li>
<li><a href="#_overview_of_session_tools">Overview of session tools</a>
<ul class="sectlevel2">
<li><a href="#_top_row">Top row</a></li>
<li><a href="#_bottom_row">Bottom row</a></li>
</ul>
</li>
<li><a href="#_overview_of_a_client">Overview of a client</a></li>
<li><a href="#add_application">Add application window</a></li>
<li><a href="#add_executable">Add executable window</a></li>
<li><a href="#client_properties">Client Properties Window</a>
<ul class="sectlevel2">
<li><a href="#_general_tab"><strong>General</strong> tab</a></li>
<li><a href="#_nsm_tab"><strong>NSM</strong> tab</a></li>
<li><a href="#_ray_hack_tab"><strong>Ray-Hack</strong> tab</a></li>
</ul>
</li>
<li><a href="#_network_sessions">Network Sessions</a></li>
<li><a href="#add_program_not_provided">Add a program not provided</a></li>
<li><a href="#_import_an_nsm_session">Import an NSM session</a></li>
<li><a href="#_the_daemons_options">The daemon&#8217;s options</a>
<ul class="sectlevel2">
<li><a href="#session_folder_shortcuts">Provide bookmarks for session folder</a></li>
<li><a href="#_auto_snapshot_at_save">Auto Snapshot at Save</a></li>
<li><a href="#_desktops_memory">Desktops Memory</a></li>
<li><a href="#_session_scripts">Session scripts</a></li>
<li><a href="#_remember_optional_gui_states">Remember optional GUI states</a></li>
</ul>
</li>
<li><a href="#snapshots">Snapshots</a></li>
<li><a href="#session_scripts">Session scripts</a></li>
<li><a href="#jack_configuration_memory">JACK configuration memory</a>
<ul class="sectlevel2">
<li><a href="#_in_which_cases_to_use_it">In which cases to use it</a></li>
<li><a href="#_usage">Usage</a></li>
<li><a href="#_working_principle">Working principle</a></li>
<li><a href="#_special_cases">Special cases</a></li>
</ul>
</li>
<li><a href="#under_the_hood">Under the hood</a></li>
<li><a href="#ray_control">Control RaySession from the command line</a></li>
<li><a href="#_frequently_asked_questions">Frequently Asked Questions</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph text-right">
<p><em>Other languages:</em> <span class="image"><a class="image" href="../fr/manual.html"><img src="images/flag_fr.jpeg" alt="EN" width="30" height="20"></a></span></p>
</div>
<div class="paragraph">
<p><em>for version 0.10.0</em></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>RaySession is an audio session manager for GNU / Linux. It allows you to start several audio programs in the same session, to save their projects together and thus to avoid multiple operations to return to a given configuration.</p>
</div>
<div class="paragraph">
<p>To be launched in RaySession, it is very much preferable that these audio programs be compatible with the NSM protocol, and many are already, among others Ardour, Qtractor, Carla, Guitarix, Mamba, Patroneo, ZynAddSubFx &#8230;&#8203;</p>
</div>
<div class="paragraph">
<p>RaySession assumes that your audio setup is working for audio production, if not, fix this first and don&#8217;t waste your time trying to use RaySession.</p>
</div>
<div class="paragraph">
<p>Now let&#8217;s see how to use it.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_simple_use_example">Simple use example</h2>
<div class="sectionbody">
<div class="paragraph">
<p>For audio production under GNU / linux, it is highly recommended to use the JACK server. Before creating or starting a session, make sure the JACK server is running, RaySession has no direct relation to JACK, however the programs you are going to launch in your session will need it.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s take an example where to compose a song, we will need Ardour and Guitarix softwares, make sure that these 2 programs are installed.</p>
</div>
<div class="paragraph">
<p>To create a new session, click at the top left on New Session (<em>or Ctrl+N</em>). A dialog window appears.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/example_new_session.png" alt="New session">
</div>
</div>
<div class="paragraph">
<p>At the top right you can see the root session folder, this is where the sessions will be saved (a RaySession session being a folder containing a file <code>raysession.xml</code>).</p>
</div>
<div class="paragraph">
<p>Enter the name you want for this new session in the field provided. To put your new session in a sub-folder, type the name as follows: <code>sub-folder/my session</code>.</p>
</div>
<div class="paragraph">
<p>The session template multiple choice box lets you choose between</p>
</div>
<div class="ulist">
<ul>
<li>
<p>An empty session template</p>
</li>
<li>
<p>A template with memory of JACK connections</p>
</li>
<li>
<p>A scripted template with memory of the JACK configuration</p>
</li>
<li>
<p>A template with basic session scripts (for advanced users with shell scripting knowledge)</p>
</li>
<li>
<p>All the session templates that you have created yourself.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>First, keep the template on <strong>With JACK patch memory</strong> , click <strong>Ok</strong> to start your session.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/example_session_launched.png" alt="Session launched">
</div>
</div>
<div class="paragraph">
<p>The session part of the window becomes active, at the top is written the name of your session, and your session already contains a client program called <strong>JACK Connections</strong>. This client will save and redo the connections of the JACK patchbay.</p>
</div>
<div class="paragraph">
<p>To add Ardour to your session, click on the <strong>Application</strong> button (<em>or Ctrl+A</em>), the application dialog will appear (more details in the <a href="#add_application">Add application window</a> section). On the right side, find Ardour (Depending on your version of ardour, it may be called Ardour5 or Ardour6) and double-click on it.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/example_add_ardour.png" alt="Add Ardour to the session" width="640" height="480">
</div>
</div>
<div class="paragraph">
<p>An Ardour client appears below JACK Connections and Ardour starts up (normally directly with an empty Ardour session).</p>
</div>
<div class="paragraph">
<p>Do the same with Guitarix.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/example_session_ready.png" alt="Session ready with Ardour and Guitarix">
</div>
</div>
<div class="paragraph">
<p>In Ardour, add a track (Menu: Track → Add a track), in the Ardour window that has appeared, name the track <strong>Guitar</strong> and put the multiple choice box configuration on <em>Stereo</em>.</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/example_ardour_track.png"><img src="images/example_ardour_track.png" alt="Add a track in Ardour for Guitarix" width="640" height="480"></a>
</div>
</div>
<div class="paragraph">
<p>In your patchbay (Catia, QJackCtl or other) or in Ardour, connect the Guitarix input to a hardware input and the Guitarix outputs to the inputs of this new Ardour track. Make sure your Guitar track inputs are not connected to the hardware inputs.</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/example_catia.png"><img src="images/example_catia.png" alt="JACK patchbay with Catia"></a>
</div>
</div>
<div class="paragraph">
<p>Here you have a configuration where you can directly record the sound of your guitar processed by Guitarix in Ardour. If you don&#8217;t have a guitar, all you have to do is sing out of tune into a mic or tap a cushion, this is just an example.</p>
</div>
<div class="paragraph">
<p>Now go back to the RaySession window, and save the current session by clicking the floppy disk button to the top right (<em>or Ctrl+S</em>). It is highly recommended because it is very practical to assign a global keyboard shortcut of your system to the save of the current session. This will depend on your desktop environment, but just assign the <em>Ctrl+Meta+S</em> shortcut to the command <code>ray_control save</code> (Meta is the Windows key), so you won&#8217;t have to return to the RaySession window to save the session.</p>
</div>
<div class="paragraph">
<p>Now close the session by clicking on the red cross at the top right (<em>or Ctrl+W</em>).</p>
</div>
<div class="paragraph">
<p>Once the session is closed, click on <strong>Open Session</strong> (<em>or Ctrl+O</em>), double-click on the session you just created to re-open it.</p>
</div>
<div class="paragraph">
<p>You must find the programs and their projects as well as the JACK connections as they were when you closed the session, and everything therefore works without any further manipulation.
One of the advantages of modularity in this specific case is that once you have finished taking the guitar, you can stop Guitarix so as not to overload the processor unnecessarily, and it will still be easy to restart it if necessary.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_overview_of_session_tools">Overview of session tools</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_top_row">Top row</h3>
<div class="imageblock">
<div class="content">
<img src="images/session_top_line.png" alt="Top line of the session frame">
</div>
</div>
<div class="paragraph">
<p>From left to right:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the menu button gives you access to</p>
<div class="ulist">
<ul>
<li>
<p><strong>save the current session as a template</strong><br>
The created session template will then appear in the multiple choice of session templates in the New Session dialog window. Be careful, however, all the files of the session will be saved in the template, so you should not do this if the session contains a lot of audio files. firstly, the copy will be long, secondly, you run the risk of unnecessarily multi-copying files which will take up a lot of space.</p>
</li>
<li>
<p><strong>Duplicate the current session</strong><br>
This is the equivalent of the well-known "Save As &#8230;&#8203;", except that RaySession has to stop and restart most programs to switch between sessions. Avoid duplicating a session with a lot of audio files, it could take a long time, but fortunately such an operation can be undone.</p>
</li>
<li>
<p><strong>Rename the session</strong><br>
It will then be necessary to stop all the clients.<br>
Alternatively, you can rename a session by duplicating it and then deleting the folder from the initial session.<br>
You can also rename a session by renaming its folder, but BE CAREFUL, this session must not be loaded!</p>
</li>
</ul>
</div>
</li>
<li>
<p>the pencil-shaped button gives you access to the session notes.<br>
Write here the information you need, the physical settings, the lyrics of a song, the recipe for granny&#8217;s cassoulet &#8230;&#8203; however do not write a novel in 3 volumes, other tools are much more suitable, and notes are limited to 65,000 characters for technical reasons.
The pencil is green when notes exist, it is orange when the notes window is open, otherwise it is transparent.</p>
</li>
<li>
<p>the name of the loaded session (here <strong>my session</strong>)</p>
</li>
<li>
<p>the <strong>Abort session</strong> button which allows you to close the session without saving it</p>
</li>
<li>
<p>the <strong>Close session</strong> button ,which saves and closes the current session.<br>
Note that you do not need to close the current session to start another. Some clients are able to switch from one session to another and it may take a lot less time than closing everything and restarting everything.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_bottom_row">Bottom row</h3>
<div class="imageblock">
<div class="content">
<img src="images/session_bottom_line.png" alt="Bottom line of the session frame">
</div>
</div>
<div class="paragraph">
<p>From left to right:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the folder-shaped button to open the session folder with your file manager</p>
</li>
<li>
<p>the yellow star-shaped button that pulls down a menu containing your favorite applications if there are any</p>
</li>
<li>
<p>the <strong>Application</strong> button which allows you to add to the session a factory application template or that you have created yourself. This is the recommended method for adding a client. see <a href="#add_application">Add application window</a>.</p>
</li>
<li>
<p>the <strong>Executable</strong> button which allows a program to be added to the session from its executable. You will need it if you want to add a program for which there is no template. see <a href="#add_executable">Add executable window</a>.</p>
</li>
<li>
<p>the reverse button to return to a previous state of the session. This requires having the program <code>git</code> installed, else this button will not appears.<br>
See <a href="#snapshots">Snapshots</a> for more details.</p>
</li>
<li>
<p>the server status indicator.<br>
Server states can actually be very stealthy, but they are displayed for a long enough time that you can see them.
The server status can be:</p>
<div class="ulist">
<ul>
<li>
<p><strong>off</strong>: no session loaded</p>
</li>
<li>
<p><strong>ready</strong>: the session is running</p>
</li>
<li>
<p><strong>launch</strong>: launch of the session&#8217;s programs</p>
</li>
<li>
<p><strong>copy</strong>: a copy is in progress, for a session duplication or to save the session as a template</p>
</li>
<li>
<p><strong>close</strong>: the session is closing</p>
</li>
<li>
<p><strong>snapshot</strong>: A snapshot of the session is being taken, so you can revert to the current session state.<br>
see <a href="#snapshots">Snapshots</a>.</p>
</li>
<li>
<p><strong>wait</strong>: The server waits for you to close yourself non-saveable programs</p>
</li>
<li>
<p><strong>script</strong>: a script is activated</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>An information or progress window is displayed if you click this status indicator if it is on <strong>copy</strong> , <strong>snapshot</strong>, or <strong>wait</strong>.</p>
</div>
</li>
<li>
<p>the <strong>Save Session</strong> button</p>
</li>
<li>
<p>the trash, here you will find the clients that you have deleted. You can then restore them in the session or permanently delete all the files they created in the session folder.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_overview_of_a_client">Overview of a client</h2>
<div class="sectionbody">
<div class="imageblock">
<div class="content">
<img src="images/client_carla.png" alt="trame d&#8217;un client">
</div>
</div>
<div class="paragraph">
<p>A client contains from left to right:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The client icon that you can click to bring up a menu with the following actions</p>
<div class="ulist">
<ul>
<li>
<p><strong>Save as application template</strong><br>
The created template will then appear in the <a href="#add_application">Add application window</a>. This then allows you to directly launch a client with the desired configuration (Ardour with such tracks, Hydrogen with such drumkit…). Be careful, this copies all the client&#8217;s files so avoid doing this if the client contains a lot of audio files.</p>
</li>
<li>
<p><strong>Rename</strong><br>
Change the client name located to the right of its icon, it is a purely visual name that can help you organize yourself.</p>
</li>
<li>
<p><strong>return to a previous state</strong><br>
Returns only the client to a previous session state, see <a href="#snapshots">Snapshots</a>.<br>
However, you will not be able to go back to a state prior to a session renaming, so you must go back the entire session.</p>
</li>
<li>
<p><strong>Properties</strong><br>
Displays the client properties window</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This menu is also accessible by right-clicking anywhere on the client.</p>
</div>
</li>
<li>
<p>The name of the client (here Carla), which can be easily changed by right-clicking → Rename</p>
</li>
<li>
<p>depending on the type and capacity of the client you can see here</p>
<div class="ulist">
<ul>
<li>
<p>an eye (possibly crossed out), this means that the client is NSM compatible and is capable to show or hide its window by clicking on the eye.</p>
</li>
<li>
<p>a <strong>Hack</strong> button, it means that the client is not NSM compatible, or at least that it is not launched with this protocol. Clicking on <strong>Hack</strong> allows to change the way it is launched by opening the client properties window on the Ray-Hack tab.</p>
</li>
</ul>
</div>
</li>
<li>
<p>The Start button which is grayed out if the client is already started.</p>
</li>
<li>
<p>the Stop button which is grayed out if the client is not started.<br>
If you stop the client and it is still not stopped after a while, the button turns red and you can click on it to kill the client. But stay relaxed, and only use it if it really seems completely inert, it could cause problems, even if nobody will send you to jail.</p>
</li>
<li>
<p>the state of the client which can be</p>
<div class="ulist">
<ul>
<li>
<p><strong>stopped</strong>: the client is stopped</p>
</li>
<li>
<p><strong>ready</strong>: the client is running and everything is ok</p>
</li>
<li>
<p><strong>open</strong>: the program is opening its project, please wait a little bit.</p>
</li>
<li>
<p><strong>close</strong>: the program is closing</p>
</li>
<li>
<p><strong>launch</strong>: if it stays on the launched state, it means</p>
<div class="ulist">
<ul>
<li>
<p>if it is a Ray-Hack client, that it does not have a configuration file</p>
</li>
<li>
<p>if it is started as an NSM client, if it is not NSM compatible, and therefore any save is in vain. It may be practical to launch certain programs in this way, such as a patchbay (Catia) or a utility whose state you do not need to save (Qrest).</p>
</li>
</ul>
</div>
</li>
<li>
<p><strong>switch</strong>: the client changes projects during a session switch</p>
</li>
</ul>
</div>
</li>
<li>
<p>the floppy disk button that allows you to save the client.<br>
If over this floppy you see</p>
<div class="ulist">
<ul>
<li>
<p>three red dots: the client contains unsaved changes</p>
</li>
<li>
<p>a green V: the client does not contain unsaved changes</p>
</li>
<li>
<p>an orange exclamation mark: It is not an NSM client, and it is impossible to save its project, you will have to do it yourself</p>
</li>
</ul>
</div>
</li>
<li>
<p>the red cross which allows you to send the client to the trash</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="add_application">Add application window</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The window for adding application is launched by clicking on the <strong>Application</strong> button (<em>or Ctrl+A</em>).</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/add_application.png" alt="Add Application window">
</div>
</div>
<div class="paragraph">
<p>The list of available applications is on the right. If the software you want to add is not present here, see <a href="#add_program_not_provided">Add a program not provided</a>.</p>
</div>
<hr>
<div class="paragraph">
<p>Top left is the filter block</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/add_application_filter.png" alt="Filter block of Add Application window">
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>the filter field allows you to enter a character string, only templates containing this character string in their name will appear.</p>
</li>
<li>
<p>the <strong>Factory</strong> checkbox displays the templates integrated into RaySession or provided by your distribution</p>
</li>
<li>
<p><strong>user</strong> displays the templates created by the user by doing <strong>Save as application template</strong></p>
</li>
<li>
<p><strong>NSM</strong> displays the NSM compatible clients, or launched as such</p>
</li>
<li>
<p><strong>Ray-Hack</strong> displays clients launched without NSM protocol</p>
</li>
</ul>
</div>
<hr>
<div class="paragraph">
<p>Bottom left the information block on the selected template on the right</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/add_application_infos.png" alt="Informations block of Add Application window">
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>at the top right of this block, a star, click on it to add it to favorites or remove it from favorites</p>
</li>
<li>
<p>If it is a user template, a <strong>User</strong> button allows you to delete this template</p>
</li>
<li>
<p>the button at the bottom right of this block allows you to access all the properties of the template, as in the <a href="#client_properties">Client Properties Window</a>, except that nothing is editable.</p>
</li>
</ul>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 100%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tip:</strong> This window is designed for very fast app addition, and behaves like <em>Alt+F2</em> on your desktop.<br>
For example, from the main RaySession window, to add Carla type <em>Ctrl+A</em> , then <code>carla</code>, select the correct template with the Up/Down arrows, then Enter.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="add_executable">Add executable window</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The window for adding an executable is launched by clicking on the <strong>Executable</strong> button (<em>or Ctrl+E</em>).</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/add_executable.png" alt="Add Executable window">
</div>
</div>
<div class="paragraph">
<p>You will need to go through this window if you want to add a client that does not appear in the list of the <a href="#add_application">Add application window</a>. This window is very simple, a field to enter the executable, an <strong>NSM Protocol</strong> box, an advanced options button.</p>
</div>
<div class="paragraph">
<p>Leave the NSM protocol checked if:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the program to launch is NSM compatible (if it is not in the list of applications, please let us know!)</p>
</li>
<li>
<p>the program to run is a utility for which there is no need to save any project (QRest, Catia…).
The state of such a program will remain on <strong>launch</strong> and will never be <strong>ready</strong>, it is irrelevant since they do not have a project to save.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you leave the <strong>NSM protocol</strong> checked, it will not be possible to add an executable to an absolute path, the executable must be located in a location provided for this purpose (you will not be able to launch <code>/usr/bin/my_program</code>, but <code>my_program</code>). You cannot enter arguments here, with or without the NSM protocol.</p>
</div>
<div class="paragraph">
<p>Unchecking <strong>NSM Protocol</strong> is equivalent to launching the program with the Ray-Hack pseudo-protocol.</p>
</div>
<div class="paragraph">
<p>If you click on the <strong>advanced options</strong> button, an advanced options block appears with</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/add_executable_plus.png" alt="Advanced Add Executable window">
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>the <strong>Start the client</strong> checkbox , if you uncheck it the client will be added but not launched</p>
</li>
<li>
<p>the multiple choice box <strong>Prefix Mode</strong>, this defines the prefix of the name of the client&#8217;s files</p>
<div class="ulist">
<ul>
<li>
<p>on <strong>Session Name</strong>, the file names will start with the session name, this is the default value</p>
</li>
<li>
<p>on <strong>Client Name</strong>, the file names will begin with the name provided by the client itself, as is the case with New Session Manager</p>
</li>
<li>
<p>on <strong>Custom</strong>, the file names will start with the value you enter in the <strong>Prefix</strong> field just below.</p>
</li>
</ul>
</div>
</li>
<li>
<p>the <strong>Prefix</strong> field which is only active if <strong>Prefix Mode</strong> is set to Custom.</p>
</li>
<li>
<p>the <strong>Client ID</strong> field (client identifier). Enter only alphanumeric characters or '_'.<br>
This is useful if you want to catch and launch existing projects in the session with an executable. This is useful if you want to load in the session projects created outside a session. There is no method to make it easier, it depends a lot on the program you are using. RaySession will insult you if you enter a client ID that already exists in the session.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="client_properties">Client Properties Window</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A client&#8217;s properties window opens from the client menu by clicking Properties.</p>
</div>
<div class="paragraph">
<p>The client properties window has 2 tabs, a General tab and a tab specific to the protocol used by the client. Depending on the client protocol, the second tab is called NSM, Ray-Hack or Ray-Net.</p>
</div>
<div class="sect2">
<h3 id="_general_tab"><strong>General</strong> tab</h3>
<div class="imageblock">
<div class="content">
<img src="images/properties_general.png" alt="Client properties">
</div>
</div>
<div class="paragraph">
<p>The first block of the General tab displays the client ID, protocol, label, description and icon.<br>
If you do not edit them, the label, description and icon are taken from the .desktop file associated with the launched executable, if found.<br>
If you want to know the .desktop file used, type <code>ray_control client CLIENT_ID get_properties</code> in a terminal (replacing CLIENT_ID with the client identifier).</p>
</div>
<div class="paragraph">
<p>Then comes the block of snapshots, see <a href="#snapshots">Snapshots</a>.</p>
</div>
<div class="paragraph">
<p>The checkbox <strong>Prevent stop without recent or possible save</strong> concerns the window that may appear when you ask a client to stop. If this box is unchecked, then the client will be stopped without a window warning you.<br>
If the box is checked, the window will warn you when</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the client is unsaveable from RaySession</p>
</li>
<li>
<p>we know that the client contains unsaved changes</p>
</li>
<li>
<p>the client appears not to have been saved for more than a minute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Whether or not to check this box depends only on the importance of your client&#8217;s save, it&#8217;s up to you to judge. That said, if the warning is annoying, just check  <strong>Don&#8217;t prevent to stop this client again</strong> in the warning window and <strong>Prevent stop without recent or possible save</strong> will be unchecked.</p>
</div>
</div>
<div class="sect2">
<h3 id="_nsm_tab"><strong>NSM</strong> tab</h3>
<div class="imageblock">
<div class="content">
<img src="images/properties_nsm.png" alt="NSM Client properties">
</div>
</div>
<div class="paragraph">
<p>The <strong>Name</strong> of the client here is provided by the client himself.<br>
The <strong>capabilities</strong> are those which are transmitted by the client at its start-up. If the client has not yet been started, this field is therefore empty.</p>
</div>
<div class="paragraph">
<p>Editing the executable allows you to change the command that launches the client. Only change it to another executable capable of loading the existing client&#8217;s project. This is useful for example if you have two versions of Ardour, one running with the command <code>ardour</code>, the other with <code>Ardour6</code>, and you want to change which version to use.</p>
</div>
<div class="paragraph">
<p>Editing the arguments is strongly discouraged, and is especially not suitable for loading a file as an argument.</p>
</div>
</div>
<div class="sect2">
<h3 id="_ray_hack_tab"><strong>Ray-Hack</strong> tab</h3>
<div class="paragraph">
<p>If the client is a Ray-Hack type, here many fields are available to you. This is not necessarily good news, the idea is to be able to load a program into the session that is not (yet) compatible with NSM. If properly implemented in the client, the NSM protocol will always be much more comfortable to use and more reliable than this hack. That said, if we can expect the NSM implementation in all audio programs, this is not the case for other programs which can still be useful in the session.</p>
</div>
<div class="paragraph">
<p>The Ray-Hack pseudo-protocol uses the attributes of proxies (nsm-proxy or ray-proxy), except that the client is launched directly in the session.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/properties_ray_hack.png" alt="Ray-Hack Client properties">
</div>
</div>
<div class="sect3">
<h4 id="_launch_block">Launch block</h4>
<div class="imageblock">
<div class="content">
<img src="images/ray_hack_launch.png" alt="ray hack launch">
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>the <strong>Folder</strong> is the folder name of this client in the session folder. The program is launched from this folder.</p>
</li>
<li>
<p>the <strong>Executable</strong> is the command that starts the program</p>
</li>
<li>
<p>The <strong>Config file</strong> will be the project file that we want to open with this program. It is more than highly recommended to reference a file in the client folder.<br>
The variable <code>$RAY_SESSION_NAME</code> will be automatically replaced by the name of the session.<br>
If this field is empty, the client status will always remain <strong>launch</strong> and will never be <strong>ready</strong>. In some cases, therefore, it may be useful to type anything here rather than nothing.</p>
</li>
<li>
<p>The <strong>Browse</strong> button opens a dialog box to find the project file and fill in the <strong>Configuration file</strong> field</p>
</li>
<li>
<p>The <strong>Arguments</strong> field includes the arguments passed to the Executable command<br>
the arguments are split as they would be in a terminal, don&#8217;t forget the " or ' if necessary.<br>
For example to reproduce <code>my_command my_argument_1 "my argument 2"</code> enter <code>my_command</code> in the <strong>Executable</strong> field and <code>my_command my_argument_1 "my argument 2 "</code> in the <strong>Arguments</strong> field.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_signals_block">Signals block</h4>
<div class="imageblock">
<div class="content">
<img src="images/ray_hack_signals.png" alt="ray hack signals">
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Save Signal</strong> can be only rarely used. It can be SIGUSR1 for programs compatible with the old LASH protocol. Otherwise leave it on <em>None</em>, if there is no save method, we cannot invent it.</p>
</li>
<li>
<p><strong>Stop Signal</strong> will usually be SIGTERM. Only change it if this signal does not close the program correctly.</p>
</li>
<li>
<p>If <strong>Wait for a window before considered it ready</strong> box is checked, then the client status will only change to <strong>ready</strong> when a window appears.<br>
If <code>wmctrl</code> is not installed, or the window manager does not seem to be compatible with it, then the client status will be <strong>ready</strong> half a second after it is launched.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>With <code>ray_control</code> you can assign signals other than those offered in the multiple choice boxes. For example
<code>ray_control client CLIENT_ID set_properties save_sig:22</code>
will define the SIGTTOU signal for the client CLIENT_ID save.<br>
Type <code>kill -l</code> to see the available signals and their numbers.</p>
</div>
</div>
<div class="sect3">
<h4 id="_non_saveable_management_block">Non-saveable management block</h4>
<div class="imageblock">
<div class="content">
<img src="images/ray_hack_non_saveable.png" alt="ray hack non saveable">
</div>
</div>
<div class="paragraph">
<p>This block is active only if the <strong>Save Signal</strong> is set to <em>None</em>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>if <strong>Tell user to close program himself at session close</strong> is checked, the client will be considered as not saveable and an orange exclamation mark will appear in front of its save icon. When closing the session, RaySession will wait for you to close the program yourself because it is impossible to know if it contains unsaved changes.</p>
</li>
<li>
<p>If <strong>Try to close window gracefully</strong> is checked, then at session close, RaySession will try to close the window as if you were closing the program window. This is very useful when the program reacts by closing if there are no unsaved changes and displaying a close confirmation window in the opposite case (most programs react in this way). If <code>wmctrl</code> is not installed or the window manager does not seem to be compatible, you will have to close the program yourself in any case.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_test_area">Test area</h4>
<div class="imageblock">
<div class="content">
<img src="images/ray_hack_test_zone.png" alt="ray hack test zone">
</div>
</div>
<div class="paragraph">
<p>The test area allows you to test the start, stop, and save settings set in this window without having to <strong>Save the changes</strong>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_network_sessions">Network Sessions</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A network session allows you to launch another session on another machine at the same time as your session. This can be particularly useful if you are using net-jack to unload your machine from part of the DSP, if you have greedy effects running on another machine for example.</p>
</div>
<div class="paragraph">
<p>Network sessions operate on a master-to-slave basis. A session is master and can have several slave sessions which are themselves masters of other slaves, but such a scenario seems completely out of the ordinary. Organize yourself simply: one master, one or more slave(s).</p>
</div>
<div class="paragraph">
<p>To launch a network session (therefore a slave), launch the <strong>Network Session</strong> application template from the applications window and follow the instructions.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/network_session_template.png" alt="Add a network session">
</div>
</div>
<div class="paragraph">
<p>You will have to start a daemon on the remote machine with the command <code>ray-daemon -p 1234</code> (<code>1234</code> is an example, put the port you want). This daemon displays something like this in the terminal:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>[ray-daemon]URL : osc.udp://192.168.1.00:1234/`
[ray-daemon]      osc.udp://nom-de-machine:1234/`
[ray-daemon]ROOT: /home/utilisateur/Ray Sessions reseau</code></pre>
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="images/network_session_invitation.png" alt="Configure a network session">
</div>
</div>
<div class="paragraph">
<p>You will need to copy one of the two URLs into the network session invitation window. The first (which begins with osc.udp://192.168.) must work for sure, the second will work only if the name of the slave machine is correctly entered in the file <code>/etc/hosts</code> of the master machine. However, entering the name of the slave machine in <code>/etc/hosts</code> and using the second URL is preferable, because the address in 192.168. will move if you connect your slave machine differently (wired, wifi), or if you reinstall the distribution.</p>
</div>
<div class="paragraph">
<p>You now have 2 RaySession windows on your master machine, one controls the master session, the other the slave. You will recognize the slave by the fact that it does not have a toolbar (<strong>New Session</strong>, <strong>Open Session</strong>, <strong>Control</strong>), nor <strong>Abort session</strong> and <strong>Close session</strong> buttons.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/network_session_child.png" alt="network session child">
</div>
</div>
<div class="paragraph">
<p>The slave window is hideable as is the case in many NSM programs.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/network_session_client.png" alt="network session client">
</div>
</div>
<div class="paragraph">
<p>If you run <code>raysession -p 1234</code> on your slave machine, you will have the slave session window in duplicate, one on each machine.</p>
</div>
<div class="paragraph">
<p><strong>Tip:</strong> Put this <code>ray-daemon -p 1234</code> in your slave machine startup.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="add_program_not_provided">Add a program not provided</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If the program you want to add does not manage a project to save, click on <strong>Executable</strong>, enter the name of the executable and click on <strong>Ok</strong>. Otherwise follow this example.</p>
</div>
<div class="paragraph">
<p>We want to add Audacity to the session here. Audacity is chosen as an example because it is known and generally installed on audio distributions. This is not necessarily a very suitable program for the modularity of an audio session given the way it handles JACK.</p>
</div>
<div class="paragraph">
<p>Click <strong>Executable</strong> (<em>or Ctrl+E</em>).
In the <a href="#add_executable">Add executable window</a>, Uncheck the <strong>NSM Protocol</strong> box, type <code>audacity</code> in the <strong>Executable</strong> field and click <strong>Ok</strong>.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/audacity_executable.png" alt="Add Executable window well done">
</div>
</div>
<div class="paragraph">
<p>A new client is created, its properties window opens on the <strong>Ray-Hack</strong> tab and Audacity is launched.</p>
</div>
<div class="paragraph">
<p>In Audacity, we will directly save an empty project in the client&#8217;s folder. The client&#8217;s folder is located in the session folder and has the name given after <strong>Folder:</strong> at the top of the <strong>Ray-Hack</strong> tab. We will call the project EXACTLY like the current RaySession session. To do this, in Audacity, go to <em>Menu → File → Save project → Save project</em>.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/audacity_save%20project.png" alt="Save empty Audacity project">
</div>
</div>
<div class="paragraph">
<p>Click <strong>Validate</strong> at the possible warning window.<br>
In the save files box that opens, you will find the session folder at the bottom left (see <a href="#session_folder_shortcuts">Provide bookmarks for session folder</a>), click on it to enter it. Inside this you should see the client&#8217;s folder as it appears at the top of the Ray-Hack tab, enter this folder. At the top left of the backup box, type the exact name of your session in the <strong>Name:</strong> field then validate.</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/audacity_save_file.png"><img src="images/audacity_save_file.png" alt="Where to save Audacity project" width="640" height="480"></a>
</div>
</div>
<div class="paragraph">
<p>Close Audacity.<br>
At the top right of the <strong>Ray-Hack</strong> tab of the client properties window, click <strong>Browse</strong>.</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/audacity_load_config_file.png"><img src="images/audacity_load_config_file.png" alt="Load CONFIG_FILE window" width="640" height="480"></a>
</div>
</div>
<div class="paragraph">
<p>select the Audacity project you just created, its name starts with the session name and ends with .aup.</p>
</div>
<div class="paragraph">
<p>If all went well, the <strong>Configuration File</strong> field became <code>$RAY_SESSION_NAME.aup</code> and the <strong>Arguments</strong> field became <code>"$CONFIG_FILE"</code>.<br>
Check the boxes <strong>Wait for a window before being considered ready</strong>, <strong>Ask the user to close the program himself</strong> and <strong>Try to close the window gracefully</strong>. Click in the bottom right corner on <strong>Save Changes</strong>.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/audacity_ray_hack_final.png" alt="Ray-Hack tab of Audacity client well done">
</div>
</div>
<div class="paragraph">
<p>Launch the Audacity client and verify that the Audacity window has the name of the session.<br>
Click on the Audacity client icon, in the drop-down menu choose <strong>Save as an application template</strong>, and enter <code>Audacity</code> the field of the dialog box that has appeared. Now when you want to launch Audacity in the session, all you have to do is launch the Audacity template from the <a href="#add_application">Add application window</a>.</p>
</div>
<div class="paragraph">
<p>Note that the client&#8217;s save button is behind an orange exclamation point, this means that RaySession is not able to save its project and that you will have to do it yourself.</p>
</div>
<div class="paragraph">
<p>Depending on what program you want to add to the session, it might not always be that easy. Some programs will require an argument that precedes the configuration file, in this case type <code>my_program --help</code> or <code>man my_program</code> to know how to load a project when the program starts, and adapt this in the <strong>Arguments</strong> field.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_import_an_nsm_session">Import an NSM session</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To import a session created with Non Session Manager or New Session Manager, move or copy the session folder to the RaySession root sessions folder (default ~/Ray Sessions). Then click <strong>Open session</strong>, your session should appear in the list of sessions, double-click on it.</p>
</div>
<div class="paragraph">
<p>RaySession will not rewrite clients added or deleted to the <code>session.nsm</code> file, as long as you open an NSM session with RaySession you must continue with RaySession.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_the_daemons_options">The daemon&#8217;s options</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Daemon options are services which can be activated and deactivated via the <strong>Control</strong> button at the top right of the main window, or via the options menu in the menu bar.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/daemon_options.png" alt="Daemon options">
</div>
</div>
<div class="paragraph">
<p>Here is the detail of the different options:</p>
</div>
<div class="sect2">
<h3 id="session_folder_shortcuts">Provide bookmarks for session folder</h3>
<div class="paragraph">
<p>In audio production, it is often used to create an audio or midi file with one program and then load it into another. This option offers something purely practical: a shortcut to the current session folder in your file manager and in the dialog boxes provided for fetching or saving files. It simply avoids wasting time browsing through your personal folder tree to find a file that you have put in your session folder, since that is where it belongs.<br>
Of course, this shortcut is deleted when the session is unloaded.<br>
Technically, shortcuts are created for GTK2, GTK3, QT4, QT5, KDE and FLTK.</p>
</div>
</div>
<div class="sect2">
<h3 id="_auto_snapshot_at_save">Auto Snapshot at Save</h3>
<div class="paragraph">
<p>This option is far from being trivial, it allows you to take a snapshot of the session after each session save. This means that in case of a technical or artistic error you will be able to find the session in the state it was in at the moment of the snapshot. This option requires that you have the <code>git</code> program installed. See <a href="#snapshots">Snapshots</a> for more details.</p>
</div>
</div>
<div class="sect2">
<h3 id="_desktops_memory">Desktops Memory</h3>
<div class="paragraph">
<p>If this option is activated, RaySession will save (or attempt to save) the number of the virtual desktop on which the client windows were located when the session was saved.
So when you restart the session or the clients, the windows will be redispatched to the desktops on which they appeared.
This option requires you to have the program <code>wmctrl</code> installed to work, and probably will not work with Wayland.</p>
</div>
</div>
<div class="sect2">
<h3 id="_session_scripts">Session scripts</h3>
<div class="paragraph">
<p>Disable this option to not activate any session script, and thus open, save or close a session completely ignoring the scripts associated with these actions.
These scripts are used by sessions with <a href="#jack_configuration_memory">JACK configuration memory</a>.
See <a href="#session_scripts">Session scripts</a> for more details.</p>
</div>
</div>
<div class="sect2">
<h3 id="_remember_optional_gui_states">Remember optional GUI states</h3>
<div class="paragraph">
<p>This option only concerns NSM clients capable of showing/hiding their graphical interface. Without this option, some of them will always start hidden, others will remember if they were visible when they were last saved. With this option enabled, the graphical interfaces will be displayed when the session is ready if they were visible during the last save or if the client has never been launched.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="snapshots">Snapshots</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Snapshots require you to have the program <code>git</code> installed, if you don&#8217;t have <code>git</code>, the reverse button does not appear and it is not possible to take or return to a snapshot.</p>
</div>
<div class="paragraph">
<p>A snapshot stores files and their contents at a specific time. Large files and files with certain extensions such as audio and video files are ignored, otherwise the snapshot process will take too long and the size of the session folders will needlessly double. This is actually not very annoying, on the contrary, since your recent audio files remain present when you go back to a previous snapshot.<br>
If despite everything the snapshot process turns out to be long, a window appears and you can safely cancel the current snapshot. If you cancel it, the automatic snapshot will no longer take place for this session.</p>
</div>
<div class="paragraph">
<p>The interest of the snapshots lies in the fact of being able to return to the previous moment of the session, before having had this brilliant artistic idea which turned out to be null and void, before having attempted a recutting of the samples with the microcoscope which finally killed all forms of musicality, before a program crashes for some reason unknown to the police&#8230;&#8203;</p>
</div>
<div class="paragraph">
<p>Don&#8217;t worry, going back to a snapshot won&#8217;t stop you from getting back to where you were.</p>
</div>
<div class="paragraph">
<p>To revert the session to a snapshot, click the reverse button located to the right of the <strong>Executable</strong> button.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/snapshots.png" alt="snapshots">
</div>
</div>
<div class="paragraph">
<p>Select the snapshot you want to revert to and click <strong>Ok</strong>. A new snapshot is taken, the session closes, the desired snapshot is recalled and the session reopens.</p>
</div>
<div class="paragraph">
<p>It is also possible to return only a client to a previous state of the session by right-clicking on the client,then <strong>Return to a previous state</strong>.
If you want you can edit for each client the files ignored by the snapshots in the <a href="#client_properties">Client Properties Window</a>.</p>
</div>
<div class="paragraph">
<p>With the <strong>Automatic snapshot after save</strong> option, a snapshot is taken immediately after each backup of the session, unless there is no change since the previous snapshot. To take a snapshot at another time, click on the reverse icon to the right of the <strong>Executable</strong> button and on <strong>Take a snapshot now</strong>, this has the advantage of being able to name the snapshot and thus having a more meaningful time mark than the date and time of the snapshot.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="session_scripts">Session scripts</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Session scripts allow you to program personalized actions when opening, saving and closing the session. They are used in particular for sessions with <a href="#jack_configuration_memory">JACK configuration memory</a>.<br>
Knowledge of shell scripting is required to edit these scripts, but anyone can use them.</p>
</div>
<div class="paragraph">
<p>Session scripts are located in a folder <code>ray-scripts</code> located either in a session folder or in a parent folder.<br>
For example, for a session being in:<br>
<code>~/Ray Sessions/avec_script_de_foo/ma session</code></p>
</div>
<div class="paragraph">
<p>the session scripts folder may be</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>~/Ray Sessions/avec_script_de_foo/ma session/ray-scripts
~/Ray Sessions/avec_script_de_foo/ray-scripts
~/Ray Sessions/ray-scripts
~/ray-scripts</code></pre>
</div>
</div>
<div class="paragraph">
<p>The advantage of such behavior is to be able to script a set of sessions without having to copy the scripts there, but above all to deliver an unscripted session when it is transferred to someone else for collective work.<br>
Only the script folder closest to the session in the tree will be considered. Thus, a <code>ray-scripts</code> empty folder in a session will disable scripts for that session.</p>
</div>
<div class="paragraph">
<p>To edit the scripts, start by creating a session with the template with the basic scripts, this is a template session with scripts that does not include any particular action. Go to the folder <code>ray-scripts</code> in the session folder, you will find the files <code>load.sh</code>, <code>save.sh</code> and <code>close.sh</code>. In each of these scripts, <code>ray_control run_step</code> corresponds to the normal action performed (depending on the script: load, save or close the session). If one of these three scripts is of no use to you, delete it, it will save time not to go through that script.</p>
</div>
<div class="paragraph">
<p>The script files must imperatively be executable to work.</p>
</div>
<div class="paragraph">
<p>You will probably need the command line utility <code>ray_control</code> to perform actions relating to a particular client. type <code>ray_control --help</code> to know all its possibilities, see also <a href="#ray_control">Control RaySession from the command line</a>.</p>
</div>
<div class="paragraph">
<p>JACK memory configuration session template uses session scripts, but we can also imagine many possible actions according to your needs and desires, for example:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>define a specific order for launching clients when the session is opened (an example is provided in the source code)</p>
</li>
<li>
<p>make a backup copy of the session on an external hard drive each time you close it</p>
</li>
<li>
<p>send a <em>Ctrl+S</em> shortcut to non-saveable client windows when saving the session (an example is provided in the source code)</p>
</li>
<li>
<p>Turn on the red light at the entrance to the studio when opening, turn it off when closing</p>
</li>
<li>
<p>Start the coffee machine at the end of the session (stupid example, go and press the button on the coffee maker, anyway you will have to change the filter!)</p>
</li>
<li>
<p>Make many, many, many mistakes that will crash your session, be careful of course!</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="jack_configuration_memory">JACK configuration memory</h2>
<div class="sectionbody">
<div class="paragraph">
<p>It is possible thanks to session scripts to automatically recall the JACK configuration specific to a session before loading it. This behavior may remind some of the operation of LADISH studios, much better done, at least that&#8217;s what is hoped.</p>
</div>
<div class="sect2">
<h3 id="_in_which_cases_to_use_it">In which cases to use it</h3>
<div class="paragraph">
<p>This can be useful:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If you need to use a specific audio interface for the session</p>
</li>
<li>
<p>If you are working on multiple projects with different sample rates (such session at 44100 Hz, such session at 48000 Hz).<br>
This will prevent you from having to reconfigure, stop and restart JACK yourself, or even avoid forgetting to do so and being insulted by certain programs.</p>
</li>
<li>
<p>If you want to avoid loading a very DSP-intensive session (for example in the mixing phase) with a too small buffer (128 for example).<br>
Note that on most audio interfaces it is possible to change the buffer size hotly (without restarting JACK).</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_usage">Usage</h3>
<div class="paragraph">
<p>The Session scripts option must be enabled (This option is enabled by default).</p>
</div>
<div class="paragraph">
<p>To use the JACK configuration memory, create a new session from the <strong>With JACK configuration memory</strong> template.
It is in fact a scripted session (see <a href="#session_scripts">Session scripts</a>) which launches a script supplied with RaySession, but which is completely external to it, so RaySession still has no direct relation to JACK.</p>
</div>
<div class="paragraph">
<p>Read the information window on this subject then validate. JACK restarts then your session starts.</p>
</div>
</div>
<div class="sect2">
<h3 id="_working_principle">Working principle</h3>
<div class="paragraph">
<p>Each time the session is saved, the JACK configuration is saved in the session, in the <code>jack_parameters</code> file.<br>
Before opening the session, JACK is restarted if the configuration of the session is different from the current configuration of JACK.<br>
After closing the session, JACK is restarted if necessary with the current configuration before opening.<br></p>
</div>
<div class="paragraph">
<p>The configuration of the PulseAudio → JACK bridges is also saved and restored with the JACK configuration.</p>
</div>
<div class="paragraph">
<p>If you open this session after having copied it to another computer, the JACK configuration will not be recalled but will be overwritten when saving. Only the sampling frequency of the session will be used.</p>
</div>
</div>
<div class="sect2">
<h3 id="_special_cases">Special cases</h3>
<hr>
<div class="paragraph">
<p><strong>To open a session without reloading its configuration from JACK:</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>disable the <strong>Session scripts</strong> option</p>
</li>
<li>
<p>open the session</p>
</li>
</ul>
</div>
<hr>
<div class="paragraph">
<p><strong>To change the JACK configuration of a session:</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>Start JACK with the desired configuration</p>
</li>
<li>
<p>Disable the Session scripts option</p>
</li>
<li>
<p>Open the session</p>
</li>
<li>
<p>Re-enable the Session scripts option</p>
</li>
<li>
<p>Save the session</p>
</li>
</ul>
</div>
<hr>
<div class="paragraph">
<p><strong>To make an old session sensitive to the configuration of JACK</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>copy the folder <code>ray-scripts</code> of a session with memory from the JACK configuration to the session folder</p>
</li>
<li>
<p>Activate the Session scripts option</p>
</li>
<li>
<p>Open the session</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><strong>or</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>move the session to a sub-folder containing the good one <code>ray-scripts</code> folder</p>
</li>
<li>
<p>Open the session</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="under_the_hood">Under the hood</h2>
<div class="sectionbody">
<div class="paragraph">
<p>RaySession is really just a GUI for ray-daemon. When you launch RaySession, the GUI launches and connects to the daemon, and it stops the daemon when closed. The graphical interface and the daemon communicate with each other by OSC (Open Sound Control) messages, as is the case between the daemon and the NSM clients. Thus, you can connect several graphical interfaces to a daemon, even remotely. Tap <code>raysession --help</code> to see how.</p>
</div>
<div class="paragraph">
<p>It is not forbidden to have several daemon instances launched simultaneously, so if you launch RaySession while an instance is already launched, it will launch a new daemon. However, this way of working being unusual, the use of a single daemon is favored. So, if a daemon is running and it has no GUI attached, raysession will connect to that daemon by default.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="ray_control">Control RaySession from the command line</h2>
<div class="sectionbody">
<div class="paragraph">
<p>the command <code>ray_control</code> lets you do just about anything you can do with the GUI, and a little more. type <code>ray_control --help-all</code> to know all the possibilities.</p>
</div>
<div class="paragraph">
<p>In case there are multiple daemons started (see <a href="#under_the_hood">Under the hood</a>), <code>ray_control</code> will only consider the one that was started first, unless you specify its OSC port with the <code>--port</code> option or <code>RAY_CONTROL_PORT</code> environment variable.</p>
</div>
<div class="paragraph">
<p>One might think that there is no point in using <code>ray_control</code> since the command <code>oscsend</code> allows to send an OSC message to the daemon, it is false.<br>
Firstly, because <code>oscsend</code> allows you to send messages but not to obtain information in a simple way (which are the active clients? What is the executable of such and such client? &#8230;&#8203;), secondly, because the command <code>ray_control</code> will end when the requested action is taken, for example <code>ray_control open_session "my session"</code> will end when the session is loaded.</p>
</div>
<div class="paragraph">
<p>Remember to assign <code>ray_control save</code> to a global shortcut of your desktop environment (<em>Ctrl+Meta+S</em>), this will save you a lot of time!</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_frequently_asked_questions">Frequently Asked Questions</h2>
<div class="sectionbody">
<div class="paragraph">
<p><strong>Is it still worth running Ardour (or another NSM compatible DAW) directly rather than in RaySession?</strong></p>
</div>
<div class="paragraph">
<p>Except for a really tiny project, no.
If you are using Ardour, always run it from RaySession, firstly, the automatic snapshot after save can be of unexpected help to you, secondly, you are not immune to needing another program even if you did not plan it.</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2020-11-13 18:58:39 +0100
</div>
</div>
</body>
</html>