For a voice-and-piano song moving from D major to B-flat major, specify down a major third, or -4 semitones. Keep the voice and both piano staves together. The same destination key reached by going up a minor sixth puts the music an octave higher than the downward version.

The downloadable practice song shows the mistakes recognition can make, including two missing final notes. Its transposed example was made from the original editable score, so you will still need to correct the recognition of your own PDF. The test details and files appear below.

Choose the route that fits your source

A PDF may contain crisp vector notation or a photograph of a page. Neither gives a transposition tool the editable note objects it needs. Before running recognition, ask whether the publisher or arranger can supply the notation file.

What you haveWhere to startWhat to check
MusicXML, MXL, or a MuseScore scoreOpen the editable file in MuseScore Studio. Skip OMR and start with source verification.Compare it with the intended edition; an editable file can still contain errors.
A clear PDF of printed staff notationTry Audiveris on a short representative passage, then export MusicXML.Include a system break and any lyrics or accidentals in the pilot.
A paper scan or phone photographImprove the source image before recognition.Look for cut-off staves, page curvature, shadows, and dots that merge with staff lines.
Handwriting, dense orchestration, or unusual notationBudget for manual entry or specialist transcription; test the difficult page first.The single printed song tested here provides no accuracy estimate for these inputs.
A lead sheet with chord symbolsCheck the melody and the chord objects separately after import.A chord printed as plain text may not respond to a chord-transposition option.
A part for a transposing instrumentEstablish the instrument and written-versus-concert pitch before changing notes.A B-flat instrument and a piece in B-flat major describe different things.

Codex is useful when you want it to organize files, call recognition and notation tools, or generate comparisons across several scores. The official Codex CLI documentation describes local code editing and command execution. For this workflow, use an environment that can access your working folder and the installed applications.

If you already have a checked editable score and only need one new key, MuseScore's Transpose dialog can finish the job. Use Codex when you want help running recognition, finding file errors, comparing the original and transposed MusicXML, or repeating the process across several scores. You can still do the musical corrections in the notation editor.

Specify the interval, register, and written or sounding pitch

Write the request before touching the score. Include the source key, destination key, direction, interval, parts to move, and whether pitches are written or sounding. For the practice song, the instruction is:

Source: D major, concert pitch, voice plus piano
Target: B-flat major
Move: down a major third (-4 semitones), every pitched part
Preserve: rhythm, lyrics, expression, repeats, and part relationships
Do not: move individual notes into another octave or simplify the accompaniment

Check a few notes by hand. D4 becomes B-flat3; F-sharp4 becomes D4; A4 becomes F4. In that same downward move, a D-major chord becomes B-flat major, Bm7 becomes Gm7, and A/C-sharp becomes F/A. Check both the root and bass of a slash chord.

For a singer, inspect the lowest and highest notes before choosing the move. A melody spanning D4 to A4 would span B-flat3 to F4 after this transposition. Also examine passages that stay high or low for several measures: a technically reachable final note does not tell you whether the whole phrase is comfortable. If the result needs local octave changes, treat those as arrangement decisions and record them separately.

For a clarinet, trumpet, horn, or saxophone part, establish whether the source shows written pitch or concert pitch. MuseScore's Staff/Part properties include the instrument's transposition, the difference between its written and sounding pitch. Changing the view to concert pitch is a different operation from moving the piece to a new key. Confirm the instrument setting and the exported part's pitch convention to avoid applying an instrument transposition twice.

Prepare the PDF and the working folder

Keep an untouched source and separate the files produced at each stage. This example folder layout is a suggested organization for your own job:

score-work/
  01-source/score.pdf
  02-omr/                 raw MXL, Audiveris project, recognition log
  03-corrected/           checked score in its original key
  04-transposed/          editable score and PDF in the destination key
  05-review/              corrections, comparison report, open questions

Record the page count and expected staves. For a piano grand staff, two staves do not necessarily mean two instrument parts: the practice song uses separate MusicXML parts for the hands, while another export may represent piano as one part with two staves. Record both the musical instruments and how your file represents them.

