Transcribe a hymn with your AI assistant

# SATB transcription instructions for AI assistants
Version 1.1 — 2026-10-20. Domain: https://satb.netlify.app

## Task and delivery
Read this guide before transcribing a user's hymn image for SATB. Ask for the photo if it is absent: a website URL does not give you the user's image. Use only files the user provides or authorizes. Produce a downloadable UTF-8 .json song file in the format below, plus a concise review report. Do not deploy, upload to a public library, or claim the song is verified merely because it parses. If you cannot read this URL, ask the user to attach this guide. Never pretend to have fetched it.

## Transcription procedure
1. Read the whole page: title, tune, key, time, clefs, pickup, repeats, all systems and verses. Keep printed and internal measure numbers mapped. Ask for closer photos of unreadable regions.
2. Transcribe each staff system from the image, then separate S/A/T/B using stems, rhythm, rests, voice continuity, shared noteheads and crossings. Highest pitch is not always soprano. In historical hymns, a tenor-labelled melody remains tenor. Confirm clef octave conventions; use sounding pitch.
3. Write an event ledger for each part: measure, onset in quarter-note units, sounding pitch, duration, rest, tie or slur, syllable. Account for every printed note once per intended voice; duplicate shared noteheads only where notation indicates unison voices. Preserve staggered fuging entries and each voice's own rests.
4. Read staff positions, key signature and measure-local accidentals explicitly. Recheck ledger lines, cancellations, dotted notes/rests, beams, triplets, ties and final chords. Never replace unfamiliar harmony with a more conventional chord. Harmony can flag a question, not prove a correction.
5. Align lyrics independently for EVERY part and verse. Copy printed repeated words and voice-specific entries. Do not copy soprano timing into all parts. Hyphenate syllables; carry a syllable over melismas and ties. Include verses below the score only when supplied/readable. Clearly disclose editorial fits, inferred repetitions and omissions.
6. Independently re-read every measure against the image, especially entries, crossings and cadences. Check durations and syllable counts with code if available. Listen to each part and the ensemble if playback is available; otherwise state that listening was not tested. Arithmetic and AI agreement do not establish musical accuracy.
7. Report uncertain spots with measure, part, alternatives and needed evidence. Do not conceal uncertainty with invented notes, padding rests or altered measure lengths. An incomplete draft must be labelled as such; ask for better input when needed.

## Native file contract (preferred)
Use a JSON object {"app":"SATB Rehearsal","songs":{"unique-id":{...song...}}}.
Song fields: id (same as map key, letters/digits/hyphen recommended), title, optional number/tune/music/text/source/subtitle, fifths (integer -7..7), time (e.g. "4/4"), pickup (quarter-note units, 0 if none), tempo (quarter notes per minute), parts, lyrics, lyricsByPart.
parts MUST have S, A, T, B. Each is an equally long array of measure STRINGS. Separate note tokens with spaces. Do not supply MIDI numbers, arrays of note objects, ABC or chord symbols in these strings.
Token: PITCH:DURATION, optionally ending in ~. Examples: Bb3:q, F#4:e, Cn4:h, r:q. C4 is middle C. ALL pitches are explicit sounding pitches: fifths does NOT apply accidentals to playback. Eb major still requires Eb, Ab and Bb tokens. Rests use lowercase r.
Durations in quarter-note units: w=4, h=2, q=1, e=0.5, s=0.25, dw=6, dh=3, dq=1.5, de=0.75, t=2/3, te=1/3. No other duration codes. If the notation cannot be represented faithfully, report the limitation rather than invent a code.
A trailing ~ on the CURRENT note continues the PREVIOUS syllable. C4:q C4:q~ represents a continuation into the second C. D4:e E4:e~ is a two-note melisma. It is not a tie-start marker. Matching pitches with continuation may be sustained by playback. Do not put ~ on the first sounding note without a preceding syllable.
One measure per array element, including rests for silent voices. Measure sum normally numerator*4/denominator. pickup sets first measure and by default shortens the final bar by the complementary amount. For genuinely irregular or non-complementary bars, provide lens, an array of positive quarter-unit lengths matching ALL measures. Do not use lens to hide recognition errors. Expand repeats consistently in all voices and lyrics; disclose the expansion. Multiple notes simultaneously within one SATB voice require explicit review; do not silently discard chord tones.
lyricsByPart MUST be {"S":[verse1,...],"A":[...],"T":[...],"B":[...]}. Each verse is one string for the full part. Spaces separate words, hyphens separate syllables ("of-fered"). Rest tokens consume no syllable. Notes ending ~ consume no new syllable. A standalone _ occupies one lyric slot and holds the previous syllable for verse-specific melismas. Each verse's hyphen/space split syllable count (including _) must equal that part's non-rest, non-~ note count. Use the same verse count in all parts. Set legacy lyrics to a copy of lyricsByPart.S. Do not flatten all verses into one string. Do not invent missing verse text.

