A Hands-On Introduction to Pakt.

Prerequisites:
	- You need pakt, preferably a later version like 0.3.2, installed.
	- For the 'paktc' thing in the last paragraphs, you'd also need at least the 'gtk/' and 'control/' parts of the 'glasnost' experimental distro. These will be packaged with the standard pakt distro soon, i guess...
	- You should also know a little about GStreamer/gst-launch. If you don't, read up in the GStreamer documentation and experiment with some simple pipelines first.


Hello.

So you managed to compile and install this beasty pakt thing and now what? You probably know that you can use it to run GStreamer pipelines, but how?

Well, like so:
	> paktd --gst 'videotestsrc ! xvimagesink'
	
This should start a 'pakt daemon' that runs the specified (simple) pipeline that should open a video window with the well-known a test image. Also you should get the Message
	[General message] Loaded module: gst 0.3.3pre2 (GStreamer)
which informs you that the gst pakt module was loaded.

So you ask: How is this different from gst-launch, except for the strange --gst '...' syntax? And I answer: mainly that this pakt daemon now not only runs the pipeline, but also represents it as XML to network clients on the default port (which is, for historical reasons, 1955).

Your generic pakt client is 'pash'- the pakt shell. Simply starting it will try to connect to localhost on port 1955, and if you have the last command still running, you should be connected to this paktd. Type "get" to see a shallow representation of the hierarchy that paktd is representing:

	> pash
	
	[ pash ] the pakt shell 0.3.3pre2
			 (c) 2k3 daniel fischer <dan@subsignal.org>
			 Protected by the GPL. NO WARRANTY.
	
	[General message] client connected
	/ get
	
	<p:root xmlns:p="http://subsignal.org/pakt/p/" xmlns:gst="http://subsignal.org/pakt/gst/" name="root">
	  <p:system name="system"/>
	  <p:module name="gst"/>
	  <gst:thread name="thread0"/>
	</p:root>

Let's ignore the p:system and p:module tags for now, but note that this snippet of XML has two namespaces defined: 'p' for general Pakt things and 'gst' for gstreamer 'elements'. We're highly interested in the gst:thread thing and wonder if there's anything inside. So we do:
	/ cd thread0/
	/thread0/ get
	
	<gst:thread xmlns:gst="http://subsignal.org/pakt/gst/" name="thread0" priority="NORMAL" state="STATE_PLAYING">
	  <gst:videotestsrc name="videotestsrc0"/>
	  <gst:xvimagesink name="xvimagesink0"/>
	</gst:thread>
	
	/thread0/
	
So, with pash, you can navigate around the XML hierarchy on the server with the shell-like 'cd'. We're not really talking 'directories' here, but i think if you got the ideas of a file hierarchy and an XML node hierarchy, you will see the similarities... You can change to a 'current working node', which is displayed as your prompt (and if things work and you use some graphical terminal, also in the title of the terminal window). Any commands you type will be directed to that node.

Apart from 'cd', 'ls' will also work as you might expect it. It is a short version of a simple 'get'. It won't show you the actual XML snippet, but only a list of names of the children of the current node.

In pash, apart from 'cd' and 'ls' (and 'quit' and 'exit'), anything you type will be transformed to XML and sent to the connected pakt server. So typing 'get' will actually send a <get/> message to the server, and the XML you see in return, is the reply from the server to that message. Any 'parameters' you pass a pash 'command' will be transformed to XML attributes. As an example, 'get depth=-1' will be transformed to '<get depth="-1"/>'.

Let's see what happens if we just send some bullshit command:

	/thread0/ foo someparameter="foobar"
	/thread0/
	
Nothing? Well, not quite. A '<foo someparameter="foobar"/>' was sent to paktd, but that didn't know what to do with it. Take a look on the paktd console, you should see a message like:
	[General warning] Could not instantiate foo - no class found

So what 'classes' are there to instantiate? Quite a few- you could have a look in the /system/registry/ part of a running paktd to see what objects it can instantiate (which depends on the modules that were loaded), but for a start you might just stick with me, I will tell you some hints :)

You can in fact instantiate any available GStreamer element. If you're still in /thread0/ with your pash, type 'fakesrc'.
	/thread0/ fakesrc
A peek on the server console will tell you nothing, which is a good thing. Do an 'ls':
	/thread0/ ls
	  videotestsrc0
	  xvimagesink0
	  name
	  priority
	  state
	  fakesrc0

We can see that, in addition to what was there before (a videotestsrc and an xvimagesink, as well as name, priority and state attributes of thread0), there is now also an 'fakesrc0' element. There is a full-grown GStreamer fake source now running on the server, or, to be exact, 'NULLing', it is instantiated in memory, but not in a GStreamer 'playing' state. We could go there and set it to playing, or we could also first instantiate an 'fakesink', connect the two and then start them, but we'll do neither of such, because this is advanced stuff and you will just figure out details later.

Let's do something more interesting first. We'll just leave the fakesrc to idle away, and move on to the 'videotestsrc0' element. Here you should note about the tab-expansion mechanism of pakt, which in good libreadline tradition can save you hell of a lot of typing. Instead of typing out 'videotestsrc0', just type 'vid' and press the tab key. Oh wonder, oh magic!

For videotestsrc, we set the pattern to 'snow':

	/thread0/ cd videotestsrc0/
	/thread0/videotestsrc0/ set pattern=snow

The video window showing the test image should now be rather noisy. This is the wonder of pakt, you manipulate the XML representation and by means of black magic, the running GStreamer pipeline changes its behaviour. In fact, it's two-way black magic, so should one of the element parameters change due to some external force (for example, somebody else setting it from another pash), it's XML representation (in the server space, not on your screen :) will also change. You can even subscribe to receive updates whenever a parameter changes (monitoring), but i'll save that for a later date.

First, to finish up this first short intro, we'll start up a proper GUI client for the running pipeline. In a new shell (or after you've quit pash), launch 'paktc'. This is actually a shortcut for 'paktc --host localhost --port 1955 --stylesheet /usr/local/share/pakt/gst2control.xsl -m gtk,control', which:
	- starts up a 'pakt client', which is a very similar thing to a pakt daemon, but not waits for connections, but
	- connects to a given pakt daemon (localhost:1955),
	- retrieves its complete XML hierarchy
	- transforms that document with the given stylesheet, which here will output the XML description for a simple GTK window with controls for all the pipelines elements
	- loads the relevant modules (what's 'relevant' really depends on what stylesheet you use), in this case 'gtk' and 'control'
	- instantiates the transformed document as 'living' objects.
	
That whole procedure should open a new window on your screen, showing a tabbed view of all involved gstreamer elements (thread0, videotestsrc0, xvimagesink0 and if you didn't restart paktd, also our newly-instantiated fakesrc0), and their parameters. All these parameters are live, if you change them they will be updated on the server side, and if they are changed by another process, they will be updated in the GTK controls. Note that a lot of the parameters you see this way, you probably shouldnt change while the pipeline is running, or paktd will crash. For now, just type "smpte" in the 'pattern' text entry box of videotestsrc0 and witness the wonder of pakt once more.

This should be enough for a start, you will already get an idea of what pakt is about. If you have questions or comments, drop me a line.