docs/analyze-response-format-examples.json

{
  "note": "Illustrative POST /analyze HTTP 200 JSON bodies for single-staff v1. Shapes follow docs/analyze-api-spec.md; musical values are synthetic.",
  "version": "1.0-single-staff",
  "examples": {
    "single_image_monophonic": {
      "request_id": "11111111-2222-3333-4444-555555555555",
      "source": {
        "total_images": 1,
        "filenames": ["sample_oneline_0.png"]
      },
      "score_context": {
        "clef": "treble",
        "key_signature": { "fifths": -1 },
        "time_signature": "4/4",
        "tempo_bpm_reference": 72,
        "divisions": 4,
        "source": "client"
      },
      "timeline": {
        "divisions": 4,
        "time_signature": "4/4",
        "tempo_bpm_reference": 72
      },
      "melody": {
        "voice_id": "melody1",
        "reduction_rule": "top_note_max_two_parts",
        "events": [
          {
            "event_id": "e_0001",
            "type": "rest",
            "duration_div": 4,
            "onset_div": 0,
            "segment_order": 1
          },
          {
            "event_id": "e_0002",
            "type": "note",
            "step": "F",
            "octave": 4,
            "alter": 0,
            "pitch_midi": 65,
            "duration_div": 4,
            "onset_div": 4,
            "confidence": 0.91,
            "segment_order": 1,
            "bbox": [120, 18, 14, 10]
          },
          {
            "event_id": "e_0003",
            "type": "note",
            "step": "G",
            "octave": 4,
            "alter": 0,
            "pitch_midi": 67,
            "duration_div": 2,
            "onset_div": 8,
            "confidence": 0.88,
            "segment_order": 1,
            "bbox": [160, 16, 12, 10]
          }
        ]
      },
      "segment_map": [
        {
          "segment_id": "seg1",
          "order": 1,
          "filename": "sample_oneline_0.png",
          "width": 726,
          "height": 120,
          "event_index_range": { "start": 0, "end": 2 }
        }
      ],
      "warnings": ["timing_from_pixel_gaps_heuristic"],
      "meta": {
        "pipeline_mode": "single_staff_v1",
        "preprocess": {
          "segments": [
            {
              "segment_order": 1,
              "original_size": { "width": 726, "height": 120 },
              "work_size": { "width": 726, "height": 120 },
              "uniform_scale": 1.0,
              "deskew_deg": 1.2,
              "illumination_normalized": true
            }
          ]
        }
      }
    },
    "single_image_chord_reduction_to_top": {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "source": {
        "total_images": 1,
        "filenames": ["sample_oneline_chord.png"]
      },
      "score_context": {
        "clef": "treble",
        "key_signature": { "fifths": 0 },
        "time_signature": "4/4",
        "tempo_bpm_reference": null,
        "divisions": 4,
        "source": "client"
      },
      "timeline": {
        "divisions": 4,
        "time_signature": "4/4",
        "tempo_bpm_reference": null
      },
      "melody": {
        "voice_id": "melody1",
        "reduction_rule": "top_note_max_two_parts",
        "events": [
          {
            "event_id": "e_0001",
            "type": "note",
            "step": "E",
            "octave": 5,
            "alter": 0,
            "pitch_midi": 76,
            "duration_div": 8,
            "onset_div": 0,
            "confidence": 0.84,
            "segment_order": 1,
            "bbox": [40, 22, 18, 12]
          },
          {
            "event_id": "e_0002",
            "type": "note",
            "step": "D",
            "octave": 5,
            "alter": -1,
            "pitch_midi": 73,
            "duration_div": 4,
            "onset_div": 8,
            "confidence": 0.8,
            "segment_order": 1,
            "bbox": [90, 20, 16, 11]
          }
        ]
      },
      "segment_map": [
        {
          "segment_id": "seg1",
          "order": 1,
          "filename": "sample_oneline_chord.png",
          "width": 900,
          "height": 140,
          "event_index_range": { "start": 0, "end": 1 }
        }
      ],
      "warnings": ["annotation_overlap_detected", "timing_from_pixel_gaps_heuristic"],
      "meta": {
        "pipeline_mode": "single_staff_v1",
        "preprocess": {
          "segments": [
            {
              "segment_order": 1,
              "original_size": { "width": 900, "height": 140 },
              "work_size": { "width": 900, "height": 140 },
              "uniform_scale": 1.0,
              "deskew_deg": 0.4,
              "illumination_normalized": true
            }
          ]
        }
      }
    },
    "two_images_merged_timeline": {
      "request_id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
      "source": {
        "total_images": 2,
        "filenames": ["sample_oneline_0.png", "sample_oneline_1.png"]
      },
      "score_context": {
        "clef": "treble",
        "key_signature": { "fifths": -1 },
        "time_signature": "4/4",
        "tempo_bpm_reference": 60,
        "divisions": 4,
        "source": "client"
      },
      "timeline": {
        "divisions": 4,
        "time_signature": "4/4",
        "tempo_bpm_reference": 60
      },
      "melody": {
        "voice_id": "melody1",
        "reduction_rule": "top_note_max_two_parts",
        "events": [
          {
            "event_id": "e_0001",
            "type": "note",
            "step": "C",
            "octave": 5,
            "alter": 0,
            "pitch_midi": 72,
            "duration_div": 4,
            "onset_div": 0,
            "segment_order": 1
          },
          {
            "event_id": "e_0002",
            "type": "note",
            "step": "D",
            "octave": 5,
            "alter": 0,
            "pitch_midi": 74,
            "duration_div": 4,
            "onset_div": 4,
            "segment_order": 1
          },
          {
            "event_id": "e_0003",
            "type": "note",
            "step": "E",
            "octave": 5,
            "alter": 0,
            "pitch_midi": 76,
            "duration_div": 4,
            "onset_div": 8,
            "segment_order": 2
          },
          {
            "event_id": "e_0004",
            "type": "rest",
            "duration_div": 4,
            "onset_div": 12,
            "segment_order": 2
          }
        ]
      },
      "segment_map": [
        {
          "segment_id": "seg1",
          "order": 1,
          "filename": "sample_oneline_0.png",
          "width": 726,
          "height": 120,
          "event_index_range": { "start": 0, "end": 1 }
        },
        {
          "segment_id": "seg2",
          "order": 2,
          "filename": "sample_oneline_1.png",
          "width": 700,
          "height": 118,
          "event_index_range": { "start": 2, "end": 3 }
        }
      ],
      "warnings": ["line_break_between_images", "timing_from_pixel_gaps_heuristic"],
      "meta": {
        "pipeline_mode": "single_staff_v1",
        "preprocess": {
          "segments": [
            {
              "segment_order": 1,
              "original_size": { "width": 726, "height": 120 },
              "work_size": { "width": 726, "height": 120 },
              "uniform_scale": 1.0,
              "deskew_deg": 1.1,
              "illumination_normalized": true
            },
            {
              "segment_order": 2,
              "original_size": { "width": 700, "height": 118 },
              "work_size": { "width": 700, "height": 118 },
              "uniform_scale": 1.0,
              "deskew_deg": -0.6,
              "illumination_normalized": true
            }
          ]
        }
      }
    },
    "error_unprocessable_staff_layout": {
      "error": {
        "code": "UNPROCESSABLE_STAFF_LAYOUT",
        "message": "Expected exactly one staff per image.",
        "details": {
          "segment_order": 1,
          "detected_staff_candidates": 2
        }
      }
    }
  }
}