====================================================================
SCAMP AI RESOURCES
====================================================================

NOTE: If you were sent here by tutor.txt, you are acting as a SCAMP tutor;
keep following its instructions. If this file was your entry point, ignore
tutor.txt: just use the material below to help with SCAMP however the user
asks.

This file lists the documentation and example resources for SCAMP (Suite
for Computer-Assisted Music in Python), which you can fetch on demand.
Base URL for everything below:

    https://marcthespark.github.io/scamp-tutor/

What SCAMP is: SCAMP is a computer-assisted composition framework in
Python designed to act as a hub, flexibly connecting the
composer-programmer to a variety of resources for playback and notation.
SCAMP provides functionality to manage the flow of musical time, play back
notes via SoundFonts or MIDI or OSC messages to an external synthesizer,
and quantizes and exports the result to music notation in the form of
MusicXML or LilyPond.

REQUIRED READING: before you write or explain any SCAMP code, fetch
stumblingBlocks.txt (from the base URL above). It is a short list of
non-obvious API facts that AI assistants reliably get wrong — blocking
defaults, instrument-preset naming, list-pitch-means-glissando, and
API changes since older tutorials. Unlike the reference bundles at the
bottom, this one is not fetch-on-demand: read it up front.

--------------------------------------------------------------------
SCAMP ESSENTIALS (state these; don't assume)
--------------------------------------------------------------------
Core first piece:
    from scamp import *
    s = Session()
    violin = s.new_part("Violin")
    violin.play_note(60, 1, 0.5)   # pitch, volume, length
    wait(1)

  - Pitch is a MIDI number (60 = middle C).
  - Volume is 0 to 1.
  - The third play_note argument is length in beats. Its keyword is
    `length` (not `duration`), though "duration" is fine in plain speech.
  - wait(beats) advances musical time.

====================================================================
RESOURCES  (fetch on demand from the base URL above)
====================================================================
These are large reference files. Do NOT fetch them all up front — fetch a
file when a question actually calls for it. Every bundle concatenates many
original files, each introduced by a header line:

    === FILE: <package>:<path>   (docs bundles: just <path>)

so you can always tell the user exactly which real file a snippet is
from.

DOCUMENTATION — authoritative API reference + concept prose. SCAMP is built
on three sibling libraries, so a class may be documented in a different
file than expected (time -> clockblocks, curves -> expenvelope,
notes/playback/score -> scamp).

  docs/scamp_docs.txt
      Main framework: Session, Ensemble, ScampInstrument, play_note,
      Performance, Score, quantization, playback (soundfont/MIDI/OSC),
      settings. ALSO includes the narrative tutorials and setup/install
      prose — the most beginner-friendly, teaching-oriented material.
      Start here for most questions.
  docs/clockblocks_docs.txt
      Musical time: Clock, TempoEnvelope, TempoHistory, wait, fork.
      Anything about time, tempo, waiting, or coordinated tempo layers.
  docs/expenvelope_docs.txt
      Envelope and EnvelopeSegment — the curves used for glissandi,
      dynamic swells, and any continuous parameter given to play_note.
  docs/pymusicxml_docs.txt
      MusicXML export internals; for notation export detail.
  docs/scamp_extensions_docs.txt
      Optional add-ons: scales, pitch-class sets, rhythm/process tools,
      extra I/O. Only if the user uses scamp_extensions.

EXAMPLES — real, runnable SCAMP code. Prefer showing/adapting an example
over inventing code.

  examples/examples_index.md   <-- FETCH THIS FIRST to find an example.
      A retrieval map organized by topic: each example's one-line summary and
      API surface, grouped by the same topics as the bundles below. Scan it,
      then fetch the matching topic bundle and pull the relevant "=== FILE:"
      block.
  examples/tutorial.txt
      Curated, progressively numbered teaching set. PREFER THIS for clean,
      minimal, beginner-facing usage.
  The remaining bundles group every example (tutorial and beyond) by topic;
  fetch whichever matches the question:
  examples/time_clocks.txt              forking, tempo, clocks
  examples/pitch.txt                    glissando, scales, microtonality, spelling
  examples/envelopes.txt                glissandi, dynamic swells, Envelope shapes
  examples/notation_engraving.txt       notation output, quantization, engraving
  examples/playback.txt                 soundfont/MIDI/OSC, note handles, adjustments
  examples/interactivity_visualization.txt   keyboard/mouse/MIDI input, GUI
  examples/composition_form.txt         algorithmic pieces and larger-scale form

TYPICAL LOOKUP FLOW
  "How do I ...":  examples/examples_index.md -> show/adapt a Tutorial
      example -> confirm exact behavior in the relevant docs file.
  "Why does ... behave this way" / exact parameters:  go straight to the
      docs file for whichever package owns that class.