If you are scanning paper, Audiveris recommends grayscale and about 300 DPI for a normal A4 or US Letter page, with 400 DPI for small symbols. Its scanning guidance also advises avoiding rotation, warping, shadows, and scanner processing that distorts symbols. Increasing the resolution setting on a blurry image does not restore missing dots or accidentals. Obtain a clearer scan when those details cannot be read.

Keep page order and full staff edges visible. In a pilot, include the places where recognition has the most to distinguish: a clef change, a crowded chord, a dotted rhythm, or the first system of the next page. Only use material you are entitled to process, and check permission before sharing the resulting files. You can use the original practice score below without uploading someone else's edition.

Install Audiveris for recognition and MuseScore Studio for editing and PDF export. Python and music21 are optional for scripted comparisons. The September 12, 2026 test used Audiveris 5.11.0, MuseScore Studio 4.7.5, music21 9.9.1, and Tesseract 5.5.2. Those are historical environment details, not a requirement to install those versions today. Check the official Audiveris installation instructions for your operating system.

Run recognition and save the unedited export

Open the PDF in Audiveris and check that the expected pages loaded. Choose Book > Transcribe book to process the book, or Sheet > Transcribe sheet for the current page. The transcription walkthrough shows these commands. Start with the pilot passage so you can assess the editing work before processing a long score.

Use Book > Save book to retain the Audiveris project, then Book > Export book to produce compressed MusicXML, usually an .mxl file. The export documentation explains the distinction: the .omr project retains recognition information that MusicXML cannot hold. Save both for your own job. Open the MXL in MuseScore and preserve that raw file before editing.

If Codex will run the job from a terminal, have it locate the installed executable and report its version first. The following is a command template based on the Audiveris CLI documentation; replace the executable path and run it from your working folder:

"/absolute/path/to/Audiveris" -batch -save -export \
  -output "$PWD/02-omr" "$PWD/01-source/score.pdf"

Check the log and locate the actual output files before continuing. A finished process is not proof that all pages, lyrics, or staves were recognized. Do not run a later command against an older MXL left in the output folder after a failed attempt.

If notes appear but words do not, inspect OCR configuration. In the practice-song test, the first attempt had no OCR languages installed. The second used a Tesseract fast model without the legacy components requested by Audiveris; a compatible full English model allowed the third attempt to complete. The OCR language documentation distinguishes the linked Tesseract library, compatible language files, and the configured language selection. Match that selection to the lyrics; installing the Tesseract command-line program alone does not establish that Audiveris can find the required data.

Correct the score in its original key

Put the source PDF beside the imported notation. Work in the original key so a wrong pitch can be traced directly to its printed position. Save an editable MuseScore file for corrections and export the checked score as MusicXML when you finish. Keep a correction list with the page, system, part, measure, source symbol, imported value, and change you made.

In the practice song, recognition omitted two whole notes in measure 8. These give you two specific places to compare in the source and transposed PDFs:

LocationOriginal PDFRaw recognitionAfter moving down a major third
Measure 8, voiceD4 whole noteNote missingB-flat3 whole note
Measure 8, piano bassD2 whole noteNote missingB-flat1 whole note

For your own score, enter a correction only when the source is readable. If a dot or accidental is ambiguous, mark its location and ask the owner or a musician to resolve it. A polished export cannot resolve an unreadable source note.

  1. Check the staff and part list across every system break. Confirm that a shortened name such as “V.” continues the same vocal part rather than starting a new one. Preserve independent voices within a staff.
  2. Compare pitches and accidentals measure by measure, including the effect of clef and key-signature changes. Inspect every note in a chord. A correct melody does not validate the accompaniment.
  3. Check rests, dots, ties, tuplets, and voice timing. A measure containing several voices cannot be validated by adding every printed duration together; check each voice's timeline and its alignment with the bar.
  4. Read each lyric verse against its notes. Inspect hyphens, syllables held across several notes, and verse endings. Dynamics such as p and mf must not appear as lyric syllables.
  5. Check expression and navigation: slur endpoints, ties, hairpins, dynamics, articulations, tempo, repeat barlines, and ending brackets. Compare placement as well as object counts.

