01

Where the commands are

Every command is in the command palette (Ctrl+Shift+P, Cmd+Shift+P on macOS) under Lily#: — type lily to list them. The ones that work on the file you are editing are also on the editor's right-click menu, and a few live where their subject is: on a file in the Explorer, or in the preview.

To give a command a key of your own, open Keyboard Shortcuts (Ctrl+K Ctrl+S) and search for lilysharp..

02

What every rewrite promises

The commands that rewrite the file — everything under Reshaping the file and Harmony and key — share three rules:

• The result is checked before you get it. A rewrite that should not change the music (Regroup, Split Sections, Convert Octaves, Extract Phrase, Respell Notes) is compiled and compared with the file as it was, note by note or by its MIDI, and is refused — with the reason, and nothing changed — if anything would sound different.
• One undo. Each command is applied as a single edit, so Ctrl+Z once puts the file back.
• Errors first. A file with syntax errors is left alone; fix the red squiggles and run the command again.

03

New Score

Opens a new, untitled .lys from a template — one part, a section, a form and a score — with the title selected so you can type over it, and the preview beside it. It is also File → New File… → Lily# Score (.lys). In the new file, type lesson and Ctrl+Space for the lessons.

04

Import MusicXML…

Turns a MusicXML file — .xml, .musicxml or the compressed .mxl — into Lily#. From the command palette it asks for the file and opens the result as a new untitled .lys; from the Explorer's right-click menu it writes NAME.lys beside the file. Either way the preview opens beside it.

An import is a faithful starting point, not a byte-for-byte copy: what Lily# writes differently or leaves out is listed in a warning when it is done. Sections come from the rehearsal marks, or — with none — from each change of key, time or clef. The notes are written with absolute octaves (c', d''); set lilysharp.import.relativeOctave for relative ones. The command line does the same: lysc import score.musicxml.

05

Convert Image/PDF to Lily# (.lys)… · Show Original Scan

Reads printed music from a scan (.png, .jpg, .bmp, .tif) or a PDF with an optical music reader and opens the .lys it writes, with the preview. The reader is a separate extension (Windows x64, Beta), not part of Lily#: on Windows the command is in the palette and offers to install it when it is missing; once it is installed, scans and PDFs also get the command on their right-click menu.

Show Original Scan opens the scanned pages beside a .lys read this way — from the picture button in the editor's title bar, or the palette — with the marks the reader was unsure of boxed in red. Click a box to go to its music; the caret lights the box of what it is on. The doubtful notes are also marked @todo in the source, so they show in red in the preview until you have checked them. With lilysharp.omr.verifyOnSave, saving has the reader engrave the file again and compare it with the scan, bar by bar.

06

Regroup (by part ⇄ by section)

A Lily# file can be written two ways round: by part, each part holding its sections, or by section, each section holding every part's music. The first suits a part copied in one go (a bass line, a drum part); the second suits writing a song section by section. Regroup rewrites the whole file into the other way, music unchanged.

