File Structure

The Hello World example used one instrument and one section. This page adds a second instrument, performance directions, annotations, and a repeat, using the real ลาวดวงเดือน (Lao Duang Duen).

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<thai-score xmlns="https://thaimusicxml.anan.ovh/ns/1" version="1.0">
  <header>
    <title>ลาวดวงเดือน</title>
    <composer><text align="right">ทำนอง: พระเจ้าบรมวงศ์เธอ กรมหมื่นพิไชยมหินทโรดม</text></composer>
  </header>
  <structure>
    <direction>
      <nathap value="ลาว" />
      <chan value="2" />
      <bpm>60</bpm>
    </direction>
    <repeat times="2">
      <annotation>ท่อน 1</annotation>
      <section id="s1" name="ท่อน 1" />
      <annotation>
        <text align="right">(กลับต้น)</text>
      </annotation>
    </repeat>
  </structure>
  <ensemble>
    <part id="P1">
      <instrument-name>ระนาดเอก</instrument-name>
      <instrument-short-name>รน.เอก</instrument-short-name>
    </part>
    <part id="P2" type="unpitched">
      <instrument-name>ฉิ่ง</instrument-name>
    </part>
  </ensemble>
  <part-data part="P1">
    <section-ref section="s1">
      <line number="1">
        <measure number="1"><rest/><rest/><rest/><rest/></measure>
        <measure number="2"><rest/><rest/><rest/><rest/></measure>
        <measure number="3"><rest/><note pitch="ด"/><note pitch="ร"/><note pitch="ม"/></measure>
        <measure number="4"><rest/><note pitch="ซ"/><rest/><note pitch="ด"/></measure>
        <measure number="5"><rest/><rest/><rest/><note pitch="ร"/></measure>
        <measure number="6"><note pitch="ด"/><note pitch="ด"/><note pitch="ด"/><note pitch="ด"/></measure>
        <measure number="7"><note pitch="ซ"/><note pitch="ล"/><note pitch="ด"/><note pitch="ล"/></measure>
        <measure number="8"><note pitch="ซ"/><note pitch="ม"/><rest/><note pitch="ซ"/></measure>
      </line>
      <line number="2">
        <measure number="1"><rest/><rest/><rest/><note pitch="ล"/></measure>
        <measure number="2"><note pitch="ซ"/><note pitch="ซ"/><note pitch="ซ"/><note pitch="ซ"/></measure>
        <measure number="3"><rest/><note pitch="ม"/><note pitch="ซ"/><note pitch="ม"/></measure>
        <measure number="4"><note pitch="ซ"/><note pitch="ล"/><note pitch="ด"/><note pitch="ล"/></measure>
        <measure number="5"><rest/><rest/><note pitch="ด"/><note pitch="ล"/></measure>
        <measure number="6"><rest/><note pitch="ซ"/><rest/><note pitch="ม"/></measure>
        <measure number="7"><note pitch="ร"/><note pitch="ม"/><note pitch="ซ"/><note pitch="ม"/></measure>
        <measure number="8"><note pitch="ร"/><note pitch="ด"/><rest/><note pitch="ร"/></measure>
      </line>
      <line number="3">
        <measure number="1"><rest/><rest/><rest/><note pitch="ม"/></measure>
        <measure number="2"><note pitch="ร"/><note pitch="ร"/><note pitch="ร"/><note pitch="ร"/></measure>
        <measure number="3"><note pitch="ซ"/><note pitch="ล"/><note pitch="ซ"/><note pitch="ด"/></measure>
        <measure number="4"><rest/><note pitch="ร"/><rest/><note pitch="ม"/></measure>
        <measure number="5"><rest/><note pitch="ซ"/><rest/><rest/></measure>
        <measure number="6"><rest/><note pitch="ด"/><rest/><note pitch="ร"/></measure>
        <measure number="7"><rest/><note pitch="ม"/><note pitch="ซ"/><note pitch="ร"/></measure>
        <measure number="8"><note pitch="ม"/><note pitch="ร"/><note pitch="ด"/><note pitch="ล"/></measure>
      </line>
      <line number="4">
        <measure number="1"><rest/><rest/><rest/><rest/></measure>
        <measure number="2"><note pitch="ซ"/><note pitch="ล"/><note pitch="ด"/><note pitch="ม"/></measure>
        <measure number="3"><note pitch="ร"/><note pitch="ด"/><note pitch="ร"/><note pitch="ม"/></measure>
        <measure number="4"><rest/><note pitch="ซ"/><rest/><note pitch="ล"/></measure>
        <measure number="5"><rest/><rest/><note pitch="ด"/><note pitch="ล"/></measure>
        <measure number="6"><note pitch="ซ"/><note pitch="ม"/><note pitch="ซ"/><note pitch="ล"/></measure>
        <measure number="7"><note pitch="ซ"/><note pitch="ล"/><note pitch="ด"/><note pitch="ล"/></measure>
        <measure number="8"><rest/><note pitch="ซ"/><note pitch="ซ"/><note pitch="ซ"/></measure>
      </line>
      <ending pass="2">
        <annotation>ลงเที่ยว 2</annotation>
        <line number="4">
          <measure number="1"></measure>
          <measure number="2"></measure>
          <measure number="3"></measure>
          <measure number="4"></measure>
          <measure number="5"></measure>
          <measure number="6"></measure>
          <measure number="7"><rest/><note pitch="ด"/><note pitch="ร"/><note pitch="ม"/></measure>
          <measure number="8"><rest/><note pitch="ร"/><rest/><note pitch="ด"/></measure>
        </line>
      </ending>
    </section-ref>
  </part-data>
  <part-data part="P2">
    <section-ref section="s1">
      <line number="1">
        <measure number="1"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="2"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="3"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="4"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="5"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="6"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="7"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="8"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
      </line>
      <line number="2">
        <measure number="1"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="2"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="3"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="4"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="5"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="6"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="7"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="8"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
      </line>
      <line number="3">
        <measure number="1"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="2"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="3"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="4"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="5"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="6"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="7"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="8"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
      </line>
      <line number="4">
        <measure number="1"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="2"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="3"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="4"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="5"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="6"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        <measure number="7"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
        <measure number="8"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
      </line>
      <ending pass="2">
        <annotation>ลงเที่ยว 2</annotation>
        <line number="4">
          <measure number="1"></measure>
          <measure number="2"></measure>
          <measure number="3"></measure>
          <measure number="4"></measure>
          <measure number="5"></measure>
          <measure number="6"></measure>
          <measure number="7"><rest/><rest/><rest/><note sound="ฉิ่ง"/></measure>
          <measure number="8"><rest/><rest/><rest/><note sound="ฉับ"/></measure>
        </line>
      </ending>
    </section-ref>
  </part-data>
