[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[][ 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. 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 primarily 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.

As a feature of LilyPond, the dimensions of the cropped output file are always rounded up to integer (PostScript) big points; this might cause a little bit of whitespace at the right margin. To avoid that, set the line-width paper variable to an integer big point value like 450\bp.

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

datadir string

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).

first string

Only show music with a length given by string at the beginning. This is equivalent to 

showFirstLength = string

if inserted at the beginning of the input file. If both -dfirst and showFirstLength are set, the command-line option takes precedence. See Extracting fragments of music. Default: #f.

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: Similar to font-ps-resdir, this option skips TrueType fonts because embedding TrueType fonts might cause garbled characters. To avoid garbling characters, use gs-never-embed-fonts, as this embeds TrueType fonts despite its name.

Default: #f (meaning no export directory).

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 a 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: Similar to font-export-dir, this option skips TrueType fonts because embedding TrueType fonts might cause garbled characters. To avoid garbling characters, use gs-never-embed-fonts, as this embeds TrueType fonts despite its name.

Default: #f (meaning no subset directory).

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 a help screen and exit. 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 option can be passed multiple times to include several files. Default: not set (meaning no global settings file).

job-count num

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

last string

Only show music with a length given by string at the end. This is equivalent to 

showLastLength = string

if inserted at the beginning of the input file. If both -dlast and showLastLength are set, the command-line option takes precedence. See Extracting fragments of music. Default: #f.

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 (being a non-negative integer). 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 string

Set default paper size to string. Default: "a4".

pixmap-format string

Set Ghostscript’s output format for pixel images to string. 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. Both width and height must be non-negative integers.

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.

Default: 0 for both width and height (meaning both dimensions are derived from the EPS bounding box).

point-and-click value

If value is #t, add ‘point & click’ links to PDF and SVG output.

There are more possible option values; see section 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.

read-file-list bool

If bool is #t, handle all file arguments on the command line as lists of LilyPond input files to be processed, with one input file per line in these lists. Default: #f.

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 (which must be a positive number). 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 string

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

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.

staff-size num

Set global staff size to num points (which must be a positive number). This is equivalent to 

#(set-global-staff-size num)

if inserted at the beginning of the input file. Default: 20pt.

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 string

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

use-paper-size-for-page bool

If bool is #t, each page is set to the paper size, possibly cropping parts that extend beyond the paper. Setting it #f resizes the page to contain the content as necessary. Default: #t.

verbose bool

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 >> ]
[][ Up : Command-line usage ][]

<< Back to Documentation Index

LilyPond Application Usage v2.25.15 (development-branch).