Incipit search

The incipit search is available as part of the Search API. However, there are a number of additional features available in the incipit search that are further discussed here.

Perhaps the easiest way to understand the Incipit search API is to use the user interface to construct some queries and then analyze the URL that the UI generates as the search input. As with all other URLs on RISM Online, a JSON representation of the results can be found by requesting the URL with an Accept header of application/ld+json.

A further note: Not all records in RISM Online with an "Incipit" entry have music notation attached. Some records are described by a text incipit, and others have been catalogued with only the key, clef, or time signature described.

Plaine and Easie

The incipit search is built around Plaine and Easie (PAE), a small music notation encoding system designed for incipit capture. Incipits are primarily monophonic (a single voice) and intended to serve as a melodic identifier, for the purposes of distinguishing one musical work from another.

This documentation will assume some knowledge of PAE. You are encouraged to read the PAE documentation for more details on how PAE works.

The first thing to know about the RISM Online Incipit Search is that search queries are expressed as PAE. However, valid PAE can just be a set of pitch names -- Verovio will assume an even note duration value, and also assume that the notes are given in the fifth octave. (That is, "C" = C5, or Middle C). Verovio also serves as a way of normalizing PAE queries so that the differences between two expressions of PAE that encode the same melody do not have an impact on the search results.

When queries are processed, Verovio will extract some representations from them, and use those representations as the query format to our Solr search instance. The default representation is "intervals", which means the PAE is processed to a representation of the chromatic intervals of the PAE string, and this is used as the basis of the query to the Solr index. This provides matches that are transposition-invariant. In contrast, the "exact pitch" representation extracts a string that includes the letter pitch values. This can be effective if you are searching for a certain melody, but only want results that are in a specific key. Finally, the "contour" representation provides a way of melodic search that attempts to match the melodic direction between intervals, similar to the well-known Parson's Code.

At this time, note durations have no effect on query results. They are supported as PAE input, but they are dropped from the query representations generated by Verovio.

Clef, Key Signature, Time Signature

In the incipit search interface there are controls for adjusting the clef, key signature, and time signature. It is perhaps notable that of these three, only "key signature" has an effect on search results, and only indirectly. The key signature is sent to ensure that the contour is processed correctly, and thus the intervals are computed accurately.

If you wish to actually filter results by any of these properties, the filter queries should be used. These function exactly the same as the other search interfaces.

Text Queries

A "Keyword Query" field is given on the incipit search interface. With this, users may combine a melodic query with keywords appearing anywhere in the text of a record, and results will be filtered by these keywords as well.