Documentation for filters in VHV.

Filters allow you to manipulate the contents of Humdrum data before it is converted into notation. They can also be used to manipulate the data when preparing a score, such as to add a new spine, or to beam notes together.

As an example of filtering before rendering to music notation, a graphic score can be transposed while keeping the Humdrum data in the text editor at the original pitch. Here are links to Mozart’s Sonata facile, which was written in C major but can be transposed to any other key:

C-flat major | C major (unfilterd) | C-sharp major | D major | D-flat major | E-flat major | E major | F major | F-sharp major | G-flat major | G major | A-flat major | A major | B-flat major | B major

Notice in each case that the Humdrum data in the text editor remains in C major. If you want to alter the Humdrum data in the text editor, then type the alt-c keyboard shortcut. This will “compile” the filters in the data and replace the original data with the filtered data. Here are examples where the music is displayed in every key and the data is also modified to match that key:

C-flat major | C major (unfilterd) | C-sharp major | D major | D-flat major | E-flat major | E major | F major | F-sharp major | G-flat major | G major | A-flat major | A major | B-flat major | B major

Filter toolbar

A filter toolbar is available in the top right corner of the VHV interface:


If no toolbar is visible, then press alt-shift-N to make the toolbar visible, or press alt-shift-E to toggle display of both the menu and the toolbar. If a different toolbar is visible, click on the circular icon on the right until the filter toolbar is visible. The keyboard shortcut 5+alt-n can be typed to display the filter toolbar directly (you may need to click in the music notation pane to defocus the text editor; otherwise, a “5” will be inserted into the text).

Using the filter toolbar

Type a filter into the filter box. As you type the filter, nothing will happen to the notation since the filter is not yet being applied. After you have finished entering the filter, either press the return key, or click on the filter icon on the right side of the filter input box. This will cause the filter icon to highlight in yellow, meaning that the filter is currently being applied to the data:


If you type more content in the filter box, the filter icon will stop highlighting and the filter will stop being applied to the data. In such a case, press return or click on the filter icon to reactivate the filter. You can also click on the yellow filter icon to stop the filter from being applied before the data is converted into graphical notation.

If you want to replace the original Humdrum data in the text editor with the filtered data, click on the
icon or type alt-c to "compile" the filter.

Embedded filters

Instead of using the toolbar interface, you can also type filter commands directly into the Humdrum data. Prefix the filter with !!!filter:. Each filter line found in the data will be processed in sequence before displaying the notation; otherwise, the placement of the filter lines is not important: they can go at the top, bottom or somewhere in the middle of the data.

Here is an example of embedding three separate filters into the data:

Embedding three filters.
Embedding three filters into Humdrum data.

The first three lines of the data contain the filters:

!!!filter: myank -m 1-3
!!!filter: extract -i kern
!!!filter: transpose -t -m3

The myank filter extracts the first three measures of the score, the extract filter removes the lyrics from the score, and transpose transposes the music down a minor third. To use all three filters from the toolbar, separate them with the pipe character (|). This can also be done to merge multiple filters onto a single line in the data:

!!!filter: myank -m 1-3 | extract -i kern | transpose -t -m3
Combining three filters.
Combining three filters on filter toolbar.

Examples by topic/filter

Click on the blue filter text to load the filter into VHV and apply to a sample piece of music.

Transposition

The transposition filter can be used to transpose the score in various ways that are illustrated below.

Compound filters

Here are examples of how to mix multiple filters together. Each filter is separated from the next with a pipe character (|).

Musical excerpts

The myank filter can be used to extract musical examples from longer scores.

Part extraction

The extract filter can be used to extract parts and other data spines from a full score.

Chords

The chord filter can be used to manipulate chords.

Searching

The msearch filter (meaning music search) can be used to search for musical patterns.

Search and replace

The shed filter can be used to search and replace content in Humdrum data. “Shed” stands for “Humdrum sed” (dyslexic, but easier to pronounce).

Counterpoint

The cint filter (meaning composite intervals) can be used to study counterpoint. The cint program is an intersection of functionalities between the mint and hint programs of the Humdrum Toolkit, and it creates counterpoint modules that consist of four notes in two voices, which in turn generates two harmonic and two melodic intervals for each module.

Command-line filters

The filters available in VHV come from humlib. Filters can be compiled as command-line tools:

Command-line use of myank and transpose filters.
Command-line use of myank and transpose filters.
Equivalent filtering in VHV.
Equivalent filtering in VHV.

There are additional command-line tools in humlib that are not available as filters. These mostly involve extra tools for data analysis other than data manipulation or generating music notation. More tools for the command-line are also available in Humdrum Extras and the Humdrum Toolkit. See the humdrum-tools repository for instructions on how to compile and use these tools on the command-line.