Skip to main content
Overlays attach analytical metadata to score regions without modifying the score itself. See: /MRS-Specification-RFC#10-analytical-overlays

​
Purpose

Overlays enable:
  • Harmonic analysis (chord symbols, Roman numerals)
  • Thematic analysis (motifs, themes, occurrences)
  • Form analysis (phrases, periods, sections)
  • Voice-leading analysis
  • Performance annotations
This information enriches context views and the structural index without cluttering the score content.

​
Overlay Structure

(overlays
  (overlay :id harmonic-analysis
    :type harmonic
    :author "harmony-agent"
    :created "2026-01-17T10:30:00Z"
    
    :regions
      ((region :measures #uuid "..." #uuid "..."
               :content
                 (chord :beat 0 :symbol Cm :function i)
                 (chord :beat 2 :symbol Fm :function iv)
                 (chord :beat 0 :symbol G7 :function V7))))
  
  (overlay :id motivic-analysis
    :type thematic
    :author "analysis-agent"
    :created "2026-01-17T10:30:00Z"
    
    :themes
      ((theme :id theme-a :label "Main theme"
              :first-occurrence #uuid "..."
              :characteristics "descending fourth, dotted rhythm")
       (theme :id theme-b :label "Second theme"
              :first-occurrence #uuid "..."
              :characteristics "lyrical, stepwise"))))

​
Overlay Types

​
Harmonic Analysis

(overlay :id harmonic-analysis
  :type harmonic
  :author "harmony-agent"
  :regions
    ((region :measures #uuid "..." #uuid "..."
             :content
               (chord :beat 0 :symbol Cm :function i :inversion root)
               (chord :beat 2 :symbol Ddim7 :function viio7/V)
               (chord :beat 0 :symbol G7 :function V7 :cadence half))))
FieldDescription
:symbolChord symbol (Cm, G7, etc.)
:functionRoman numeral function
:inversionroot, first, second, third
:cadenceCadence type if applicable

​
Thematic Analysis

(overlay :id motivic-analysis
  :type thematic
  :themes
    ((theme :id theme-a 
            :label "Main theme"
            :first-occurrence #uuid "..."
            :characteristics "descending fourth, dotted rhythm"
            :occurrences [#uuid "..." #uuid "..." #uuid "..."])
     (theme :id theme-b
            :label "Second theme"
            :first-occurrence #uuid "...")))

​
Form Analysis

(overlay :id form-analysis
  :type form
  :structure
    ((section :type exposition :measures #uuid "..." #uuid "...")
     (section :type development :measures #uuid "..." #uuid "...")
     (section :type recapitulation :measures #uuid "..." #uuid "..."))
  :phrases
    ((phrase :type antecedent :measures #uuid "..." #uuid "...")
     (phrase :type consequent :measures #uuid "..." #uuid "...")))

​
Voice-Leading Analysis

(overlay :id voice-leading
  :type voice-leading
  :issues
    ((issue :type parallel-fifths 
            :location (:measure #uuid "..." :beat 2)
            :parts [soprano bass])
     (issue :type hidden-octaves
            :location (:measure #uuid "..." :beat 0)
            :parts [alto tenor])))

​
Overlay Lifecycle

LifecycleDescription
PersistentStored with the score, survives save/load
SessionValid only for current editing session
DerivedRecomputed after score changes

​
Derived Overlays

Some overlays can be automatically derived:
  • Key signature regions (from measure attributes)
  • Tempo regions (from tempo markings)
  • Rehearsal structure (from rehearsal marks)
Others require analysis:
  • Harmonic function (needs chord identification)
  • Thematic material (needs pattern recognition)
  • Form labels (needs structural analysis)

​
Usage in Context Views

Overlays feed into context views: 
(context-view harmonic-context
  :source overlay:harmonic-analysis
  :measures #uuid "..." #uuid "..."
  :content
    (harmony-events
      (chord :measure #uuid "..." :beat 0 :symbol Cm :function i)
      ...))

​
Usage in Structural Index

Overlays enrich the structural index: 
(structural-index
  ...
  :harmonic-spine (:ref overlay:harmonic-analysis)
  :thematic-catalog (:ref overlay:motivic-analysis)
  ...)

​
Overlay Attribution

Every overlay includes:
FieldDescription
:idUnique identifier
:typeOverlay type
:authorWho created it (agent or human)
:createdCreation timestamp
This enables tracking provenance and managing multiple analyses.