Filters do nothing more than receive MIDI events and transform them into other MIDI events. Filters are placed in pipelines and connected to other filters. A filter receives input from the previous filter in its pipeline, and sends output to the next filter in its pipeline.
There are two broad classes of filters: Standard filters are C++ add-ons that can be added and removed from the system. Sequitur includes a number of standard filters that cover a wide range of tasks, as well as a development kit that allows C++ developers to add additional filters.
Sequitur also includes multi filters, which are filters built from other filters. Users can add, delete and modify multi filters with the imcluded Edit Multi Filter window.
This window, available from the Windows->Filters menu item of any song or track window, displays a list of all the filters installed on your system. From the Filter menu you can create, modify, or delete multi filters. Add a filter to a pipeline by dragging it from this window to the desired location.
The Manage Filters window is similar to a Tracker window, and displays a list of filters and their attributes. The attributes are:
The most common type of filter is through, which can be placed anywhere in the tool and multi filter pipelines, anywhere but the head of the input pipeline, and anywhere but the tail of the output pipeline. Through filters are further separated into tool filters, which can only be placed in a tool pipeline, and multi filters, which can be used any place a through filter can be used, and can also be added, modified and deleted by users.
Input filters allow you to record MIDI data. They may only be placed at the head of the input pipeline. These filters typically correspond to MIDI controller devices attached to your computer, for example a keyboard or drum machine.
Output filters are used to select which MIDI device(s) will be used for playback. They may only be placed at the tail of the output pipeline. These filters typically correspond to MIDI devices attached to your computer.
Multi filters which can not be modified appear in a light gray colour. Multi filters which are invalid appear in red. A multi filter is usually invalid because it shares the exact same key as another filter. Invalid filters are not available anywhere but the Manage Filters window. To make a multi filter valid, change its key to a unique value.
Descriptions of all the installed filters is available in Appendix A: The Filters.
7.1.1. Menu Bar
Filter
7.2. Sharing Multi Filters
Multi filters are stored as files on your hard drive, so they can be shared easily with other users. A multi filter can be stored in one of two directories:
All multi filters located in the first folder can not be modified, and appear as light gray in the Manage Filters window. By default, all multi filters that ship with Sequitur are located in this read-only directory. Use the path attribute of the Manage Filters window to locate a particular multi filter.
The Edit Multi Filter window is accessed by opening the Manage Filters window and either double-clicking an existing filter or selecting Filter->New. This window is divided into four pages: General, Pipeline, Description and Icon. The General page contains several required pieces of information; after that, the Pipeline is the most important page.
7.3.1. The General Page
This page allows you set the filter's name, key, author and author's email. The author and email fields are optional, but each filter must have at least a name and a key. Ideally, each filter has a unique name, since this is the label seen by users.
Each filter is required to have a unique key, which is what Sequitur uses to distinguish between filters. Keys should be given the pattern of "[implementor:filter_name]"; for example, all Angry Red Planet filters have an implementor of "arp", so a Chorus multi filter's key would be "arp:Chorus". The Edit Multi Filter window will prevent you from using a key already in use. Additionally, for any multi filters that share the same key, only the first one loaded will be available for use in pipelines.
7.3.2. The Pipeline Page
The filter can have any number of pipelines. If it has none, it will do nothing.
The multi filter must have one and only one Input filter -- this is the filter that receives incoming MIDI data. The filter must have one or more Output filters. The number of Output filters determines the filter's maximum possible connections. When this multi filter is inserted into a pipeline, if it has two Output filters, it will be allowed to connect up to two destination filters. All MIDI data from the first Output filter will be sent to the first connection, all MIDI data from the second Output filter will be sent to the second connection, etc. The Input and Output filters are added automatically whenever you press the Add button to add a new pipeline.
7.3.3. The Description Page
This page lets you type in two separate descriptions. The short description, which appears in the description column of the Manage Filters window, should be a brief explanation of the filter. The long description should be HTML-formatted text that explains in detail the filter's operation. It appears in Appendix A: The Filters.
7.3.4. The Icon Page
Users identify filters by their icon that appears in the Manage Filters window and in the pipelines. This icon editor is an extremely simply paint program provided as a convenience for touching up icons. It is highly recommended that you do any real work in an application which you can copy to and paste from, such as QuickRes. The only tools available for drawing are the pencil, which paints the current colour, and the dropper, which reads the color.
The New menu commands must first be used to create a new blank icon.
The Copy and Paste menu commands can be used to transfer the icon to and from a better paint program. Copy and paste works fine with Be's QuickRes application, and may work with other BeOS paint programs.
The Flip Horizontally and Flip Vertically menu commands mirror the icon around the x and y axis, respectively.
The Fill with Alpha command fills every pixel in the icon with at most the current alpha value (if the pixel's alpha is already below the current alpha, it is left alone). This option is mainly used for devices.
7.4. Installing New Filters
Filter add-ons for Sequitur can be placed in the following folder:
True to the live nature of BeOS, it's not necessary to exit Sequitur before installing new add-ons. Simply drop them in a valid directory and watch them appear in the filter window.
7.5. Writing New Filters
Sequitur includes a development kit and the source code for nearly all of its filters (not included are the input and output filters) in the DevKit/ExampleFilters/ folder. Several specific code examples are provided: The Dan filter is heavily commented, and the Dianne and Eric filters are additional examples.
None of these filters provide examples of writing user interfaces to change your filter's attributes. Please direct any questions to Eric Hackborn.