## Mechanical validation checklist
- JSON parses; map key equals song.id; all four parts exist; measure counts equal.
- Every token passes pitch/duration grammar. Recalculate sounding pitch with accidental and octave.
- Each part's duration sum equals the real measure length including pickup, without fabricated padding.
- Every verse of each part has exactly the expected syllable slots. Check actual word-to-note alignment too.
- Source repeats, rests, ties, key changes and lyrics are represented or their limitations disclosed.
- Original file remains unchanged when revising; return a clearly named new file.
A small format example is at https://satb.netlify.app/satb-example.json. It demonstrates serialization, not musical validation of a hymn.

## User workflow
Attach the complete score in ChatGPT Work with file access, code execution and downloadable output, follow the source-verified protocol below (a recognizer is optional), download the complete SATB JSON, then use Songs → Add a hymn → Load song file. Review the vocal parts and any piano accompaniment. No SATB API access or private repository access is required. External AI account limits and costs still apply. Images are shared with the assistant the user chooses, not automatically by Psalmster.


## Accuracy-first transcription protocol (SATB; updated 2026-10-24)

Follow this source-verified workflow before the older image-transcription procedure above. A recognizer is optional; it is not a prerequisite for transcription. The vocal-structure and piano instructions here clarify that procedure: four JSON part keys do not imply four different sung melodies. Existing vocal token syntax remains unchanged.

### Mandatory Work-mode check — before starting

SATB transcription in ChatGPT requires **Work mode**. Before analyzing a score, transcribing notes or creating output, verify from the available session/runtime information that Work is active. Never infer the mode from the user's request, project name or a previous conversation, and never claim verification without evidence.

If Work is inactive or cannot be verified, stop before attempting the task and tell the user: “Open this conversation in ChatGPT Work before we begin. SATB transcription requires file access, code execution and downloadable output.” Do not attempt the transcription in ordinary Chat or offer a provisional manual transcription while waiting. Resume only after Work is verified; then check that the required tools are available and report specific missing capabilities early.

These instructions cannot switch the application into Work mode automatically.

