[ << Running lilypond ] | [Top][Contents][Index] | [ Updating files with convert-ly >> ] |
[ < Basic command-line options for LilyPond ] | [ Up : Command-line usage ] | [ Environment variables > ] |
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 prefixno-
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 bylilypond-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’sps2pdf
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
andsvg
.-
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 theclip-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, usegs-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, usegs-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
variableprint-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
, oreps
) to use for the separate page images inlilypond-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
, oreps
) to use for the ‘tall page’ image inlilypond-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 ] | [ Environment variables > ] |