Online Guzheng21 strings · Jianpu practice

Sheet format reference · Jianpu 简谱 → JSON

The guzheng sheet JSON format

Online Guzheng plays numbered notation stored as a small JSON file. The whole format is one object with a measures array — here is every field, a worked example, and a prompt you can hand to an AI along with a photo of your sheet.

Three steps to a playable sheet

  1. Give any AI assistant the prompt below together with a photo or PDF of your jianpu sheet.
  2. Save the JSON it returns as a .json file.
  3. Open the guzheng, switch to 🎼 Sheet Play and click 📂 Upload JSON sheet.

Nothing is uploaded to a server. The file is parsed in your browser and kept in local storage so it is still there next time. You can also build a sheet by hand in ✏️ Sheet Editor and export it as JSON.

A complete example

Two measures — an ascending pentatonic bar, then a tremolo, a rest and one note an octave up.

example-sheet.json
{
  "version": 1,
  "title": "Pentatonic Warm-Up",
  "artist": "Your name (optional)",
  "key": "D",
  "tempo": 88,
  "timeSignature": "4/4",
  "measures": [
    { "notes": [
      { "degree": 1, "beats": 1 },
      { "degree": 2, "beats": 1 },
      { "degree": 3, "beats": 1 },
      { "degree": 5, "beats": 1 }
    ] },
    { "notes": [
      { "degree": 6, "beats": 2, "technique": "tremolo" },
      { "degree": 0, "beats": 1 },
      { "degree": 1, "octave": 1, "beats": 1 }
    ] }
  ]
}

Top-level fields

FieldTypeMeaning
versionnumberAlways 1. Reserved for future format changes.
titlestringShown above the sheet. Falls back to “Untitled sheet”.
artiststring, optionalComposer, arranger or source. Displayed next to the title.
keystring, optionalThe letter from the 1=D marking — “D”, “G”, “Bb”, “F#”. The app transposes the whole instrument to match, up to 7 semitones either way.
temponumberBeats per minute, 20–300. Missing or invalid values become 80 with a warning.
timeSignaturestring, optionalAs printed, e.g. “4/4” or “2/4”. Sets the barline count; defaults to 4/4.
youtubeobject, optional{ "videoId": "…" } — an 11-character id or a full YouTube URL. Loads the karaoke beat panel.
measuresarray, requiredOne entry per printed measure: { "notes": [ … ] }. Must not be empty.

Note fields

Each entry of measures[n].notes is one printed note or rest, in reading order.

FieldTypeMeaning
degreeinteger 0–7The printed jianpu digit. 0 is a rest. 4 and 7 are played by press-bending strings 3 and 6 — write them exactly as printed.
octaveinteger −2…2, optionalDots above the digit → 1 (two dots → 2). Dots below → −1 (two dots → −2). Omit for the middle octave.
beatsnumber 0–16, optionalLength in quarter-note beats. Defaults to 1. Bad values become 1 with a warning.
techniquestring, optionalCurrently only "tremolo" (摇指). Anything else is ignored.

Degrees and strings

The instrument is tuned D pentatonic — D, E, F♯, A, B repeating across 21 strings. Jianpu 4 and 7 have no string of their own; the app plays them by press-bending the green 3 and 6 strings, exactly as a player would. Write 4 and 7 normally and the app handles it.

DegreePitch (key of D)How it is playedString colour
1Dstring 1 of each group
2Estring 2 of each group
3F♯string 3 of each groupgreen
4Gpress-bend from 3 (+1 semitone)green
5Astring 4 of each group
6Bstring 5 of each groupgreen
7C♯press-bend from 6 (+2 semitones)green

A degree that lands outside the 21-string range is shown in red on the sheet and skipped during playback, with a warning above the panel. Lower the octave value or transpose with Tuning.

Reading rhythm into beats

beats counts quarter-note beats, so it maps directly onto the underlines, dashes and dots of printed jianpu. Merge tied notes into a single note with the summed value.

PrintedNamebeats
5plain digit1
5 —one dash2
5 — —two dashes3
dotted1.5
5 (one underline)eighth0.5
5 (one underline, dotted)dotted eighth0.75
5 (two underlines)sixteenth0.25

Prompt for converting a sheet with an AI

Copy this, paste it into ChatGPT, Claude, Gemini or any other assistant, and attach a clear photo or PDF of the jianpu page. It is the same specification as above, written for a model.

Jianpu → JSON prompt
Convert the attached jianpu (简谱, numbered musical notation) sheet music for guzheng into JSON.

Output ONLY a single JSON object — no commentary, no markdown code fence — with exactly this shape:

{
  "version": 1,
  "title": "song title as printed",
  "artist": "composer / source (optional)",
  "key": "D",
  "tempo": 88,
  "timeSignature": "4/4",
  "measures": [
    { "notes": [
      { "degree": 3, "octave": 0, "beats": 1 },
      { "degree": 5, "beats": 0.5 },
      { "degree": 6, "beats": 0.5, "technique": "tremolo" },
      { "degree": 1, "octave": 1, "beats": 2 }
    ] },
    { "notes": [
      { "degree": 0, "beats": 1 },
      { "degree": 6, "octave": -1, "beats": 3 }
    ] }
  ]
}

Rules:
- One entry in "measures" per printed measure. Split at every barline, reading left to right, top row to bottom row.
- "degree": the printed digit 1–7. Use 0 for a rest.
- "octave": dots above the digit → 1 (two dots → 2). Dots below → -1 (two dots → -2). No dots → 0 (or omit).
- "beats": length in quarter-note beats. Bare digit = 1. One underline = 0.5, two underlines = 0.25. A small dot after the digit makes it 1.5× (dotted note, e.g. 1.5). Each dash "—" after a digit adds 1 beat (so "5 — —" = beats 3). Merge tied notes into one note with the summed beats.
- "key": from the "1=D" marking — the letter only, e.g. "D", "G", "Bb", "F#". The app auto-tunes to it.
- "tempo": the metronome marking (♩=88). If missing, estimate from the tempo word.
- "timeSignature": as printed, e.g. "4/4" or "2/4".
- "technique": optional. Use "tremolo" on notes marked 摇指 / tremolo. Omit otherwise.
- Optionally add "youtube": { "videoId": "11-char id" } if a backing/karaoke video is known.
- Grace notes and ornaments: skip them, keep only the main melody notes. For chords, keep the top (melody) note.
- Do not transpose anything — copy the digits exactly as printed. Degrees 4 and 7 are fine: the app plays them by press-bending strings 3 and 6.

Models misread crowded scans. Load the result, listen once with 👂 Listen, and fix anything wrong in ✏️ Sheet Editor before practising.

Sheet music is copyrighted like any other work. Convert music you wrote, music you have a licence for, or traditional and public-domain pieces — and keep the result to yourself unless the rights allow otherwise. This site hosts no third-party sheet music and never uploads yours: your file stays in your own browser.

The bundled demo and every exercise in Lessons is original material written for this site, free for you to use.