EPUB 3 Enhancer

Inputs

• Metadata
  Metadata to be included in the EPUB.

  Metadata to be included in the EPUB.

  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:

  • All (valid) fields in the provided metadata document end up in the output EPUB. More than one field with the same property is allowed. 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.
  • Any metadata fields in the input EPUB that have matching fields (same property in case of 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.
  • Metadata fields in the input that do not have any matching fields in the provided metadata document are preserved in the output.

  There are a number of fields that result in addional changes in the EPUB (apart from an updated metadata section in the package document):

  • If the provided metadata document contains one or more 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.
  • If the provided metadata document contains one or more 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
  • If the provided metadata document contains exactly one 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:

  • The dcterms:modified field gets updated whenever Pipeline produces an EPUB. As a consequence, any dcterms:modified fields in the provided metadata document are ignored.
  Media-type:

  • application/xml
  Sequence: yes
• Input EPUB 3
  The EPUB you want to convert.

  The EPUB you want to convert.

  You may alternatively use the “mimetype” document if your input is a unzipped/”exploded” version of an EPUB.

  Media-type:

  • application/epub+zip
  • text/plain
  Sequence: no
• Text-to-speech configuration file
  Configuration file for text-to-speech.

  Configuration file for text-to-speech.

  More details on the configuration file format.

  Media-type:

  • application/vnd.pipeline.tts-config+xml
  Sequence: no

Outputs

• Output EPUB 3
  The output braille file.
  Media-type:

  • text
• TTS log
  Log file with information about text-to-speech process.

Options

• Update 'lang' attributes based on metadata
  Whether to update 'lang' and 'xml:lang' attributes of content documents based on metadata in the package document.

  Whether to update 'lang' and 'xml:lang' attributes of content documents based on metadata in the package document.

  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.

  Possible values: true or false
  Default value: false
• identifier'> elements based on EPUB metadata
  Whether to update <meta name='dc:identifier'> elements of content documents based on metadata in the package document.

  Whether to update elements of content documents based on metadata in the package document.

  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.

  Possible values: true or false
  Default value: false
• Enable TTS log
  Whether or not to make the TTS log available.

  Whether or not to make the TTS log available.

  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.

  Possible values: true or false
  Default value: p:system-property('d:org.daisy.pipeline.tts.log')
• Translate to braille
  Whether to produce a braille rendition.
  Possible values: true or false
  Default value: false
• Style sheets
  A list of CSS/Sass style sheets to take into account.

  A list of CSS/Sass style sheets to take into account.

  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.

  Possible values: <anyURI>
  Default value:
• Perform sentence detection
  Whether to add markup (span elements) for sentences.

  Whether to add markup (span elements) for sentences.

  This setting has no effect when text-to-speech is also enabled. In that case sentences are always marked up.

  Possible values: true or false
  Default value: false
• Ensure headings for all sections
  Whether to generate a heading element for sections that don't have one.

  Whether to generate a heading element for sections that don't have one.

  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.

  Possible values: true or false
  Default value: false
• Style sheet parameters
  A list of parameters passed to the style sheets.

  A list of parameters passed to the style sheets.

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

  Possible values: <stylesheet-parameters>
  Default value:
• Braille translator query
  Possible values: A query

  The syntax is as follows (described in terms of CSS grammar):

  query
   : feature*
   ;
  feature
   : '(' S* IDENT S* [ ':' S* value ]? ')' S*
   ;
  value
   : string | integer | IDENT
   ;
  

  Default value: (translator:liblouis)
• Perform text-to-speech
  Whether to use a speech synthesizer to produce media overlays.

  Whether to use a speech synthesizer to produce media overlays.

  This will remove any existing media overlays in the EPUB.

  Possible values: One of the following:

  true

  Yes

  false

  No

  default

  If publication has no media overlays yet

  Default value: default
• Sentence class
  Class attribute to mark sentences with.

  Class attribute to mark sentences with.

  When sentence detection is enabled, this option may be used to add a class attribute to the span elements that represent the sentences.

  Possible values: Any <string>
  Default value:
• Lexicons
  A list of PLS lexicons to take into account.

  A list of PLS lexicons to take into account.

  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:

  1. Graphemes with regex=”false” come first, no matter if there is a lookahead or not;
  2. then come graphemes with regex=”true” and no lookahead;
  3. then graphemes with regex=”true” and one or two lookaheads.

  Within these categories, lexemes are matched in the same order as they appear in the lexicons.

  Possible values: <anyURI>
  Default value: p:system-property('d:org.daisy.pipeline.tts.default-lexicon')
• Update <title> elements based on EPUB metadata
  Whether to update <title> elements of content documents based on metadata in the package document.

  Whether to update