Transforms an EPUB 3 publication into an EPUB 3 publication with audio and/or a braille rendition.
If specified, the document must be a single
metadata
or
package
element. A
prefix
attribute is
allowed on the root element. The metadata will be injected in the EPUB’s package document, possibly
overwriting existing metadata. This works as follows:
meta
elements with a refines
attribute must refine
elements within the metadata document itself. Elements that refine elements in the EPUB’s package
document will be dropped.meta
fields, same element name in case of dc:*
fields) in the provided metadata document are omitted,
together with any meta
elements that refine them.There are a number of fields that result in addional changes in the EPUB (apart from an updated
metadata
section in the package document):
dc:identifier
fields, the first one without a refines
attribute will be used to update the
unique-identifier
attribute on the package document. The dc:identifier
metadata in the content documents can also be
aligned with it. This behavior can be enabled or disabled with the “Update elements based on EPUB metadata” option.dc:title
fields, the
first one can also be used as the title
element in the content documents. This behavior can be
enabled or disabled with the “Update dc:language
field,
it can be used to update the xml:lang
and lang
attributes of the content documents. This
behavior can be enabled or disabled with the “Update ‘lang’ attributes based on metadata” option.Some fields are ignored:
dcterms:modified
field gets updated whenever Pipeline produces an EPUB. As a consequence, any dcterms:modified
fields in the provided metadata document are ignored.You may alternatively use the “mimetype” document if your input is a unzipped/”exploded” version of an EPUB.
If there is exactly one
dc:language
element,
use its value to create xml:lang
and lang
attributes on the root elements of all content
documents (overwriting any existing attributes)
If the “Metadata” option is used to inject new metadata into the EPUB, the resulting metadata is used to generate the attributes.
true
or false
false
Use the primary identifier (provided by the
dc:identifier
element identified by the
unique-identifier
attribute) to create a <meta name='dc:identifier'>
element in all content documents
(overwriting any existing elements with the same name).
If the “Metadata” option is used to inject new metadata into the EPUB, the resulting metadata is used to generate the attributes.
true
or false
false
The TTS log contains a great deal of additional information that is not present in the main job log and that is helpful for troubleshooting. Most of the log entries concern particular chunks of text of the input document.
The default can be changed using the
org.daisy.pipeline.tts.log
property.
true
or false
p:system-property('d:org.daisy.pipeline.tts.log')
true
or false
false
A list of CSS/Sass style sheets to take into account, both for braille transcription (if a braille rendition is requested), and for text-to-speech (if text-to-speech is enabled).
Must be a space separated list of URIs, absolute or relative to the input.
All style sheets are applied at once, but the order in which they are specified has an influence on the cascading order.
If the “Apply author style sheets” option is enabled, author style sheets will be taken into account and will take precedence over any style sheets specified through this option (user style sheets).
When generating the braille rendition, style sheets are interpreted according to braille CSS rules. When performing text-to-speech, they are interpreted as aural CSS.
For info on how to use Sass (Syntactically Awesome StyleSheets) see the Sass manual.
This setting has no effect when text-to-speech is also enabled. In that case sentences are always marked up.
true
or false
false
For sectioning elements that don’t have a heading element, one can be created. The headings are
generated based on the section element’s aria-label
attribute. If the aria-label
attribute is not present, no heading element is generated. When an
aria-label
is used to generate a heading, it is replaced with a
aria-labelledby
attribute that points to the
new heading. The rank of the generated heading matches the depth of the corresponding TOC item in
the navigation document.
true
or false
false
Style sheets, whether they’re user style sheets (specified with the “stylesheet” option) or author style sheets (associated with the source), may have parameters (Sass variables). The “stylesheet-parameters” option, which takes a comma-separated list of key-value pairs enclosed in parenthesis, can be used to set these variables.
For example, if a style sheet uses the Sass variable “foo”:
@if $foo {
/* some style that should only be enabled when "foo" is truthy */
}
you can control that variable with the following parameters list: (foo:true)
.
The syntax is as follows (described in terms of CSS grammar):
query
: feature*
;
feature
: '(' S* IDENT S* [ ':' S* value ]? ')' S*
;
value
: string | integer | IDENT
;
(translator:liblouis)
This will remove any existing media overlays in the EPUB.
true
false
default
default
When sentence detection is enabled, this option may be used to add a class attribute to the span
elements that represent the sentences.
Must be a space separated list of URIs, absolute or relative to the input.
Lexicons can also be attached to the source document, using a ‘link’ element.
PLS lexicons allow you to define custom pronunciations of words. It is meant to help TTS processors deal with ambiguous abbreviations and pronunciation of proper names. When a word is defined in a lexicon, the processor will use the provided pronunciation instead of the default rendering.
The syntax of a PLS lexicon is defined in Pronunciation Lexicon Specification (PLS) Version 1.0, extended with regular expression matching. To enable regular expression matching, add the “regex” attribute, as follows:
<lexicon xmlns="http://www.w3.org/2005/01/pronunciation-lexicon" version="1.0"
alphabet="ipa" xml:lang="en">
<lexeme regex="true">
<grapheme>([0-9]+)-([0-9]+)</grapheme>
<alias>between $1 and $2</alias>
</lexeme>
</lexicon>
The regex feature works only with alias-based substitutions. The regex syntax used is that from XQuery 1.0 and XPath 2.0.
Whether or not the regex attribute is set to “true”, the grapheme matching can be made more accurate by specifying the “positive-lookahead” and “negative-lookahead” attributes:
<lexicon version="1.0" xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
alphabet="ipa" xml:lang="en">
<lexeme>
<grapheme positive-lookahead="[ ]+is">SB</grapheme>
<alias>somebody</alias>
</lexeme>
<lexeme>
<grapheme>SB</grapheme>
<alias>should be</alias>
</lexeme>
<lexeme xml:lang="fr">
<grapheme positive-lookahead="[ ]+[cC]ity">boston</grapheme>
<phoneme>bɔstøn</phoneme>
</lexeme>
</lexicon>
Graphemes with “positive-lookahead” will match if the beginning of what follows matches the “position-lookahead” pattern. Graphemes with “negative-lookahead” will match if the beginning of what follows does not match the “negative-lookahead” pattern. The lookaheads are case-sensitive while the grapheme contents are not.
The lexemes are matched in this order:
Within these categories, lexemes are matched in the same order as they appear in the lexicons.
p:system-property('d:org.daisy.pipeline.tts.default-lexicon')