--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/relpipe-data/examples-jack-ports.xml Thu Oct 22 01:51:32 2020 +0200
@@ -0,0 +1,170 @@
+<stránka
+ xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
+ xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
+
+ <nadpis>Working with JACK ports</nadpis>
+ <perex>list ports and connections, connect and disconnect ports, both MIDI and audio</perex>
+ <m:pořadí-příkladu>04400</m:pořadí-příkladu>
+
+ <text xmlns="http://www.w3.org/1999/xhtml">
+
+ <p>
+ A powerful audio system called <a href="https://jackaudio.org/">JACK</a> allows us to
+ build pipelines consisting of audio interfaces, players, recorders, filters and effects…
+ and route sound streams (both PCM and MIDI) through them.
+ MIDI messages can come from keyboards or other hardware MIDI controllers or from MIDI players and other software.
+ </p>
+
+ <p>
+ In JACK, we have <em>clients</em> (applications) and they have <em>ports</em> (input and output channels).
+ The JACK graph consists of connections between input and output ports.
+ There might be multiple connections from or to a single port – singals are then replicated or combined.
+ Obviously, we can connect MIDI ports only to other MIDI ports and PCM/audio ports only to other ports of the same kind.
+ However there can be applications with both kinds of ports that e.g. translate MIDI signal to audio signal (synthesizers).
+ </p>
+
+ <m:img src="img/jack-connections-2.png"/>
+
+ <p>
+ The JACK <em>daemon</em> is responsible for maintaining the graph and transmitting the messages.
+ Clients connect to the <em>daemon</em>.
+ </p>
+
+ <p>
+ Since <m:a href="release-v0.17">v0.17</m:a>, we can list the ports using the <code>relpipe-in-jack</code> command:
+ </p>
+
+ <m:pre jazyk="bash"><![CDATA[relpipe-in-jack --list-ports true --list-midi-messages false | relpipe-out-tabular]]></m:pre>
+
+ <p>and see it as a relation:</p>
+
+ <pre><![CDATA[port:
+ ╭───────────────────────────────────┬───────────────┬─────────────────┬──────────────────┬────────────────────┬────────────────────┬────────────────┬────────────────┬─────────────────────────╮
+ │ name (string) │ uuid (string) │ input (boolean) │ output (boolean) │ physical (boolean) │ terminal (boolean) │ mine (boolean) │ midi (boolean) │ type (string) │
+ ├───────────────────────────────────┼───────────────┼─────────────────┼──────────────────┼────────────────────┼────────────────────┼────────────────┼────────────────┼─────────────────────────┤
+ │ system:capture_1 │ │ false │ true │ true │ true │ false │ false │ 32 bit float mono audio │
+ │ system:capture_2 │ │ false │ true │ true │ true │ false │ false │ 32 bit float mono audio │
+ │ system:playback_1 │ │ true │ false │ true │ true │ false │ false │ 32 bit float mono audio │
+ │ system:playback_2 │ │ true │ false │ true │ true │ false │ false │ 32 bit float mono audio │
+ │ j2a_bridge:playback │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ relpipe-in-jack_processed:midi-in │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ relpipe-out-jack:midi-out │ │ false │ true │ false │ false │ false │ true │ 8 bit raw midi │
+ │ a2j_bridge:capture │ │ false │ true │ false │ false │ false │ true │ 8 bit raw midi │
+ │ yoshimi:left │ │ false │ true │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ yoshimi:right │ │ false │ true │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ yoshimi:midi in │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ Qtractor:Master/in_1 │ │ true │ false │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ Qtractor:Master/in_2 │ │ true │ false │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ Qtractor:Master/out_1 │ │ false │ true │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ Qtractor:Master/out_2 │ │ false │ true │ false │ false │ false │ false │ 32 bit float mono audio │
+ │ qmidiarp:in │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ qmidiarp:out 1 │ │ false │ true │ false │ false │ false │ true │ 8 bit raw midi │
+ │ qmidiarp:out 2 │ │ false │ true │ false │ false │ false │ true │ 8 bit raw midi │
+ │ jack-keyboard:midi_out │ │ false │ true │ false │ false │ false │ true │ 8 bit raw midi │
+ │ jack-keyboard:midi_in │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ relpipe-in-jack_original:midi-in │ │ true │ false │ false │ false │ false │ true │ 8 bit raw midi │
+ │ relpipe-in-jack:midi-in │ │ true │ false │ false │ false │ true │ true │ 8 bit raw midi │
+ ╰───────────────────────────────────┴───────────────┴─────────────────┴──────────────────┴────────────────────┴────────────────────┴────────────────┴────────────────┴─────────────────────────╯
+Record count: 22]]></pre>
+
+ <p>
+ Port names are prefixed with the names of clients.
+ We see the port direction in the <code>input</code> and <code>output</code> attributes
+ and can distinguish MIDI and audio ports by the value of the <code>midi</code> attribute.
+ </p>
+
+ <p>
+ We can also list the connections using the <code>--list-connections true</code> option:
+ </p>
+
+ <pre><![CDATA[connection:
+ ╭────────────────┬───────────────────────────┬───────────────────────────────────╮
+ │ event (string) │ source_port (string) │ destination_port (string) │
+ ├────────────────┼───────────────────────────┼───────────────────────────────────┤
+ │ connect │ system:capture_1 │ Qtractor:Master/in_1 │
+ │ connect │ system:capture_2 │ Qtractor:Master/in_2 │
+ │ connect │ relpipe-out-jack:midi-out │ qmidiarp:in │
+ │ connect │ relpipe-out-jack:midi-out │ relpipe-in-jack_original:midi-in │
+ │ connect │ yoshimi:left │ system:playback_1 │
+ │ connect │ yoshimi:right │ system:playback_2 │
+ │ connect │ Qtractor:Master/out_1 │ system:playback_1 │
+ │ connect │ Qtractor:Master/out_2 │ system:playback_2 │
+ │ connect │ qmidiarp:out 1 │ yoshimi:midi in │
+ │ connect │ qmidiarp:out 1 │ relpipe-in-jack_processed:midi-in │
+ │ connect │ jack-keyboard:midi_out │ qmidiarp:in │
+ │ connect │ jack-keyboard:midi_out │ relpipe-in-jack_original:midi-in │
+ ╰────────────────┴───────────────────────────┴───────────────────────────────────╯
+Record count: 12]]></pre>
+
+ <p>
+ Instead of formatting as a table, we can direct this relation into a file and later recreate the saved connections:
+ </p>
+
+ <m:pre jazyk="bash"><![CDATA[relpipe-in-jack --list-connections true --list-midi-messages false > connections.rp
+cat connections.rp | relpipe-out-jack --required-connections 0]]></m:pre>
+
+ <p>
+ If we want to store the connections in a human readable format in order to be able to edit them,
+ we should add e.g. <code>relpipe-out-csv</code> (or XML, or Recfile) stage before redirecting the stream to the file
+ and add <code>relpipe-in-csv</code> etc. stage to the second pipeline.
+ </p>
+
+ <pre><![CDATA["event","source_port","destination_port"
+"connect","system:capture_1","Qtractor:Master/in_1"
+"connect","system:capture_2","Qtractor:Master/in_2"
+"connect","relpipe-out-jack:midi-out","qmidiarp:in"
+"connect","relpipe-out-jack:midi-out","relpipe-in-jack_original:midi-in"
+"connect","yoshimi:left","system:playback_1"
+"connect","yoshimi:right","system:playback_2"
+"connect","Qtractor:Master/out_1","system:playback_1"
+"connect","Qtractor:Master/out_2","system:playback_2"
+"connect","qmidiarp:out 1","yoshimi:midi in"
+"connect","qmidiarp:out 1","relpipe-in-jack_processed:midi-in"
+"connect","jack-keyboard:midi_out","qmidiarp:in"
+"connect","jack-keyboard:midi_out","relpipe-in-jack_original:midi-in"]]></pre>
+
+
+ <p>
+ Or we can write the file by hand and just send it to the JACK output module:
+ </p>
+
+ <m:pre jazyk="bash"><![CDATA[cat connections.csv | relpipe-in-csv | relpipe-out-jack --required-connections 0]]></m:pre>
+
+ <p>
+ The primary purpose of the <code>relpipe-out-jack</code> is sending MIDI messages.
+ And because it does not make much sense to send them nowhere, it waits for at least one connection.
+ But if we are not sending any messages and are using this tool just to connect or disconnect the ports,
+ we should set <code>--required-connections 0</code>.
+ </p>
+
+ <p>
+ We can also connect or disconnect particular ports specified on the command line:
+ </p>
+
+ <m:pre jazyk="bash"><![CDATA[relpipe-in-jack --connect-ports "a2j_bridge:capture" "qmidiarp:in" --list-midi-messages false]]></m:pre>
+
+ <p>
+ The primary purpose of the <code>relpipe-in-jack</code> command is monitoring the MIDI commands.
+ If we want just to connect or disconnect some ports, we can disable monitoring by setting <code>--list-midi-messages false</code>
+ and the command will return immediately.
+ </p>
+
+ <p>
+ The port names are suggested by the Bash-completion, so we do not have to memorize them.
+ Because these names contain the colon, we should use quotes (otherwise the Bash-completion may be confused).
+ </p>
+
+ <p>
+ Disconnecting works the same way – just use the <code>--disconnect-ports</code> option
+ or specify the <code>disconnect</code> command in the <code>event</code> attribute.
+ </p>
+
+ <p>
+ Note: there are sophisticated GUI tools focused on working with the JACK graph
+ like <a href="https://qjackctl.sourceforge.io/">QjackCtl</a> or <a href="https://kx.studio/Applications:Claudia">KXStudio/Claudia</a>.
+ But sometimes it is useful to have a simple CLI tool for this job.
+ </p>
+
+ </text>
+
+</stránka>