CORTEX documentation index
 
 
release   2.1.2
maintained by   Eric Moon
last updated   13 June, 2000
For current project info, visit http://cortex.sourceforge.net

Installation
Release Notes
Source & Binary License
 

 
1)    Overview & General Usage
 
[up] [down]
routing
window
intro

Revision 2.1.0 of Cortex introduced a kick-ass new routing window design courtesy of Christopher Lenz (cmlenz@gmx.de.) The routing view now has two distinct viewing modes: "Icon View" and "Mini Icon View", selectable from the context menu that appears when you click the right mouse button in an empty area of the window.

"Icon View" is the default; it's similar to the old look & feel (though a lot nicer to look at) -- nodes are displayed as rectangular tiles with inputs and outputs arranged vertically on the left and right sides, respectively. Nodes are assigned icons based on the type of node, or the owning application if any.

"Mini Icon View" is a more compact display: connection points are layed out horizontally, with inputs on the top and outputs on the bottom.)

In either view, nodes can be freely dragged around. You can select multiple nodes by <shift>-clicking or by dragging a selection rectangle around them. Try right-clicking a node or connection to see the specific commands available for it. Node positions in both views will be remembered the next time Cortex is run. If you find the gray background dull, try dragging in an image file or a color from one of the many color-chooser apps out there (I like kColor.)

making
connections

New connections can be made by dragging between two connection points (it doesn't matter if you drag from an input or an output.) The wire will snap to connection points as the mouse nears them (this doesn't guarantee that such a connection is possible.)

To disconnect two nodes, click on a wire and press the <delete> key, or right-click it and select "Disconnect."

Restrictions: Cortex locks the connection between the system mixer and the audio output. The Media Server doesn't look kindly upon apps that break that connection. Connections from file-producer nodes (more about those below) are also locked, due to a bug in the Media Kit.

dormant
nodes

Now for a look at the second window: labeled "Media Add-Ons", it displays all the media nodes available in add-ons (these are also known as "Dormant Nodes.") Additional information on a given node can be had by right-clicking and selecting "Get Info."

To create, or instantiate, a new copy of a given dormant node, drag it to a spot in the routing window. If Cortex was able to successfully create a new instance of the node, a corresponding panel will appear in the routing window.

Danger! Cortex currently allows you to instantiate any dormant node you want. Some add-on nodes, such as sound-card inputs and outputs, can't be created more than once, and instantiating a new copy will break the existing one. If this happens, the "Restart Media Services" in the Media preferences panel should return the system to a usable state.

File-producers: to create a node capable of playing a given media file (audio or video), drag it the file into the routing window. Note that if you create a video-producer in this fashion, it can't be hooked straight up to a raw video output, since it produces compressed video. You can use the "Decoder Node" add-on to produce raw video that can be directly displayed in the Video Window (and hopefully a video output as well -- but I don't have one to test with, so no guarantees!) Note as well that the Video Window must be started manually before it'll display anything.

To delete a node, click on it (to select the node), then press the <delete> key, or right-click the nodeand select "Release."

saving
node-sets

new cool thing: you can save an XML-based description of the currently selected set of nodes via the "Save Nodes" option in the 'File' menu. Nodes that you've instantiated in Cortex are fully described, so that they are recreated when you load the node-set. Nodes owned by outside applications are described to the point that connections to/from them may be reestablished if they still exist but Cortex will make no attempt to recreate outside nodes if it can't find them.

the
transport
window

The transport controls (start/stop) are located in a separate floating window (if it's not visible, select "Transport" from the "Window" menu.) When one or more nodes are connected, Cortex binds them together into a group, allowing you to control the nodes in unison. If you want, you can disable this behavior by right-clicking any node in a group and picking "Lock Group" under the "Advanced" submenu. Nodes connected to or from any node in the group will thereafter remain in their own groups.

The upper-left quadrant of the transport window lists information on the currently selected group, if any. Selecting a node in the routing window causes its group -- if it has one -- to be selected in the inspector. You can click on the group name to edit it; there's not much reason to do so yet (groups aren't saved with node-sets yet.) The bottom of this status display may be used to show error information in a future release.