1. **Establish scope from the whole score.** Read title, hymn number, edition, clefs, key, time, pickup, repeats, all systems and all supplied verses. Establish whether this is four-part singing, unison with keyboard accompaniment, or another arrangement. Respect explicit vocal and octave instructions. For requested identical-pitch unison, copy the complete melody identically into S, A, T and B, with no octave transposition. For actual four-part singing, preserve independent lines and voice crossing; highest pitch alone does not establish voice identity.
2. **Choose a method suited to the supplied score.** Direct visual transcription of a readable score is allowed without first running a recognizer, installing OMR software or finding a digital edition. Use an available recognizer or a machine-readable edition only when it helps; neither is required. Verify any alternate edition's notes, harmonization and rhythms against this exact arrangement: a matching tune name is insufficient. State whether the method was AI visual reading, OMR-assisted transcription or conversion from a verified digital edition. Do not use rejected transcriptions as note references. If the source is unreadable or completion is blocked, identify the precise issue early and request better input rather than guessing or delivering successive tiny provisional note inventories when the user requested a complete hymn.
3. **Review systematic errors in the chosen method.** Inspect all staves for missing beams, eighths read as quarters, false or omitted notes, missing chord tones and misplaced voices. For direct visual transcription, check staff positions and rhythmic groupings against the source. If OMR is used, inspect its warnings and compare printed beam thickness and staff spacing with the recognizer's measured scale before adjusting settings and rerunning. Do not spend prolonged effort installing or repairing an optional recognizer; disclose the limitation and use another suitable method. Enlargement or text masking may help; check that preprocessing preserves stems, ledger lines, accidentals and staff/system relationships. Preserve original files.
4. **Retain the complete notation in an event ledger.** Record every onset, explicit sounding pitch, duration, rest, tie, slur, staff and voice. Calibrate staff positions separately for each system, allowing for photographic skew. Keep every chord tone and independently sustained inner note, including shorter and longer same-pitch notes in separate voices. A keyboard part must remain polyphonic; do not force it into four monophonic vocal streams. Log shared noteheads and any duplicate key strikes consolidated for playback.
5. **Check accidentals and octave meaning explicitly.** SATB pitches are sounding pitches: `fifths` does not apply accidentals to playback. In a one-flat key, write `Bb`, not bare `B`, unless the notation supplies a natural. Check accidental scope, cancellations, barline resets, clef conventions and ties. Do not move an uncomfortable vocal pitch by an octave without authorization.
6. **Verify the complete score against the source.** Compare every note and chord at its printed onset and duration, on both staves and in every system. Check staff positions, dots, beams, rests, sustained notes, ties and slurs separately. Harmony, scales, cadences and voice leading may flag errors; they do not authorize replacing readable notation with a more plausible chord. Document unresolved readings with measure, staff, voice, alternatives and needed evidence. Assistant source review is not independent human review.
7. **Normalize only real rhythmic structure.** Join complementary fragments when the source shows one measure split across a system break. Map printed segments to normalized measures. Preserve pickups, short final bars, source rests and independent holds. Use `lens` only for true source lengths; never pad with invented rests or alter bars to pass a validator. Distinguish a tie sustaining one pitch from a slur connecting separately sounded pitches.
8. **Align every supplied verse.** Verify actual word-to-note placement, syllabification, melismas and continuations. Align four-part voices independently; explicitly identical unison lines use identical note and lyric timing in all four keys. Preserve repeated words, staggered entries and voice-specific text. The current-note `~` token continues the previous syllable; matching adjacent pitches with `~` may be sustained by playback. Use `_` only for a source-supported verse-specific hold. Do not invent notes or words to balance syllable counts.
9. **Produce and test the complete output.** Deliver a downloadable SATB JSON with the whole vocal score, all requested accompaniment and every supplied verse. Run the public parser/validator for syntax, measure lengths and lyric slots. Check piano bounds, polyphony and holds separately: the public vocal validator does not establish piano completeness or accuracy. Where available, test the actual SATB import and playback scheduler, including all verses and seeking into held piano notes. If MusicXML or MIDI exports are generated, reopen them and compare pitch/onset/duration events with the final JSON. Round-trip equality establishes serialization fidelity, not agreement with the printed page.
10. **State what was verified.** Distinguish structural validation, source-note review, lyric placement, playback scheduling, audio rendering and human listening. Synthetic audio or a schedule that runs is not proof of correct notes. Deliver only the complete downloadable SATB JSON by default, accompanied by a brief note about the checks performed and any unresolved uncertainties. Do not create or attach a ZIP package, MusicXML, MIDI, audio preview, source ledger or separate verification report as a user deliverable unless the user explicitly requests those extras. Supporting recognition files, event ledgers and exports may still be used internally when needed for the accuracy checks above; they are not required downloads. Record editorial tempo, reductions, ambiguities, source identity and recognition settings when a recognizer was used. If completion is blocked, say exactly what remains; do not label a partial result complete. Do not modify or deploy the website as part of transcription unless asked.

### External score access and transcription edge cases (2026-10-24)

