[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Basic command-line options for LilyPond ][ Up : Command-line usage ][]

Advanced command-line options for LilyPond

Option ‘-d’ is the command-line interface to LilyPond’s Scheme function ly:set-option. This means that all options listed here can also be set within ‘.ly’ files.

-d, --define-default=option-name[=value]
-d, --define-default=no-option-name

Set the equivalent internal Scheme symbol option-name to value. For example, the command-line option 

-dbackend=svg

is equivalent to 

#(ly:set-option 'backend 'svg)

in a LilyPond input file.

If value is not supplied, use #t as the value (which might produce strange results if the expected value type is not boolean). The prefix no- may be added to option-name to switch ‘off’ an option, providing #f as the value. For example, 

-dpoint-and-click='#f'

is the same as 

-dno-point-and-click

[Note that the ‘#’ character introduces a comment in many shells. For this reason it is recommended to always quote expressions that contain it.]

The following table lists all supported option names together with its values. Within Scheme code, option values can be read using function ly:get-option.

anti-alias-factor num

Render at a higher resolution (using factor num, which must be a positive integer ≤8) and scale down the result to prevent ‘jaggies’ in PNG images. Default: 1.

aux-files bool

If bool is #t, create ‘.tex’, ‘.texi’, and ‘.count’ files. This option is mostly for use by lilypond-book. Default: #f.

backend symbol

Use symbol as the backend for LilyPond output. Possible values are:

ps

This is the default setting. PostScript files include TTF, Type1, and OTF fonts. No ‘subsetting’ of these fonts is done. Be aware that using ‘oriental’ character sets like Japanese can lead to very large file sizes.

For PDF output, the ps backend is used, too; the resulting PS data is post-processed by Ghostscript’s ps2pdf script, which also does font subsetting by default.

cairo

This creates graphics output throught the Cairo library. This backend can output ps, eps, pdf, png and svg.

svg

Scalable Vector Graphics. A single SVG file is created for every page of output. Music glyphs are encoded as vector graphics, but text fonts are not embedded in the SVG files. Any SVG viewer will therefore need the relevant text fonts to be available to it for proper rendering of both text and lyrics. It is recommended to not use font ‘lists’ or ‘aliases’ in case an SVG viewer is unable to handle them.

clip-systems bool

If bool is #t, extract music fragments out of a score. This requires that the clip-regions function has been defined within the \layout block. See Extracting fragments of music. No fragments are extracted though if used with the ‘-dno-print-pages’ option. Default: #f.

compile-scheme-code bool

Use the Guile compiler to run Scheme code, instead of the evaluator. For more information, see Debugging Scheme code.

crop bool

If bool is #t, a second PDF file gets created (with extension ‘.cropped.pdf’), together with a rendered image of it (with extension ‘.cropped.png’). This output file fits all the music and headers, without margins, into a single, possibly tall page. If option ‘--svg’ is set, an additional SVG file (with extension ‘.cropped.svg’) is produced instead. If option ‘--eps’ or ‘--ps’ is set, a cropped EPS file (with extension ‘.cropped.eps’) is produced instead of a cropped PDF. Default: #f.

Note that currently this option is not well suited for multi-system output since vertical space between systems gets removed.

datadir

Prefix for data files. This is a read-only option; setting it has no effect.

debug-eval bool

If bool is #t, use the debugging Scheme evaluator, which prints backtraces with line numbers on errors. Default: #f, or #t when using --verbose.

debug-skylines bool

If bool is #t, debug skylines. Default: #f.

delete-intermediate-files bool

If bool is #t, delete the unusable, intermediate ‘.ps’ files created during compilation. Default: #t.

embed-source-code bool

If bool is #t, embed the LilyPond source files inside the generated PDF document. Default: #f.

eps-box-padding num

Pad left edge of the output EPS bounding box by num millimeters. Default: #f (meaning no bounding box padding).

font-export-dir string

Set directory for exporting fonts as PostScript files to string. This is useful when you want to create a PDF without embedded fonts first and later embed the fonts with Ghostscript as shown below. 

$ lilypond -dfont-export-dir=fontdir -dgs-never-embed-fonts foo.ly
$ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
     -sOutputFile=foo.embedded.pdf foo.pdf fontdir/*.font.ps

Note: Unlike font-ps-resdir, this method cannot embed CID fonts with Ghostscript 9.26 and later.

Note: Same as font-ps-resdir, this option skips TrueType fonts because embedding TrueType fonts later causes garbled characters. To avoid garbling characters, use gs-never-embed-fonts, as this embeds TrueType fonts despite its name.

Default: #f (meaning not to export).

font-ps-resdir string

Set directory (as string) to build a subset of the PostScript resource directory to be used for embedding fonts later. This is useful when you want to create a PDF without embedded fonts first and later embed the fonts with Ghostscript as shown below. 

$ lilypond -dfont-ps-resdir=resdir -dgs-never-embed-fonts foo.ly
$ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
     -I resdir -I resdir/Font \
     -sOutputFile=foo.embedded.pdf foo.pdf

Note: It is better not to specify the directory that contains the name ‘Resource’ because it has a special meaning when specified with the -I option for Ghostscript.

Note: Unlike font-export-dir, this method can embed CID fonts with Ghostscript 9.26 and later.

Note: Same as font-export-dir, this option skips TrueType fonts because embedding TrueType fonts later causes garbled characters. To avoid garbling characters, use gs-never-embed-fonts, as this embeds TrueType fonts despite its name.

Default: #f (meaning not to build).

gs-load-fonts bool

If bool is #t, load fonts via Ghostscript. This option makes LilyPond’s output files contain only references to all fonts, which must be resolved to real fonts in a post-processing step by Ghostscript. Default: #f.

gs-load-lily-fonts bool

If bool is #t, load LilyPond fonts via Ghostscript. This option makes LilyPond’s output files contain only references to its music fonts, which must be resolved to real fonts in a post-processing step by Ghostscript. All other fonts are still output as usual. Default: #f.

gs-never-embed-fonts bool

If bool is #t, make Ghostscript embed only TrueType fonts and no other font format. Default: #f.

help bool

If bool is #t, show this help. Default: #f.

include-book-title-preview bool

If bool is #t, include book titles in preview images. Default: #t.

include-eps-fonts bool

If bool is #t, include fonts in separate-system EPS files. Default: #t.

include-settings string

Include file string for global settings, which is included before the score is processed. This can be passed multiple times to include several files. Default: '() (meaning no global settings file).

job-count num

Process in parallel, using num jobs. Default: #f (meaning no parallel processing).

log-file string

Redirect output to the log file ‘string.log’. Default: #f (meaning no log file).

max-markup-depth num

Set maximum depth for the markup tree to value num. If a markup has more levels, assume it will not terminate on its own, print a warning, and return a null markup instead. Default: 1024.

midi-extension string

Set the default file extension for MIDI output files to ‘.string’. Default: "midi".

music-strings-to-paths bool

If bool is #t, convert text strings to paths when glyphs belong to a music font. Default: #f.

paper-size extra-quoted-string

Set default paper size to extra-quoted-string. Note that the string must be enclosed in escaped double quotes. Default: "\"a4\"".

pixmap-format symbol

Set Ghostscript’s output format for pixel images to symbol. Default: png16m.

png-width width
png-height height

For PNG output, set the width and height (in pixels) of the created image file. If one of the options is missing, the other dimension is computed according to the EPS bounding box, retaining the aspect ratio.

In addition to ‘--png’, either ‘--eps’, ‘-dcrop’, or ‘-dpreview’ should be used to get proper image scaling without clipping.

Option ‘-dresolution’ is ignored.

Note that there is a bug in ghostscript versions up to 9.52 for these two options: It produces empty PNG images if the height is larger than the width.

point-and-click bool

If bool is #t, add ‘point & click’ links to PDF and SVG output. See Point and click. Default: #t.

preview bool

If bool is #t, create preview images in addition to normal output. Default: #f.

For input file name file and output format fmt, it generates an output file having the name ‘file.preview.fmt’, containing the titles and the first system of music. If \book or \bookpart blocks are used, the titles of \book, \bookpart or \score will appear in the output, including the first system of every \score block if the \paper variable print-all-headers is set to #t.

To suppress the usual output, use the ‘-dprint-pages’ or ‘-dno-print-pages’ options according to your requirements.

print-pages bool

If bool is #t, generate full pages. Default: #t.

Option ‘-dno-print-pages’ is useful in combination with ‘-dpreview’ or ‘-dcrop’.

protected-scheme-parsing bool

If bool is #t, continue when errors in inline Scheme code are caught in the parser. If set to #f, halt on errors and print a stack trace. Default: #t.

relative-includes bool

When processing an \include command, look for the included file relative to the current file if bool is #t. If set to #f, look for the file relative to the root file. Default: #t.

resolution num

Set resolution for generating PNG pixmaps to num dpi. Default: 101.

separate-log-files bool

For input files ‘file1.ly’, ‘file2.ly’, …, output log data to files ‘file1.log’, ‘file2.log’, …, if bool is #t. Default: #f.

separate-page-formats symbol

Comma-separated list of formats (svg, pdf, png, or eps) to use for the separate page images in lilypond-book. See Other programs.

show-available-fonts bool

If bool is #t, list available font names as delivered by the fontconfig library. Appended to this list LilyPond displays the configuration settings of fontconfig itself. Default: #f.

strip-output-dir bool

If bool is #t, don’t use the directory part from input file paths while constructing output file names. Default: #t.

strokeadjust bool

If bool is #t, force PostScript stroke adjustment. This option is mostly relevant when a PDF is generated from PostScript output (stroke adjustment is usually enabled automatically for low-resolution bitmap devices). Without this option, PDF previewers tend to produce widely inconsistent stem widths at resolutions typical for screen display. However, the option does not noticeably affect print quality and causes large file size increases in PDF files. Default: #f.

tall-page-formats symbol

Comma-separated list of formats (svg, pdf, png, or eps) to use for the ‘tall page’ image in lilypond-book. See Other programs.

use-paper-size-for-page bool

If bool is #t (the default), each page is set to the paper size, possibly cropping parts that extend beyond the paper. Setting it #f will resize the page to contain the content as necessary.

verbose

Verbosity level. This is a read-only option; setting it has no effect.

warning-as-error bool

If bool is #t, change all warning and ‘programming error’ messages into errors. Default: #f.

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Basic command-line options for LilyPond ][ Up : Command-line usage ][]

<< Back to Documentation Index

LilyPond — Usage v2.25.8 (development-branch).