Listen to playback while following each part, especially at joins between systems. Use it to find a suspect passage, then compare that passage with the source. Playback does not establish correct spelling, lyric attachment, or an instruction that was never imported.

Finish this stage with a score that matches the source in the original key. Keep unresolved questions in the review folder. Transposing first would carry the recognition errors into a second key and make the comparison harder.

Transpose the checked score and export a new PDF

The following uses MuseScore's documented Transpose dialog. For the D-major practice song:

  1. Save a separate working copy of the checked score.
  2. Clear a partial selection if you intend to move the whole piece. With no selection, the dialog applies to the whole score; otherwise verify the selected range and staves.
  3. Open Tools > Transpose... and choose chromatic transposition.
  4. Choose By interval, Down, and Major third. Alternatively, use To key, Down, and B-flat major. Avoid Closest when the requested register is explicit.
  5. Keep Transpose key signatures enabled for a normal key change. Enable Transpose chord symbols and fretboard diagrams when those elements should follow the move.
  6. Apply the change and check the opening notes against D4 to B-flat3 and F-sharp4 to D4. Verify the last measure too.

Check a mid-piece key change separately. Move each section by the same interval: a passage that changes from D major to G major would become B-flat major to E-flat major after moving down a major third. If only one passage should move, record its exact measure range and check the music on either side.

Check the spelling of the notes as well as their sound. B-flat3 and A-sharp3 sound the same on an equal-tempered keyboard, but D4 moved down a major third is written B-flat3. A comparison that checks only semitone differences would miss that spelling error. In MuseScore, select the note and press J to cycle through its enharmonic spellings. Review the choice against the new key and the surrounding harmony; avoid cycling a mixed-pitch selection without checking each result.

Save the transposed native score, then export MusicXML and PDF. MuseScore's file export instructions cover File > Export and the available formats. Keep the native file for further engraving work. Reopen the exported MusicXML to check the interchange file, and open the PDF itself to inspect the printed result. A correct editor view does not verify an exported file you have not opened.

Handle the details that change from score to score

The eight-measure practice song does not cover every kind of notation. Use the following checks when they apply to your score.

Minor keys and chromatic notes

Moving B minor down a major third gives G minor. The starting key has the same two sharps as D major, but the destination is not B-flat major: the music remains minor. Name the mode in your request and use the same interval for all notes, including notes outside the key signature. For example, D-sharp4 moves to B3 in this downward move. Choosing a diatonic move instead of a chromatic one can change the intervals within the melody.

Multiple lyric verses and held syllables

The MusicXML lyric element represents text, verse numbering, syllabic information, and extensions. Preserve those fields and their attachment to notes. Compare the final word of each verse and every syllable that stretches across a phrase. A matching total can hide a word attached one note too early, a swapped verse, or a dynamic imported as text. Check the rendered spacing after transposition as well.

Pickups, tuplets, repeats, and changing meter

Identify the pickup before interpreting a short bar as a recognition failure. Record measure labels and time-signature changes so the reviewer can locate the same passage in both files. In polyphonic music, check onset positions and each voice separately; overlapping voices may be encoded with MusicXML backup and forward movements.

Keep repeats in their written form during the notation comparison. A playback sequence expanded through repeats has a different note count from the printed bars. Check first and second endings at their start and finish, not merely whether an ending object exists. Audiveris's documented limitations include unsupported tuplet types beyond triplets and 6-tuplets. Check that list before committing a complex score to this recognition route.

Chord symbols, guitar diagrams, and plain text

Inspect a few imported chord symbols in the editor. If a label is ordinary text, a command that transposes chord objects will not necessarily change it. Check the root, quality, extensions, and slash bass against the intended interval. Review fretboard diagrams for the new harmony and playing position. A capo arrangement needs its own statement of sounding key, chord shapes, and capo position before you decide which labels to change.

Transposing instruments, percussion, and octave marks

For a standard B-flat clarinet, written C4 sounds B-flat3; to sound concert C4, the player reads D4. If your piano score is in concert B-flat major, the clarinet part is written in C major. Giving both players a part labeled “B-flat major” would leave the instruction ambiguous. Decide the sounding key of the piece first, then check the written part for each instrument.