In the upper-right are the transport controls: pretty self-explanatory except for the "Preroll" button. This tells all the nodes in the group to get ready to play -- a properly implemented media node should be able to do as much pre-processing as it needs to start instantly.

The rest of the transport window is devoted to settings. The "Roll from" and "to" values allow you to set a range over which the group will play. If the "to" setting is less than or equal to the "from" setting, the group will play unhindered until you stop it. If you do specify a valid range, playback will stop when the "to" position is reached, unless one or more nodes in the group have "cycle" enabled, in which case those nodes will repeatedly play the selected region. The loop isn't guaranteed to be perfectly accurate, especially at short loop lengths, but cycle mode is useful for stress-testing a node's "seek" abilities, or for keeping a file-player node running. The "Roll to/from" controls are live while cycling nodes are running, although Cortex gives up trying to cycle a node if the loop length is too small (less than one millisecond.) The cycle setting for each node is located in the node context menu obtained by right-clicking on a node panel.

The "Run Mode" control lets you tell the nodes how to cope when they fall behind (or, if "Offline", to ignore the concept of real time altogether.) This setting may be overridden on a node-by-node basis via the "Run Mode" options in the node context menu.

The "Time Source" control lets you set the time-source for all nodes in the group. A time source is a node that regularly publishes timestamps used by other nodes to synchronize their output. The default time source used for new nodes is the "DAC Time Source" (provided you have an audio output device of some sort.) If you instantiate nodes that can act as time sources, they'll be added to this menu.

parameters

Chris has been hard at work expanding parameter (control panel) support. To open the new control-panel window for a node that has parameters, double-click the node or select "Tweak Parameters" from its context menu. If a node supports its own control-panel window, it can be displayed from the Cortex parameter window or by selecting "Start Control Panel" from the "Advanced" context submenu.

sample
nodes

Cortex comes with several sample add-on nodes. Two of them, LoggingConsumer and ToneProducer, are based on sample code from the Be Developer Newsletter. I've made a few changes to them to implement add-on support, and to make them a bit more flexible. Since they are very useful testbed nodes, future Cortex releases will likely include further improved versions of them.

Also included is a sample audio filter, Flanger. It is somewhat limited: only floating-point audio is supported (the same is true of ToneProducer.) It does include a control panel. Try instantiating ToneProducer and Flanger, connecting them together, then connecting Flanger's output to the system mixer. This is a simple example of the Media Kit's flexibility. (For truly warped sounds, try connecting a few Flangers in a row!)

To help ease format-conflict pains, AudioAdapter converts from one raw audio format to another on the fly. In most cases you can simply connect nodes to either side of it. If you get a "Bad media format" error, you may need to help AudioAdapter decide the format: in the Parameters section of the node inspector, you can pick format requirements. (Note that currently you HAVE to fully specify the output format to get it to connect to the system mixer.)


 
2)    Known Bugs (& Missing Features)
 
[up] [down]

back-end (NodeManager)

  • misbehaved nodes not handled well (the UI can lock up as it waits for NodeManager to time out on a failed operation.)
  • groups aren't split correctly. for example, if two producers are connected to a mixer, then the mixer is deleted, the producers will remain in the same group.
application/routing window
  • node-sets loaded by drag & drop should be placed at the drop point.
  • grouping information isn't saved with node-sets.
  • the workspace doesn't autoscroll as nodes are dragged.

AudioAdapter
  • format negotiation needs some work (can't connect output to the system mixer without help from the user.)
  • needs a LOT of buffers (>16) if input is connected to a system audio-player node that's being cycled (looped). probably a bug with the file-player node, but I need to do some more research...

ToneProducer
  • only floating-point output supported.

LoggingConsumer
  • takes after the Be System Mixer in not sending late notices
Flanger
  • weird noise (aliasing?) given high-pitched tones as input.
  • only floating-point output supported.


 
3)    Notes for Developers
 
[up] [down]

Come check out the SourceForge Project Page!

Comments/questions?
Let me know: em@be.com
 





Copyright © 1999-2000, Eric Moon. All rights reserved.