</thai-score>

Header

The <header> can include a <composer> alongside <title>:

<header>
  <title>ลาวดวงเดือน</title>
  <composer><text align="right">ทำนอง: พระเจ้าบรมวงศ์เธอ กรมหมื่นพิไชยมหินทโรดม</text></composer>
</header>

Like <annotation>, <composer> can hold plain text or a <text> child with an align attribute. Here the composer line is right-aligned.

Structure

The <structure> element holds the score layout. It can contain annotations, performance directions, sections, and repeats:

<structure>
  <direction>
    <nathap value="ลาว" />
    <chan value="2" />
    <bpm>60</bpm>
  </direction>
  <repeat times="2">
    <annotation>ท่อน 1</annotation>
    <section id="s1" name="ท่อน 1" />
    <annotation>
      <text align="right">(กลับต้น)</text>
    </annotation>
  </repeat>
</structure>

• <direction>: Performance directions that apply to the whole score.
  • <nathap> names the drum cycle, here หน้าทับลาว.
  • <chan> sets the ชั้น (rhythmic layer). value="2" means สองชั้น. ชั้น is not tempo; it is the spacing of the ฉิ่ง cycle. See The score model for the distinction.
  • <bpm> fixes the tempo at 60 beats per minute.
• <repeat times="2">: Wrapping a section in <repeat> plays it more than once. Here ท่อน 1 plays twice.
• <annotation>: Free-form text. Inside <structure>, annotations label sections and add performance notes. The <text align="right">(กลับต้น)</text> annotation tells the player to return to the beginning.

Line and measure numbering

Line and measure numbers are local to their parent. Lines start at 1 in each <section-ref>, and measures start at 1 in each <line>:

<section-ref section="s1">
  <line number="1">
    <measure number="1">...</measure>
    <measure number="2">...</measure>
  </line>
  <line number="2">
    <measure number="1">...</measure>
  </line>
</section-ref>

A section’s order comes from its position in <structure>, not from an attribute. Repeating a section does not change line or measure numbers. The second playthrough restarts at line 1, measure 1. See Sections, repeats, and endings for nested repeats and <line-repeat>.

Multiple instruments

The <ensemble> can list multiple parts:

<ensemble>
  <part id="P1">
    <instrument-name>ระนาดเอก</instrument-name>
    <instrument-short-name>รน.เอก</instrument-short-name>
  </part>
  <part id="P2" type="unpitched">
    <instrument-name>ฉิ่ง</instrument-name>
  </part>
</ensemble>

P1 is a ระนาดเอก (Ranat Ek, a Thai xylophone). <instrument-short-name> gives a shorter label for tight layouts.

P2 is a ฉิ่ง (Ching, small cymbals). Adding type="unpitched" means its notes use sound instead of pitch:

<rest/><rest/><rest/><note sound="ฉิ่ง"/>

sound="ฉิ่ง" is the open stroke and sound="ฉับ" is the closed stroke. This piece is สองชั้น, so the ฉิ่ง plays one stroke per measure, alternating ฉิ่ง and ฉับ every measure. The three rests before each stroke fill the other three slots.

Part data

Each instrument gets its own <part-data> element. The part attribute links back to a <part> in <ensemble>:

<part-data part="P1">
  <section-ref section="s1">
    <line number="1">
      <measure number="1"><rest/><rest/><rest/><rest/></measure>
      <measure number="2"><rest/><rest/><rest/><rest/></measure>
      <measure number="3"><rest/><note pitch="ด"/><note pitch="ร"/><note pitch="ม"/></measure>
      <measure number="4"><rest/><note pitch="ซ"/><rest/><note pitch="ด"/></measure>
      ...
    </line>
  </section-ref>
</part-data>

Every <part-data> follows the same structure: <section-ref> linking to a section, then <line> and <measure> elements. Each measure holds exactly four note slots. This piece has four beats per measure, and each beat is one slot.

The first two measures of line 1 are all rests. The ระนาดเอก enters in measure 3. A rest means the instrument strikes nothing new on that beat; it is not silence.

---

Next, see The score model for the conceptual foundations that make these elements work the way they do.

Elements introduced

<composer>, <direction>, <nathap>, <chan>, <bpm>, <repeat>, <annotation>, <text>, <instrument-short-name>

Try it in the Playground