For a mixed ensemble, verify written and sounding pitches before and after the move. Keep unpitched percussion out of a blanket pitch shift. Check octave-transposing instruments and 8va or 8vb passages against their sounding register. If the target puts a part outside its usable range, record the problem before changing the arrangement.

Long scores and damaged scans

Use page and system references in the correction list, especially when printed measure numbers are missing. Check that each staff continues as the same musical part at page boundaries. A page with a different layout, smaller notation, or handwritten additions needs its own pilot. If basic staff grouping and rhythms remain wrong after source improvement, compare the time needed for correction with entering that passage manually.

Use these checks before handing over the score

Ask Codex to compare the checked source MusicXML with the transposed MusicXML. Require locations for mismatches. Keep the PDF-to-MusicXML recognition review separate from the MusicXML-to-MusicXML transposition review; passing the second cannot repair a mistake in the first.

CheckWhat a useful comparison reportsWhat remains to read
Parts and stavesPart identities, staves, measure labels, and voice assignments; explain any representation change.A vocal line that disappears or changes identity at a system break.
PitchesMap corresponding notes by part, measure, voice, onset, and chord membership; every intended pitched note moves by the declared interval.Enharmonic spelling, accidental readability, and practical range.
RhythmCompare beat positions and note or rest lengths, including tuplets. Convert XML durations to beats before comparing files that use different units.Beaming, ties, and alignment between voices.
LyricsCompare text, verse identifiers, syllabic fields, extensions, and note attachment.Melismas, hyphens, verse order, and collisions in the PDF.
Expression and navigationCompare the locations and the start and end of each slur, hairpin, and repeat ending. Flag anything missing or unsupported.Whether the instruction applies to the intended notes and whether the repeat route is correct.
ExportReport the actual files produced and which were reopened.Clipped staves, missing glyphs, crowded systems, part labels, page turns, and readable print size.

Do not compare pitches only by sorting them or adding a checksum: two swapped notes can preserve a total. If an import splits or merges parts, resolve that mapping before comparing event sequences. Two files can have the same number of slurs while connecting different notes.

Re-engraving can change page count. Compare musical content and readability rather than requiring the new PDF to have the same number of pages. For a singer and pianist, check the page turns in the actual part or score they will use. Hand over the source, checked original-key file, transposed editable file, PDF, and remaining questions together.

Troubleshoot the symptom you can see

SymptomInspect firstNext action
No usable MXL appearsThe recognition log, selected pages, executable path, and output directory.Resolve the reported failure, rerun the pilot, and confirm a new export exists before opening it.
Notes import, but lyrics are absent or garbledAudiveris's available language data and the language selected for this book.Use compatible data for the lyric language, then compare the words with the page. Check whether dynamics became lyrics.
A part disappears halfway throughThe part list around the next system or page, including abbreviated names.Restore the intended part continuity while comparing both systems with the PDF.
The target key looks right, but the melody is too highDirection, octave, selected interval, and written-versus-concert pitch.Return to the checked original-key file and apply the intended move. Avoid stacking a second uncertain transposition on the first.
The key signature changes, but some notes do notThe selected measure range and staves; whether you changed a key signature instead of using the transposition command.Compare a known note in every part. Reapply the move from the checked original-key file with the intended scope.
Melody moves, but chord labels stay in DThe chord-transposition option and whether the labels imported as chord objects or text.Correct the labels in the editor and check slash basses. Recheck diagrams separately.
Playback sounds plausible, but a bar looks crowded or shortVoice assignments, rests, dots, tuplets, and the possibility of a pickup.Compare each voice's onset and duration with the source before adjusting spacing.
Notes and words collide in the PDFThe exported page at readable print size, especially system ends and lyric extensions.Adjust engraving in the native file, export again, and inspect the new PDF rather than only the editor.

After a pitch or rhythm correction, regenerate the transposition comparison. After a layout correction, reopen the PDF and examine the affected systems and page turns. Record which checks were repeated so a reviewer can tell whether the report belongs to the latest file.

