@node Voice Lock
@chapter Voice Lock


See
@url{http://tvraman.github.io/emacspeak/blog/voice-lock-refreshed.html}
for a high-level overview of how Emacspeak Voice-Lock has evolved over
the years.

@enumerate
@item
Emacspeak defines a number of voice overlays such as
@code{voice-bolden}, and @code{voice-lighten} that can be applied to a
given voice to change what it sounds like.

@item
Voice overlays are defined in terms of Aural CSS
(@uref{http://www.w3.org/tr/css2/aural.html, ACSS}) to keep them
independent of a specific TTS engine.

@item
For each such overlay there is a corresponding
@code{@var{<overlay-name>}-settings} variable that can be customized via
custom.

@item
The numbers in @code{voice-bolden-settings} as an example:
@end enumerate

@multitable @columnfractions 0.5 0.5
@item Setting @tab Value
@item family @tab nil
@item average-pitch @tab 1
@item pitch-range @tab 6
@item stress @tab 6
@item richness @tab nil
@item punctuation @tab nil
@end multitable

Unset values (@code{nil}) show up as ``unspecified'' in the customize
interface.

@enumerate
@item
Do not directly customize @code{voice-bolden} and friends, instead
customize the corresponding @code{voice-bolden-settings}, since that
ensures that all voices that are defined in terms of
@code{voice-bolden} get correctly updated.

@item
Discovering what to customize:
@end enumerate

Command @code{emacspeak-show-personality-at-point} (bound by default
to C-e M-v) will show you the value of properties personality and
face at point.  Describe-variable on these names should tell you
what to customize; so as an example:

Put point on a comment line, and hit @kbd{C-e M-v}: you will hear

@example
Personality emacspeak-voice-lock-comment-personality
Face font-lock-comment-delimiter-face
@end example

Describe-variable of @code{emacspeak-voice-lock-comment-personality} gives:

@example
emacspeak-voice-lock-comment-personality's value is acss-p0-s0-all

Documentation: Personality used for font-lock-comment-face This
personality uses voice-monotone whose effect can be changed globally
by customizing voice-monotone-settings.
@end example


@menu
* How It All Works.::
* What this gives.::
@end menu

@node How It All Works.
@section How It All Works

Here is a brief explanation of the connection between
@code{voice-bolden} and its associated @code{voice-bolden-settings}.


@enumerate
@item
Voice settings are initially in @code{voice-bolden-settings} which is
a list of numbers.

@item
That list of numbers needs to be translated to appropriate
device-specific codes to send to the TTS engine.

@item
You do not want to do this translation @emph{each} time you
speak something.

@item
So when @code{voice-bolden} is defined, the definition happens in
two steps:

@itemize @bullet
@item
The list of settings is stored away in
@code{voice-bolden-settings},

@item
A corresponding voice-name is generated  @MDash{} 
@samp{acss-a<n>-p<n>-r<n>-s<n>} and the corresponding control codes to
send to the device are stored away in a hash-table keyed by the above symbol.

@item
Finally, @code{voice-bolden} is assigned the above symbol.
@end itemize
@end enumerate

@node What this gives.
@section What this gives 

@enumerate
@item
The ability to customize the voice via custom by editing
the list of numbers in @code{voice-bolden-settings}

@item
When that list is edited, @code{voice-bolden} is arranged to be
updated automatically.
@end enumerate

The following additional commands from module @xref{emacspeak-wizards},
are  useful when designing aural styles.
@enumerate

@item
@code{emacspeak-wizards-generate-voice-sampler}

Generate a buffer containing text that demonstrates the effect of
various aural settings.

@item
@code{emacspeak-wizards-voice-sampler}

Applied specified aural style to text in current region.
@end enumerate
