Analytical Overlays

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))))

Field	Description
`:symbol`	Chord symbol (Cm, G7, etc.)
`:function`	Roman numeral function
`:inversion`	root, first, second, third
`:cadence`	Cadence 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

Lifecycle	Description
Persistent	Stored with the score, survives save/load
Session	Valid only for current editing session
Derived	Recomputed 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:

Field	Description
`:id`	Unique identifier
`:type`	Overlay type
`:author`	Who created it (agent or human)
`:created`	Creation timestamp

This enables tracking provenance and managing multiple analyses.

Overview

MRS-S Format

Agent Workflows

Model & Validation

Purpose

Overlay Structure

Overlay Types

Harmonic Analysis

Thematic Analysis

Form Analysis

Voice-Leading Analysis

Overlay Lifecycle

Derived Overlays

Usage in Context Views

Usage in Structural Index

Overlay Attribution

​Purpose

​Overlay Structure

​Overlay Types

​Harmonic Analysis

​Thematic Analysis

​Form Analysis

​Voice-Leading Analysis

​Overlay Lifecycle

​Derived Overlays

​Usage in Context Views

​Usage in Structural Index

​Overlay Attribution

Purpose

Overlay Structure

Overlay Types

Harmonic Analysis

Thematic Analysis

Form Analysis

Voice-Leading Analysis

Overlay Lifecycle

Derived Overlays

Usage in Context Views

Usage in Structural Index

Overlay Attribution