~alcinnz/rhapsode

0040d2b6bc9e713c113a0c43b9bb70c5524ac597 — Adrian Cochrane 3 years ago 999efb6 
Expand on documentation of available CSS properties.
patch browse 
2 files changed, 180 insertions(+), 147 deletions(-)

M css-reference.html
M docs/CSS-Speech-Tutorial.md

M css-reference.html => css-reference.html +137 -121
@@ 3,145 3,161 @@
<head>
  <meta encoding=utf-8 />
  <title>CSS3 Speech Reference</title>
  <style>
    #cue-before {cue-before: url(about:link.wav)}
    #cue-before-quiet {cue-before: url(about:link.wav) -0.1db}
    #cue-after {cue-after: url(about:link.wav)}
    #cue-after-quiet {cue-after: url(about:link.wav) -0.1db}
  </style>
</head>
<body>
  <p>This document lists the (audio related) CSS properties Rhapsode supports.
    To hear the effect of these properties, listen to it in Rhapsode.</p>

  <dl>
    <dt>voice-volume (initial <code>medium</code>)</dt>
    <dd style="voice-volume: x-soft">x-soft</dd>
    <dd style="voice-volume: soft">soft</dd>
    <dd style="voice-volume: medium">medium</dd>
    <dd style="voice-volume: loud">loud</dd>
    <dd style="voice-volume: x-loud">x-loud</dd>
    <dd style="voice-volume: medium +2db">keyword _db, e.g. medium +2db</dd>
    <dd style="voice-volume: silent">silent</dd>

    <dt>speak (initial <code>always</code>)</dt>
    <dt><code>voice-volume</code> (initial <code>medium</code>)</dt>
    <dd style="voice-volume: x-soft"><code>x-soft</code></dd>
    <dd style="voice-volume: soft"><code>soft</code></dd>
    <dd style="voice-volume: medium"><code>medium</code></dd>
    <dd style="voice-volume: loud"><code>loud</code></dd>
    <dd style="voice-volume: x-loud"><code>x-loud</code></dd>
    <dd style="voice-volume: medium +2db">keyword _db, e.g. <code>medium +2db</code></dd>
    <dd style="voice-volume: silent"><code>silent</code></dd>

    <dt><code>speak</code> (initial <code>always</code>)</dt>
    <dd>Can be <code>always</code> or <code>never</code> to determine whether the text is read.</dd>

    <dt>speak-as (initial <code>normal</code>)</dt>
    <dd style="speak-as: normal">normal</dd>
    <dd style="speak-as: spell-out">spell-out</dd>
    <dd style="speak-as: digits">digits</dd>
    <dd style="speak-as: literal-punctuation">literal-punctuation, can be suffixed to <code>normal</code>, <code>spell-out</code>, or <code>digits</code>.</dd>
    <dd style="speak-as: no-punctuation">no-punctuation, as per literal-punctuation.</dd>

    <dt>pause-before (initial <code>none</code>, non-inherited)</dt>
    <dd style="pause-before: 500ms">_ms, e.g. 500ms</dd>
    <dd style="pause-before: 1s">_s, e.g. 1s</dd>
    <dd style="pause-before: none">none</dd>
    <dd style="pause-before: x-weak">x-weak</dd>
    <dd style="pause-before: weak">weak</dd>
    <dd style="pause-before: medium">medium</dd>
    <dd style="pause-before: strong">strong</dd>
    <dd style="pause-before: x-strong">x-strong</dd>

    <dt>pause-after (initial <code>none</code>, non-inherited)</dt>
    <dd style="pause-after: 500ms">_ms, e.g. 500ms</dd>
    <dd style="pause-after: 1s">_s, e.g. 1s</dd>
    <!--<dd style="pause-after: none">none</dd>-->
    <dd style="pause-after: x-weak">x-weak</dd>
    <dd style="pause-after: weak">weak</dd>
    <dd style="pause-after: medium">medium</dd>
    <dd style="pause-after: strong">strong</dd>
    <dd style="pause-after: x-strong">x-strong</dd>

    <dt>pause (shorthand)</dt>
    <dd>pause-before pause-after</dd>
    <dt><code>speak-as</code> (initial <code>normal</code>)</dt>
    <dd style="speak-as: normal"><code>normal</code></dd>
    <dd style="speak-as: spell-out"><code>spell-out</code></dd>
    <dd style="speak-as: digits"><code>digits</code></dd>
    <dd style="speak-as: literal-punctuation"><code>literal-punctuation</code>, can be suffixed to <code>normal</code>, <code>spell-out</code>, or <code>digits</code>.</dd>
    <dd style="speak-as: no-punctuation"><code>no-punctuation</code>, as per <code>literal-punctuation</code>.</dd>

    <dt><code>pause-before</code> (initial <code>none</code>, non-inherited)</dt>
    <dd style="pause-before: 500ms">_ms, e.g. <code>500ms</code></dd>
    <dd style="pause-before: 1s">_s, e.g. <code>1s</code></dd>
    <dd style="pause-before: none"><code>none</code></dd>
    <dd style="pause-before: x-weak"><code>x-weak</code></dd>
    <dd style="pause-before: weak"><code>weak</code></dd>
    <dd style="pause-before: medium"><code>medium</code></dd>
    <dd style="pause-before: strong"><code>strong</code></dd>
    <dd style="pause-before: x-strong"><code>x-strong</code></dd>

    <dt><code>pause-after</code> (initial <code>none</code>, non-inherited)</dt>
    <dd style="pause-after: 500ms">_ms, e.g. <code>500ms</code></dd>
    <dd style="pause-after: 1s">_s, e.g. <code>1s</code></dd>
    <dd style="pause-after: none"><code>none</code></dd>
    <dd style="pause-after: x-weak"><code>x-weak</code></dd>
    <dd style="pause-after: weak"><code>weak</code></dd>
    <dd style="pause-after: medium"><code>medium</code></dd>
    <dd style="pause-after: strong"><code>strong</code></dd>
    <dd style="pause-after: x-strong"><code>x-strong</code></dd>

    <dt><code>pause</code> (shorthand)</dt>
    <dd><code>pause-before</code> <code>pause-after</code></dd>
    <dd>Single token, both <code>pause-before</code> & <code>pause-after</code> are set to the same value.</dd>

    <dt>rest-before (initial <code>none</code>, non-inherited)</dt>
    <dd style="rest-before: 500ms">_ms, e.g. 500ms</dd>
    <dd style="rest-before: 1s">_s, e.g. 1s</dd>
    <dd style="rest-before: none">none</dd>
    <dd style="rest-before: x-weak">x-weak</dd>
    <dd style="rest-before: weak">weak</dd>
    <dd style="rest-before: medium">medium</dd>
    <dd style="rest-before: strong">strong</dd>
    <dd style="rest-before: x-strong">x-strong</dd>

    <dt>rest-after (initial <code>none</code>, non-inherited)</dt>
    <dd style="rest-after: 500ms">_ms, e.g. 500ms</dd>
    <dd style="rest-after: 1s">_s, e.g. 1s</dd>
    <dd style="rest-after: none">none</dd>
    <dd style="rest-after: x-weak">x-weak</dd>
    <dd style="rest-after: weak">weak</dd>
    <dd style="rest-after: medium">medium</dd>
    <dd style="rest-after: strong">strong</dd>
    <dd style="rest-after: x-strong">x-strong</dd>

    <dt>rest (shorthand)</dt>
    <dd>rest-before rest-after</dd>
    <dt><code>rest-before</code> (initial <code>none</code>, non-inherited)</dt>
    <dd style="rest-before: 500ms">_ms, e.g. <code>500ms</code></dd>
    <dd style="rest-before: 1s">_s, e.g. <code>1s</code></dd>
    <dd style="rest-before: none"><code>none</code></dd>
    <dd style="rest-before: x-weak"><code>x-weak</code></dd>
    <dd style="rest-before: weak"><code>weak</code></dd>
    <dd style="rest-before: medium"><code>medium</code></dd>
    <dd style="rest-before: strong"><code>strong</code></dd>
    <dd style="rest-before: x-strong"><code>x-strong</code></dd>

    <dt><code>rest-after</code> (initial <code>none</code>, non-inherited)</dt>
    <dd style="rest-after: 500ms">_ms, e.g. <code>500ms</code></dd>
    <dd style="rest-after: 1s">_s, e.g. <code>1s</code></dd>
    <dd style="rest-after: none"><code>none</code></dd>
    <dd style="rest-after: x-weak"><code>x-weak</code></dd>
    <dd style="rest-after: weak"><code>weak</code></dd>
    <dd style="rest-after: medium"><code>medium</code></dd>
    <dd style="rest-after: strong"><code>strong</code></dd>
    <dd style="rest-after: x-strong"><code>x-strong</code></dd>

    <dt><code>rest</code> (shorthand)</dt>
    <dd><code>rest-before</code> <code>rest-after</code></dd>
    <dd>Single token, both <code>rest-before</code> & <code>rest-after</code> are set to the same value.</dd>

    <dt>cue-before (initial <code>none</code>, non-inherited)</dt>
    <dd style="cue-before: none">none</dd>
    <dd style="cue-before: url(link.wav)">url()</dd>
    <dd style="cue-before: url(link.wav) -1db">url() _db, e.g. url(link.wav) -1db</dd>
    <dt><code>cue-before</code> (initial <code>none</code>, non-inherited)</dt>
    <dd><em>Not supported within style attributes, side-effect of security measures</em></dd>
    <dd style="cue-before: none"><code>none</code></dd>
    <dd id="cue-before">url(_), e.g. <code>url(about:link.wav)</code></code></dd>
    <dd id="cue-before-quiet">url(_) _db, e.g. <code>url(about:link.wav) -1db</code></dd>

    <dt>cue-after (initial <code>none</code>, non-inherited)</dt>
    <dd style="cue-after: none">none</dd>
    <dd style="cue-after: url(link.wav)">url()</dd>
    <dd style="cue-after: url(link.wav) -1db">url() _db, e.g. url(link.wav) -1db</dd>
    <dt><code>cue-after</code> (initial <code>none</code>, non-inherited)</dt>
    <dd><em>Not supported within style attributes, side-effect of security measures</em></dd>
    <dd style="cue-after: none"><code>none</code></dd>
    <dd id="cue-after">url(_), e.g. <code>url(about:link.wav)</code></dd>
    <dd id="cue-after-quiet">url(_) _db, e.g. <code>url(link.wav) -1db</code></dd>

    <dt>cue (shorthand)</dt>
    <dd>cue-before cue-after</dd>
    <dt><code>cue</code> (shorthand)</dt>
    <dd><code>cue-before</code> <code>cue-after</code></dd>
    <dd>Single token, both <code>cue-before</code> & <code>cue-after</code> are set to the same value</dd>

    <dt>voice-family</dt>
    <dd style="voice-family: preserve">preserve</dd>
    <dd style="voice-family: whisper">by name, e.g. whisper</dd>
    <dd style="voice-family: preserve"><code>preserve</code></dd>
    <dd style="voice-family: whisper">by name, e.g. <code>whisper</code></dd>
    <dd>By gender, i.e. <code style="voice-family: male">male</code>, <code style="voice-family: female">female</code>, or <code style="voice-family: nuetral">neutral</code>.</dd>
    <dd style="voice-family: old male">By gender and age, e.g. old male</dd>
    <dd style="voice-family: female 3">By gender and variant number, e.g. female 3.</dd>

    <dt>voice-rate (initial <code>normal</code>)</dt>
    <dd style="voice-rate: normal">normal</dd>
    <dd style="voice-rate: x-slow">x-slow</dd>
    <dd style="voice-rate: slow">slow</dd>
    <dd style="voice-rate: medium">medium</dd>
    <dd style="voice-rate: fast">fast</dd>
    <dd style="voice-rate: x-fast">x-fast</dd>
    <dd style="voice-rate: fast 50%">keyword _%, e.g. fast 50%</dd>

    <dt>voice-pitch (initial <code>medium</code>)</dt>
    <dd style="voice-pitch: x-low">x-low</dd>
    <dd style="voice-pitch: low">low</dd>
    <dd style="voice-pitch: medium">medium</dd>
    <dd style="voice-pitch: high">high</dd>
    <dd style="voice-pitch: x-high">x-high</dd>
    <dd style="voice-pitch: low +500hz">keyword _hz, e.g. low +500hz</dd>
    <dd style="voice-pitch: low +10khz">keyword _khz, e.g. low +10khz</dd>
    <dd style="voice-pitch: low +2st">keyword _st, e.g. low +2st. In semitones.</dd>
    <dd style="voice-pitch: low 50%">keyword _%, e.g. low 50%</dd>
    <dd style="voice-pitch: +500hz">_hz, e.g. +500hz. Difference from current value.</dd>
    <dd style="voice-pitch: +10khz">_khz, e.g. +10khz. Difference from current value.</dd>
    <dd style="voice-pitch: 500hz absolute">_hz absolute <em>or</em> absolute _hz, e.g. 500hz absolute</dd>
    <dd style="voice-pitch: 10khz absolute">_khz absolute <em>or</em> absolute _hz, e.g. 10khz absolute</dd>

    <dt>voice-range (initial <code>medium</code>)</dt>
    <dd style="voice-range: x-low">x-low</dd>
    <dd style="voice-range: low">low</dd>
    <dd style="voice-range: medium">medium</dd>
    <dd style="voice-range: high">high</dd>
    <dd style="voice-range: x-high">x-high</dd>
    <dd style="voice-range: low +500hz">keyword _hz, e.g. low +500hz</dd>
    <dd style="voice-range: low +10khz">keyword _khz, e.g. low +10khz</dd>
    <dd style="voice-range: low +2st">keyword _st, e.g. low +2st. In semitones.</dd>
    <dd style="voice-range: low 50%">keyword _%, e.g. low 50%</dd>
    <dd style="voice-range: +500hz">_hz, e.g. +500hz. Difference from current value.</dd>
    <dd style="voice-range: +10khz">_khz, e.g. +10khz. Difference from current value.</dd>
    <dd style="voice-range: 500hz absolute">_hz absolute <em>or</em> absolute _hz, e.g. 500hz absolute</dd>
    <dd style="voice-range: 10khz absolute">_khz absolute <em>or</em> absolute _hz, e.g. 10khz absolute</dd>

    <dt>voice-stress (initial <code>normal</code>)</dt>
    <dd style="voice-stress: normal">normal</dd>
    <dd style="voice-stress: strong">strong</dd>
    <dd style="voice-stress: medium">medium</dd>
    <dd style="voice-stress: none">none</dd>
    <dd style="voice-stress: reduced">reduced</dd>
    <dd style="voice-family: old male">By gender and age, e.g. <code>old male</code></dd>
    <dd style="voice-family: female 3">By gender and variant number, e.g. <code>female 3</code>.</dd>

    <dt><code>voice-rate</code> (initial <code>normal</code>)</dt>
    <dd style="voice-rate: normal"><code>normal</code></dd>
    <dd style="voice-rate: x-slow"><code>x-slow</code></dd>
    <dd style="voice-rate: slow"><code>slow</code></dd>
    <dd style="voice-rate: medium"><code>medium</code></dd>
    <dd style="voice-rate: fast"><code>fast</code></dd>
    <dd style="voice-rate: x-fast"><code>x-fast</code></dd>
    <dd style="voice-rate: fast 50%">keyword _%, e.g. <code>fast 50%</code></dd>

    <dt><code>voice-pitch</code> (initial <code>medium</code>)</dt>
    <dd style="voice-pitch: x-low"><code>x-low</code></dd>
    <dd style="voice-pitch: low"><code>low</code></dd>
    <dd style="voice-pitch: medium"><code>medium</code></dd>
    <dd style="voice-pitch: high"><code>high</code></dd>
    <dd style="voice-pitch: x-high"><code>x-high</code></dd>
    <dd style="voice-pitch: low +500hz">keyword _hz, e.g. <code>low +500hz</code></dd>
    <dd style="voice-pitch: low +10khz">keyword _khz, e.g. <code>low +10khz</code></dd>
    <dd style="voice-pitch: low +2st">keyword _st, e.g. <code>low +2st</code>. In semitones.</dd>
    <dd style="voice-pitch: low 50%">keyword _%, e.g. <code>low 50%</code></dd>
    <dd style="voice-pitch: +500hz">_hz, e.g. <code>+500hz</code>. Difference from current value.</dd>
    <dd style="voice-pitch: +10khz">_khz, e.g. <code>+10khz</code>. Difference from current value.</dd>
    <dd style="voice-pitch: 500hz absolute">_hz absolute <em>or</em> absolute _hz, e.g. <code>500hz absolute</code></dd>
    <dd style="voice-pitch: 10khz absolute">_khz absolute <em>or</em> absolute _hz, e.g. <code>10khz absolute</code></dd>

    <dt><code>voice-range</code> (initial <code>medium</code>)</dt>
    <dd style="voice-range: x-low"><code>x-low</code></dd>
    <dd style="voice-range: low"><code>low</code></dd>
    <dd style="voice-range: medium"><code>medium</code></dd>
    <dd style="voice-range: high"><code>high</code></dd>
    <dd style="voice-range: x-high"></code>x-high</dd>
    <dd style="voice-range: low +500hz">keyword _hz, e.g. <code>low +500hz</code></dd>
    <dd style="voice-range: low +10khz">keyword _khz, e.g. <code>low +10khz</code></dd>
    <dd style="voice-range: low +2st">keyword _st, e.g. <code>low +2st</code>. In semitones.</dd>
    <dd style="voice-range: low 50%">keyword _%, e.g. <code>low 50%</code></dd>
    <dd style="voice-range: +500hz">_hz, e.g. <code>+500hz</code>. Difference from current value.</dd>
    <dd style="voice-range: +10khz">_khz, e.g. <code>+10khz</code>. Difference from current value.</dd>
    <dd style="voice-range: 500hz absolute">_hz absolute <em>or</em> absolute _hz, e.g. <code>500hz absolute</code></dd>
    <dd style="voice-range: 10khz absolute">_khz absolute <em>or</em> absolute _hz, e.g. <code>10khz absolute</code></dd>

    <dt><code>voice-stress</code> (initial <code>normal</code>)</dt>
    <dd style="voice-stress: normal"><code>normal</code></dd>
    <dd style="voice-stress: strong"><code>strong</code></dd>
    <dd style="voice-stress: medium"><code>medium</code></dd>
    <dd style="voice-stress: none"><code>none</code></dd>
    <dd style="voice-stress: reduced"><code>reduced</code></dd>

    <dt><code>-rhaps-marker</code> (initial <code>""</code>, Rhapsode-specific)</dt>
    <dd>Indicates navigation interactions</dd>
    <dd><code>-rhaps-section</code> (navigate using up & down keys)</dd>
    <dd><code>-rhaps-paragraph</code> (navigate using left & right keys)</dd>
    <dd><code>"-rhaps-tablecell"_":"_"x"_</code> (navigate tables using arrow keys)</dd>
    <dd><code>"main"</code> (starting element)</dd>
  </dl>
  <aside><audio src="css-reference.ogg" controls></audio></aside>
