4. Scheme functions

Function: add-bar-glyph-print-procedure a b

Specify the single glyph glyph that calls print procedure proc. The procedure proc has to be defined in the form (make-...-bar-line grob extent) even if the extent is not used within the routine.

Function: ly:add-context-mod contextmods modification

Adds the given context modification to the list contextmods of context modifications.

Function: add-grace-property a b c d

Set sym=val for grob in context-name.

Function: ly:add-interface iface desc props

Add a new grob interface. iface is the interface name, desc is the interface description, and props is the list of user-settable properties for the interface.

Function: ly:add-listener callback disp cl

Add the single-argument procedure callback as listener to the dispatcher disp. Whenever disp hears an event of class cl, it calls callback with it.

Function: add-music-fonts a b c d e f

Set up music fonts.

Arguments:

  • node is the font tree to modify.
  • family is the family name of the music font.
  • name is the basename for the music font. ‘name-<designsize>.otf’ should be the music font.
  • brace is the basename for the brace font. ‘brace-brace.otf’ should have piano braces.
  • design-size-alist is a list of (rounded . designsize). rounded is a suffix for font filenames, while designsize should be the actual design size. The latter is used for text fonts loaded through pango/fontconfig.
  • factor is a size factor relative to the default size that is being used. This is used to select the proper design size for the text fonts.
Function: add-new-clef a b c d e

Append the entries for a clef symbol to supported clefs and c0-pitch-alist.

Function: ly:add-option sym val internal description

Add a program option sym. val is the default value and description is a string description.

Function: add-simple-time-signature-style a b

Specify the procedure proc returning markup for a time signature style style. The procedure is called with one argument, the pair (numerator . denominator).

Function: add-stroke-glyph a b c d e

Load and add a stroke (represented by a glyph in the font) to the given flag stencil.

Function: add-stroke-straight a b c d e f g more …

Add the stroke for acciaccatura to the given flag stencil. The stroke starts for up-flags at ‘upper-end-of-flag + (0,length/2)’ and ends at ‘(0, vertical-center-of-flag-end) - (flag-x-width/2, flag-x-width + flag-thickness)’. Here ‘length’ is the whole length, while ‘flag-x-width’ is just the x extent and thus depends on the angle! Other combinations don’t look as good.

For down-stems the y coordinates are simply mirrored.

Function: alist->hash-table a

Convert alist lst to a table.

Warning: The resulting hash table is hashed by identity. This actually corresponds to the alist->hashq-table function of Guile’s (ice-9 hash-table) module, not alist->hash-table.

Function: ly:all-grob-interfaces

Return the hash table with all grob interface descriptions.

Function: ly:all-options

Get all option settings in an alist.

Function: ly:all-output-backend-commands

Return the list of extra output backend commands that are used internally in file ‘lily/stencil-interpret.cc’.

Function: ly:all-stencil-commands

Return the list of stencil commands that can be defined in the output modules (in files ‘output-*.scm’).

Function: ly:all-stencil-expressions

Return all symbols recognized as stencil expressions.

Function: allow-volta-hook a

Allow the volta bracket hook being drawn over bar line bar-glyph.

Function: alterations-in-key a

Count number of sharps minus number of flats.

Function: ly:angle x y

Calculate angle in degrees of given vector. With one argument, x is a number pair indicating the vector. With two arguments, x and y specify the respective coordinates.

Function: angle-0-2pi a

Take angle (in radians) and map it between 0 and 2pi.

Function: angle-0-360 a

Take angle (in degrees) and map it between 0 and 360 degrees.

Function: arrow-stencil a b c d e

Return a right-pointing, filled arrow-head, where x determines the basic horizontal position and y determines the basic vertical position. Both values are adjusted using staff-space, which is StaffSymbol’s staff space. thick is the used line thickness.

Function: arrow-stencil-maker a b

Return a function drawing a line from current point to destination, with optional arrows of max-size on start and end controlled by start? and end?.

Function: ly:assoc-get key alist default-value strict-checking

