> ## Documentation Index
> Fetch the complete documentation index at: https://musicready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytical Overlays

> Typed metadata layers attached to score regions.

Overlays attach analytical metadata to score regions without modifying the score itself.

See: [`/MRS-Specification-RFC#10-analytical-overlays`](/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

```clojure theme={null}
(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

```clojure theme={null}
(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

```clojure theme={null}
(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

```clojure theme={null}
(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

```clojure theme={null}
(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:

```clojure theme={null}
(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:

```clojure theme={null}
(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.