Practice files and what was tested

September Window is an original eight-measure song with a vocal staff, piano grand staff, and two lyric verses. The source occupies one A4 page. Download the D-major source PDF, the B-flat review PDF, or the practice and test files (ZIP). The kit contains raw recognition, setup logs, an authored answer key, a correction list, scripts, and an unfinished musician checklist.

Recognition split the vocal line at a system break, omitted the final voice and bass notes, treated two dynamics as lyrics, and added two ending brackets absent from the source. Its 50 lyric items matched the source's total only because p and mf replaced the missing final words “today” and “again.” All 32 right-hand chord objects kept the source's pitch and duration sequence.

The saved music21 report counts four parts: two vocal fragments and two piano staves. If you open the raw XML, you will see three part elements because it stores the piano as one part with two staves. Map the musical parts before comparing these counts.

The correction list describes eight kinds of recognition error. The supplied script, transpose_and_audit.py, makes its “corrected” file by copying the song's original editable MusicXML, then transposes that copy. It does not apply eight repairs to the raw MXL. Use the files to study the recognition errors and compare the two keys; correct your own imported score before transposing it.

Saved resultScope
3 parts; 8 measures per partThe original editable song and transposed file have the same parts and measures.
136 pitched noteheads moved -4 semitonesThe stored comparison checks the pitched sequence of this practice song.
72 note or chord durations matchedThe 72 entries count single notes or whole chords. The script does not compare rests or every voice’s timing.
50 lyric items matchedThe script compares verse number, text, and syllabic values in sequence, not every placement or lyric extension.
Expression checks passedThe script checks counts and object presence for the song's marks, not where every marking starts and ends.
Musician review remains openThe musician checklist is unfinished. Treat the PDF as a review copy.

The ZIP's script is for this song, not an arbitrary PDF. To replay it in a separate working copy, create artifacts/omr-pass3-legacy-ocr/ and copy artifacts/september-window-raw-omr.mxl into that folder as september-window-source-d-major.mxl. The actual second failure log is audiveris-pass2-english.log, rather than the name given in the README. Keep your own scores outside this example folder so a practice run cannot be mistaken for processing your music.

A Codex prompt for your own score

Copyable score-transposition prompt
Help me transpose a printed score PDF using installed music tools.

Source PDF: [absolute path]
Working folder: [absolute path]
Expected pages, instruments, staves, and lyric verses: [counts and names]
Source key; written or sounding pitch: [key and pitch type]
Destination: [key]
Exact move: [direction, named interval, signed semitones]
Scope: [whole score or exact measures and parts]
Known details: [pickup, key/meter changes, repeats, octave marks]

First inspect the source and report installed OMR and notation tools,
their versions, and missing dependencies. Preserve the source.

1. Run OMR on a representative passage. Retain raw MusicXML/MXL,
   recognition logs, and the OMR project where available.
2. List discrepancies against the PDF in its original key, with page,
   part, measure, and voice locations. Do not guess unreadable symbols.
   Pause for me to resolve musical ambiguities and approve corrections.
3. Save a checked original-key MusicXML and an editable notation file.
   Do not substitute an unrelated file or answer key for corrections.
4. Transpose that checked file by the declared interval. Preserve part
   relationships. Flag range problems before any arrangement change.
5. Compare corresponding pitches, rests, voice timing, key changes,
   lyrics and their attachment, expression spans, and repeat navigation.
   Mark unsupported or unperformed checks NOT CHECKED.
6. Export new MusicXML and PDF files. Reopen them and list layout
   concerns, including page turns and lyric collisions.

Return file paths, the correction list, and PASS/FAIL/NOT CHECKED
for each comparison, stating exactly what the check examined.
Keep the PDF labeled NEEDS_MUSICIAN_REVIEW until a qualified reader
has compared the music with the source and approved the result.

If recognition fails, give Codex the failure location and log rather than asking it to retry the whole score unchanged. If the notation imports correctly but the singer cannot use the range, revise the declared interval and rebuild from the checked original-key file. Keep the previous review copy under its own filename so the performer can identify which version to use.