Return value if key in alist, else default-value (or #f if not specified). If strict-checking is set to #t and key is not in alist, a programming error is output.

Function: assoc-get _ _ [_ [_]]

- LilyPond procedure: ly:assoc-get (SCM key, SCM alist, SCM default_value, SCM strict_checking)

Return value if key in alist, else default-value (or #f if not specified). If strict-checking is set to #t and key is not in alist, a programming error is output.

Function: at-bar-line-substitute-caesura-type a

At a bar line, create the caesura using substitute-type rather than the value of caesuraType.

Function: ly:axis-group-interface::add-element grob grob-element

Add grob-element to the axis group grob. In particular, grob becomes parent to grob-element on all axes supported by grob, unless the parents are already set.

Function: ly:bar-line::calc-anchor a

Calculate the anchor position of a bar line. The anchor is used for the correct placement of bar numbers, etc.

Function: bar-line::calc-break-visibility a

Calculate the visibility of a bar line at line breaks.

Function: bar-line::calc-glyph-name a

Return the name of the bar line glyph printed by grob for the actual break direction.

Function: bar-line::calc-glyph-name-for-direction a b

Find the glyph name for a bar line. glyphs is the list of bar-line types to consider in order. Each must have been defined with define-bar-line. dir is the break direction to consider: LEFT = end of line, CENTER = middle of line, RIGHT = start of line.

Function: bar-line::compound-bar-line a b c

Build the bar line stencil.

Function: bar-line::draw-filled-box a b c d e

Return a straight bar line created by ly:round-filled-box looking at x-ext, y-ext, thickness. The blot is calculated by bar-line::calc-blot, which needs extent and grob. y-ext is not necessarily of same value as extent.

Function: ly:bar-line::print a

The print routine for bar lines.

Function: bar-line::widen-bar-extent-on-span a b

Widen the bar line extent towards span bars adjacent to grob grob.

Function: base-length a b

Get baseMoment rational value for time-signature from time-signature-settings.

Function: ly:basic-progress str rest

A Scheme callable function to issue a basic progress message str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: beam-exceptions a b

Get beamExceptions value for time-signature from time-signature-settings.

Function: beat-structure a b c

Get beatStructure value in base-length units for time-signature from time-signature-settings.

Function: bend::arrow-head-stencil a b c d e

Return an arrow head stencil, calculated from the given dimensions height and width, and translated to x-y-coords, the end of the bend-spanners (curved) line.

Function: bend::calc-bend-x-begin a b c d

Calculate the starting values in x direction of the bend. After a line break, the values from the right bound are taken minus 1.5 staff spaces. For bends-down or if grob property 'style equals to 'pre-bend, 'hold or 'pre-bend-hold, interval-center is applied the topmost note head of the starting note heads. In any other case the right edge of the starting note head is used. The value of BendSpanner.details.horizontal-left-padding is added, which may be changed by an appropriate override. Returns a list of the same length as the amount of bend-starting note heads.

Function: bend::calc-bend-x-end a b c

Calculate the ending x coordinate of bend-spanner. At the line end, take the items of BreakAlignGroup into account and a little bit of padding. Ends an unbroken spanner or the last of a broken one in the middle of the topmost note head of its bounding note column.

Function: bend::target-cautionary a

Set 'display-cautionary of all relevant note heads of spanners right bound to true. As a result they appear parenthesized. This procedure is the default value of 'before-line-breaking.

Function: bend::text-string a

Take a spanner grob and calculate a list with the quarter tone diffs between the pitches of starting and ending bound. Because bending to different amounts is very unlikely, only the first element of this list is returned as a string.

Function: bend-spanner::print a

Return the final stencil. A line and curve, an arrow head and a text representing the amount a string is bent.

Function: ly:bezier-extent control-points axis

Compute the extent of the Bézier curve defined by control-points along axis.

Function: ly:bezier-extract control-points t-min t-max

Return a sub-curve of the Bézier curve defined by control-points. The sub-curve is delimited by the curve points indexed by t-min and t-max (between 0 and 1, 0 = first control point, 1 = last control point). A sub-curve of a Bézier curve is in turn a Bézier curve.

Function: ly:book? x

Is x a smob of class Book?

Function: ly:book-add-bookpart! book-smob book-part

Add book-part to book-smob book part list.

Function: ly:book-add-score! book-smob score

Add score to book-smob score list.

Function: ly:book-book-parts book

Return book parts in book.

Function: book-first-page a b

Return the 'first-page-number of the entire book.

Function: ly:book-header book

Return header in book.

Function: ly:book-paper book

Return paper in book.

Function: ly:book-process book-smob default-paper default-layout output

Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-process-to-systems book-smob default-paper default-layout output

Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-scores book

Return scores in book.

Function: ly:book-set-header! book module

Set the book header.

Function: box-grob-stencil a

Make a box of exactly the extents of the grob. The box precisely encloses the contents.

Function: box-stencil a b c

Add a box around stencil, producing a new stencil.

Function: ly:bp num

num bigpoints (1/72th inch).

Function: ly:bracket a iv t p

Make a bracket in direction a. The extent of the bracket is given by iv. The wings protrude by an amount of p, which may be negative. The thickness is given by t.

Function: bracketify-stencil a b c d e

Add brackets around stil, producing a new stencil.

Function: break-alignable-interface::self-alignment-of-anchor a

Return a value for g’s self-alignment-X that will place g on the same side of the reference point defined by a break-aligned item such as a Clef.

Function: break-alignable-interface::self-alignment-opposite-of-anchor a

Return a value for g’s self-alignment-X that will place g on the opposite side of the reference point defined by a break-aligned item such as a Clef.

Function: ly:break-alignment-interface::find-nonempty-break-align-group

Find the BreakAlignGroup with the given break-align-symbol in this BreakAlignment. Return #f if there is no such group. Also return #f if the group has empty X-extent, which can happen if it contains only omitted items.

Function: break-alignment-list a b c

Return a callback that calculates a value based on a grob’s break direction.

Function: ly:broadcast disp ev

Send the stream event ev to the dispatcher disp.

Function: caesura-script-interface::before-line-breaking a

Callback for CaesuraScript grob. Eliminate scripts aligned to bar lines if they might collide with a span bar. Some types of bar lines have visible span bars and some don’t. For consistent notation, we don’t check whether particular SpanBar grobs are actually visible, just that they exist.

Function: caesura-to-bar-line-or-divisio a b c

caesuraTypeTransform callback to print articulated caesurae as chant breath marks using the infrastructure for modern bar lines when possible.

Function: caesura-to-divisio a b c

caesuraTypeTransform callback to print articulated caesurae as chant breath marks.

Function: ly:cairo-output-stencil basename stencil paper formats

dump a single stencil through the Cairo backend

Function: ly:cairo-output-stencils basename stencils header paper formats

dump book through cairo backend

Function: calc-harmonic-pitch a b

Calculate the harmonic pitches in music given pitch as the non-harmonic pitch.

Function: ly:camel-case->lisp-identifier name-sym

Convert FooBar_Bla to foo-bar-bla style symbol.

Function: centered-spanner-interface::calc-x-offset a

Compute the shift from this spanner’s reference point to a point centered between two non-musical columns, according to the spacing-pair property. This also takes self-alignment-X into account. The default for spacing-pair is '(break-alignment . break-alignment).

Function: centered-stencil a

Center stencil stencil in both the x and y directions.

Function: ly:chain-assoc-get key achain default-value strict-checking

Return value for key from a list of alists achain. If no entry is found, return default-value or #f if default-value is not specified. With strict-checking set to #t, a programming error is output in such cases.

Function: chain-assoc-get _ _ [_ [_]]

- LilyPond procedure: ly:chain-assoc-get (SCM key, SCM achain, SCM default_value, SCM strict_checking)

Return value for key from a list of alists achain. If no entry is found, return default-value or #f if default-value is not specified. With strict-checking set to #t, a programming error is output in such cases.

Function: change-pitches a b

Recurse through music, applying converter to pitches. converter is typically a transposer or an inverter (see file ‘scm/modal-transforms.scm’), but may be user-defined. The converter function must take a single pitch as its argument and return a new pitch. These are LilyPond Scheme pitches, e.g., (ly:make-pitch 0 2 0).

Function: check-context-path _ [_]

Check a context property path specification path, a symbol list (or a single symbol), for validity and possibly complete it. Returns the completed specification, or #f when rising an error (using optionally location).

Function: ly:check-expected-warnings

Check whether all expected warnings have really been triggered.

Function: check-grob-path a rest …

Check a grob path specification path, a symbol list (or a single symbol), for validity and possibly complete it. Returns the completed specification, or #f if invalid, optionally using location for an error message. If an optional keyword argument #:start start is given, the parsing starts at the given index in the sequence ‘Context.Grob.property.sub-property...’, with the default of ‘0’ implying the full path.

If there is no valid first element of path fitting at the given path location, an optionally given #:default default is used as the respective element instead without checking it for validity at this position.

The resulting path after possibly prepending default can be constrained in length by optional arguments #:min min and #:max max, defaulting to ‘1’ and unlimited, respectively.

Function: check-music-path a rest …

Check a music property path specification path, a symbol list (or a single symbol), for validity and possibly complete it. Returns the completed specification, or #f when rising an error (using optionally location).

Function: chord-name->german-markup a

Return pitch markup for PITCH, using german note names. If B-instead-of-Bb is set to #t real german names are returned. Otherwise semi-german names (with Bb and below keeping the british names)

Function: chord-name->italian-markup a

Return pitch markup for pitch, using Italian/French note names. If french? is set to #t, french ‘ré’ is returned for pitch D instead of ‘re’.

Function: circle-stencil a b c

Add a circle around stencil, producing a new stencil.

Function: clef-transposition-markup a b

The transposition sign formatting function. oct is supposed to be a string holding the transposition number, style determines the way the transposition number is displayed.

Function: ly:cm num

num cm.

Function: collect-book-music-for-book a b

Book music handler.

Function: collect-bookpart-for-book a

Top-level book-part handler.

Function: collect-music-aux a b

Pass music to score-handler, with preprocessing for page layout instructions.

Function: collect-music-for-book a

Top-level music handler.

Function: ly:command-line-code

The Scheme code specified on the command line with option ‘-e’.

Function: ly:command-line-options

The Scheme options specified on the command line with option ‘-d’.

Function: comparator-from-key a b

Return a comparator function that applies key to the two elements and compares the results using cmp. Especially useful for sorting.

Function: ly:connect-dispatchers to from

Make the dispatcher to listen to events from from.

Function: construct-chord-elements a b c

Build a chord on root using modifiers in modifications. NoteEvents have duration duration.

Notes: Natural 11 is left from chord if not explicitly specified.

Entry point for the parser.

Function: ly:context? x

Is x a smob of class Context?

Function: ly:context-current-moment context

Return the current moment of context.

Function: ly:context-def? x

Is x a smob of class Context_def?

Function: ly:context-def-lookup def sym val

Return the value of sym in context definition def (e.g., \Voice). If no value is found, return val or '() if val is undefined. sym can be any of ‘default-child’, ‘consists’, ‘description’, ‘aliases’, ‘accepts’, ‘property-ops’, ‘context-name’, ‘group-type’.

Function: ly:context-def-modify def mod

Return the result of applying the context-mod mod to the context definition def. Does not change def.

Function: ly:context-event-source context

Return event-source of context context.

Function: ly:context-events-below context

Return a stream-distributor that distributes all events from context and all its subcontexts.

Function: ly:context-find context name

Find a parent of context that has name or alias name. Return #f if not found.

Function: ly:context-grob-definition context name

Return the definition of name (a symbol) within context as an alist.

Function: ly:context-id context

Return the ID string of context, i.e., for \context Voice = "one" … return the string one.

Function: ly:context-matched-pop-property context grob cell

This undoes a particular \override, \once \override or \once \revert when given the specific alist pair to undo.

Function: ly:context-mod? x

Is x a smob of class Context_mod?

Function: ly:context-mod-apply! context mod

Apply the context modification mod to context.

Function: ly:context-name context

Return the name of context, i.e., for \context Voice = "one" … return the symbol Voice.

Function: ly:context-output-def context

Return the output definition of context.

Function: ly:context-parent context

Return the parent of context, #f if none.

Function: ly:context-property context sym def

Return the value for property sym in context. If def is given, and property value is '(), return def.

Function: ly:context-property-where-defined context name def

Return the context above context where name is defined, or def (defaulting to '()) if no such context is found.

Function: ly:context-pushpop-property context grob eltprop val

Do \temporary \override or \revert operation in context. The grob definition grob is extended with eltprop (if val is specified) or reverted (if unspecified).

Function: ly:context-set-property! context name val

Set value of property name in context context to val.

Function: context-spec-music _ _ [_ [_]]

Add \context context = id \with mods to m.

Function: ly:context-unset-property context name

Unset value of property name in context context.

Function: copy-repeat-chord a b c d

Copy all events in event-types (be sure to include rhythmic-events) from original-chord over to repeat-chord with their articulations filtered as well. Any duration is replaced with the specified duration.

Function: count-list a

Given lst as (E1 E2 .. ), return ((E1 . 1) (E2 . 2) ... ).

Function: create-glyph-flag a b c

Create a flag stencil by looking up the glyph from the font.

Function: cross-staff-connect a

Set cross-staff property of the stem to this function to connect it to other stems automatically

Function: cue-substitute a

Must happen after quote-substitute.

Function: cyclic-base-value a b

Take value (for example, an angle) and modulo-maps it between 0 and base cycle.

Function: ly:debug str rest

A Scheme callable function to issue a debug message str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: default-flag a

Create a flag stencil for the stem. Its style is derived from the 'style Flag property. By default, lilypond uses a C++ Function (which is slightly faster) to do exactly the same as this function. However, if one wants to modify the default flags, this function can be used to obtain the default flag stencil, which can then be modified at will. The correct way to do this is:

\override Flag #'stencil = #default-flag
\override Flag #'style = #'mensural
Function: ly:default-scale

Get the global default scale.

Function: define-bar-line a b c d

Define a bar glyph bar-glyph and its substitutes at the end of a line (eol-glyph), at the beginning of a line (bol-glyph) and as a span bar (span-glyph). The substitute glyphs may be either strings or booleans: #t calls for the same value as bar-glyph and #f calls for no glyph.

Function: define-event-class a b

Defines a new event class derived from parent, a previously defined event class.

Macro: define-event-function

Like define-music-function, but the return value must be a post-event.

Function: define-fonts a b c

Return a string of all fonts used in paper, invoking the functions define-font and define-pango-pf for producing the actual font definition.

Macro: define-markup-command

Define a markup function. Syntax:

(define-markup-command (command layout props arg1 arg2 …)
                       (type1? type2? …)
                       [ #:properties ((property1 default1)
                                       (property2 default2)
                                       …) ]
    [ #:category category ]
    [ #:as-string expression ]
    [ "doc-string" ]
    command-body)

This macro defines the markup function command-markup. When this function is applied as

(command-markup layout props arg1 arg2 …)

it executes command-body, a sequence of S-expression similar to the body of a define form. The body should return a stencil.

type1?, type2?, etc., are type predicates for the arguments arg1, arg2, etc. doc-string is an optional description of the command; this can be retrieved using procedure-documentation on command-markup, and is used for built-in markup commands to generate the documentation.

Moreover, this macro defines a helper function make-command-markup, which can be applied as

(make-command-markup arg1 arg2 …)

(without layout and props arguments). This yields a markup. Interpreting it, using (interpret-markup markup layout props), invokes command-markup as above.

The specified properties are available as let-bound variables in the command body, using the respective default value as fallback in case the property is not found in props, or #f if no default was given. props itself is left unchanged: if you want defaults specified in that manner passed down into other markup functions, you need to adjust props yourself.

If the as-string named argument is given, it should be an expression, which is evaluated by markup->string when lossily converting markups to strings. The expression can use all variables available in the main body, namely layout, props, the arguments, and the properties. However, in many cases layout will be #f because such an output definition is not available (such as for MIDI output). This case must be accounted for. The expression can recursively call markup->string, passing it #:layout layout #:props props.

The autogenerated documentation makes use of some optional specifications that are otherwise ignored:

  • category is either a symbol or a symbol list specifying the categories for this markup command in the docs.
  • As an element of the ‘properties’ list, you may directly use command-markup instead of a (property default) to indicate that this markup command is called by the newly defined command, adding its properties to the documented properties of the new command. There is no protection against circular definitions.

Some object properties are attached to the resulting command-markup function according to the parameters of the definition: markup-command-signature, markup-function-category, markup-function-properties.

Macro: define-markup-list-command

Same as define-markup-command, but defines a command that, when interpreted, returns a list of stencils instead of a single one.

Markup list commands are recognizable programmatically by having the markup-list-function? object property to #t.

Macro: define-music-function

Define and return a music function. Syntax:

(define-music-function (arg1 arg2 …)
                       (type1? type2? …)
    function-body)

type1?, type2?, etc., can take one of the forms predicate? for mandatory arguments satisfying the predicate, (predicate?) for optional parameters of that type defaulting to #f, (predicate? value) for optional parameters with a specified default value (evaluated at definition time). An optional parameter can be omitted in a call only when it cannot get confused with a following parameter of different type.

A music function must return a music expression.

Macro: define-scheme-function

Like define-music-function, but the return type is not restricted to music.

Macro: define-syntax-function

Helper macro for ly:make-music-function. Syntax:

  (define-syntax-function result-type?
                          (arg1 arg2 …)
                          (type1? type2? …)
    function-body)
  

See define-music-function for information on type predicates. result-type? can specify a default in the same manner as predicates, to be used in case of a type error in arguments or result.

Function: define-tag-group a

Define a tag group consisting of the given tags, a list of symbols. Returns #f if successful, and an error message if there is a conflicting tag group definition.

Macro: define-void-function

Like define-music-function, but the return value must be the special ‘*unspecified*’ value (i.e., what most Guile functions with “unspecified” value return). Use this when defining functions for executing actions rather than returning values, to keep LilyPond from trying to interpret the return value.

Function: degrees->radians a

Convert the given angle from degrees to radians.

Function: descend-to-context _ _ [_ [_]]

Like context-spec-music, but only descending.

Function: determine-split-list a b c

Event lists evl1 and evl2 should be ascending. chord-range is a pair of numbers (min . max) defining the distance in steps between notes that may be combined into a chord or unison.

Function: determine-string-fret-finger a b c d

Determine string numbers and frets for playing notes as a chord, given specified information specified-info. specified-info is a list with two list elements, specified strings defined-strings and specified fingerings defined-fingers. Only a fingering of 0 will affect the fret selection, as it specifies an open string. If defined-strings is '(), the context property defaultStrings is used as a list of defined strings. Looks for predefined fretboards if predefinedFretboardTable is not #f. If rest is present, it contains the FretBoard grob, and a fretboard gets created. Otherwise, a list of (string fret finger) lists is returned.

If the context-property supportNonIntegerFret is set #t, micro-tones are supported for TabStaff, but not not for FretBoards.

Function: ly:dimension? d

Is d a dimension? Used to distinguish length variables from normal numbers.

Function: ly:dir? s

Is s a direction? Valid directions are -1, 0, or 1, where -1 represents left or down, 1 represents right or up, and 0 represents a neutral direction.

Function: dir-basename a rest …

Strip suffixes in rest, but leave directory component for file.

Function: ly:directed direction magnitude

Calculate an (x . y) pair with optional magnitude (defaulting to 1.0) and direction specified either as an angle in degrees or a coordinate pair giving the direction. If magnitude is a pair, the respective coordinates are scaled independently, useful for ellipse drawings.

Function: ly:disconnect-dispatchers to from

Stop the dispatcher to listening to events from from.

Function: ly:dispatcher? x

Is x a smob of class Dispatcher?

Function: display-lily-music _ [_]

Display the music expression expr using LilyPond syntax.

Function: display-music _ [_]

Display music, not done with music-map for clarity of presentation.

Function: display-scheme-music _ [_]

Display obj, typically a music expression, in a friendly fashion, which often can be read back in order to generate an equivalent expression.

Function: dodecaphonic-no-repeat-rule a b c

An accidental rule that typesets an accidental before every note (just as in the dodecaphonic accidental style) except if the note is immediately preceded by a note with the same pitch. This is a common accidental style in contemporary notation.

Function: ly:duration? x

Is x a smob of class Duration?

Function: ly:duration<? p1 p2

Is p1 shorter than p2?

Function: ly:duration->string dur

Convert dur to a string.

Function: ly:duration-compress dur factor

Compress dur by rational factor.

Function: ly:duration-dot-count dur

Extract the dot count from dur.

Function: duration-dot-factor a

Given a count of the dots used to extend a musical duration, return the numeric factor by which they increase the duration.

Function: ly:duration-factor dur

Extract the compression factor from dur. Return it as a pair.

Function: ly:duration-length dur

The length of the duration as a moment.

Function: duration-length a

Return the overall length of a duration, as a number of whole notes. (Not to be confused with ly:duration-length, which returns a less useful Moment object.)

Function: duration-line::calc a

Return list of values needed to print a stencil for DurationLine.

Function: duration-line::print a

Return the stencil of DurationLine.

Function: ly:duration-log dur

Extract the duration log from dur.

Function: duration-log-factor a

Given a logarithmic duration number, return the length of the duration, as a number of whole notes.

Function: ly:duration-scale dur

Extract the compression factor from dur. Return it as a rational.

Function: duration-visual a

Given a duration object, return the visual part of the duration (base note length and dot count), in the form of a duration object with non-visual scale factor 1.

Function: duration-visual-length a

Given a duration object, return the length of the visual part of the duration (base note length and dot count), as a number of whole notes.

Function: dynamic-text-spanner::before-line-breaking a

Monitor left bound of DynamicTextSpanner for absolute dynamics. If found, ensure DynamicText does not collide with spanner text by changing 'attach-dir and 'padding. Reads the 'right-padding property of DynamicText to fine-tune space between the two text elements.

Function: ly:effective-prefix

Return effective prefix. For example, if LilyPond Scheme files are stored in directory ‘/foo/bar/scm’ and PS files in ‘/foo/bar/ps’, the effective prefix is ‘/foo/bar’.

Function: elbowed-hairpin a b

Create hairpin based on a list of coords in (cons x y) form. x is the portion of the width consumed for a given line and y is the portion of the height. For example, '((0 . 0) (0.3 . 0.7) (0.8 . 0.9) (1.0 . 1.0)) means that at the point where the hairpin has consumed 30% of its width, it must be at 70% of its height. Once it is to 80% width, it must be at 90% height. It finishes at 100% width and 100% height. If coords does not begin with '(0 . 0) the final hairpin may have an open tip. For example ’(0 . 0.5) will cause an open end of 50% of the usual height.

mirrored? indicates if the hairpin is mirrored over the y axis or if just the upper part is drawn.

Returns a function that accepts a hairpin grob as an argument and draws the stencil based on its coordinates.

#(define simple-hairpin
  (elbowed-hairpin '((0 . 0)(1.0 . 1.0)) #t))

\relative c' {
  \override Hairpin #'stencil = #simple-hairpin
  a\p\< a a a\f
}
Function: ellipse-stencil a b c d

Add an ellipse around stencil, padded by the padding pair, producing a new stencil.

Function: end-broken-spanner? a

Is spanner broken and the last of its broken siblings? See also unbroken-or-last-broken-spanner?.

Function: ly:engraver-announce-end-grob engraver grob cause

Announce the end of a grob (i.e., the end of a spanner) originating from given engraver instance, with grob being a grob. cause should either be another grob or a music event.

Function: ly:engraver-make-grob engraver grob-name cause

Create a grob originating from given engraver instance, with given grob-name, a symbol. cause should either be another grob or a music event.

Function: ly:engraver-make-item engraver grob-name cause

Same as ly:engraver-make-grob, but always create a grob with the Item class. This is useful when the same grob definition is used to create grobs of differing classes.

Function: ly:engraver-make-spanner engraver grob-name cause

Same as ly:engraver-make-grob, but always create a grob with the Spanner class. This is useful when the same grob definition is used to create grobs of differing classes.

Function: ly:engraver-make-sticky engraver grob-name host cause

Utility function to create a grob sticking to another grob. This acts like either ly:engraver-make-item or ly:engraver-make-spanner, depending on the class of the host. Additionally, the host is made the parent of the newly created sticky grob on the y axis and, for items, on the x axis. Sticky spanners take their bounds from their host and their end is announced with the end of the host.

Sticky grobs must have the sticky-grob-interface interface, see sticky-grob-interface.

Function: ly:error str rest

A Scheme callable function to issue the error str. The error is formatted with format; rest holds the formatting arguments (if any).

Function: eval-carefully a b rest …

Check whether all symbols in expression symbol are reachable in module module. In that case evaluate, otherwise print a warning and set an optional default.

Function: ly:event? obj

Is obj a proper (non-rhythmic) Event object?

Function: event-chord-notes a

Return a list of all notes from event-chord.

Function: event-chord-pitches a

Return a list of all pitches from event-chord.

Function: event-chord-reduce a

Reduce event chords in music to their first note event, retaining only the chord articulations. Returns the modified music.

Function: event-chord-wrap! a

Wrap isolated rhythmic events and non-postevent events in music inside of an EventChord. Chord repeats ‘q’ are expanded using the default settings of the parser.

Function: ly:event-deep-copy m

Copy m and all sub-expressions of m.

Function: event-has-articulation? a b

Is event-type in the articulations list of the music causing stream-event?

Function: ly:event-property sev sym val

Get the property sym of stream event sev. If sym is undefined, return val or '() if val is not specified.

Function: ly:event-set-property! ev sym val

Set property sym in event ev to val.

Function: expand-repeat-chords! a b

Walk through music and fill repeated chords (notable by having a duration in duration) with the notes from their respective predecessor chord.

Function: expand-repeat-notes! a

Walk through music and give pitchless notes (not having a pitch in pitch or a drum type in drum-type) the pitch(es) from the predecessor note/chord if available.

Function: ly:expect-warning str rest

A Scheme callable function to register a warning to be expected and subsequently suppressed. If the warning is not encountered, a warning about the missing warning is shown. The message should be translated with (_ ...) and changing parameters given after the format string.

Function: extract-beam-exceptions a

Create a value useful for setting beamExceptions from music.

Function: extract-music a b

Return a flat list of all music matching pred? inside of music, not recursing into matches themselves.

Function: extract-named-music a b

Return a flat list of all music named music-name (either a single event symbol or a list of alternatives) inside of music, not recursing into matches themselves.

Function: ly:extract-subfont-from-collection collection-file-name idx subfont-file-name

Extract the subfont of index idx in TrueType collection (TTC) or OpenType/CFF collection (OTC) file collection-file-name and write it to file subfont-file-name.

Function: extract-typed-music a b

Return a flat list of all music with type (either a single type symbol or a list of alternatives) inside of music, not recursing into matches themselves.

Function: ly:find-file name

Return the absolute file name of name, or #f if not found.

Function: find-named-props a b

Used by \magnifyMusic and \magnifyStaff. If grob-descriptions is equal to the all-grob-descriptions alist (defined in ‘scm/define-grobs.scm’), this finds all grobs that can have a value for the prop-name property, and return them as a list in the following format:

'((grob prop-name)
  (grob prop-name)
  ...)
Function: find-pitch-entry a b c d

Return the first entry in keysig that matches pitch by notename and octave. Alteration is not considered. accept-global states whether key signature entries should be included. accept-local states whether local accidentals should be included. If no matching entry is found, #f is returned.

Function: finger-glide::print a

The stencil printing procedure for grob FingerGlideSpanner. Depending on the grob property style several forms of appearance are printed. Possible settings for grob property style are zigzag, trill, dashed-line, dotted-line, stub-left, stub-right, stub-both, bow, none and line, which is the default.

Function: first-assoc a b

Return first successful assoc of key from keys in lst.

Function: first-broken-spanner? a

Is spanner broken and the first of its broken siblings? See also unbroken-or-first-broken-spanner?.

Function: first-member a b

Return first successful member (of member) from members in lst.

Function: flat-flag a

Flat flag style. The angles of the flags are both 0 degrees.

Function: flatten-list a

Unnest list.

Function: flip-stencil a b

Flip stencil stil in the direction of axis. Value X (or 0) for axis flips it horizontally. Value Y (or 1) flips it vertically. stil is flipped in place; its position, the coordinates of its bounding box, remains the same.

Function: fold-some-music a b c d

This works recursively on music like fold does on a list, calling ‘(pred? music)’ on every music element. If #f is returned for an element, it is processed recursively with the same initial value of ‘previous’, otherwise ‘(proc music previous)’ replaces ‘previous’ and no recursion happens. The top music is processed using init for ‘previous’.

Function: ly:font-config-add-directory dir

Add directory dir to FontConfig.

Function: ly:font-config-add-font font

Add font font to FontConfig.

Function: ly:font-config-display-fonts

Dump a list of all fonts visible to FontConfig.

Function: ly:font-config-get-font-file name

Get the file for font name, as found by FontConfig.

Function: ly:font-design-size font

Given the font metric font, return the design size, relative to the current output-scale.

Function: ly:font-file-name font

Given the font metric font, return the corresponding file name.

Function: ly:font-get-glyph font name

Return a stencil from font for the glyph named name. If the glyph is not available, return an empty stencil.

Note that this command can only be used to access glyphs from fonts loaded with ly:system-font-load; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings fetaMusic and fetaBraces, respectively.

Function: ly:font-glyph-name-to-charcode font name

Return the character code for glyph name in font.

Note that this command can only be used to access glyphs from fonts loaded with ly:system-font-load; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings fetaMusic and fetaBraces, respectively.

Function: ly:font-glyph-name-to-index font name

Return the index for name in font.

Note that this command can only be used to access glyphs from fonts loaded with ly:system-font-load; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings fetaMusic and fetaBraces, respectively.

Function: ly:font-index-to-charcode font index

Return the character code for index in font.

Note that this command can only be used to access glyphs from fonts loaded with ly:system-font-load; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings fetaMusic and fetaBraces, respectively.

Function: ly:font-magnification font

Given the font metric font, return the magnification, relative to the current output-scale.

Function: ly:font-metric? x

Is x a smob of class Font_metric?

Function: ly:font-name font

Given the font metric font, return the corresponding name.

Function: font-name-split a

Return (font-name . design-size) from font-name string or #f.

Function: ly:font-sub-fonts font

Given the font metric font of an OpenType font, return the names of the subfonts within font.

Function: for-some-music a b

Walk through music, process all elements calling stop? and only recurse if this returns #f.

Function: ly:format str rest

LilyPond specific format function, supporting ~a and ~[0-9]f. Basic support for ~s is also provided.

Function: ly:format-output context

Given a global context in its final state, process it and return the Music_output object in its final state.

Function: format-segno-mark-considering-bar-lines a b

When bar lines incorporate segni, print no mark for the first segno because that would be redundant. Print the usual marks for later segni to avoid ambiguity.

Function: fret->pitch a

Calculate a pitch given fret for the harmonic.

Function: fret-parse-terse-definition-string a b

Parse a fret diagram string that uses terse syntax; return a pair containing props, modified to include the string-count determined by definition-string, and a fret indication list with the appropriate values.

Function: function-chain a b

Apply a list of functions in function-list to arg. Each element of function-list is structured (cons function '(arg2 arg3 ...)). If function takes arguments besides arg, they are provided in function-list. Example:

(function-chain 1 `((,+ 1) (,- 2) (,+ 3) (,/)))
   ⇒ 1/3
Function: generate-crop-stencil a

Returns a stencil for the cropped output of the given Paper_book

Function: generate-preview-stencil a

Returns a stencil for a preview of given Paper_book

Function: ly:generic-bound-extent grob common

Determine the extent of grob relative to common along the x axis, finding its extent as a bound when it a has bound-alignment-interfaces property list set and otherwise the full extent.

Function: ly:get-all-function-documentation

Get a hash table with all LilyPond Scheme extension functions.

Function: ly:get-all-translators

Return a list of all translator objects that may be instantiated.

Function: get-bound-note-heads a

Take a spanner grob and return a pair containing all note heads of the initial starting and the final NoteColumn.

Function: ly:get-cff-offset font-file-name idx

Get the offset of the ‘CFF’ table for font-file-name, returning it as an integer. The optional idx argument is useful for OpenType/CFF collections (OTC) only; it specifies the font index within the OTC. The default value of idx is 0.

Function: get-chord-shape a b c

Return the chord shape associated with shape-code and tuning in the hash-table base-chord-shapes.

Function: ly:get-context-mods contextmod

Returns the list of context modifications stored in contextmod.

Function: ly:get-font-format font-file-name idx

Get the font format for font-file-name, returning it as a symbol. The optional idx argument is useful for TrueType Collections (TTC) and OpenType/CFF collections (OTC) only; it specifies the font index within the TTC/OTC. The default value of idx is 0.

Function: ly:get-option var

Get a global option setting.

Function: get-postscript-bbox a

Extract the bounding box from string, or return #f if not present.

Function: ly:get-spacing-spec from-scm to-scm

Return the spacing spec going between the two given grobs, from-scm and to-scm.

Function: get-tweakable-music a

When tweaking music, return a list of music expressions where the tweaks should be applied. Relevant for music wrappers and event chords.

Function: glyph-flag a

Simulatesthe default way of generating flags: Look up glyphs flags.style[ud][1234] from the feta font and use it for the flag stencil.

Function: ly:grob? x

Is x a smob of class Grob?

Function: grob::all-objects a

Return a list of the names and contents of all properties having type ly:grob? or ly:grob-array? for all interfaces supported by grob grob.

Function: grob::compose-function a b

Create a callback entity func to be stored in a grob property, based on the grob property data data (which can be plain data, a callback itself, or an unpure-pure container).

Function or unpure-pure container func accepts a grob and a value and returns another value. Depending on the type of data, func is used for building a grob callback or an unpure-pure container.

Function: grob::display-objects a

Display all objects stored in properties of grob grob.

Function: grob::inherit-parent-property a b rest …

grob callback generator for inheriting a property from an axis parent, defaulting to default if there is no parent or the parent has no setting.

Function: grob::name a

Return the name of the grob grob as a symbol.

Function: grob::offset-function a b rest …

Create a callback entity func to be stored in a grob property, based on the grob property data data (which can be plain data, a callback itself, or an unpure-pure container).

Function func accepts a grob and returns a value that is added to the value resulting from data. Optional argument plus defaults to ‘+’ but may be changed to allow for using a different underlying accumulation.

If data is #f or '(), it is not included in the sum.

Function: grob::relay-other-property a

grob callback generator for returning the value of another property, which is identified by the symbol property.

Function: grob::rhythmic-location a

Return a pair consisting of the measure number and moment within the measure of grob grob.

Function: grob::unpure-Y-extent-from-stencil a

The unpure height will come from a stencil whereas the pure height will come from pure-function.

Function: grob::when a

Return the global timestep (a Moment) of grob grob.

Function: ly:grob-alist-chain grob global

Get an alist chain for grob grob, with global as the global default. If unspecified, font-defaults from the layout block is taken.

Function: ly:grob-array? x

Is x a smob of class Grob_array?

Function: ly:grob-array->list grob-arr

Return the elements of grob-arr as a Scheme list.

Function: ly:grob-array-length grob-arr

Return the length of grob-arr.

Function: ly:grob-array-ref grob-arr index

Retrieve the indexth element of grob-arr.

Function: ly:grob-basic-properties grob

Get the immutable properties of grob.

Function: ly:grob-chain-callback grob proc sym

Find the callback that is stored as property sym of grob grob and chain proc to the head of this, meaning that it is called using grob and the previous callback’s result.

Function: ly:grob-common-refpoint grob other axis

Find the common refpoint of grob and other for axis.

Function: ly:grob-common-refpoint-of-array grob others axis

Find the common refpoint of grob and others (a grob-array) for axis.

Function: ly:grob-default-font grob

Return the default font for grob grob.

Function: ly:grob-extent grob refp axis

Get the extent in axis direction of grob relative to the grob refp.

Function: ly:grob-get-vertical-axis-group-index grob

Get the index of the vertical axis group the grob grob belongs to; return -1 if none is found.

Function: ly:grob-interfaces grob

Return the interfaces list of grob grob.

Function: ly:grob-layout grob

Get \layout definition from grob grob.

Function: ly:grob-list->grob-array grob-list

Convert a Scheme list of grobs to a grob array.

Function: ly:grob-object grob sym val

Return the value of a pointer in grob grob of property sym. When sym is undefined in grob, it returns val if specified or '() (end-of-list) otherwise. The kind of properties this taps into differs from regular properties. It is used to store links between grobs, either grobs or grob arrays. For instance, a note head has a stem property, the stem grob it belongs to. Just after line breaking, all those grobs are scanned and replaced by their relevant broken versions when applicable.

Function: ly:grob-original grob

Return the unbroken original grob of grob, grob may be an item or spanner.

Function: ly:grob-parent grob axis def

Get the parent of grob. axis is 0 for the x axis, 1 for the y axis. If grob has no parent on this axis (yet), return def, or '() if def is not specified.

Function: ly:grob-pq<? a b

Compare two grob priority queue entries. This is an internal function.

Function: ly:grob-properties? x

Is x a smob of class Grob_properties?

Function: ly:grob-property grob sym val

Return the value for property sym of grob. If no value is found, return val or '() if val is not specified.

Function: ly:grob-property-data grob sym

Return the value for property sym of grob, but do not process callbacks.

Function: ly:grob-pure-height grob refp beg end val

Return the pure height of grob given refpoint refp. If no value is found, return val or '() if val is not specified.

Function: ly:grob-pure-property grob sym beg end val

Return the pure value for property sym of grob. If no value is found, return val or '() if val is not specified.

Function: ly:grob-relative-coordinate grob refp axis

Get the coordinate in axis direction of grob relative to the grob refp.

Function: ly:grob-robust-relative-extent grob refp axis

Get the extent in axis direction of grob relative to the grob refp, or (0,0) if empty.

Function: ly:grob-script-priority-less a b

Compare two grobs by script priority. For internal use.

Function: ly:grob-set-nested-property! grob symlist val

Set nested property symlist in grob grob to value val.

Function: ly:grob-set-object! grob sym val

Set sym in grob grob to value val.

Function: ly:grob-set-parent! grob axis parent-grob

Set parent-grob as the parent of grob grob in axis axis.

Function: ly:grob-set-property! grob sym val

Set sym in grob grob to value val.

Function: ly:grob-spanned-column-rank-interval grob

Return a pair with the rank of the furthest left column and the rank of the furthest right column spanned by grob.

Function: ly:grob-staff-position sg

Return the y position of sg relative to the staff.

Function: ly:grob-suicide! grob

Kill grob.

Function: ly:grob-system grob

Return the system grob of grob.

Function: grob-transformer a b

Create an override value good for applying func to either pure or unpure values. func is called with the respective grob as first argument and the default value (after resolving all callbacks) as the second.

Function: ly:grob-translate-axis! grob d a

Translate grob on axis a over distance d.

Function: ly:grob-vertical<? a b

Does a lie above b on the page?

Function: ly:gulp-file name size

Read size characters from the file name, and return its contents in a string. If size is undefined, the entire file is read. The file is looked up using the search path.

Function: ly:gulp-file-utf8 name size

Read size characters from the file name, and return its contents in a string decoded from UTF-8. If size is undefined, the entire file is read. The file is looked up using the search path.

Function: ly:has-glyph-names? font-file-name idx

Does the font for font-file-name have glyph names? The optional idx argument is useful for TrueType Collections (TTC) and OpenType/CFF collections (OTC) only; it specifies the font index within the TTC/OTC. The default value of idx is 0.

Function: ly:hash-table-keys tab

Return a list of keys in tab.

Function: headers-property-alist-chain a

Take a list of \header blocks (Guile modules). Return an alist chain containing all of their bindings where the names have been prefixed with header:. This alist chain is suitable for interpreting a markup in the context of these headers.

Function: hook-stencil a b c d e f

Return a hook stencil where x determines the horizontal position and y determines the basic vertical position. The final stencil is adjusted vertically using staff-space, which is StaffSymbol’s staff space, and uses blot, which is the current 'blot-diameter. The stencil’s thickness is usually taken from grob 'details, thick serves as a fallback value.

Function: ly:in-event-class? a b

Does event ev belong to event class cl?

Function: ly:inch num

num inches.

Function: ly:input-both-locations sip

Return input location in sip as

(file-name first-line first-column last-line last-column)
Function: ly:input-file-line-char-column sip

Return input location in sip as (file-name line char column).

Function: ly:input-location? x

Is x a smob of class Input?

Function: ly:input-message sip msg rest

Print msg as a GNU compliant error message, pointing to the location in sip. msg is interpreted similar to format’s argument, using rest.

Function: ly:input-warning sip msg rest

Print msg as a GNU compliant warning message, pointing to the location in sip. msg is interpreted similar to format’s argument, using rest.

Function: interpret-markup _ _ _

- LilyPond procedure: ly:text-interface::interpret-markup Convert a text markup into a stencil. Takes three arguments, layout, props, and markup.

layout is a \layout block; it may be obtained from a grob with ly:grob-layout. props is an alist chain, i.e., a list of alists. This is typically obtained with (ly:grob-alist-chain grob (ly:output-def-lookup layout 'text-font-defaults)). markup is the markup text to be processed.

Function: ly:interpret-music-expression mus ctx

Interpret the music expression mus in the global context ctx. The context is returned in its final state.

Function: interval-center a

Center the number pair x, if an interval.

Function: interval-index a b

Interpolate interval between between left (dir=-1) and right (dir=+1).

Function: interval-length a

Length of the number pair x, if an interval.

Function: ly:intlog2 d

The 2-logarithm of 1/d.

Function: invalidate-alterations a

Invalidate alterations in context.

Elements of 'localAlterations corresponding to local alterations of the key signature have the form '((octave . notename) . (alter barnum . end-mom)). Replace them with a version where alter is set to 'clef to force a repetition of accidentals.

Entries that conform with the current key signature are not invalidated.

Function: ly:item? g

Is g an Item object?

Function: item::extra-spacing-height-including-staff a

Return a value for extra-spacing-height that augments the extent of the grob to the extent of the staff.

Function: ly:item-break-dir it

The break status direction of item it. -1 means end of line, 0 unbroken, and 1 beginning of line.

Function: ly:item-get-column it

Return the PaperColumn or NonMusicalPaperColumn associated with this Item.

Function: ly:iterator? x

Is x a smob of class Music_iterator?

Function: layout-line-thickness a

Get the line thickness of the grob’s corresponding layout.

Function: layout-set-absolute-staff-size a

Set the absolute staff size inside of a \layout{} block. sz is in points.

Function: layout-set-staff-size a

Set the staff size inside of a \layout{} block. sz is in points.

Function: ly:length x y

Calculate magnitude of given vector. With one argument, x is a number pair indicating the vector. With two arguments, x and y specify the respective coordinates.

Function: ly:lily-lexer? x

Is x a smob of class Lily_lexer?

Function: ly:lily-parser? x

Is x a smob of class Lily_parser?

Function: lilypond-main a

Entry point for LilyPond.

Function: lilypond-version-outdated? a b

Is file-version outdated compared to lily-version? This is defined as a version that is from a lower release series (corresponding to the first two numbers of the version) or a version from the same unstable release series (odd minor version number) with a lower patch level (third number). A stable version from the same series does not count as outdated because compatibility is preserved.

Function: ly:line-interface::line grob startx starty endx endy

Make a line using layout information from grob grob.

Function: list-insert-separator a b

Create new list, inserting between between elements of lst.

Function: list-join a b

Put intermediate between all elements of lst.

Function: ly:listened-event-class? disp cl

Does disp listen to any event type in the list cl?

Function: ly:listened-event-types disp

Return a list of all event types that disp listens to.

Function: ly:listener? x

Is x a smob of class Listener?

Function: lookup-markup-command a

Return (function . signature) for a markup command code, or return #f.

Function: lyric-hyphen::vaticana-style a

Draw a LyricHyphen grob as needed for Gregorian chant in Editio Vaticana style, that is, apply it once, flush-left. If the text property of LyricHyphen is set, print this markup. If the property is not set, use a hyphen character.

Function: lyric-text::print a

Allow interpretation of tildes as lyric tieing marks.

Function: make-accidental-dodecaphonic-rule a b

Variation on function make-accidental-rule that creates an dodecaphonic accidental rule.

Function: make-accidental-rule a b

Create an accidental rule that makes its decision based on the octave of the note and a laziness value.

octaveness is either 'same-octave or 'any-octave and defines whether the rule should respond to accidental changes in other octaves than the current. 'same-octave is the normal way to typeset accidentals – an accidental is made if the alteration is different from the last active pitch in the same octave. 'any-octave looks at the last active pitch in any octave.

laziness states over how many bars an accidental should be remembered. 0 is the default – accidental lasts over 0 bar lines, that is, to the end of current measure. A positive integer means that the accidental lasts over that many bar lines. -1 is ‘forget immediately’, that is, only look at key signature. #t is ‘forever’.

Function: ly:make-book paper header scores

Make a \book of paper and header (which may be #f as well) containing \scores.

Function: ly:make-book-part scores

Make a \bookpart containing \scores.

Function: make-bow-stencil a b c d e f

Create a bow stencil. It starts at point start, ends at point stop. thickness is the thickness of the bow. The higher the value of number angularity, the more angular the shape of the bow. bow-height determines the height of the bow. orientation determines whether the bow is concave or convex. Both variables are supplied to support independent usage.

Done by calculating a horizontal unit bow first, then moving all control points to the correct positions. Limitation: s-curves are currently not supported.

Function: make-c-time-signature-markup a

Make markup for the ‘C’ time signature style.

Function: make-circle-stencil a b c

Make a circle of radius radius and thickness thickness.

Function: make-clef-set a

Generate the clef setting commands for a clef with name clef-name.

Function: make-connected-line a b

Take a list of points, points. Return a line connecting points, using ly:line-interface::line and getting layout information from grob.

Function: make-connected-path-stencil a b c d e f

Make a connected path described by the list pointlist, beginning at point (0, 0), with thickness thickness, and scaled by x-scale in the x direction and y-scale in the y direction. connect and fill are boolean arguments that specify whether the path should be connected or filled, respectively.

Function: ly:make-context-mod mod-list

Create a context modification, optionally initialized via the list of modifications mod-list.

Function: make-cue-clef-set a

Generate the clef setting commands for a cue clef with name clef-name.

Function: make-cue-clef-unset

Reset the clef settings for a cue clef.

Function: ly:make-dispatcher

Return a newly created dispatcher.

Function: ly:make-duration length dotcount num den

Make a duration. length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by the optional argument dotcount.

The duration factor is optionally given by integers num and den, alternatively by a single rational number.

A duration is a musical duration, i.e., a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.

Function: make-duration-of-length a

Make duration of the given moment length.

Function: make-ellipse-stencil a b c d

Make an ellipse of x radius x-radius, y radius y-radius, and thickness thickness with fill defined by fill.

Macro: make-engraver

Like make-translator, but create an engraver, i.e., the resulting translator is only run in layout output and ignored in MIDI.

Function: make-filled-box-stencil a b

Make a filled box.

Function: ly:make-global-context output-def

Set up a global interpretation context, using the output block output-def. The context is returned.

Function: ly:make-global-translator global

Create a translator group and connect it to the global context global. The translator group is returned.

Function: make-glyph-time-signature-markup a b

Make markup for a symbolic time signature of the form timesig.<style><numerator><denominator>, for example ‘timesig.mensural34’. If the music font does not have a glyph for the requested style and fraction, issue a warning and make a numbered time signature instead.

Function: ly:make-grob-properties alist

Package the given property list alist in a grob property container stored in a context property with the name of a grob.

Function: make-grob-property-override a b c

Make a Music expression that overrides gprop to val in grob. This is a \temporary \override, making it possible to \revert to any previous value afterwards.

Function: make-grob-property-revert a b

Revert the grob property gprop for grob.

Function: make-grob-property-set a b c

Make a Music expression that overrides a gprop to val in grob. Does a pop first, i.e., this is not a \temporary \override.

Function: make-harmonic a

Convert music variable mus to harmonics.

Function: make-line-stencil a b c d e

Make a line stencil of given line width and set its extents accordingly.

Function: ly:make-listener a

This is a compatibility wrapper for creating a ‘listener’ for use with ly:add-listener from a callback taking a single argument. Since listeners are equivalent to callbacks, this is no longer needed.

Function: make-modal-inverter a b c

Wrapper function for inverter-factory.

Function: make-modal-transposer a b c

Wrapper function for transposer-factory.

Function: ly:make-moment m g gn gd

Create a moment with rational main timing m, and optional grace timing g.

A moment is a point in musical time. It consists of a pair of rationals (m, g), where m is the timing for the main notes, and g the timing for grace notes. In absence of grace notes, g is zero.

For compatibility reasons, it is possible to write two numbers specifying numerator and denominator instead of the rationals. These forms cannot be mixed, and the two-argument form is disambiguated by the sign of the second argument: if it is positive, it can only be a denominator and not a grace timing.

Function: ly:make-music props

Make a C++ Music object and initialize it with props.

This function is for internal use and is only called by make-music, which is the preferred interface for creating music objects.

Function: make-music a rest …

Create a music object of given name, and set its properties according to music-properties, a list of alternating property symbols and values. Example:

(make-music 'OverrideProperty
            'symbol 'Stem
            'grob-property 'thickness
            'grob-value (* 2 1.5))

Instead of a successive symbol and value, an entry in the list may also be an alist or a music object in which case its elements, respectively its mutable property list (properties not inherent to the type of the music object), are taken.

The argument list will be interpreted left to right, so later entries override earlier ones.

Function: ly:make-music-function signature func

Make a function to process music, to be used for the parser. func is the function, and signature describes its arguments. signature’s cdr is a list containing either ly:music? predicates or other type predicates. Its car is the syntax function to call.

Function: ly:make-music-relative! music pitch

Make music relative to pitch, return final pitch.

Function: ly:make-output-def

Make an output definition.

Function: make-oval-stencil a b c d

Make an oval from two Bézier curves, of x radius x-radius, y radius y-radius, and thickness thickness with fill defined by fill.

Function: ly:make-page-label-marker label

Return page marker with label label.

Function: ly:make-page-permission-marker symbol permission

Return page marker with page breaking and turning permissions.

Function: ly:make-pango-description-string chain size

Make a PangoFontDescription string for the property alist chain at size size.

Function: ly:make-paper-outputter port alist default-callback

Create an outputter dumping to port. alist should map symbols to procedures. See file ‘output-ps.scm’ for an example. If default-callback is given, it is called for unsupported expressions.

Function: make-part-combine-context-changes a b

Generate a sequence of part combiner context changes from a split list.

Function: make-part-combine-marks a b

Generate a sequence of part combiner events from a split list.

Function: make-partial-ellipse-stencil a b c d e f g

Create an elliptical arc. x-radius is the x radius of the arc. y-radius is the y radius of the arc. start-angle is the starting angle of the arc (in degrees). end-angle is the ending angle of the arc (in degrees). thick is the thickness of the line. connect is a boolean flag indicating whether the end should be connected to the start by a line. fill is a boolean flag indicating whether the shape should be filled.

Function: make-path-stencil _ _ _ _ _ #:line-cap-style line-cap-style #:line-join-style line-join-style

Make a stencil based on the path described by the list path, with thickness thickness, and scaled by x-scale in the x direction and y-scale in the y direction (the difference with scaling the resulting stencil using ly:stencil-scale is that this scaling does not change the thickness). fill is a boolean argument that specifies whether the path should be filled. Valid path commands are

moveto rmoveto lineto rlineto curveto rcurveto closepath

and their standard SVG single-letter equivalents

M m L l C c Z z
Macro: make-performer

Like make-translator, but create a performer, i.e., the resulting translator is only run in MIDI and ignored in layout output. Scheme performers do not support acknowledgers and process-acknowledged.

Function: ly:make-pitch octave note alter

Make a pitch. octave is specified by an integer, zero for the octave containing middle C. note is a number indexing the global default scale, with 0 corresponding to pitch C and 6 usually corresponding to pitch B. Optional alter is a rational number of 200-cent whole tones for alteration.

Function: ly:make-prob type init rest

Create a Prob object.

Macro: make-relative

The list of pitch or music variables in variables is used as a sequence for creating relativable music from music.

When the constructed music is used outside of \relative, it just reflects plugging in the variables into music.

The action inside of \relative, however, is determined by first relativizing the surrogate reference with the variables plugged in and then using the variables relativized as a side effect of relativizing reference for evaluating music.

Since pitches don’t have the object identity required for tracing the effect of the reference call, they are replaced only for the purpose of evaluating reference with simple pitched note events.

The surrogate reference expression has to be written with that in mind. In addition, it must not contain copies of music that is supposed to be relativized but rather the originals. This includes the pitch expressions. As a rule, inside of #{…#} variables must only be introduced using #, never via the copying construct $. The reference expression will usually just be a sequential or chord expression naming all variables in sequence, implying that following music will be relativized according to the resulting pitch of the last or first variable, respectively.

Since the usual purpose is to create more complex music from general arguments and since music expression parts must not occur more than once, one does generally need to use copying operators in the replacement expression music when using an argument more than once there. Using an argument more than once in reference, in contrast, does not make sense.

There is another fine point to mind: music must only contain freshly constructed elements or copied constructs. This will be the case anyway for regular LilyPond code inside of #{…#}, but any other elements (apart from the variables themselves which are already copied) must be created or copied as well.

The reason is that it is usually permitted to change music in-place as long as one does a ly:music-deep-copy on it, and such a copy of the whole resulting expression will not be able to copy variables/values inside of closures where the information for relativization is being stored.

Function: make-repeat a b c d

Create a repeat music expression, with all properties initialized properly.

Function: ly:make-rotation angle center

Make a transform rotating by angle in degrees. If center is given as a pair of coordinates, it is the center of the rotation, otherwise the rotation is around (0, 0).

Function: ly:make-scale steps

Create a scale. The argument is a vector of rational numbers, each of which represents the number of 200-cent tones of a pitch above the tonic.

Function: ly:make-scaling scale scaley

Create a scaling transform from argument scale and optionally scaley. When both arguments are given, they must be real and give the scale in x and y direction. If only scale is given, it may also be complex to indicate a scaled rotation in the manner of complex number rotations, or a pair of reals for specifying different scales in x and y direction like with the first calling convention.

Function: ly:make-score music

Return score with music encapsulated in it.

Function: make-semitone->pitch a

Convert pitches, an unordered list of note values covering (after disregarding octaves) all absolute pitches in need of conversion, into a function converting semitone numbers (absolute pitch missing enharmonic information) back into note values.

For a key signature without accidentals

c cis d es e f fis g gis a bes b

might be a good choice, covering Bb major to A major and their parallel keys, and melodic/harmonic C minor to A minor.

Function: ly:make-skyline segments axis direction

Create a new skyline from a list of segments. A skyline is an object representing an outline along a ‘horizon axis’, much like a city skyline. The argument segments is a list of segments. A segment has the form '((x1 . y1) . (x2 . y2)). The resulting skyline, viewed on the given axis, has a builing joining these two points for each segment. x1, y1, x2, y2 may be infinite. The buildings can be given in any order, and overlap.

Function: ly:make-spring ideal min-dist

Make a spring. ideal is the ideal distance of the spring, and min-dist is the minimum distance.

Function: ly:make-stencil expr xext yext

Stencils are device independent output expressions. They carry two pieces of information:

  1. A specification of how to print this object. This specification is processed by the output backends, for example ‘scm/output-ps.scm’.
  2. The vertical and horizontal extents of the object, given as pairs. If an extent is unspecified (or if you use empty-interval as its value), it is taken to be empty.
Function: make-stencil-boxer a b c

Return function that adds a box around the grob passed as argument.

Function: make-stencil-circler a b c

Return function that adds a circle around the grob passed as argument.

Function: ly:make-stream-event cl proplist

Create a stream event of class cl with the given mutable property list.

Function: make-tmpfile a

Return a temporary file (as a Scheme port). If dir is #f, a file in the directory given by the environment variable $TMPDIR is created.

Function: ly:make-transform xx yx xy yy x0 y0

Create a transform. Without options, it is the identity transform. Given four arguments xx, yx, xy, and yy, it is a linear transform. Given six arguments (with x0 and y0 last), it is an affine transform.

Transforms can be called as functions on other transforms (concatening them) or on points given either as complex number or real number pair. See also ly:make-rotation, ly:make-scaling, and ly:make-translation.

Function: ly:make-translation x y

Make a transform translating by x and y. If only x is given, it can also be a complex number or a pair of numbers indicating the offset to use.

Macro: make-translator

Helper macro for creating Scheme translators usable in both ‘\midi’ and ‘\layout’.

The usual form for a translator is an association list (or alist) mapping symbols to either anonymous functions or to another such alist.

make-translator accepts forms where the first element is either an argument list starting with the respective symbol, followed by the function body (comparable to the way define is used for defining functions), or a single symbol followed by subordinate forms in the same manner. You can also just make an alist pair literally (the ‘car’ is quoted automatically) as long as the unevaluated ‘cdr’ is not a pair. This is useful if you already have defined your engraver functions separately.

Symbols mapping to a function would be initialize, start-translation-timestep, pre-process-music, process-music, stop-translation-timestep, and finalize. Symbols mapping to another alist specified in the same manner are listeners with the subordinate symbols being event classes.

A template for writing a translator with all methods is:

(lambda (context)
  (let (local-variables ...)
    (make-translator
     ((initialize translator)
      ...)
     ((start-translation-timestep translator)
      ...)
     (listeners
      ((event-class-1 translator event)
       ...)
      ((event-class-2 translator event #:once)
       ...))
     ((process-music translator)
      ...)
     (acknowledgers
      ((grob-interface-1 translator grob source-translator)
       ...)
      ((grob-interface-2 translator grob source-translator)
       ...))
     ((process-acknowledged translator)
      ...)
     ((stop-translation-timestep translator)
      ...)
     ((finalize translator)
      ...))))

This can be used as the argument to \consists.

For listeners, a special feature is available: the argument list of a listener can be terminated with the keyword #:once. This makes for a listener that is only ever triggered once per time step. If it receives several events in the same time step, it emits a warning, except if they are all equal (where equality is checked recursively, with equal?).

Function: make-transparent-box-stencil a b

Make a transparent box.

Function: ly:make-unpure-pure-container unpure pure

Make an unpure-pure container. unpure should be an unpure expression, and pure should be a pure expression. If pure is omitted, the value of unpure will be used twice, except that a callback is given two extra arguments that are ignored for the sake of pure calculations.

Function: map-selected-alist-keys a b c

Return alist with function applied to all of the values in list keys. Example:

(map-selected-alist-keys - '(a b) '((a . 1) (b . -2) (c . 3) (d . 4)))
   ⇒ ((a . -1) (b . 2) (c . 3) (d . 4))
Function: map-some-music a b

Walk through music, transform all elements calling map? and only recurse if this returns #f. elements or articulations that are not music expressions are discarded: this allows some amount of filtering.

map-some-music may overwrite the original music.

Function: marked-up-headfoot a b

Read variables what-odd and what-even from the page’s layout. Interpret either of them as markup, with properties reflecting the variables in the page’s layout and header modules.

Function: marked-up-title a

Read variables what-odd and what-even from the page’s layout. Interpret either of them as markup, with properties reflecting the variables in the page’s layout and header modules.

Macro: markup

The markup macro provides a LilyPond-like syntax for building markups using Scheme keywords, replacing \command with #:command. For example, this:

\markup { foo
          \raise #0.2 \hbracket \bold bar
          \override #'(baseline-skip . 4)
          \bracket \column { baz bazr bla }
}

translates to this:

(markup "foo"
        #:raise 0.2 #:hbracket #:bold "bar"
        #:override '(baseline-skip . 4)
        #:bracket #:column ("baz" "bazr" "bla"))
Function: markup->string _ #:layout layout #:props props

Convert a markup or markup list to an approximate string representation. This is useful for, e.g., PDF metadata and MIDI markers.

The optional named layout and props argument are an output definition and a property alist chain, like the ones that are used when interpreting markups.

Function: markup-command-list? a

Check whether x is a markup command list, i.e., a list composed of a markup list function and its arguments.

Function: markup-default-to-string-method a b rest …

The default markup->string handler for markups, used when markup->string encounters a markup that has no special as-string expression defined. This applies markup->string on all markup arguments and joins the results, separating them with spaces.

Macro: markup-lambda

Defines and returns an anonymous markup command. Other than not registering the markup command, this is identical to define-markup-command.

Function: markup-list? a

Return a true value if x is a list of markups or markup command lists.

Macro: markup-list-lambda

Same as markup-lambda but defines a markup list command that, when interpreted, returns a list of stencils instead of a single one.

Function: measure-counter::text a

A number for a measure count. Broken measures are numbered in parentheses. When the counter spans several measures (like with compressed multi-measure rests), it displays a measure range.

Function: mensural-flag a

Mensural flags: Create the flag stencil by loading the glyph from the font. Flags are always aligned with staff lines, so we need to check the end point of the stem: For stems ending on staff lines, use different flags than for notes between staff lines. The idea is that flags are always vertically aligned with the staff lines, regardless of whether the note head is on a staff line or between two staff lines. In other words, the inner end of a flag always touches a staff line.

Function: ly:message str rest

A Scheme callable function to issue the message str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: middle-broken-spanner? a

Is spanner broken and among the middle broken pieces (i.e., neither the first nor the last)?

Function: midi-program a

Return the program of the instrument.

Function: ly:minimal-breaking paper-book

Break (pages and lines) the Paper_book object paper-book without looking for optimal spacing: stack as many lines on a page before moving to the next one.

Function: ly:mm num

num mm.

Function: mmrest-of-length a

Create a multi-measure rest of exactly the same length as mus.

Function: modern-straight-flag a

Modern straight flag style (for composers like Stockhausen, Boulez, etc.). The angles are 18 and 22 degrees and thus smaller than for the ancient style of Bach, etc.

Function: ly:module->alist mod

Dump the contents of module mod as an alist.

Function: ly:module-copy dest src

Copy all bindings from module src into dest.

Function: ly:modules-lookup modules sym def

Look up sym in the list modules, returning the first occurrence. If not found, return def or #f if def isn’t specified.

Function: ly:moment? x

Is x a smob of class Moment?

Function: ly:moment<? a b

Compare two moments.

Function: ly:moment-add a b

Add two moments.

Function: ly:moment-div a b

Divide two moments.

Function: ly:moment-grace mom

Extract grace timing as a rational number from mom.

Function: ly:moment-grace-denominator mom

Extract denominator from grace timing.

Function: ly:moment-grace-numerator mom

Extract numerator from grace timing.

Function: ly:moment-main mom

Extract main timing as a rational number from mom.

Function: ly:moment-main-denominator mom

Extract denominator from main timing.

Function: ly:moment-main-numerator mom

Extract numerator from main timing.

Function: ly:moment-mod a b

Modulo of two moments.

Function: ly:moment-mul a b

Multiply two moments.

Function: ly:moment-sub a b

Subtract two moments.

Function: ly:music? obj

Is obj a Music object?

Function: music->make-music a

Generate an expression that, once evaluated, may return an object equivalent to obj, that is, for a music expression, a (make-music ...) form.

Function: music-clone a rest …

Clone music and set properties according to music-properties, a list of alternating property symbols and values:

(music-clone start-span 'span-direction STOP)

Only properties that are not overridden by music-properties are actually fully cloned.

Function: ly:music-compress a b

Compress mus by scale.

Function: ly:music-deep-copy m origin

Copy m and all sub expressions of m. m may be an arbitrary type; cons cells and music are copied recursively. If origin is given, it is used as the origin for one level of music by calling ly:set-origin! on the copy.

Function: ly:music-duration-compress mus fact

Compress mus by factor fact, which is a Moment.

Function: ly:music-duration-length mus

Extract the duration field from mus and return the length.

Function: music-filter a b

Filter out music expressions that do not satisfy pred?.

Function: ly:music-function? x

Is x a smob of class Music_function?

Function: ly:music-function-extract x

Return the Scheme function inside x.

Function: ly:music-function-signature x

Return the function signature inside x.

Function: music-is-of-type? a b

Does mus belong to the music class type?

Function: ly:music-length mus

Get the length of music expression mus and return it as a Moment object.

Function: ly:music-list? lst

Is lst a list of music objects?

Function: music-map a b

Apply function to music and all of the music it contains.

First it recurses over the children, then the function is applied to music.

Function: ly:music-mutable-properties mus

Return an alist containing the mutable properties of mus. The immutable properties are not available, since they are constant and initialized by the make-music function.

Function: ly:music-output? x

Is x a smob of class Music_output?

Function: music-pitches a

Return a list of all pitches from music.

Function: ly:music-property mus sym val

Return the value for property sym of music expression mus. If no value is found, return val or '() if val is not specified.

Function: music-selective-filter a b c

Recursively filter out music expressions that do not satisfy pred?, but refrain from filtering the subexpressions of music that does not satisfy descend?.

Function: music-selective-map a b c

Apply function recursively to music, but refrain from mapping subexpressions of music that does not satisfy descend?.

Function: music-separator? a

Is m a separator?

Function: ly:music-set-property! mus sym val

Set property sym in music expression mus to val.

Function: ly:music-start mus

Get the start of music expression mus and return it as a Moment object.

Function: ly:music-transpose m p

Transpose m such that central C is mapped to p. Return m.

Function: music-type-predicate a

Return a predicate function that can be used for checking music to have one of the types listed in types.

Function: neo-modern-accidental-rule a b c

An accidental rule that typesets an accidental if it differs from the key signature and does not directly follow a note on the same staff line. This rule should not be used alone because it does neither look at bar lines nor different accidentals at the same note name.

Function: no-flag a

No flag: Simply return empty stencil.

Function: ly:non-fatal-error str rest

A Scheme callable function to issue the error str. The error is formatted with format; rest holds the formatting arguments (if any). When using this function, some way of signalling the error should be employed in order for the compilation to eventually result in a nonzero return code.

Function: normal-flag a

Create a default flag.

Function: not-first-broken-spanner? a

Is spanner broken and not the first of its broken siblings? The name is read “(not first) and broken”.

Function: not-last-broken-spanner? a

Is spanner broken and not the last of its broken siblings? The name is read “(not last) and broken”.

Function: ly:note-column-accidentals note-column

Return the AccidentalPlacement grob from note-column if any, or SCM_EOL otherwise.

Function: ly:note-column-dot-column note-column

Return the DotColumn grob from note-column if any, or SCM_EOL otherwise.

Function: ly:note-extra-source-file filename parser

Register a file, e.g., an image file, as being needed to compile the current file. This is used for the -dembed-source-code option. A parser may optionally be specified.

Function: ly:note-head::stem-attachment font-metric glyph-name direction

Get attachment in font-metric for attaching a stem to notehead glyph-name in the direction direction (default UP).

Function: note-name->markup a b

Return pitch markup for pitch, including accidentals printed as glyphs. If lowercase? is set to false, the note names are capitalized.

Function: note-name->string a rest …

Return pitch string for pitch, without accidentals or octaves. Current input language is used for pitch names, except if an other language is specified.

Function: note-to-cluster a

Replace NoteEvents by ClusterNoteEvents.

Function: ly:number->string s

Convert s to a string without generating many decimals.

Function: number-format a b rest …

Print num according to the requested number-type. Choices include arabic, custom, roman-ij-lower, roman-ij-upper, roman-lower (the default), and roman-upper.

For custom, custom-format must be present; it gets applied to num.

Function: offset-fret a b

Add fret-offset to each fret indication in diagram-definition and return the resulting verbose fret-diagram-definition.

Function: offsetter a b

Apply offsets to the default values of property of grob. Offsets are restricted to immutable properties and values of type number, number-pair, or number-pair-list.

Function: old-straight-flag a

Old straight flag style (for composers like Bach). The angles of the flags are both 45 degrees.

Function: ly:one-line-auto-height-breaking paper-book

Put each score on a single line, and put each line on its own page. Modify the paper-width setting so that every page is wider than the widest line. Modify the paper-height setting to fit the height of the tallest line.

Function: ly:one-line-breaking paper-book

Put each score on a single line, and put each line on its own page. Modify the paper-width setting so that every page is wider than the widest line.

Function: ly:one-page-breaking paper-book

Put each score on a single page. The paper-height settings are modified so each score fits on one page, and the height of the page matches the height of the full score.

Function: ly:optimal-breaking paper-book

Optimally break (pages and lines) the Paper_book object paper-book to minimize badness for both vertical and horizontal spacing.

Function: ly:option-usage port internal

Print ly:set-option usage. Optional port argument for the destination defaults to current output port. Specify internal to get doc for internal options.

Function: ly:otf->cff otf-file-name idx

Convert the contents of an OTF file to a CFF file, returning it as a string. The optional idx argument is useful for OpenType/CFF collections (OTC) only; it specifies the font index within the OTC. The default value of idx is 0.

Function: ly:otf-font? font

Is font an OpenType font?

Function: ly:otf-font-glyph-info font glyph

Given the font metric font of an OpenType font, return the information about named glyph glyph (a string).

Function: ly:otf-font-table-data font tag

Extract a table tag from font. Return empty string for non-existent tag.

Function: ly:otf-glyph-count font

Return the number of glyphs in font.

Function: ly:otf-glyph-list font

Return a list of glyph names for font.

Function: ly:output-def? x

Is x a smob of class Output_def?

Function: ly:output-def-clone def

Clone output definition def.

Function: ly:output-def-lookup def sym val

Return the value of sym in output definition def (e.g., \paper). If no value is found, return val or '() if val is undefined.

Function: ly:output-def-parent output-def default-value

Return the parent output definition of output-def, or default-value if output-def has no parent. default-value is optional, and defaults to '().

Function: ly:output-def-scope def

Return the variable scope inside def.

Function: ly:output-def-set-variable! def sym val

Set an output definition def variable sym to val.

Function: ly:output-description output-def

Return the description of translators in output-def.

Function: ly:output-find-context-def output-def context-name

Return an alist of all context defs (matching context-name if given) in output-def.

Function: output-module? a

Return #t if module belongs to an output module usually carrying context definitions (\midi or \layout).

Function: ly:outputter-close outputter

Close port of outputter.

Function: ly:outputter-dump-stencil outputter stencil

Dump stencil expr onto outputter.

Function: ly:outputter-dump-string outputter str

Dump str onto outputter.

Function: ly:outputter-output-scheme outputter expr

Output expr to the paper outputter.

Function: ly:outputter-port outputter

Return output port for outputter.

Function: oval-stencil a b c d

Add an oval around stencil, padded by the padding pair, producing a new stencil.

Function: override-head-style a b

Override style for heads to style.

Function: override-time-signature-setting a b

Override the time signature settings for the context in time-signature, with the new setting alist setting.

Function: ly:page-marker? x

Is x a smob of class Page_marker?

Function: ly:page-turn-breaking paper-book

Optimally break (pages and lines) the Paper_book object paper-book such that page turns only happen in specified places, returning its pages.

Function: ly:pango-font? f

Is f a Pango font?

Function: ly:pango-font-physical-fonts f

Return alist of (ps-name file-name font-index) lists for Pango font f.

Function: pango-pf-file-name a

Return the file name of the Pango physical font pango-pf.

Function: pango-pf-font-name a

Return the font name of the Pango physical font pango-pf.

Function: pango-pf-fontindex a

Return the font index of the Pango physical font pango-pf.

Function: ly:paper-book? x

Is x a smob of class Paper_book?

Function: ly:paper-book-header pb

Return the header definition (\header) in Paper_book object pb.

Function: ly:paper-book-pages pb

Return pages in Paper_book object pb.

Function: ly:paper-book-paper pb

Return the paper output definition (\paper) in Paper_book object pb.

Function: ly:paper-book-performances pb

Return performances in Paper_book object pb.

Function: ly:paper-book-scopes pb

Return scopes in Paper_book object pb.

Function: ly:paper-book-systems pb

Return systems in Paper_book object pb.

Function: ly:paper-column::break-align-width col align-syms

col should be a non-musical paper-column. This function determines the horizontal extent of a break align group contained in this column, relative to the system. The break align group is searched according to align-sym, which is either a break align symbol (see the break-align-symbol property), or a list of such symbols. For example,

(ly:paper-column::break-align-width col '(key-signature staff-bar))

tries to find a BreakAlignGroup of key signatures, but falls back on bar lines if there are no key signatures or if the extent of the BreakAlignGroup containing them is empty (for example, if they are omitted).

The special symbol break-alignment means the combined extent of all items in the paper column. It is useful as the last element of the list, for a catch-all fallback.

This function never returns an empty interval. If no matching group is found or the group has an empty extent, it returns a point interval at the coordinate of the column relative to the system.

Function: ly:paper-column::print

Optional stencil for PaperColumn or NonMusicalPaperColumn. Draws the rank number of each column, its moment in time, a blue arrow showing the ideal distance, and a red arrow showing the minimum distance between columns.

Function: ly:paper-fonts def

Return a list containing the fonts from output definition def (e.g., \paper).

Function: ly:paper-get-font def chain

Find a font metric in output definition def satisfying the font qualifiers in alist chain chain, and return it. (An alist chain is a list of alists, containing grob properties.)

Function: ly:paper-get-number def sym

Return the value of variable sym in output definition def as a double.

Function: ly:paper-outputscale def

Return the output-scale for output definition def.

Function: ly:paper-score-paper-systems paper-score

Return vector of paper_system objects from paper-score.

Function: ly:paper-system? obj

Is obj a C++ Prob object of type paper-system?

Function: ly:paper-system-minimum-distance sys1 sys2

Measure the minimum distance between two paper system Probs sys1 and sys2, using their stored skylines if possible and falling back to their extents otherwise.

Function: parenthesize-stencil a b c d e

Add parentheses around stencil, returning a new stencil.

Function: ly:parse-file name

Parse a single .ly file. Upon failure, throw ly-file-failed key.

Function: ly:parse-init name

Parse the init file name.

Function: ly:parse-string-expression parser-smob ly-code filename line

Parse the string ly-code with parser-smob. Return the contained music expression. filename and line are optional source indicators.

Function: parse-terse-string a

Parse a fret-diagram-terse definition string terse-definition and return a marking list, which can be used with a fretboard grob.

Function: ly:parsed-undead-list!

Return the list of objects that have been found alive but should have been dead, and clear that list.

Function: ly:parser-clear-error parser

Clear error flag for parser, defaulting to current parser.

Function: ly:parser-clone closures location

Return a clone of current parser. An association list of port positions to closures can be specified in closures in order to have $ and # interpreted in their original lexical environment. If location is a valid location, it becomes the source of all music expressions inside.

Function: ly:parser-define! symbol val

Bind symbol to val in current parser’s module.

Function: ly:parser-error msg input

Display an error message and make current parser fail. Without a current parser, trigger an ordinary error.

Function: ly:parser-has-error? parser

Does parser (defaulting to current parser) have an error flag?

Function: ly:parser-include-string ly-code

Include the string ly-code into the input stream for current parser. Can only be used in immediate Scheme expressions ($ instead of #).

Function: ly:parser-lookup symbol

Look up symbol in current parser’s module. Return '() if not defined.

Function: ly:parser-output-name parser

Return the base name of the output file. If parser is left off, use currently active parser.

Function: ly:parser-parse-string parser-smob ly-code

Parse the string ly-code with parser-smob. Upon failure, throw ly-file-failed key.

Function: ly:parser-set-note-names names

Replace current note names in parser. names is an alist of symbols. This only has effect if the current mode is notes.

Function: percussion? a

Return #t if the instrument should use MIDI channel 9.

Function: ly:perform-text-replacements props input-string

A string transformer to perform text replacements using the replacement-alist from the property alist chain props.

Function: ly:performance-headers performance

Return the list of headers with the innermost first.

Function: ly:performance-write performance filename name

Write performance to filename storing name as the name of the performance in the file metadata.

Function: ly:pitch? x

Is x a smob of class Pitch?

Function: ly:pitch<? p1 p2

Is p1 lexicographically smaller than p2?

Function: ly:pitch-alteration pp

Extract the alteration from pitch pp.

Function: ly:pitch-diff pitch root

Return pitch delta such that root transposed by delta equals pitch.

Function: ly:pitch-negate p

Negate pitch p.

Function: ly:pitch-notename pp

Extract the note name from pitch pp.

Function: ly:pitch-octave pp

Extract the octave from pitch pp.

Function: ly:pitch-quartertones pp

Calculate the number of quarter tones of pitch pp from middle C.

Function: ly:pitch-semitones pp

Calculate the number of semitones of pitch pp from middle C.

Function: ly:pitch-steps p

Number of steps counted from middle C of the pitch p.

Function: ly:pitch-tones pp

Calculate the number of tones of pitch pp from middle C as a rational number.

Function: ly:pitch-transpose p delta

Transpose pitch p by the amount delta, where delta is relative to middle C.

Function: ly:pointer-group-interface::add-grob grob sym grob-element

Add grob-element to grob’s sym grob array.

Function: polar->rectangular a b

Return polar coordinates (radius, angle-in-degrees) as rectangular coordinates (x-length . y-length).

Function: ly:position-on-line? sg spos

Return whether spos is on a line of the staff associated with the grob sg (even on an extender line).

Function: prepend-alist-chain a b c

Convenience to make a new alist chain from chain by prepending a binding of key to val. This is similar to acons, for alist chains (lists of alists).

Function: ly:prob? x

Is x a smob of class Prob?

Function: ly:prob-immutable-properties prob

Retrieve an alist of immutable properties.

Function: ly:prob-mutable-properties prob

Retrieve an alist of mutable properties.

Function: ly:prob-property prob sym val

Return the value for property sym of Prob object prob. If no value is found, return val or '() if val is not specified.

Function: ly:prob-property? obj sym

Is boolean prop sym of obj set?

Function: ly:prob-set-property! obj sym value

Set property sym of obj to value.

Function: ly:prob-type? obj type

Is obj the specified prob type?

Function: ly:programming-error str rest

A Scheme callable function to issue the internal warning str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: ly:progress str rest

A Scheme callable function to print progress str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: ly:property-lookup-stats sym

Return hash table with a property access corresponding to sym. Choices are prob, grob, and context.

Function: ly:pt num

num printer points.

Function: ly:pure-call data grob start end rest

Convert property data (unpure-pure container or procedure) to value in a pure context defined by grob, start, end, and possibly rest arguments.

Function: pure-chain-offset-callback a b c d

Sometimes, a chained offset callback is unpure and there is no way to write a pure function that estimates its behavior. In this case, we use a pure equivalent that will simply pass the previous calculated offset value.

Function: ly:randomize-rand-seed

Randomize C random generator.

Function: ratio->fret a

Calculate a fret number given ratio for the harmonic.

Function: ratio->pitch a

Calculate a pitch given ratio for the harmonic.

Function: read-lily-expression a b

Read a lilypond music expression enclosed within #{ and #} from port and return the corresponding Scheme music expression. ‘$’ and ‘#’ introduce immediate and normal Scheme forms.

Function: recording-group-emulate a b

Interpret music according to odef, but store all events in a chronological list, similar to the Recording_group_engraver in LilyPond version 2.8 and earlier.

Function: ly:register-stencil-expression symbol

Add symbol as head of a stencil expression.

Function: ly:register-translator creator name description

Register a translator creator (usually a descriptive alist or a function/closure returning one when given a context argument) with the given symbol name and the given description alist.

Function: ly:relative-group-extent elements common axis

Determine the extent of elements relative to common in the axis direction.

Function: remove-grace-property a b c

Remove all sym for grob in context-name.

Function: remove-whitespace a

Remove characters satisfying char-whitespace? from string strg.

Function: ly:rename-file oldname newname

Rename oldname to newname. In contrast to Guile’s rename-file function, this replaces the destination if it already exists. On Windows, fall back to copying the file contents if newname cannot be deleted.

Function: ly:reset-all-fonts

Forget all about previously loaded fonts.

Function: retrieve-glyph-flag a b c d

Load the correct flag glyph from the font.

Function: retrograde-music a

Return music in retrograde (reversed) order.

Function: revert-fontSize a b

Used by \magnifyMusic and \magnifyStaff. Calculate the previous fontSize value (before scaling) by factoring out the magnification factor mag (if func-name is 'magnifyMusic), or by factoring out the context property magnifyStaffValue (if func-name is 'magnifyStaff). Revert the fontSize in the appropriate context accordingly.

With \magnifyMusic, the scaling is reverted after the music block it operates on. \magnifyStaff does not operate on a music block, so the scaling from a previous call (if there is one) is reverted before the new scaling takes effect.

Function: revert-head-style a

Revert style for heads.

Function: revert-props a b c

Used by \magnifyMusic and \magnifyStaff. Revert each prop in props in the appropriate context. func-name is either 'magnifyMusic or 'magnifyStaff. The props list is formatted like:

'((Stem thickness)
  (Slur line-thickness)
  ...)
Function: ly:round-filled-box xext yext blot

Make a Stencil object that prints a black box of dimensions xext, yext and roundness blot.

Function: ly:round-polygon points blot extroversion filled-scm

Make a Stencil object that prints a black polygon with corners at the points defined by points (list of coordinate pairs) and roundness blot. Optional extroversion shifts the outline outward, with the default of 0 keeping the middle of the line just on the polygon.

Function: rounded-box-stencil a b c d

Add a rounded box around stencil, producing a new stencil.

Function: ly:run-translator mus output-def

Process mus according to output-def. An interpretation context is set up, and mus is interpreted with it. The context is returned in its final state.

Function: scale-beam-thickness a

Used by \magnifyMusic. Scaling Beam.beam-thickness exactly to the mag value will not work. This uses two reference values for beam-thickness to determine an acceptable value when scaling, then does the equivalent of a \temporary \override with the new value.

Function: scale-fontSize a b

Used by \magnifyMusic and \magnifyStaff. Look up the current fontSize in the appropriate context and scale it by the magnification factor mag. func-name is either 'magnifyMusic or 'magnifyStaff.

Function: scale-layout a b

Return a clone of paper, scaled by the given scale factor.

Function: scale-props a b c d

Used by \magnifyMusic and \magnifyStaff. For each prop in props, find the current value of the requested prop, scale it by the magnification factor mag, and do the equivalent of a \temporary \override with the new value in the appropriate context. If allowed-to-shrink? is #f, don’t let the new value be less than the current value. func-name is either 'magnifyMusic or 'magnifyStaff. The props list is formatted like:

'((Stem thickness)
  (Slur line-thickness)
  ...)
Function: ly:score? x

Is x a smob of class Score?

Function: ly:score-add-output-def! score def

Add an output definition def to score.

Function: ly:score-embedded-format score layout

Run score through layout (an output definition) scaled to correct output-scale already, returning a list of layout lines.

Function: ly:score-error? score

Was there an error in the score?

Function: ly:score-header score

Return score header.

Function: ly:score-music score

Return score music.

Function: ly:score-output-defs score

All output definitions in a score.

Function: ly:score-set-header! score module

Set the score header.

Function: scorify-music a

Preprocess music.

Function: seconds->moment a b

Return a moment equivalent to s seconds at the current tempo.

Function: select-head-glyph a b

Select a note head glyph string based on note head style style and duration log log.

Function: self-alignment-interface::self-aligned-on-breakable a

Return the X-offset that places grob according to its self-alignment-X over the reference point defined by the break-align-anchor-alignment of a break-aligned item such as a Clef.

Function: sequential-music-to-chord-exceptions a rest …

Transform sequential music seq of type

<<c d e>>-\markup{ foobar }

to (cons cde-pitches foobar-markup), or to (cons de-pitches foobar-markup) if omit-root is given and non-false.

Function: set-accidental-style a rest …

Set accidental style to style. Optionally take a context argument, e.g., 'Staff or 'Voice. The context defaults to Staff, except for piano styles, which use GrandStaff as a context.

Function: ly:set-color-names alist

Define named colors for ly:stencil-in-color. alist has the entries of the format (name . color), where color is a list of length 3 (RGB) or 4 (RGB+alpha).

Function: ly:set-default-scale scale

Set the global default scale. This determines the tuning of pitches with no accidentals or key signatures. The first pitch is C. Alterations are calculated relative to this scale. The number of pitches in this scale determines the number of scale steps that make up an octave. Usually the 7-note major scale.

Function: set-global-staff-size a

Set the default staff size, where sz is thought to be in points.

Function: ly:set-grob-creation-callback cb

Specify a procedure that gets called every time a new grob is created. The callback receives as arguments the grob that was created, the name of the C++ source file that caused the grob to be created, and the corresponding line number in the C++ source file. Call with #f as argument to unset the callback.

Function: ly:set-grob-modification-callback cb

Specify a procedure that gets called every time LilyPond modifies a grob property. The callback receives as arguments the grob that is being modified, the name of the C++ file in which the modification was requested, the line number in the C++ file in which the modification was requested, the name of the function in which the modification was requested, the property to be changed, and the new value for the property. Call with #f as argument to unset the callback.

Function: ly:set-middle-C! context

Set the middleCPosition variable in context based on the variables middleCClefPosition and middleCOffset.

Function: set-mus-properties! a b

Set all of alist as properties of m.

Function: ly:set-option var val

Set a program option.

Function: ly:set-origin! m origin

Set the origin given in origin to m. m is typically a music expression or a list of music. List structures are searched recursively, but recursion stops at the changed music expressions themselves.

origin is generally of type ly:input-location?, defaulting to (*location*). Other valid values for origin are a music expression which is then used as the source of location information, or #f or '() in which case no action is performed. The return value is m itself.

Function: set-output-property a b c

Usage example: \applyoutput #(set-output-property 'Clef 'extra-offset '(0 . 1))

Function: ly:set-property-cache-callback cb

Specify a procedure that gets called whenever LilyPond calculates a callback function and caches the result. The callback receives as arguments the grob whose property it is, the name of the property, the name of the callback that calculated the property, and the new (cached) value of the property. Call with #f as argument to unset the callback.

Function: shift-one-duration-log a b c

Add shift to duration-log of 'duration in music and optionally dot to any note encountered. The number of dots in the shifted music may not be less than zero.

Function: shift-right-at-line-begin a

Shift an item to the right, but only at the start of the line.

Function: shift-semitone->pitch a b

Given a function semitone->pitch converting a semitone number into a note value for a lookup table created in relation to C, returns a corresponding function in relation to key. The note values returned by this function differ only enharmonically from the original semitone->pitch function.

Function: skip->rest a

Replace mus by RestEvent of the same duration if it is a SkipEvent. Useful for extracting parts from crowded scores.

Function: skip-of-length a

Create a skip of exactly the same length as mus.

Function: skip-of-moment-span a b

Make skip music fitting between start-moment and end-moment. The grace part of end-moment matters only if start-moment and end-mom have the same main part.

Function: ly:skyline? x

Is x a smob of class Skyline?

Function: ly:skyline->points skyline horizon-axis

Return a list of points from the given skyline, if viewed with horizon-axis as ‘horizon axis’. Joining the points with a line draws the outline of the skyline.

Function: ly:skyline-distance skyline other-skyline horizon-padding

Compute the distance between the two skylines, padding by horizon-padding if provided.

Function: ly:skyline-empty? sky

Return whether skyline sky is empty.

Function: ly:skyline-height skyline x

Return the height of skyline at point x.

Function: ly:skyline-max-height skyline

Return the maximum height found in skyline.

Function: ly:skyline-max-height-position skyline

Return the position at which skyline reaches its maximum height.

Function: ly:skyline-merge skyline1 skyline2

Merge the two given skylines.

Function: ly:skyline-pad skyline horizon-padding

Return a version of skyline padded by horizon-padding along the horizon.

Function: ly:skyline-touching-point skyline other-skyline horizon-padding

Get the point where skyline and other-skyline (having opposite directions) reach their minimum distance. If horizon-padding is provided, one skyline is padded with it first.

Function: ly:skylines-for-stencil stencil axis

Return a pair of skylines representing the outline of stencil. axis is the ‘horizon axis’ (i.e., this function gives skylines suitable for the vertical-skylines property if axis is X, and for horizontal-skylines if axis is Y).

Function: ly:smob-protects

Return LilyPond’s internal smob protection list.

Function: ly:solve-spring-rod-problem springs rods length ragged

Solve a spring and rod problem for count objects that are connected by count-1 springs, and an arbitrary number of rods. count is implicitly given by springs and rods. The springs argument has the format (ideal, inverse_hook) and rods is of the form (idx1, idx2, distance).

length is a number, ragged a boolean.

The function returns a list containing the force (positive for stretching, negative for compressing and #f for non-satisfied constraints) followed by spring-count+1 positions of the objects.

Function: ly:source-file? x

Is x a smob of class Source_file?

Function: ly:source-files parser-smob

Return a list of input files that have been opened up to here, including the files that have been closed already. A parser, parser-smob, may optionally be specified.

Function: ly:span-bar::before-line-breaking a

A dummy callback that kills the Grob grob if it contains no elements.

Function: ly:span-bar::calc-anchor a

Calculate the anchor position of the SpanBar. The anchor is used for the correct placement of bar numbers, etc.

Function: ly:span-bar::calc-glyph-name a

Return the 'glyph-name of the corresponding BarLine grob. The corresponding SpanBar glyph is computed within span-bar::compound-bar-line.

Function: span-bar::compound-bar-line a b c

Build the stencil of the span bar.

Function: ly:span-bar::print a

The print routine for span bars.

Function: ly:span-bar::width a

Compute the width of the SpanBar stencil.

Function: Span_stem_engraver a

Connect cross-staff stems to the stems above in the system.

Function: ly:spanner? g

Is g a spanner object?

Function: ly:spanner-bound spanner dir def

Get one of the bounds of spanner. dir is -1 for left, and 1 for right. If the spanner does not (yet) have a bound for this direction, return def, or '() if def is not specified.

Function: ly:spanner-broken-into spanner

Return broken-into list for spanner.

Function: ly:spanner-set-bound! spanner dir item

Set grob item as bound in direction dir for spanner.

Function: ly:spawn command rest

Simple Scheme interface to the GLib function g_spawn_sync. If an error occurs, format it with format and rest.

Function: split-list-by-separator a b

Split lst at each element that satisfies pred, and return the parts (with the separators removed) as a list of lists. Example:

(split-list-by-separator '(a 0 b c 1 d) number?)
   ⇒ ((a) (b c) (d))
Function: ly:spring? x

Is x a smob of class Spring?

Function: ly:spring-set-inverse-compress-strength! spring strength

Set the inverse compress strength of spring.

Function: ly:spring-set-inverse-stretch-strength! spring strength

Set the inverse stretch strength of spring.

Function: stack-lines a b c d

Stack stencils vertically with a baseline skip.

Function: stack-stencil-line a b

Adjoin a list of stencils along the x axis, leaving space between the end of each stencil and the beginning of the following stencil. Stencils with empty y extent are not given space before them and don’t avoid overlapping other stencils.

Function: stack-stencils a b c d

Stack stencils stils in direction axis, dir, using padding.

Function: stack-stencils-padding-list a b c d

Stack stencils stils in direction axis, dir, using a list of paddings.

Function: staff-ellipsis::calc-y-extent a

Callback for StaffEllipsis grob, which is used with skipTypesetting.

Function: staff-ellipsis::print a

Callback for StaffEllipsis grob, which is used with skipTypesetting.

Function: ly:staff-symbol-line-thickness grob

Return the current staff line thickness in the staff associated with grob, expressed as a multiple of the current staff space height.

Function: ly:staff-symbol-staff-radius grob

Return the radius of the staff associated with grob.

Function: ly:staff-symbol-staff-space grob

Return the current staff space height in the staff associated with grob, expressed as a multiple of the default height of a staff space in the traditional five-line staff.

Function: ly:stderr-redirect fd-or-file-name mode

Redirect standard error output (stderr) to file descriptor fd if the first parameter is an integer, or to file file-name, opened with mode.

Function: ly:stencil? x

Is x a smob of class Stencil?

Function: ly:stencil-add args

Combine stencils. Takes any number of arguments.

Function: ly:stencil-aligned-to stil axis dir

Align stencil stil using its own extents. dir is a number. -1 and 1 are left and right, respectively. Other values are interpolated (so 0 means the center).

Function: ly:stencil-combine-at-edge first axis direction second padding

Construct a stencil by putting second next to first. axis can be 0 (x axis) or 1 (y axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. first and second may also be '() or #f.

Function: ly:stencil-empty? stil axis

Return whether stil is empty. If an optional axis is supplied, the emptiness check is restricted to that axis.

Function: ly:stencil-expr stil

Return the expression of stencil stil.

Function: ly:stencil-extent stil axis

Return a pair of numbers signifying the extent of stencil stil in axis direction (0 or 1 for x and y axis, respectively).

Function: ly:stencil-in-color stc r g b a

Put stencil stc in a different color. Accepts either three values for r, g, b and an optional value for a, or a single CSS-like string.

Function: ly:stencil-outline stil outline

Return a stencil with the stencil expression (inking) of stencil stil but with outline and dimensions from stencil outline.

Function: ly:stencil-rotate stil angle x y

Return a stencil stil rotated by angle degrees around the relative offset (x, y). E.g., an offset of (-1, 1) rotates the stencil around the left upper corner.

Function: ly:stencil-rotate-absolute stil angle x y

Return a stencil stil rotated by angle degrees around point (x, y), given in absolute coordinates.

Function: ly:stencil-scale stil x y

Scale stencil stil using the horizontal and vertical scaling factors x and optional y (defaulting to x). Negative values flip or mirror stil without changing its origin; this may result in collisions unless it is repositioned.

Function: ly:stencil-stack first axis direction second padding mindist

Construct a stencil by stacking second next to first. axis can be 0 (x axis) or 1 (y axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. first and second may also be '() or #f. As opposed to ly:stencil-combine-at-edge, metrics are suited for successively accumulating lines of stencils. Also, second stencil is drawn last.

If mindist is specified, reference points are placed apart at least by this distance. If either of the stencils is spacing, padding and mindist do not apply.

Function: ly:stencil-translate stil offset

Return a copy of stencil stil but translated by offset (a pair of numbers).

Function: ly:stencil-translate-axis stil amount axis

Return a copy of stencil stil but translated by amount in axis direction.

Function: stencil-true-extent a b

Return the extent of the actual printed ink of stencil on axis.

Function: stencil-whiteout _ [_ [_ [_]]]

White-out a stencil (i.e., add a white background around it).

style, thickness and line-thickness are optional arguments. If set, style determines the shape of the white background. Given 'outline the white background is produced by stencil-whiteout-outline, given 'rounded-box it is produced by stencil-whiteout-box with rounded corners, given other arguments (e.g., 'box) or when unspecified it defaults to stencil-whiteout-box with square corners. If thickness is specified it determines how far, as a multiple of line-thickness, the white background extends past the extents of stencil stil. If thickness has not been specified, an appropriate default is chosen based on style.

Function: stencil-whiteout-box _ [_ [_ [_]]]

White-out a stencil by printing it on top of a white (or color) rectangle.

thickness is how far, as a multiple of line-thickness, the white outline extends past the extents of stencil stil.

Function: stencil-whiteout-outline _ [_ [_ [_ [_]]]]

White-out a stencil by surrounding it with white (or color) around its outline.

This function works by creating a series of white or color stencils radially offset from the original stencil with angles from 0 to 2*pi, at an increment of angle-inc, and with radii from radial-inc to thickness. thickness is how big the white outline is, as a multiple of line-thickness. radial-increments is how many copies of the white stencil we make on our way out to thickness. angle-increments is how many copies of the white stencil we make between 0 and 2*pi.

Function: straight-flag a b c d e f

Create a stencil for a straight flag. flag-thickness and flag-spacing are given in staff spaces, upflag-angle and downflag-angle are given in degrees, and upflag-length and downflag-length are given in staff spaces.

All lengths are scaled according to the font size of the note.

Function: ly:stream-event? obj

Is obj a Stream_event object?

Function: ly:string-percent-encode str

Encode all characters in string str with hexadecimal percent escape sequences, with the following exceptions: characters ‘-./_’ and characters in ranges 0-9, A-Z, and a-z.

Function: ly:string-substitute a b s

Replace string a by string b in string s.

Function: style-note-heads a b c

Set style for all heads in music. Works both inside of and outside of chord construct.

Function: suggest-convert-ly-message a

Internally used when the file has an error, to suggest usage of convert-ly if the \version statement is considered outdated compared to the LilyPond version that is running.

Function: symbol-concatenate rest …

Like string-concatenate, but for symbols.

Function: ly:system-font-load name

Load the OpenType system font ‘name.otf’. Fonts loaded with this command must contain three additional SFNT font tables called LILC, LILF, and LILY, needed for typesetting musical elements. Currently, only the Emmentaler and the Emmentaler-Brace fonts fulfill these requirements.

Note that only ly:font-get-glyph and derived code (like \lookup) can access glyphs from the system fonts; text strings are handled exclusively via the Pango interface.

Function: tag-group-get a

Return the tag group (as a list of symbols) that the given tag symbol belongs to, #f if none.

Function: tags-keep-predicate a

Return a predicate that returns #f for any music that is to be removed by \keepWithTag on the given symbol or list of symbols tags.

Function: tags-remove-predicate a

Return a predicate that returns #f for any music that is to be removed by \removeWithTag on the given symbol or list of symbols tags.

Function: teaching-accidental-rule a b c

An accidental rule that typesets a cautionary accidental if it is included in the key signature and does not directly follow a note on the same staff line.

Function: ly:text-interface::interpret-markup

Convert a text markup into a stencil. Takes three arguments, layout, props, and markup.

layout is a \layout block; it may be obtained from a grob with ly:grob-layout. props is an alist chain, i.e., a list of alists. This is typically obtained with (ly:grob-alist-chain grob (ly:output-def-lookup layout 'text-font-defaults)). markup is the markup text to be processed.

Function: ly:time-signature::print a

Print routine for time signatures.

Function: ly:transform? x

Is x a smob of class Transform?

Function: ly:transform->list transform

Convert a transform matrix to a list of six values. Values are xx, yx, xy, yy, x0, y0.

Function: ly:translate-cpp-warning-scheme str

Translate a string in C++ printf format and modify it to use it for Scheme formatting.

Function: ly:translator? x

Is x a smob of class Translator?

Function: ly:translator-context trans

Return the context of the translator object trans.

Function: ly:translator-description creator

Return an alist of properties of translator definition creator.

Function: ly:translator-group? x

Is x a smob of class Translator_group?

Function: ly:translator-name creator

Return the type name of the translator definition creator. The name is a symbol.

Function: ly:transpose-key-alist l pit

Make a new key alist of l transposed by pitch pit.

Function: ly:ttf->pfa ttf-file-name idx

Convert the contents of a TrueType font file to PostScript Type 42 font, returning it as a string. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:ttf-ps-name ttf-file-name idx

Extract the PostScript name from a TrueType font. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:type1->pfa type1-file-name

Convert the contents of a Type 1 font in PFB format to PFA format. If the file is already in PFA format, pass it through.

Function: unbroken-or-first-broken-spanner? a

Is spanner either unbroken or the first of its broken siblings?

Function: unbroken-or-last-broken-spanner? a

Is spanner either unbroken or the last of its broken siblings?

Function: unbroken-spanner? a

Is spanner unbroken? A spanner has to be broken if it spans more than one system, or if one of its bounds is on the limit of the system. This function returns #f on the clones, but #t on the originals.

Function: unfold-repeats a b

Replace repeats of the types given by types with unfolded repeats. If types is an empty list, repeated-music is taken, unfolding all.

Function: unfold-repeats-fully a

Unfold repeats and expand the resulting unfolded-repeated-music.

Function: uniq-list a

Remove doublets from list lst (i.e., make its elements unique), assuming that it is sorted. Uses equal? for comparisons.

Function: ly:unit

Return the unit used for lengths as a string.

Function: unity-if-multimeasure a b

Given a context and a duration, return 1 if the duration is longer than the measureLength in that context, and #f otherwise. This supports historic use of Completion_heads_engraver to split c1*3 into three whole notes.

Function: ly:unpure-call data grob rest

Convert property data (unpure-pure container or procedure) to value in an unpure context defined by grob and possibly rest arguments.

Function: ly:unpure-pure-container? x

Is x a smob of class Unpure_pure_container?

Function: ly:unpure-pure-container-pure-part pc

Return the pure part of pc.

Function: ly:unpure-pure-container-unpure-part pc

Return the unpure part of pc.

Function: ly:usage

Print usage message.

Function: value-for-spanner-piece a b

Associate a piece of broken spanner grob with an element of list arg.

Function: ly:verbose-output?

Was verbose output requested, i.e., is the log level at least DEBUG?

Function: ly:version

Return the current LilyPond version as a list, e.g., (1 3 127 uu1).

Function: ly:version? a b

Use operator op to compare the currently executed LilyPond version with a given version ver, which is passed as a list of numbers.

Function: voicify-music _ [_]

Recursively split chords that are separated with \\. Optional id can be a list of context ids to use. If numeric, they also indicate a voice type override. If id is just a single number, that’s where numbering starts.

Function: volta-bracket::calc-hook-visibility a

Determine the visibility of the volta bracket end hook, returning #t if no hook should be drawn.

Function: ly:volta-bracket::calc-shorten-pair a

Calculate the shorten-pair values for an ideal placement of the volta brackets relative to the bar lines.

Function: volta-spec-music a b

Add \volta number-list to music.

Function: ly:warning str rest

A Scheme callable function to issue the warning str. The message is formatted with format; rest holds the formatting arguments (if any).

Function: ly:warning-located location str rest

A Scheme callable function to issue the warning str at the specified location in an input file. The message is formatted with format; rest holds the formatting arguments (if any).

Function: ly:wide-char->utf-8 wc

Encode the Unicode codepoint wc, an integer, as UTF-8.

Function: write-me a b

Return x. Display message and write x. Handy for debugging, possibly turned off.


LilyPond – Internals Reference v2.24.3 (stable-branch).