</body>
</html>


M docs/CSS-Speech-Tutorial.md => docs/CSS-Speech-Tutorial.md +43 -26
@@ 1,7 1,5 @@
**Wanted:** Guidance on creating a great audio theme. Maybe based on voice acting
or public speaking theory.
**Wanted:** Written descriptions of the various outcomes of properties. I.e,
how does `speak-as: spell-out` differ from normal.

Rhapsode still lets you apply CSS styles to your webpages, but since it outputs
audio rather than video it supports a different set of CSS properties. This page


@@ 22,18 20,18 @@ Usage:
  `speak: always`

Valid Options:
  - `always`
  - `never`
  - `always` - Yes, it should be read aloud. **default**
  - `never` - Skips over the element entirely, no time spent on it.

#### `speak-as`
Usage:
  `speak-as: spell-out`

Valid options:
  - `spell-out`
  - `digits`
  - `literal-punctuation`
  - `no-punctuation`
  - `spell-out` - announces each individual letter or digit.
  - `digits` - announces each individual digit.
  - `literal-punctuation` - announces any punctuation marks.
  - `no-punctuation` - Does not read any punctuation.

## The Voice
You can use the `voice-family` attribute to select a voice either by age/gender/variant


@@ 41,13 39,16 @@ or by it's name. Just like font-family this'll make a big difference to the "loo
of your page.