- **Hymnary blocks automated access.** In the BRIDGEWATER session, the tune page opened and advertised MusicXML, but the direct MusicXML download returned HTTP 403 (Forbidden). The user reports that Hymnary blocks bots and that this failure is typical. Expect bot-access restrictions; a successful metadata lookup does not establish permission or ability to fetch the score. Do not attribute a particular HTTP 403 to a confirmed technical cause beyond the evidence returned, or assume every resource is inaccessible. A search result, media link or readable tune page does not establish that the notation was downloaded. A web reader's “unsupported content-type” error is a separate reader limitation; report the actual failure from each route accurately.
- **Use a bounded fallback.** After a blocked download, record the resource and status and avoid repeatedly retrying the same URL. Prefer asking the user to download the MusicXML or clean PDF in their normal browser and attach it when automated score access is blocked. Alternatively use another accessible machine-readable edition or available OMR on the supplied score. An authorized browser route is useful only if it actually permits ordinary access; do not retry bot requests through different identities or treat a browser as a way to evade the block. Do not bypass access controls. Compare any alternate edition against this exact image before using its notes: tune name, key or matching title alone does not verify the harmonization, octave placement, rhythms or voice assignments.
- **Check capabilities separately from Work mode.** Work supplies a workspace; it does not guarantee Audiveris, another recognizer, music libraries, audio rendering or browser playback are installed and usable. Check the actual tools early and distinguish “not installed”, installation/access failures, and a failed recognition run. Never imply that recognition or a digital-edition comparison happened when it did not. Direct visual transcription does not require trying recognition or digital-edition retrieval first. Disclose the method and any relevant tool limitations, preserve the full-score review requirements, and stop for better input if notes remain unreadable. A missing recognizer is not a blocker by itself and does not justify reviving a rejected result.
- **Read fuging entries and underlay by voice.** In this supplied BRIDGEWATER arrangement, bass, tenor, soprano and alto enter at different times, and the lower voices repeat the final poetic line. Preserve the printed rests, rearticulated unisons and voice-specific repetitions; do not give every part the soprano's lyric schedule. Recalibrate staff lines in each system, count ledger-line steps and check sounding octaves directly rather than correcting an unusual register by ear or expectation.
- **Review extra chord tones explicitly.** A four-part score can contain more than four simultaneous pitches, including a divisi final chord. The vocal measure-string contract is monophonic per part. Do not silently discard a tone, invent chord-token syntax or call a four-note reduction an exact transcription. An extra printed tone can be retained for ensemble playback using the existing polyphonic piano contract only as a clearly disclosed playback adaptation: identify the source voice/staff, pitch, onset and duration, and explain that it follows the accompaniment mixer and does not appear or sound as a second isolated vocal note. Do not describe such an event as printed keyboard accompaniment when no keyboard part is supplied.
- **Separate printed lyrics from editorial fits.** When only verse 1 has underlay, later stanzas need a separate fit to each voice's notes and repetitions. Identify contractions, elisions, alternative syllabifications and inferred repetitions explicitly. For example, this image's verse 2 “The unfathomed deep he makes his bed” has nine ordinarily spoken syllables for eight attacks; fitting it requires an editorial decision, not a claim that the count already matches. Never silently change the supplied words or add/remove notes to satisfy the lyric checker.
- **Validate the right object and report the limits.** Import files use the native `{"app":"SATB Rehearsal","songs":{"id":song}}` envelope. Pass the individual `song` object to `SATBPublicValidation.inspect`, not the envelope. Run syntax, measure-duration and per-voice/per-verse lyric checks; check any piano events separately. Zero validator errors establish structural consistency, not correct pitches, source underlay, successful site import or verified audible playback. State which of those checks actually ran.

### Existing polyphonic piano contract

The current SATB player accepts optional `piano` data on each individual song, alongside `parts` and `lyricsByPart`. No schema extension is needed for independent keyboard notes:

```json
"piano": {
  "right": [
    {"pitch": "C4", "start": 0, "duration": 2},
    {"pitch": "E4", "start": 0, "duration": 1}
  ],
  "left": [
    {"pitch": "G2", "start": 0, "duration": 3}
  ]
}
```

This is a property fragment inside a complete song, not a standalone import file. Each event is one sounded pitch. `start` and `duration` are finite numbers in quarter-note units from the beginning of the encoded pickup, not seconds, 1-based beats or within-measure offsets. Start must be nonnegative and duration positive; the event must end within the song. Simultaneous starts encode chords; overlapping durations preserve independent holds. Use explicit sounding pitch strings, including accidentals. Gaps represent silence; do not invent a piano rest pitch. Resolve written ties into sustained playback events. Retain source slurs and other notation detail in companion MusicXML or metadata; current piano playback uses its ordinary articulation.

`right` and `left` retain the two source staves; do not reorder crossing notes by register. Accompaniment repeats automatically with each verse, follows tempo and seeking, and shares the **Accompaniment** volume slider with the other vocal parts. Do not pre-repeat all verses inside the event arrays. Vocal `parts` remain measure strings, not piano event objects. The singer's score displays vocal parts, not a full engraved keyboard score. Use JSON upload to retain this accompaniment; the current four-voice MusicXML import path is not a full keyboard-accompaniment importer.

Check every piano event's pitch syntax, onset, duration, source coverage and correspondence with both staves. Passing a vocal-only validator does not validate these arrays. Do not derive supposedly printed accompaniment from rejected SATB guesses or generic chord patterns.

## Public validation references

- Agent instructions: https://satb.netlify.app/llms.txt
- Vocal example JSON: https://satb.netlify.app/satb-example.json
- SATB-compatible browser validator: https://satb.netlify.app/validate-song.html
- Public note parser: https://satb.netlify.app/satb-core-public.js
- Public validation wrapper: https://satb.netlify.app/satb-public-validator.js

These resources require no access to SATB's private repository. The browser validator runs locally and checks vocal format, measure lengths and lyric-slot discrepancies. It does not read sheet music, certify lyric placement or check piano completeness. Import through **Songs → Add a hymn → Load song file**, then listen with the vocal and piano mixer controls.