// by part                          // by section
part melody { clef treble           part melody { clef treble }
  section A { c'4 d' e' f' | }      part bass { clef bass }
  section B { g'1 | }
}                                   section A {
part bass { clef bass                 melody { c'4 d' e' f' | }
  section A { c1 | }                  bass { c1 | }
  section B { g,1 | }               }
}                                   section B {
                                      melody { g'1 | }
                                      bass { g,1 | }
                                    }

Run it again to go back. More on the two layouts: Parts and sections.

07

Split Sections to Match a Part

In a file grouped by part, one part may cut a section into several (A of 16 bars and B of 121) while the others still write it whole. The editor warns that the section is not the same length everywhere. This command cuts the other parts — and the section's chord rows and lyrics — at the same bars, and makes every form play A B where it played A.

• Run it with the caret anywhere, or from the warning's lightbulb (Ctrl+.), which names the section.
• If the parts cut the section differently, it asks which part to follow. One confirmation then shows the whole plan before anything changes.
• Every cut part must sound and count exactly as before. A slur, tie or hairpin running across a cut is carried into the new section. A beam, a pedal or another span across a cut, or a cut in the middle of a bar, is reported instead, and nothing changes.

08

Convert Octaves to Absolute / to Relative

Rewrites the whole file into the other octave mode. In relative mode (the default) a note without marks lands nearest the note before it; in absolute mode (octave absolute) a bare c is always the same C. Every note keeps the pitch it sounds — only its ' and , marks and the octave lines change — and the result is compared with the file note by note.

A note that no score plays has no octave to keep, so the command names it and stops: play it in a form, or remove it. Absolute octaves are the safer mode for music an AI writes, since one wrong mark cannot shift every note after it. The command line: lysc octave --absolute song.lys.

09

Extract Phrase from Section

Lifts music out of a section into a named phrase at the top level and writes the name where it was, so other parts and sections can use the same music (theme, or theme' an octave up). With the caret in a section's music it takes that music; with a selection, the whole bars the selection touches. It asks for the name, then checks that the file still sounds exactly the same, or changes nothing.

// before                                  // after
section A { melody { c'4 d' e' f' | g'1 | } }   phrase theme { c'4 d' e' f' | g'1 | }
                                                section A { melody { theme } }

More on phrases: Phrases.

10

Add Chord Track (auto-harmonize)

Writes a first harmonization of the melody as a chords harmony row, placed directly above the melody's staff. It picks one chord per bar from the key's seven diatonic triads — the one whose notes cover most of the bar's melody, longer notes and the downbeat counting more — and prefers the common chords (I, IV, V) when it is close. In a major key the V is written as a V7. A bar of rests keeps the chord before it.

The file keeps its layout: a file grouped by section gets a chords block in each section; one grouped by part gets one top-level track with a section per section. It is a starting point to edit — the chords are plain text in the file. The key it harmonizes in is the file's key; set the right one first (Guess Section Key helps). The command line: lysc harmonize song.lys.

11

Guess Section Key…

For music written down before its key was known — transcribed by ear, or played in. Put the caret in a section (or select several sections, or put it on a section's name in a form) and run the command. It reads the section's notes in every part and lists the keys they fit, best first:

Lily#: key of section A (no key stated at its start)
  key c major    C major · score 1.03 · best guess
  key c minor    C minor · score 0.76

Only the likely keys are listed: those scoring within 0.3 of the best, at most five. The score compares how long each pitch sounds with the pattern a major or minor key gives its notes; the key whose tonic the section ends on gets a small extra. The tonic is spelled the way the notes are written — fis major when the music writes sharps, ges major when it writes flats.

Picking a key writes it as the key the section starts in: a key already there is rewritten; otherwise it goes in the section's header (section A { key d major … }), and in a file grouped by part with no top-level section A, a line section A { key d major } is added. Every part playing the section takes the key, and the next section starts again from the file's own. Then the command offers to respell the notes for the new key. Esc at either step changes nothing.

A guess, not a verdict: a short or modal section can fit two keys equally well, and the parallel or relative key is often a close second. Listen, and pick.

12

Respell Notes to Key…

Notes written before the key was known often come out spelled the wrong way round — fis where G♭ major wants ges, b where it wants ces, or fis and ges both in one section. They sound right but print wrong: accidentals against the key signature. This command respells the section at the caret (or every section a selection touches) for the key it starts in. If no key is stated there, it uses the guessed key and tells you so.

It lists what it would change, all checked; uncheck any you want to keep as written, and Enter applies the rest:

Lily#: respell section A for ges major (G♭ major)
  ☑ fis → ges    3 notes
  ☑ ais → bes    1 note
  ☑ b → ces      1 note
  ☑ cis → des    1 note
  ☑ dis → ees    1 note
  ☑ gis → aes    1 note

// before, in G♭ major
fis'4 gis' ais' b' | cis''4 dis'' f'' fis'' | fis'1 |
// after: every note sounds as before
ges'4 aes' bes' ces'' | des''4 ees'' f'' ges'' | ges'1 |

• A note in the key's scale takes the scale's spelling.
• A note outside the scale is left alone when the section writes it one way — a written aes in C major is your choice. When the section writes it several ways, it is unified to the spelling written most; a tie goes to the key's way (the raised sixth and seventh in a minor key, gis in A minor; otherwise sharps in a sharp key, flats in a flat key).
• Notes after a key change inside the section are left alone.
• Every note keeps its pitch. In relative mode a new letter changes where the next note lands, and b ⇄ ces crosses the octave, so the octave marks are recomputed; the result is checked note by note, or nothing changes.

13

Play, step and sound

The sound comes from the preview, so with no preview open the first Alt+P opens one; press again to play. As you edit, the notes you land on and type sound too — Audition.

14

The preview's menu

Everything else the preview does — the link between notes and source, the score picker, the colours — is in The preview.

15

Export

Export as PDF, SVG, PNG, LilyPond (.ly), MusicXML, MIDI and VOCALOID sequence (.vsqx). They are in the command palette, in the preview, and in the Lily#: Export submenu when you right-click .lys files in the Explorer — select several to export every score of every file into one folder. From the preview, the export is the score the preview shows, under that score's own form. Whichever way, the file written is the one lysc writes from the command line.

16

With AI

Transform Selection with AI… (Ctrl+I, also on the right-click menu) rewrites the selected bars as you ask in words, and shows the answer engraved beside the original before anything changes. Select AI Model… chooses the model. Both are described in AI in the editor.