### Reference
**Wanted: denote syntax and properly format list**
#### `voice-family`
Usage:
  `voice-family: OPTIONS`
  `voice-family: child female`

- genders: male female neutral
- ages: child young old
Specifies a comma-seperated list of voices, which can be specified by name (known
to the text-to-speech engine) or age/gender/variant-number which it depicts.
age/gender/number must be specified in that order, but only gender must be specified.

- genders: `male` `female` `neutral`
- ages: `child` `young` `old`. May also be specified as approximate age in years.


## Speaking Style


@@ 62,50 63,58 @@ that keyword.

### Reference
#### `voice-volume`
How loud the sound is, either as keyword or in decibels.

Usage:
  `voice-volume: medium -10dB`

Valid keywords:
  - `silent`
  - `x-soft`
  - `silent` - no sound for this duration.
  - `x-soft` - quieter
  - `soft`
  - `medium`
  - `loud`
  - `x-loud`
  - `medium`
  - `x-loud` - louder

#### `voice-rate`
How fast the sound is, as a keyword with optional percentage adjustment.

Usage:
  `voice-rate: medium -10%`

Valid keywords:
  - `x-slow`
  - `x-slow` - slower
  - `slow`
  - `medium`
  - `fast`
  - `x-fast`
  - `x-fast` - faster

