kwx_logo

KWlive Realizer white paper

Preface

The target audience for this document is anyone interested in using or co-developing the KWlive realizer.
The About section is meant to make clear to both users and developers what the software is about.
The How to use it section explains in short how to get started with using the software
The Developers section aims to give insight into the design of the application, the technologies that were used and the choices that were made:

About

Introduction

KWlive is the name for the set of applications within the KeyWorx platform suiting "live" multi-user audio/visual performance. The KWlive Realizer is the (currently OSX) application that realizes the actual audio/visual output. It has no "human friendly" (graphical) user interface itself. Most of the time the only visual appearance of the application is just a window on your screen. The realizer plays media files, receives media streams and OSC (open sound control data) , does the digital signal processing on the media and mixes all of that to an audio/visual output in realtime. The application could be defined as a Multi-User Cross Media Synthesizer : a distributed application that allows multiple players to generate, synthesize and process images, sounds and text within a shared realtime environment.

(User)interface

The Realizer functions as a server that can host multiple clients that control it. Controlling the Realizer means basically telling it which files to play and which effects to add. These commands are typically sent by another application, a patcher, via XML/TCP and OSC/UDP. The patcher is the application that is supposed to have a friendly user-interface. The XML-protocol used for the communication between the patcher and the Realizer consists of messages that invoke functions of the Realizer. Some example functions are : "make-module" and "connect" . A full listing of the XML-protocol can be found in the Realizer protocol section. OSC (open sound control) is used as the protocol for sending control data. This data can be patched to control all module parameters.

Concepts

Rationale

What were the main reasons for starting this project

Applications / Installations

Related tools

How to use it

Installation

For help with building the realizer please visit : http://dev.waag.org/projects/kwlive/
Once you have a build Realizer place it in any folder you like.

Configuration

The realizer is a bundle application all its configuration files, plugins and resources are located in the bundle. "Right" mouseclick on the application and select "Show package contents" to see what is inside the bundle. Open the main configuration file (Contents/Resources/config.xml) in a text editor. A short description of the main configuration groups: More on configuration can be found here: Configuring

Patching with telnet

Sending xml messages via telnet can be considered as the lowest level interface to the realizer. Although it is a very user unfriendly interface it proves itself handy for "debug" purposes, because all response messages of the realizer are directly visible. The next listing shows an example telnet session to a realizer running on "the same" machine:
lolo:~/ lodewijk$ telnet 127.0.0.1 1234
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
<patch>
	<make-module-req type="MoviePlayer" id="mp1" />
</patch>
<patch>
	<make-module-rsp />
</patch>
<patch>
	<set-attribute-req moduleid="mp1" name="file" value="file:///Users/lodewijk/Movies/movie.mov" />
</patch>
<patch>
	<set-attribute-rsp />
</patch>
<patch>
	<connect-req frommodule="mp1" output="image out" tomodule="OutputWindow1" input="image in" />
</patch>
<patch>
	<connect-rsp />
</patch>
A full listing of the xml protocol can be found in the Realizer protocol section

Developers section

Open source

The realizer source code is open source. All used libraries that are "closed source" can be considered "system libraries". All realizer source files are distributed under the following license :
Waag OSS license statement.

Version: MPL 1.1/GPL 2.0/LGPL 2.1

The contents of this file are subject to the Mozilla Public License Version
1.1 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
for the specific language governing rights and limitations under the
License.

The Initial Developer of the Original Code is "Waag Society / for old and new media"
Portions created by the Initial Developer are Copyright (C) 2004
the Initial Developer. All Rights Reserved.

Alternatively, the contents of this file may be used under the terms of
either the GNU General Public License Version 2 or later (the "GPL"), or
the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
in which case the provisions of the GPL or the LGPL are applicable instead
of those above. If you wish to allow use of your version of this file only
under the terms of either the GPL or the LGPL, and not to allow others to
use your version of this file under the terms of the MPL, indicate your
decision by deleting the provisions above and replace them with the notice
and other provisions required by the GPL or the LGPL. If you do not delete
the provisions above, a recipient may use your version of this file under
the terms of any one of the MPL, the GPL or the LGPL.

