Share quick settings menus and validated voice discovery

This commit is contained in:
Storm Dragon committed 2026-11-15 12:28:29 -05:00
1 parent e7bd1d0043
commit 5ca137c879
5 files changed
+671 -28

No files matched your search

+21
View File
@@ -16,6 +16,24 @@ Import `git.stormux.org/storm/screenreader-common/emoji` and call
The module targets Go 1.24 or newer and has no external dependencies.
## Quick settings
`quicksettings.Menu` is the quick settings menu shared by both readers:
categories of entries, a remembered position in each category, value stepping
and the spoken announcement. Entries are toggles (checked/unchecked), choices
and numeric ranges. Entries and categories wrap at both ends; ranges stop at
their limits. Readers describe their entries, report current values through a
`Host`, and apply each changed `Result` themselves, so each reader keeps its own
settings storage, profiles, persistence and key bindings. `Replace` reports when
the selected entry disappeared so a reader can refuse to change a different
setting by mistake. `MessageIDs` lists the menu's own English messages for
translation catalogs.
Both readers store rate, pitch and volume on Speech Dispatcher's -100..100
scale, which the hardware protocol also uses. `speechdispatcher.DiscoverQuery`
validates module and voice lists, drops repeated voice aliases and keeps
partial results; `Discover` returns the same data as a `Catalog`.
## AI-assisted contributions
AI-assisted contributions are welcome. The person submitting a contribution
@@ -25,6 +43,9 @@ review. Check the maintained branch and whether the change is still needed
before editing. Describe what changed, the tests run, and remaining live reader
checks. Leave submission to the contributor after their review and testing.
The shared quick menu and validated discovery API are available starting with
v0.5.0. Both readers pin this version for standalone builds.
## License
GPL-3.0-or-later. See [LICENSE](LICENSE).
+284
View File
@@ -0,0 +1,284 @@
// Copyright (c) 2026 Storm Dragon
// SPDX-License-Identifier: GPL-3.0-or-later
// Package quicksettings implements the reader-independent quick settings
// menu: categories of entries, a remembered position in each category,
// value stepping and the spoken announcement. Readers own their settings:
// they describe entries, report current values and apply each change.
package quicksettings
import (
"strconv"
"git.stormux.org/storm/screenreader-common/internalui/message"
)
type Messages = message.Messages
type Kind uint8
const (
// Toggle is announced as checked or unchecked; either step flips it.
Toggle Kind = iota + 1
// Choice steps through Options and wraps at both ends.
Choice
// Range steps by Step and stops at Min and Max.
Range
)
type Option struct{ ID, Label string }
// Entry describes one setting. Label and option labels are English message
// IDs passed through the menu's translator.
type Entry struct {
ID string
Label string
Kind Kind
// Range limits and step size.
Min, Max, Step int
// EmptyIsDefault announces a Choice whose selected ID is empty as
// "<label> default", such as an unset speech module or voice.
EmptyIsDefault bool
}
type Category struct {
ID, Label string
Entries []Entry
}
// Value holds an entry's value; only the field matching its Kind is used.
type Value struct {
Checked bool
Choice string
Number int
}
// Host reports current values and the options of Choice entries. The menu
// calls it synchronously from Handle.
type Host interface {
Value(Entry) Value
Options(Entry) []Option
}
type Command uint8
const (
CurrentEntry Command = iota + 1
CurrentValue
NextEntry
PreviousEntry
NextValue
PreviousValue
NextCategory
PreviousCategory
)
// Result is one handled command. When Changed is true the host applies
// Value to Entry before speaking Text; an asynchronous host speaks Text when
// the change succeeds. Available is false for an empty menu or an entry
// without options, and Text then explains why.
type Result struct {
Entry Entry
Value Value
Changed bool
Available bool
Text string
}
// Menu is not safe for concurrent use. Copy it with Clone.
type Menu struct {
Messages Messages
categories []Category
category int
positions []int
}
// New drops categories without entries.
func New(categories []Category, messages Messages) *Menu {
menu := &Menu{Messages: messages}
menu.Replace(categories)
return menu
}
// IsValueChange reports whether command changes the selected entry's value.
func IsValueChange(command Command) bool { return command == NextValue || command == PreviousValue }
// Replace installs a new entry set, keeping the selected category and each
// category's selected entry when their IDs are still present. kept is false
// when the previously selected entry no longer exists; hosts should then not
// apply a value change to whichever entry is selected instead.
func (m *Menu) Replace(categories []Category) (kept bool) {
var selectedCategory, selectedEntry string
if entry, ok := m.Selected(); ok {
selectedEntry = entry.ID
}
selectedEntries := make(map[string]string)
for index, category := range m.categories {
if index == m.category {
selectedCategory = category.ID
}
selectedEntries[category.ID] = category.Entries[m.positions[index]].ID
}
m.categories, m.positions, m.category = nil, nil, 0
for _, category := range categories {
if len(category.Entries) == 0 {
continue
}
category.Entries = append([]Entry(nil), category.Entries...)
position := 0
for index, entry := range category.Entries {
if entry.ID == selectedEntries[category.ID] {
position = index
break
}
}
if category.ID == selectedCategory {
m.category = len(m.categories)
}
m.categories = append(m.categories, category)
m.positions = append(m.positions, position)
}
entry, ok := m.Selected()
return selectedEntry == "" || ok && entry.ID == selectedEntry
}
func (m *Menu) Clone() *Menu {
clone := *m
clone.categories = append([]Category(nil), m.categories...)
clone.positions = append([]int(nil), m.positions...)
return &clone
}
func (m *Menu) Categories() []Category {
categories := append([]Category(nil), m.categories...)
for index := range categories {
categories[index].Entries = append([]Entry(nil), categories[index].Entries...)
}
return categories
}
// Selected reports the current entry; ok is false for an empty menu.
func (m *Menu) Selected() (entry Entry, ok bool) {
if len(m.categories) == 0 {
return Entry{}, false
}
return m.categories[m.category].Entries[m.positions[m.category]], true
}
func (m *Menu) Handle(command Command, host Host) Result {
if len(m.categories) == 0 {
return Result{Text: m.Messages.T("Quick menu not available")}
}
categoryChanged := command == NextCategory || command == PreviousCategory
switch command {
case NextCategory:
m.category = (m.category + 1) % len(m.categories)
case PreviousCategory:
m.category = (m.category + len(m.categories) - 1) % len(m.categories)
}
entries := m.categories[m.category].Entries
position := &m.positions[m.category]
switch command {
case NextEntry:
*position = (*position + 1) % len(entries)
case PreviousEntry:
*position = (*position + len(entries) - 1) % len(entries)
}
entry := entries[*position]
result := Result{Entry: entry, Value: host.Value(entry), Available: true}
step := 0
switch command {
case NextValue:
step = 1
case PreviousValue:
step = -1
}
var options []Option
switch entry.Kind {
case Toggle:
if step != 0 {
result.Value.Checked = !result.Value.Checked
result.Changed = true
}
case Choice:
options = host.Options(entry)
if len(options) == 0 {
result.Available = false
result.Text = m.Messages.Format("{0} not available", m.Messages.T(entry.Label))
if categoryChanged {
result.Text = m.Messages.T(m.categories[m.category].Label) + ". " + result.Text
}
return result
}
if step != 0 {
index := -1
for candidate, option := range options {
if option.ID == result.Value.Choice {
index = candidate
break
}
}
if index < 0 {
if step > 0 {
index = 0
} else {
index = len(options) - 1
}
} else {
index = (index + step + len(options)) % len(options)
}
result.Changed = options[index].ID != result.Value.Choice
result.Value.Choice = options[index].ID
}
case Range:
if step != 0 {
next := max(entry.Min, min(entry.Max, result.Value.Number+step*entry.Step))
result.Changed = next != result.Value.Number
result.Value.Number = next
}
}
text, labelled := m.describe(entry, result.Value, options)
if !labelled && (categoryChanged || command == CurrentEntry || command == NextEntry || command == PreviousEntry) {
text = m.Messages.T(entry.Label) + " " + text
}
if categoryChanged {
text = m.Messages.T(m.categories[m.category].Label) + ". " + text
}
result.Text = text
return result
}
// Describe returns the value announcement used after a value change.
func (m *Menu) Describe(entry Entry, value Value, options []Option) string {
text, _ := m.describe(entry, value, options)
return text
}
func (m *Menu) describe(entry Entry, value Value, options []Option) (text string, labelled bool) {
switch entry.Kind {
case Toggle:
if value.Checked {
return m.Messages.T("checked"), false
}
return m.Messages.T("unchecked"), false
case Choice:
if entry.EmptyIsDefault && value.Choice == "" {
return m.Messages.T(entry.Label) + " " + m.Messages.T("default"), true
}
for _, option := range options {
if option.ID == value.Choice {
return m.Messages.T(option.Label), false
}
}
if len(options) > 0 {
return m.Messages.Format("{0} not available", value.Choice), false
}
return value.Choice, false
}
return strconv.Itoa(value.Number), false
}
// MessageIDs lists the menu's own English messages for translation catalogs.
func MessageIDs() []string {
return []string{"Quick menu not available", "{0} not available", "checked", "unchecked", "default"}
}
+185
View File
@@ -0,0 +1,185 @@
// Copyright (c) 2026 Storm Dragon
// SPDX-License-Identifier: GPL-3.0-or-later
package quicksettings
import (
"strings"
"testing"
)
type fakeHost struct {
values map[string]Value
options map[string][]Option
}
func (h *fakeHost) Value(entry Entry) Value { return h.values[entry.ID] }
func (h *fakeHost) Options(entry Entry) []Option { return h.options[entry.ID] }
func (h *fakeHost) apply(result Result) { h.values[result.Entry.ID] = result.Value }
func (h *fakeHost) run(m *Menu, command Command) Result {
result := m.Handle(command, h)
if result.Changed {
h.apply(result)
}
return result
}
func fixture() (*Menu, *fakeHost) {
menu := New([]Category{
{ID: "speech", Label: "Speech", Entries: []Entry{
{ID: "rate", Label: "speech rate", Kind: Range, Min: -100, Max: 100, Step: 10},
{ID: "voice", Label: "speech voice", Kind: Choice, EmptyIsDefault: true},
}},
{ID: "empty", Label: "Empty"},
{ID: "reading", Label: "Reading", Entries: []Entry{
{ID: "punctuation", Label: "punctuation level", Kind: Choice},
{ID: "emoticons", Label: "emoticons", Kind: Toggle},
}},
}, Messages{})
host := &fakeHost{
values: map[string]Value{"rate": {Number: 80}, "punctuation": {Choice: "some"}},
options: map[string][]Option{
"voice": {{ID: "", Label: "default"}, {ID: "alice", Label: "Alice"}},
"punctuation": {{ID: "none", Label: "none"}, {ID: "some", Label: "some"}, {ID: "all", Label: "all"}},
},
}
return menu, host
}
func TestNavigationAdjustmentAndAnnouncements(t *testing.T) {
menu, host := fixture()
for _, step := range []struct {
command Command
want string
}{
{CurrentEntry, "speech rate 80"},
{NextValue, "90"},
{NextValue, "100"},
{NextValue, "100"},
{CurrentValue, "100"},
{NextEntry, "speech voice default"},
{NextValue, "Alice"},
{CurrentEntry, "speech voice Alice"},
{NextValue, "speech voice default"},
{NextEntry, "speech rate 100"},
{PreviousEntry, "speech voice default"},
{NextCategory, "Reading. punctuation level some"},
{NextValue, "all"},
{NextValue, "none"},
{PreviousValue, "all"},
{NextEntry, "emoticons unchecked"},
{NextValue, "checked"},
{PreviousValue, "unchecked"},
{NextCategory, "Speech. speech voice default"},
{PreviousCategory, "Reading. emoticons unchecked"},
} {
if got := host.run(menu, step.command).Text; got != step.want {
t.Fatalf("%v: got %q, want %q", step.command, got, step.want)
}
}
if len(menu.Categories()) != 2 {
t.Fatal("empty category was kept", menu.Categories())
}
}
func TestChangedOnlyWhenValueMoves(t *testing.T) {
menu, host := fixture()
host.values["rate"] = Value{Number: 100}
if result := menu.Handle(NextValue, host); result.Changed || !result.Available {
t.Fatal(result)
}
if result := menu.Handle(PreviousValue, host); !result.Changed || result.Value.Number != 90 {
t.Fatal(result)
}
if result := menu.Handle(CurrentValue, host); result.Changed {
t.Fatal(result)
}
}
func TestUnavailableMenuAndOptions(t *testing.T) {
menu := New(nil, Messages{})
if result := menu.Handle(NextEntry, &fakeHost{}); result.Available || result.Text != "Quick menu not available" {
t.Fatal(result)
}
menu, host := fixture()
host.options["voice"] = nil
menu.Handle(NextEntry, host)
if result := menu.Handle(NextValue, host); result.Available || result.Changed || result.Text != "speech voice not available" {
t.Fatal(result)
}
}
func TestReplaceKeepsSelectionByID(t *testing.T) {
menu, host := fixture()
menu.Handle(NextCategory, host)
menu.Handle(NextEntry, host)
categories := menu.Categories()
categories[0], categories[1] = categories[1], categories[0]
categories[0].Entries = append([]Entry{{ID: "new", Label: "new", Kind: Toggle}}, categories[0].Entries...)
if !menu.Replace(categories) {
t.Fatal("kept selection reported as removed")
}
if entry, ok := menu.Selected(); !ok || entry.ID != "emoticons" {
t.Fatal(entry, ok)
}
categories[0].Entries = categories[0].Entries[:2]
if menu.Replace(categories) {
t.Fatal("removed selection reported as kept")
}
if !IsValueChange(NextValue) || !IsValueChange(PreviousValue) || IsValueChange(NextEntry) {
t.Fatal("value change classification")
}
menu.Replace(nil)
if _, ok := menu.Selected(); ok {
t.Fatal("empty menu reported a selection")
}
}
func TestCloneIsIndependent(t *testing.T) {
menu, host := fixture()
clone := menu.Clone()
menu.Handle(NextEntry, host)
if entry, _ := clone.Selected(); entry.ID != "rate" {
t.Fatal(entry)
}
}
func TestMessagesAreTranslated(t *testing.T) {
menu, host := fixture()
menu.Messages = Messages{Translate: strings.ToUpper}
if got := menu.Handle(NextCategory, host).Text; got != "READING. PUNCTUATION LEVEL SOME" {
t.Fatal(got)
}
for _, id := range MessageIDs() {
if id == "" {
t.Fatal("empty message ID")
}
}
}
func TestMissingChoiceIsNotAnnouncedAsAnotherValue(t *testing.T) {
menu, host := fixture()
menu.Handle(NextEntry, host)
host.values["voice"] = Value{Choice: "removed"}
if got := menu.Handle(CurrentEntry, host).Text; got != "speech voice removed not available" {
t.Fatal(got)
}
if got := menu.Handle(NextValue, host); !got.Changed || got.Value.Choice != "" {
t.Fatal(got)
}
if got := menu.Handle(PreviousValue, host); !got.Changed || got.Value.Choice != "alice" {
t.Fatal(got)
}
}
func TestCategoriesCannotMutateMenuOrClone(t *testing.T) {
menu, _ := fixture()
clone := menu.Clone()
categories := menu.Categories()
categories[0].Entries[0].ID = "modified"
for _, current := range []*Menu{menu, clone} {
if entry, _ := current.Selected(); entry.ID != "rate" {
t.Fatal(entry)
}
}
}
+119 -28
View File
@@ -7,56 +7,147 @@ package speechdispatcher
import (
"context"
"errors"
"fmt"
"strings"
"unicode"
"unicode/utf8"
)
type Voice struct{ Name, Language, Variant string }
type Catalog map[string][]Voice
// Discover uses its own connection, so slow modules never hold up speech.
// The empty module selects the server default.
func Discover(ctx context.Context, socket string) (Catalog, error) {
query, err := OpenQuery(ctx, socket, false, false)
if err != nil {
// Discovery is a complete catalog query. Modules lists the server's modules;
// Voices holds each module's voices, keyed "" for the server default; Errors
// records modules whose voice list could not be read.
type Discovery struct {
Modules []string
Voices map[string][]Voice
Errors map[string]error
}
// ValidModule accepts module and language identifiers safe to send in SSIP.
func ValidModule(module string) bool {
for _, char := range module {
if !(char >= 'a' && char <= 'z' || char >= 'A' && char <= 'Z' || char >= '0' && char <= '9' || char == '.' || char == '_' || char == '+' || char == '-') {
return false
}
}
return true
}
// ValidSelection rejects identifiers that could break an SSIP command line.
func ValidSelection(module, language, voice string) error {
if !ValidModule(module) || !ValidModule(language) {
return fmt.Errorf("invalid speech module or language")
}
if !utf8.ValidString(voice) || len(voice) > 1024 || voice != "" && strings.TrimSpace(voice) == "" {
return fmt.Errorf("invalid speech voice")
}
for _, char := range voice {
if unicode.IsControl(char) {
return fmt.Errorf("invalid speech voice")
}
}
return nil
}
// ParseVoices validates a LIST SYNTHESIS_VOICES reply. Some modules repeat
// aliases; the synthesis name is the stable ID, so repeats are dropped.
func ParseVoices(rows []string) ([]Voice, error) {
voices := make([]Voice, 0, len(rows))
seen := map[string]bool{}
for _, row := range rows {
fields := strings.Split(row, "\t")
if len(fields) < 2 || len(fields) > 3 || fields[0] == "" || fields[1] == "" {
return nil, fmt.Errorf("invalid speech voice list")
}
if err := ValidSelection("", fields[1], fields[0]); err != nil {
return nil, err
}
defer query.Close()
modules, err := query.Command(ctx, "LIST OUTPUT_MODULES")
if err != nil {
return nil, err
}
catalog := Catalog{}
for _, module := range append([]string{""}, modules...) {
if strings.ContainsAny(module, "\r\n\x00") {
if seen[fields[0]] {
continue
}
seen[fields[0]] = true
voice := Voice{Name: fields[0], Language: fields[1]}
if len(fields) == 3 {
voice.Variant = fields[2]
}
voices = append(voices, voice)
}
return voices, nil
}
// DiscoverQuery never speaks. Partial failures keep the modules that
// succeeded and record the others in Errors. The caller bounds ctx.
func DiscoverQuery(ctx context.Context, query *Query) (Discovery, error) {
result := Discovery{Voices: map[string][]Voice{}, Errors: map[string]error{}}
modules, err := query.Command(ctx, "LIST OUTPUT_MODULES")
if err != nil {
return result, err
}
seen := map[string]bool{}
for _, module := range modules {
if module == "" || !ValidModule(module) || seen[module] {
return result, fmt.Errorf("invalid Speech Dispatcher module list")
}
seen[module] = true
}
result.Modules = modules
// Query the server default before selecting any named module.
for _, module := range append([]string{""}, modules...) {
var rows []string
var err error
if module != "" {
_, err = query.Command(ctx, "SET SELF OUTPUT_MODULE "+module)
}
if err == nil {
rows, err = query.Command(ctx, "LIST SYNTHESIS_VOICES")
}
if err == nil {
voices, parseErr := ParseVoices(rows)
if parseErr != nil {
// The reply was fully consumed; subsequent modules remain safe.
result.Errors[module] = parseErr
continue
}
result.Voices[module] = voices
}
if err != nil {
delete(result.Voices, module)
result.Errors[module] = err
// A rejected command ends a complete reply. A broken stream must
// never be reused: a late reply could belong to the previous module.
var rejected *Rejection
if errors.As(err, &rejected) {
err = nil
continue
if !errors.As(err, &rejected) {
break
}
}
}
return result, nil
}
// Discover uses its own connection, so slow modules never hold up speech.
// The empty module selects the server default. Modules whose voices could
// not be read are omitted; a broken connection returns what was read.
func Discover(ctx context.Context, socket string) (Catalog, error) {
query, err := OpenQuery(ctx, socket, false, false)
if err != nil {
return nil, err
}
defer query.Close()
discovery, err := DiscoverQuery(ctx, query)
if err != nil {
return nil, err
}
catalog := Catalog{}
for module, voices := range discovery.Voices {
catalog[module] = voices
}
for _, err := range discovery.Errors {
var rejected *Rejection
if !errors.As(err, &rejected) {
return catalog, err
}
catalog[module] = nil
for _, row := range rows {
fields := strings.Split(row, "\t")
if len(fields) < 2 {
continue
}
voice := Voice{Name: fields[0], Language: fields[1]}
if len(fields) > 2 {
voice.Variant = fields[2]
}
catalog[module] = append(catalog[module], voice)
}
}
return catalog, nil
}
+62
View File
@@ -41,3 +41,65 @@ func TestDiscoverVoicesAndOutputModule(t *testing.T) {
t.Fatal("echo voice/module not configured")
}
}
func TestParseVoicesRejectsMalformedRowsAndKeepsNames(t *testing.T) {
for _, row := range []string{"Missing tabs", "name\ten\tvariant\textra", "name\ten\rCANCEL ALL", "bad\x00name\ten"} {
if _, err := ParseVoices([]string{row}); err == nil {
t.Fatal("accepted malformed catalog row", row)
}
}
voices, err := ParseVoices([]string{"Cherokee \tchr\tnone", "Alias\ten", "Alias\ten-US"})
if err != nil || len(voices) != 2 || voices[0].Name != "Cherokee " || voices[1].Language != "en" {
t.Fatal(voices, err)
}
if err := ValidSelection("espeak-ng", "chr", "Cherokee "); err != nil {
t.Fatal(err)
}
if err := ValidSelection("espeak-ng", "chr", " "); err == nil {
t.Fatal("accepted whitespace-only name")
}
if err := ValidSelection("bad module", "", ""); err == nil {
t.Fatal("accepted unsafe module")
}
}
func TestDiscoverRejectsUnsafeModuleList(t *testing.T) {
path, _ := newSettingsServer(t, func(command string) string {
if command == "LIST OUTPUT_MODULES" {
return "200-good\r\n200-bad module\r\n200 OK\r\n"
}
return "200 OK\r\n"
})
if _, err := Discover(context.Background(), path); err == nil {
t.Fatal("accepted an unsafe module name")
}
}
func TestDiscoveryContinuesAfterMalformedVoiceList(t *testing.T) {
module := ""
path, _ := newSettingsServer(t, func(command string) string {
switch command {
case "LIST OUTPUT_MODULES":
return "200-broken\r\n200-good\r\n200 OK\r\n"
case "SET SELF OUTPUT_MODULE broken":
module = "broken"
case "SET SELF OUTPUT_MODULE good":
module = "good"
case "LIST SYNTHESIS_VOICES":
if module == "broken" {
return "200-malformed\r\n200 OK\r\n"
}
return "200-Voice\ten\tnone\r\n200 OK\r\n"
}
return "200 OK\r\n"
})
query, err := OpenQuery(context.Background(), path, false, false)
if err != nil {
t.Fatal(err)
}
defer query.Close()
catalog, err := DiscoverQuery(context.Background(), query)
if err != nil || catalog.Errors["broken"] == nil || len(catalog.Voices["good"]) != 1 {
t.Fatal(catalog, err)
}
}