Music Lesson

An instrument or music lesson extracted from a video — learning an instrument, chords, scales, technique, theory, or a specific song. Captures the instrument, what is taught, the ordered lesson steps, and practice guidance. Optional fields are omitted when the creator does not state them — do not infer.

Fields

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "vidextract.predefined.music_lesson.v1",
  "title": "Music Lesson",
  "description": "An instrument or music lesson extracted from a video — learning an instrument, chords, scales, technique, theory, or a specific song. Captures the instrument, what is taught, the ordered lesson steps, and practice guidance. Optional fields are omitted when the creator does not state them — do not infer.",
  "type": "object",
  "required": [
    "title",
    "summary",
    "steps"
  ],
  "additionalProperties": false,
  "properties": {
    "title": {
      "type": "string",
      "description": "Title of the lesson, e.g. 'First 7 chords on guitar'."
    },
    "summary": {
      "type": "string",
      "description": "Two or three sentences describing what is taught and the goal of the lesson."
    },
    "instrument": {
      "type": "string",
      "description": "Instrument taught, lowercased, e.g. 'guitar', 'piano', 'drums', 'violin'. Use 'voice' for singing. Omit if purely theory."
    },
    "lessonType": {
      "type": "string",
      "enum": [
        "technique",
        "chords",
        "scales",
        "theory",
        "song-tutorial",
        "rhythm",
        "ear-training",
        "improvisation",
        "warmup",
        "fundamentals"
      ],
      "description": "Primary focus of the lesson. Pick the single best fit. Omit if unclear."
    },
    "level": {
      "type": "string",
      "enum": [
        "beginner",
        "intermediate",
        "advanced"
      ],
      "description": "Target skill level if stated or clearly implied. Omit if unclear."
    },
    "musicalKey": {
      "type": "string",
      "description": "Key of the piece or exercise if stated, e.g. 'G major', 'A minor'. Omit otherwise."
    },
    "tempo": {
      "type": "string",
      "description": "Tempo as stated, e.g. '120 bpm', 'slow'. Omit otherwise."
    },
    "songTaught": {
      "type": "string",
      "description": "If the lesson teaches a specific song, its title (and artist if given). Omit otherwise."
    },
    "prerequisites": {
      "type": "array",
      "description": "Skills, gear, or setup the creator says the learner should already have, e.g. 'a tuned guitar', 'know basic open chords'.",
      "items": {
        "type": "string"
      }
    },
    "musicalElements": {
      "type": "array",
      "description": "Specific chords, scales, notes, or patterns taught in the lesson.",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the element, e.g. 'G major', 'C chord', 'pentatonic scale', 'down-up strum'."
          },
          "type": {
            "type": "string",
            "enum": [
              "chord",
              "scale",
              "note",
              "rhythm-pattern",
              "interval",
              "progression",
              "arpeggio",
              "technique"
            ],
            "description": "What kind of element this is. Omit if unclear."
          },
          "instruction": {
            "type": "string",
            "description": "How to play or finger it as described, e.g. 'first finger on second fret of the third string'. Omit if not detailed."
          }
        }
      }
    },
    "steps": {
      "type": "array",
      "description": "Ordered lesson steps in the order taught.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "instruction"
        ],
        "additionalProperties": false,
        "properties": {
          "instruction": {
            "type": "string",
            "description": "What to do or learn in this step."
          },
          "focus": {
            "type": "string",
            "description": "The specific chord, technique, or concept this step centers on. Omit if general."
          },
          "videoTimestamp": {
            "type": "string",
            "description": "Start timestamp of this step in the source video, 'mm:ss' or 'h:mm:ss'. Omit if unknown.",
            "pattern": "^(\\d{1,2}:)?\\d{1,2}:\\d{2}$"
          }
        }
      }
    },
    "techniques": {
      "type": "array",
      "description": "Named techniques taught, e.g. 'alternate picking', 'bending', 'pedal use', each with a brief note.",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Technique name."
          },
          "explanation": {
            "type": "string",
            "description": "Brief explanation as given. Omit if only named."
          }
        }
      }
    },
    "practiceTips": {
      "type": "array",
      "description": "Practice routines, drills, or advice for mastering the material.",
      "items": {
        "type": "string"
      }
    },
    "commonMistakes": {
      "type": "array",
      "description": "Mistakes the creator warns learners against, e.g. 'muting adjacent strings', 'pressing too hard'.",
      "items": {
        "type": "string"
      }
    }
  }
}

Use it via the API

Pass schemaId: "vidextract.predefined.music_lesson.v1" when you submit an extraction. The call returns an id immediately. Poll GET /v1/extractions/{id}/result (or register a webhook) for the structured result.

curl -s -X POST https://postreef.com/v1/extractions \
  -H "x-api-key: $VIDEXTRACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
       "inputs": ["transcript", "comments"],
       "schemaId": "vidextract.predefined.music_lesson.v1"}'

Full request/response shape in the API reference; copy-paste poll loops in the API quickstart.