Terminology

As Soundium and Decklight have been constantly under heavy development, there are a few terms which you should be aware of

Soundium may refer to Soundium and Decklight together, or only to the graphical frontend, depending on the context. Also for the graphical frontend, we sometimes just use the term Client.

Decklight refers to the multimedia processing engine, therefore sometimes just called the Engine. Decklight currently comes in two version: Decklight 2 is our production environment, i.e., the one we use for our own artistic work. It is very stable, and has been thoroughly tested. However we do not put any further development efforts in to this version, except for fixing serious bugs. Decklight 3 is the development release, which has a largely revised architecture, and fixes many flaws from Decklight 2. It has not been extensively tested, and functionality is still limited (in terms of available processing nodes) as we first concentrate on settling the design of the core engine.

Bouncelets are the processing entities, containing of input and output ports which can be connected. In the published papers, the proper term used instead is processing node. Also be aware that the names of processing nodes and associated ports sometimes may appear a bit weird in Decklight 2, most of them are results of night coding sessions and reflect the author's state...

Note: Always remember that Soundium is a research project. So far, it requires quite a bit of knowledge in computer science and media processing in order to use it. Without knowing what you're doing, you'll be able to crash the system easily.

Running Decklight and Soundium

Always start Decklight first, then Soundium. Also note that you will need to restart Soundium after the engine crashes (which of course never happens), or when you load another sl1 file (which is normally not necessary, because of the design tree).

Decklight2 on Linux:

 $ cd decklight2
 $ src/arch/unix/decklight

Decklight3 on Linux

 $ cd decklight3
 $ src/os/decklight

Note: Since libtool is used src/os/decklight is not really an executable, but a launch script. If you need to debug this with gdb, use libtool gdb src/os/decklight!

Decklight3 on Mac OS X

Build the application using XCode, and start it either from XCode directly or from the Finder.

Command Line Options

There are a few command line options for static configuration of the engine. Launch decklight with --help will output a list with available options.

Starting Soundium2

 $ java -jar soundium2.jar

Alternativley, Resman, the "resource manager" can be started individuallly (speeds up turn-around cycle):

 $ java -Dresman -jar soundium2.jar &
 $ java -Dno_resman -jar soundium2.jar

Command Line Options

There are a few command line options that may help you. You will get a short help by calling

 java -Dhelp -jar soundium2.jar

In particular, you may increase the amount of available memory (in case your resource library is growing):

 java -Xmx512m -jar soundium2.jar

And, there seem to be some problems with the GTK look&feel, so you may use standard Metal by calling:

 java -Dlf=Metal -jar soundium2.jar

First Time Run: Setting Up MetaDB and add Resources

The first time Soundium's resman is started, the location of the metadb needs to be specified. The directory layout may look as follows (choose it at your discretion):

 ~/sndm/metadb
 ~/sndm/resources

Put your resources into resources, and specify metadb when resman asks for it. Then, in Soundium's File menu go to Source->Filesystem... and select resources. Then you may select File->Scanner... to see how resman is scanning the resources and generates the previews (which happens only once, the previews are stored in the metadb). Later you may add additional resources, and resman will scan them automatically.

Note: Currently there are two small problems with workarounds: With some window managers on linux, the "Select MetaDB" dialog is hidden behind Soundium's splash screen on startup (e.g. fluxbox). I was able to drag the dialog and then select the MetaDB. In addition, Soundium does not create the file 'root_res', which should be in the MetaDB directory -- subsequently Soundium will run, but throw some exceptions. You can add the 'root_res' file yourself, by just touching 'root_res' in the MetaDB dir. The second issue is fixed in the latest Soundium binary

First Steps

Note: The examples here apply to Decklight3. For Decklight2, it is basically the same, but Bouncelet names are very different. Further, Soundium is currently streamlined for Decklight2, so some features may behave a bit weird when using Decklight3. We will fix this as soon as Decklight3 advances.

Loading an SL1 File

When you start up, the client will open a file selector in order to load an SL1 file. You can either create a new file, or load an existing file. After selecting or creating a file, Soundium's main window will be opened (Figure 1). Soundium provides different basic layouts, they can be set in the Settings menu. The screenshots shown here were taken using the "Split Layout".

Figure 1: Soundium's main window after creating an empty SL1 file.

Main Views

Provided you started Soundium including Resman, you will see three tabs with the principal control panes: Designs, Engines, and Resman.

• Designs: Contains the design tree, which represents the organisation of content. The tree grows as you are working with Soundium, and you can jump from node to node by double clicking on them in order to change a design. The highlighted node in the Design tree is the currently active one.
• Engines: Contains the processing graph, i.e., Bouncelets (processing nodes) that are interconnected. An important difference to many other tools is that the graph is automatically layouted, that means, you cannot move nodes manually. If you click on a Bouncelet, the node inspector will show in the right area of Figure 1.
• Resman: This is the interface to your media library. More on this later.