Platform(s)

At this moment the KWlive realizer is Mac OSX only. Currently an XCode project (XCode uses gcc) is available. Since porting the application to other platforms is one of our next goals, we have been putting effort in isolating and tagging platform dependent code.

Technologies / Dependencies

Plugins

Making a plugin for the realizer is probably the first step in contributing to the project. Realizer plugins are bundled libraries extending the functionality of the application in the form of a module. Modules can input and/or output audio, video and abstract signals, furthermore there are no restrictions to what a module can do. Thanks to the plugin SDK developing a plugin is quite easy and numerous examples are provided in the "plugin" directory of the source code.

Realizer protocol

XML is used for : the following block contains a complete list of possible requests to the realizer.
patch:
all requests and responses should be enclosed by a "patch"-tag. For example:

<patch>
	<make-module-req type="string" id="string"/>
</patch>


	request:
	<make-module-req type="string" id="string"/>
	response:
	<make-module-rsp />
	negative response:
	<make-module-nrsp reason="string"/>

	request:
	<delete-module-req id="string"/>
	repsonse:
	<delete-module-rsp/>
	negative response:
	<delete-module-nrsp reason="string"/>
	
	
	request:
	<connect-req frommodule="string" output="string" tomodule="string" input="string"/>
	repsonse:
	<connect-rsp/>
	negative response:
	<connect-nrsp  reason="string"/>
	
	request:
	<disconnect-req  tomodule="string" input="string"/>
	repsonse:
	<disconnect-rsp/>
	negative response:
	<disconnect-nrsp  reason="string"/>
	

	request:
	<set-input-req moduleid="string" input="string" value="float"/>
	repsonse:
	<set-input-rsp/>
	negative response:
	<set-input-nrsp reason="string"/>

	request:
	<set-attribute-req moduleid="string" name="string" value="string"/>
	repsonse:
	<set-attribute-rsp/>
	negative repsonse:
	<set-attribute-nrsp reason="string"/>

	request:
	<set-active-req moduleid="string" value="boolean"/>
	repsonse:
	<set-active-rsp/>
	negative repsonse:
	<set-active-nrsp reason="string"/>
	
	request:
		<get-patch-req/>
	response:
		<get-patch-rsp/>
	negative repsonse:
		<get-patch-nrsp/>
		
	request:
		<clear-patch-req/>
	response:
		<clear-patch-rsp/>
	negative repsonse:
		<clear-patch-nrsp/>	
	
control:
all requests and responses should be enclosed by a "control"-tag. For example;

<control>
	<get-moduledeflist-req/>
</control>	

	request:
	<get-moduledeflist-req/>
	repsonse:
	<get-moduledeflist-rsp>
		<module type="string">
			<!-- moduledef -->
		</module>
		<module type="string">
			<!-- moduledef -->
		</module>
		<module type="string">
			<!-- moduledef -->
		</module>
	</get-moduledeflist-rsp>
	negative response:
	<get-moduledeflist-nrsp/>
	
	
	request:    
	<!-- set the n-th created output to a window (stream and file to be implemented later) -->
	<set-imageoutput-req nr="string" >  
		<window hsize="string" vsize="string" hpos="string" vpos="string" />
	</set-imageoutput-req >
	response:
	<set-imageoutput-rsp/>
	negative response:
	<set-imageoutput-nrsp/>
	
	request:
	<!-- legal value's for level:
	none
	error
	warning
	message
	verbose
	debug
	-->
	<set-loglevel-req level="debug" /> 
	
	response:
	<set-loglevel-rsp/>
	negative response:
	<set-loglevel-nrsp/>

Generated on Wed Feb 8 18:14:11 2006 by  doxygen 1.4.5