Filters are a method of embedding Humdrum Extras commands into Humdrum files. Filters have the form:
!!!filter: command
Multiple filters can be given on separate lines and will be executed in sequence, or combined into a single line separated by a pipe character.
!!!filter: command1
!!!filter: command2
!!!filter: command3
or
!!!filter: command1 | command2 | command3
These filter lines will be processed by verovio as the Humdrum data is being loaded, allowing Humdrum Extras commands to be used easily within the web browser to transform the data before it is converted into notation.
A simple, but handy, filter to use is the autobeam tool. Notice in the
following example that there are no explicit beams in the data (L for a
beam start and J for a beam end). Nevertheless, the notation is
displaying beams. Try to add more notes and/or remove the filter line
to see what happens. The filter line can occur anywhere in the data,
so also try moving it to the bottom of the data.
Multiple filters can be applied to the data. The filters can be given a separate lines, with the order in the file being the order that the filters will be applied. Also pipe characters can be used to separate two or more filter commands on a single line. Here is an example of transposing a chorale from A minor to G minor, and then arranging the layout of the parts onto grand-staff:
Try removing the filter in the above example to see what the notation of the original notation looks like.
Bug caveat
Currently filters must always be syntactically correct as they are typed; otherwise, the verovio toolkit will exit on with an error and no longer work until you reload the page (this will eventually be fixed). In the meantime, you should ensure that the filter is never in an invalid state by using one of the two following methods. VHV will automatically restart verovio if it crashes due to a poorly formed filter, but sometimes there may still be problems.
delaying filter activation
A simple method of avoiding an invalid filter command is to type the line
without the colon (:) after filter. Once the filter has been finished, go
back and add the colon character. This will activate the filter, since verovio
will not be able to interpret the line as a filter command.
freezing notation generation
You can also use the alt-f command to temporarily disable processing of the Humdrum data through the verovio toolkit. After freezing the notation, type the filter command in any way that you like. Afterward, type alt-f again to re-activate the processing of the Humdrum data with the verovio toolkit. The filter should not be applied as the Humdrum data is converted.
Compiling filters
The output of filtering can replace the input Humdrum data by
typing the command alt-c to “compile”
the filter. This is useful for doing some data processing of Humdrum
files with in the VHV editor. For example, the extract tool can
be used to extract a part from a full score, or to rearrange spines
in the data.
interaction between filters and graphic editing
Once a filter has been added to a file in the VHV editor, it may not be possible to use the graphic editing commands anymore.
The reason for this is that, internal to verovio, the Humdrum data is first filtered and then converted into MEI data and then SVG images. In order to communicate between the SVG images and the original Humdrum data, XML IDs that embed the line and field numbers of the Humdrum data; however, these IDs are in reference to the filtered Humdrum data not the pre-filtered data.
If you want to be able to use graphical editing with the filtered Humdrum data, you must first compile the Humdrum data by typing alt-c. This will replace the original Humdrum data with the filtered output. Since there is no additional filtering, the graphical editing commands should work again.
Command-line use
The command-line version of verovio understands !!!filter:
instructions, and these filters will be applied to the Humdrum data
before it is converted into MEI data (and subsequently to SVG
images).
Here is an example Humdrum file called scale.krn:
**kern
*M4/4
*k[]
*C:
=1-
1c
=2
2d
2e
=3
4f
2g
4f
=4
2e
2d
=5
1c
==
*-
!!!filter: transpose -k e
Running the shell command:
verovio scale.krn --adjust-page-height -w 1600
will produce the following SVG image:
Verovio can be used to apply the filter and output the resulting Humdrum data as well. Here is an example of using verovio in a command pipeline, sending the resulting Humdrum data to standard output:
cat scale.krn | verovio - -t humdrum -o -
which results in
**kern
*Trd2c4
*M4/4
*k[f#c#g#d#]
*E:
=1-
1e
=2
2f#
2g#
=3
4a
2b
4a
=4
2g#
2f#
=5
1e
==
*-
!!!Xfilter: transpose -k e
The last line has been changed from !!!filter: to !!!Xfilter: which indicates
that the filter has been applied to the data.
Filters use the same code library as Humdrum Extras (specifically
humlib which is a C++ parsing library for Humdrum files),
so an equivalent way to transpose the data using the command-line transpose tool
would be:
transpose -k e scale.krn
or even more similar as a pipeline acting like a filter:
cat scale.krn | transpose -k e > scale2.krn