Generally, you can always explore GUI features by right-clicking tree or graph nodes, or connections.

Importing an Engine

The first step is to import an engine. Therefore, go to the Design view, right-click on the "example.sl1" node, and select "Branch". A new node with version number "1.2" will appear. When you click on the "1.2" node, the SL1 editor will open in the right pane. There you enter

 decklight = import "emp://critter.inf.ethz.ch";

where as the hostname corresponds to the machine, where Decklight is running. After entering the code, click the "Apply" button on the top. If the engine is found, "Apply" results in no error, otherwise, the "1.2" node will be marked with a red cross, and you get an error message in the editor. Generally, whenever you change, you first need to issue "Apply" in order to commit the SL1 code to the design tree.

Design tree nodes can be named, by entering a name in the "Label" field. Here we change the name to "import". After entering the text, the name of the "1.2" node changes to "import" in the design tree.

Next, you may double-click on the "import" node, or issue "Make Current", in order to make the node active. The "import" node then turns yellow, as shown in Figure 2.

Figure 2: The design tree after activating the "import" node.

Creating Content

Next, we switch to the "Engines" tab, and a large black void will open up - because there are no Bouncelets yet. A right-click in the white area reveals a hierarchical Bouncelet menu. In order to create a viewport, the root of an scene graph, browse through the menu and select the viewport bouncelet. Afterwards, the node will be visible in the graph view (Figure 3).

Figure 3: Creating a Viewport.

Now, also create a cube. In order to connect the viewport and the cube, move the mouse over the viewport, until a small red dot appears, and click-drag the connection to the cube. For completing the connection, you have two options: First, you can use the table in the inspector to select ports to be connected. Second, you can right click on either the cube or the viewport node, and then use the submenus to actually connect the individual ports.

At this point, you may notice that there is neither a viewport nor a viewport with a cube visible. That is because your operations are not commited yet. You can also see this when you go back to the Design view, where a new design node "1.3" is shown, but is currently red. If you now press CTRL-K, your pending operations will be commited to the engine, the viewport will show up and the design node will turn yellow, i.e. it gets activated. The "Engines" view at that point will look something like in Figure 4.

Figure 4: A simple processing graph.

But where is the cube? Well, Decklight's default color settings are set to black, thus we need to insert a color node first. Therefore, move the mouse cursor on the connection between the viewport and the cube, right-click, and select the insert menu, and a corresponding color node (Figure 5).

Figure 5: Inserting a color node.

Modifying Parameters

After the color node is inserted, select it by a single click, and the node inspector will show up. From there select a fancy color, and you will see the cube in the window.

Figure 6: The color node inspector.

Now that you have modified parameter, you will notice that there is another design node in the design tree. Soundium handles parameter changes to the engine immediately, and collects them in a new design. By again issueing CTRL-K, the collected changes will be commited to the design tree, and any upcoming modification will result in a new design node.

By now you should have multiple design nodes. You can always jump back and forth by double-clicking a node. Try it! You can also jump back and create a new branch, or respectively a new branch is automatically created as you modify parameters or the processing graphs structure.

Sometimes, however, it is not desirable to track all parameters changes of certain processing nodes. This typically applies to global configurations that need to be constant among multiple designs. Therefore, processing nodes (or individual ports) can be marked global. In order to achieve this, you have directly edit a design's SL1 code (Figure 7).

Figure 7: Making the viewport global by editing a design node.

After you apply your changes, you may jump into the design node again, switch to the Engines view, and modify the viewport node. Then you will notice that no new design node is created.

The Resource Manager

So far we have dealt with a simple red cube. This section will show how resman can be used in order to create a textured cube. First, you will have to add a few property nodes to your scene graph: A style property, and a texture property. In addition you will need to attach a node for loading a texture. The resulting processing graph including the generated SL1 code is shown in Figure 8.

Figure 8: A processing graph which includes texturing.

Before you can use Resman, you will of course have to add some content to the resource directory. You can just copy files or directories into the resource directory you specified (e.g., ~/sndm/resources, as suggested above. Then you open the "Scanner" (File Menu) and issue "Rescan" (which is not necessary, if you added the content before starting Soundium).

Note 1: Currently supported data types are most image formats, including animated gifs, which are actually used as movie content. Future implementations will allow arbitrary movie formats.

Now you can switch to the Resman view. You will notice a few tabs on the right, they act as search selections, which can be named. Then you can add search criteria, and a given key (as a regular expression). If a search is successful, you will get a browseable list on the left hand side. Out of this list, resources can be selected and then assigned to the processing graph by right-clicking the resource. The pop-up menu will show a list of input ports of corresponding processing nodes, where a resource can be assigned (Figure 9).

Note 2: After adding new resource, resman is creating previews on the fly when used for the first time. This may take some time, especially when adding large collections.

Figure 9: Selecting and assigning a resource