Theory

: Manual
Prev		Next

Theory of Operation

iARS is a browser plugin which is launched automatically when the browser receives an embedded object of the appropriate MIME type. Such a HTML document is produced by the IAEM portal according to the users selection. It must contain information about the streaming source, processing directive and the interface description for the graphical representation of the processing directive.

The plugin launches the Pd application and controls the Pd instance over a specified interface so that it can apply patches, data and control the processing.

According to the interface description the plugin builds a graphical representation of the chosen patch. This UI is interactive and provides various controls. Every change by the user is reported to the Pd instance to alter the actual value of the parameter in the patch. As additional feature the plugin provides a drawing area from the browser window to the Pd instance where Pd may visualise the processing using the OpenGL extension library GEM.

The audio data source is defined as URL of a streaming server. The information of which mountpoint at which server is streaming the desired data is provided as parameter in the HTML document the object is embedded. Pd connects to the streaming server directly, its streaming object is provided with the connection details by the plugin. Alternatively the patch may also synthesise any sound without using any streaming source.

The OBJECT Tag to embed iARS

The information embedded into the HTML documents in order to launch the plugin has to be formatted as in the following example:

Example 1. Embedded plugin request

	    
	    
<html>
  ...
  <body>
    <object type="application/iARS"
      width="800"
      height="300"

      <param name="PATCH" value="http://localhost/advanced.pd">
      <param name="EXTRAS" value="http://localhost/extras.zip">
      <param name="GUI" value="http://localhost/advanced.xml">
      <param name="STREAM" value="http://localhost:8000/NJKSI34K/">

    </object>
   ...
 </body></html>

The following information must be provided by the document.

Table 1. OBJECT tag specifiers

Name	Value	Description
type	string	This is the application/iARS MIME type registered from our plugin.
STREAM	URI	The URI from the requested audio data file. This is the streaming mountpoint of the content database system.
PATCH	URI	The location of the Pd patch to be loaded to the Pd application. It determines the signal processing.
EXTRAS	URI	A zip file containing extra externals or patch abstractions for the main patch. It must be a ZIP file and it must not contain directories, but every file packed in the bottom level directory.
GUI	URI	The location of the GUI description file for this patch. The file must be compliant to the patch to be able to alter the right values.

For all values relative paths may be used as well as absolut paths. The key is that the browser may access it with the information provided.

Graphical user interface

The plugins GUI is a dynamical user interface displayed in a section of a browser window. It contains a variable amount of controls described by an IDL (interface description language). The interface description is a XML based document delivered from the portal with every Pd patch in order to determine the graphical representation of the patch. If no description is available just the general on/off button is available.

The IDL document is also intended to save current states of parameters. IDL files can be saved describing the GUI and the actual values of the controls. If the IDL file contains more than one interface description the plugin realises the first, but is offering the others as seperate presetting buttons providing the possibility to switch between different presettings or even different controls.(not yet implemented)

A simple text widget is part of the GUI to provide some feedback data to the user. This resembles the standard output from a normal UNIX shell. (not yet implemented)

Subsequently, the controls and the IDL document structure is defined:

Plugin Controls

Every instance of the plugin provides a menu containing switches for DSP on/off and streaming control (play, pause, rewind and forward). Besides that menu, controls are defined in the IDL file. The controls have parameter properties and a name assigned. The following controls are available

Table 2. Plugin GUI controls

Name	Parameter	Description
On/Off button	Value, Bind	A button with two states that can be assigned to any variable in the Pd patch.
Trigger button	Value, Bind	A trigger button. Equivalent to the Pd "bang".
HSlider, VSlider	Min, Max, Value, Bind	Horizontal and vertical slider for altering variables within a certain range.
Knob	Min, Max, Value, Bind	A knob (as needed for mixer) working very much like the sliders above.
Textfield	Value, Bind	An editable textfield for numbers as well as symbols
Textdisplay	Value, Bind	An non-editable textfield for numbers as well as symbols
GLWindow	Bind	An openGL window for GEM to draw in. The window handle is provided through the binding.
Table	Min, Max, Size, Bind	The equivalent to the array object of pd. Min, Max set the Y axis scale, the size the X Axis size.

All elements may be grouped by the group tag as described in the next section and may use width and height attributes to determine their size.

The following example shows all available objects as valid XML code:

Example 2. All objects allowed

 
	    
<vslider name="Slider1" min="0" max="100" bind="s1" value="20"
	width="50" height="100"/>  
<hslider name="Slider2" min="0" max="100" bind="s2" value="20"
	width="100" height="50"/> 
<trigger name="Push" bind="p1" value="0" width="50" height="20"/>
<onoff name="Power" bind="p2" value="0" width="50" height="20"/>
<knob name="Knob1" min="0" max="100" bind="k1" value="20" width="50"
	height="50"/> 
<levelmeter name="LV1" min="0" max="100" bind="vu1" value="20"
	width="50" height="100"/>  
<textfield name="Text1" bind="t1" value="text" width="100" height="50"/>
<textdisplay name="Text2" bind="t2" value="text" width="100"
	height="50"/> 
<glwindow name="GEM" bind="handle" width="300" height="300"/>
<table name="Table" bind="array" size="100" min="-1" max="1"
	width="400" height="400"/>

Document Type Definition

This section defines the IDL document layout. The provided DTD determines the syntax and semantics of any possible IDL document.

The description has to be enclosed in a interface tag, one streaming input tag is compulsory to specify the streaming object in Pd. Other elements may be grouped in boxes which have orientations affecting the way elements are arranged in these boxes. Every input element has to specify a binding (= Pd receiver), a value range and a starting value.

The following example shows a simple interface description.

Example 3. IDL document example.

 
	    
<?xml version="1.0"?>
<!DOCTYPE interface SYSTEM "idl.dtd">

<!-- This is an example file for the use of the idl-dtd, the interface -->
<!-- description language document type definition for the IAEM plugin -->
<!-- for detailed description of all elements refer to idl.dtd -->


<!-- Christopher Frauenberger, created 24.2.2003 -->
<!-- $Id: manual.xml,v 1.1 2004/06/08 09:44:54 frauenberger Exp $ -->

  <author>Christopher Frauenberger</author>
  <patch>advanced.pd</patch>
  <version>1.0</version>

  <input name="stream"/>

  <group name="Advanced" orientation="vertical">
    <group name="Filter" orientation="horizontal">
      <vslider name="Bass Gain" bind="bass-gain" min="0" max="127"
       value="100"/>
      <vslider name="Mid Gain" bind="mid-gain" min="0" max="127"
       value="100"/>
    </group>
    <knob name="Harmonizer" bind="harm-transpose" 
     min="-1200" max="1200" value="0"/>
  </group>
 
</interface>

Prev	Home	Next
		Installation