summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAdrian Cochrane <adrian@openwork.nz>2020-06-13 18:45:59 +1200
committerAdrian Cochrane <adrian@openwork.nz>2020-06-13 18:45:59 +1200
commit0040d2b6bc9e713c113a0c43b9bb70c5524ac597 (patch)
tree8b46977d2900020f842a58e9309e5e088f0cabca
parent999efb6707c0419fa5fc598513ceaabb8bd0952e (diff)
downloadrhapsode-0040d2b6bc9e713c113a0c43b9bb70c5524ac597.tar.gz
rhapsode-0040d2b6bc9e713c113a0c43b9bb70c5524ac597.tar.bz2
rhapsode-0040d2b6bc9e713c113a0c43b9bb70c5524ac597.zip
Expand on documentation of available CSS properties.
-rw-r--r--css-reference.html258
-rw-r--r--docs/CSS-Speech-Tutorial.md69
2 files changed, 180 insertions, 147 deletions
diff --git a/css-reference.html b/css-reference.html
index 4645fd7..a4f6ea7 100644
--- a/css-reference.html
+++ b/css-reference.html
@@ -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>
diff --git a/docs/CSS-Speech-Tutorial.md b/docs/CSS-Speech-Tutorial.md
index fb13749..c61d24a 100644
--- a/docs/CSS-Speech-Tutorial.md
+++ b/docs/CSS-Speech-Tutorial.md
@@ -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