#### `voice-pitch`
How high or low the sound is, in (kilo)hertz or with percentage/semitone adjustment.

Usage:
  `voice-pitch: medium +10%`

Valid keywords:
  - `x-low`
  - `x-low` - lower pitch
  - `low`
  - `medium`
  - `high`
  - `x-high`
  - `x-high` - higher pitch
  - `absolute` - indicates the given value in (kilo)hertz should be used regardless of the inherited value.

#### `voice-range`
By how much does the pitch of the sound change. Syntax matches `voice-pitch`.

#### `voice-stress`
Usage:
  `voice-stress: moderate`

Valid keywords:
  - `strong`
  - `strong` - more stress
  - `moderate`
  - `none`
  - `reduced`
  - `reduced` - less stress.

## Rests, Pauses, and Auditory Cues
On either end of your text you can place an audio cue to identify it, and on


@@ 122,15 131,23 @@ and links. And silence functions exactly like whitespace in a visual browser.
### Reference
> Note: `pause` and `rest` mirror functionality
> Note: `-before` and `-after` are both offered by the api as well
#### `pause`
#### `pause`/`rest`
Usage:
  `pause: before weak 50ms`
  `pause-before: weak 50ms`

In seconds or milliseconds, or as keyword.

Valid keywords:
  - `x-weak`
  - `x-weak` - less
  - `weak`
  - `medium`
  - `strong
  - `strong` - more

#### `cue`
Usage:
  `cue-after: url(censor.wav)`

Specifies .wav file to play between the corresponding pause/rest by relative URL.

## Text Generation
Rhapsode supports (some of) the same text generation attributes as visual