A sound theme is a set of sounds and vibrations that replace SandFly's own, with its own settings for control sounds and 3D audio. Install as many as you like and switch between them. SandFly's own sounds are the SandFly theme, which is always there.
Sound themes are in SandFly settings, under Sound and vibration > Sound themes.
A theme comes as a theme file, which is a ZIP file. There are several ways to install one:
- Open it with SandFly. Open a theme file from your file manager or your browser's downloads, and choose Install sound theme.
- Share it with SandFly. Share a theme file, or a link to one, from another app, and choose Install sound theme. Sharing a page from your browser works too, as long as it is a link to a theme file or to a GitHub repository with a theme in it.
- From a file. In Sound themes, under Install a theme, choose From a file.
- From a link. In Sound themes, under Install a theme, choose From a link, and
enter or paste a link. It can be a link to a theme file, or to a GitHub repository, such as
https://github.com/someone/my-theme. Links must start with https. - From a source. In Sound themes, under Install a theme, choose From a source, and add the address of a repository, or of a branch or folder in one, on GitHub, GitLab, Codeberg, Gitea or Bitbucket. Its theme files are listed, and choosing one installs it. The list starts with SandFly's own themes, aaron-gh/sandfly-themes, until it is removed. Remove source removes a source from the list; themes installed from it stay installed.
Before installing, SandFly says who made the theme, what it has, and anything in it that it could not use. Choose Install and use to switch to it at once, or Install to keep using the theme you have. Installing a theme with the same name as one you have replaces it.
Each installed theme is listed in Sound themes, and the one in use says so. Select a theme to use it, to read about it, to save it as a theme file, or to remove it.
Under Settings of the theme in use:
- Control sounds and vibrations gives each kind of control, such as buttons, checkboxes and edit fields, its own sound and its own vibration, in place of the focus sound and vibration, as the Unspoken add-on does for NVDA with sounds. SandFly has a control sound and vibration of its own for each, which the theme can replace. When a control's sound or vibration plays, SandFly leaves out saying what kind of control it is. A control's vibration plays even with Sound feedback off, so you can learn the kinds of control by touch alone. A kind of control whose sound the theme sets to no sound plays the focus sound with its own vibration, and SandFly says what kind of control it is.
- 3D audio sets when control sounds play in 3D: with headphones, always, or never.
- Still say the kind of control says the kind of control, such as "button", after its sound. It is on by default for SandFly's theme and off for others.
- Sounds lists every sound, where you can replace any of them with a sound file of your own, preview it, or go back to SandFly's sound.
Each theme remembers its own Control sounds and vibrations, 3D audio and Still say the
kind of control settings, so switching themes switches them too. A theme starts with the
settings in its theme.json.
To replace a few sounds without installing anything, use Sounds with the SandFly theme in use. To share your sounds, select the theme and choose Save as a theme file.
Choose Create new theme above the installed themes. Enter a Name, and optionally a Description, Author, and Website, then choose OK. Cancel leaves your themes unchanged. Names must be different from an installed theme.
The new theme opens in the sound editor. Choose your sounds and the control-sound and 3D audio settings. Save, at the top, saves the theme and puts it in use. Save as a theme file opens the system file picker so you can choose a filename and location; exporting alone does not put the theme in use. Back or Navigate up asks before discarding the draft. If you leave the Control sounds setting untouched, it is enabled automatically when the saved theme contains control sounds.
A theme file is a ZIP file with a theme.json and the sound files, all in the same folder. Name
each sound after the sound it replaces, such as focus.wav. A theme only needs the sounds it
changes. Every other sound stays SandFly's own.
my-theme.zip
theme.json
focus.wav
tick.ogg
control_button.wav
LICENSE.txt
The folder can also be inside one folder of the ZIP file, as when GitHub makes a ZIP file of a
repository. So a GitHub repository with theme.json and the sounds at the top is a theme too, and
its link installs it.
Files called LICENSE, LICENCE, COPYING, README, NOTICE, AUTHORS or CREDITS, with
.txt, .md or no extension, are kept with the theme, and saved with it when someone shares it
again. Put the license of your sounds there. SandFly leaves out any other files.
The circle menu has eight sounds, radial_menu_1 to radial_menu_8. A file called radial_menu replaces all eight. A file called after one of
them, such as radial_menu_3.ogg, replaces that one, and comes before radial_menu.
A ZIP file of sounds alone, without a theme.json, also installs, named after the file.
{
"format": 1,
"name": "Soft",
"author": "Your name",
"description": "Quiet, rounded sounds for every action.",
"license": "CC-BY-4.0",
"website": "https://github.com/someone/soft",
"settings": {
"control_sounds": true,
"3d_audio": "headphones"
},
"sounds": {
"scroll_tone": "none",
"window_state": "none"
},
"vibrations": {
"focus": { "pattern": [0, 12], "strength": [[12, 90]], "effects": [["tick", 100, 0]] },
"control_button": { "pattern": [0, 20, 30, 20] },
"scroll_tone": "none"
}
}Every field is optional.
| Field | What it is |
|---|---|
format |
The version of this format, 1. A theme for a newer SandFly still installs, with a warning. |
name |
The theme's name. Without one, the theme is named after its file. A theme with the same name as an installed one replaces it. |
author |
Who made it. |
description |
A sentence or two about it. |
license |
The license of the sounds, such as GPL-2.0 or CC0-1.0. Include its text in the theme too. |
website |
Where to find out more, or get updates. |
settings.control_sounds |
true or false: whether control sounds and vibrations are on with this theme. Without it, they are on when the theme has a control sound or a control vibration. |
settings.3d_audio |
"headphones", "always" or "never": when control sounds play in 3D. Without it, "headphones". |
settings.speak_roles |
true or false: whether the kind of control is still said after its control sound. Without it, false. |
sounds |
Settings for sounds by event name, such as "scroll_tone": "none" to play no sound for an event. |
vibrations |
The theme's own vibrations, by the name of the sound they play with. See below. |
Name each sound file after one of these, with the extension of its format. WAV, OGG, MP3, FLAC, M4A, AAC and Opus all work, up to 5 MB each and 50 MB for the whole theme. A file Android can't play is left out when the theme is installed, and SandFly says so.
| Name | Plays for |
|---|---|
focus |
Focus on an item |
focus_actionable |
Focus on an actionable item |
view_entered |
Touching an empty area |
tick |
Click |
long_clicked |
Long press |
scroll_tone |
Scroll |
chime_up |
Entering a list |
chime_down |
Leaving a list |
complete |
Action done or end reached |
window_state |
Window change |
next_reading_control |
Next reading control |
previous_reading_control |
Previous reading control |
edge_gesture_bottom |
A finger touching an edge where an edge gesture starts, or sliding back to it |
edge_gesture_middle |
An edge gesture reaching its first stage, or sliding back to it |
edge_gesture_top |
An edge gesture reaching its second stage |
insertion_point_moved |
Moving by character, word, line or paragraph moves the cursor in a text field being edited |
column_wrap |
Swiping forward to an item on a row below |
column_wrap_back |
Swiping back to an item on a row above |
agentic_interaction_start |
The SandFly Pro agent starts a task |
agentic_interaction_complete |
The agent finishes a task |
agentic_interaction_ask |
The agent asks a question or asks to confirm an action |
agentic_interaction_sensitive_stop |
The safety check stops an action of the agent |
agentic_interaction_fail |
The agent can't finish a task |
typo |
Spelling error |
hyperlink |
Link |
formatting |
Formatted text |
screen_off |
Screen off |
screen_on |
Screen on |
screen_hidden |
The screen is hidden |
screen_shown |
The hidden screen is shown again |
loading |
Loading |
model_loading |
The on-device AI model loading |
browse_mode_on_v4_2 |
Browse mode on |
browse_mode_off_v4_2 |
Browse mode off |
keyboard_opened |
An on-screen keyboard opens |
keyboard_closed |
An on-screen keyboard closes |
sandfly_notification |
SandFly posts a notification on a notification channel without a sound |
radial_menu |
Circle menu (all eight notes play this one sound) |
display_connected |
Braille display connected |
display_disconnected |
Braille display disconnected |
double_beep |
Braille command failed |
turn_on |
Braille auto scroll on |
turn_off |
Braille auto scroll off |
calibration_done |
Braille keyboard calibrated |
control_button |
Control sound: button |
control_checkbox |
Control sound: checkbox, also switches and toggle buttons |
control_radio_button |
Control sound: radio button |
control_edit_text |
Control sound: edit field |
control_combo_box |
Control sound: drop-down list |
control_slider |
Control sound: slider |
control_link |
Control sound: link on a web page |
control_image |
Control sound: image |
control_clock |
Control sound: clock |
control_tab |
Control sound: tab |
control_menu_item |
Control sound: menu item |
control_list_item |
Control sound: list item |
control_tree_item |
Control sound: tree item on a web page |
volume_change |
A volume step, with Volume change feedback set to Tone or Tone and speech |
braille_keyboard_character |
Braille keyboard: typing a character |
braille_keyboard_space |
Braille keyboard: space |
braille_keyboard_delete |
Braille keyboard: deleting a character or a word |
braille_keyboard_new_line |
Braille keyboard: new line |
A theme can also set any sound to "none" in theme.json to silence it:
"sounds": {
"scroll_tone": "none",
"window_state": "none"
}This is useful for themes modeled after other screen readers, such as iOS VoiceOver, which play fewer sounds. In SandFly under Sounds, you can also select No sound (or use the accessibility action Set to no sound) for any sound event.
The braille keyboard sounds play only with Typing sounds on in the braille keyboard's settings.
volume_change plays at the volume of the stream that changed, such as media or ring, and not at
the Sound feedback volume. A step while it plays starts it again. Without it, SandFly plays a
generated tone. It has no vibration.
The names are also shown in SandFly: in Sounds, selecting a sound shows its name after its title, such as "Click (tick)".
Tips:
- Keep sounds short. Focus and control sounds play on every swipe, and a new control sound cuts off the one before it.
- Control sounds, and the focus and list sounds while control sounds are on, come from where the item is on the screen. They are mixed down to mono for that, so make them mono to hear them as you made them.
- Leave some headroom. SandFly plays sounds at the volume of its Sound feedback volume setting, which can't make a quiet sound louder than it is.
A theme can replace every vibration SandFly plays, and define each pattern itself. A vibration the theme leaves out keeps SandFly's.
Each sound has a vibration, which plays with it even when sound feedback is off. A theme gives a
sound its own vibration by the name of the sound, as in the table above. It then replaces that
vibration everywhere it plays: with the sound, and wherever SandFly plays the same vibration
without the sound, such as the click vibration of the circle menu and the focus vibration of
selection. radial_menu replaces the vibrations of all eight circle menu notes. control_link
plays the vibration of hyperlink, but a theme can give it one of its own. column_wrap and
column_wrap_back play with the focus sound, and their vibrations play in place of the focus
vibration.
These vibrations have no sound, and a theme replaces them by these names:
| Name | Plays for |
|---|---|
announcement |
An app's announcement |
braille_keyboard_character |
Typing a character on the braille keyboard |
braille_keyboard_space |
Space, delete, moving the cursor or changing the reading unit on the braille keyboard |
braille_keyboard_new_line |
A new line or deleting a word on the braille keyboard |
braille_keyboard_hold |
Holding the fingers down on the braille keyboard |
braille_keyboard_gesture |
Other gestures on the braille keyboard |
braille_keyboard_nothing_to_delete |
Deleting with nothing left to delete on the braille keyboard |
direct_touch_on |
Direct touch turning on |
direct_touch_off |
Direct touch turning off |
The braille keyboard vibrations play only with Vibration feedback on, and each has its own switch in Individual sounds and vibrations. The direct touch vibrations play only with direct touch's vibration setting on.
A theme can give each kind of control its own vibration, by the names of the control sounds, such
as control_button, so that people can tell what a control is by touch alone. SandFly has none
of its own. A control vibration:
- plays in place of the focus vibration, with Control sounds and vibrations on;
- plays even with Sound feedback off;
- leaves the kind of control out of the speech, as a control sound does;
- works without a control sound: the control then plays the focus sound with its own vibration;
- has its own switch in Individual sounds and vibrations, under Vibrations, except for links on web pages, which share the switch of the link vibration.
Keep control vibrations short and easy to tell apart, because controls are focused often. Build
them from the same taps, clicks, rises and falls, and give each kind its own rhythm, since some
phones can only play the pattern form. For example:
"vibrations": {
"control_button": {
"pattern": [0, 15, 40, 15],
"strength": [[15, 255], [40, 0], [15, 255]],
"effects": [["click", 255, 0], ["click", 255, 40]]
},
"control_checkbox": {
"pattern": [0, 15, 30, 40],
"strength": [[15, 255], [30, 0], [40, 160]],
"effects": [["click", 255, 0], ["quick_rise", 160, 30]]
},
"control_list_item": {
"pattern": [0, 10, 50, 10],
"effects": [["click", 140, 0], ["click", 140, 50]]
}
}A vibration is "none", for no vibration, or an object with up to three forms of the same
vibration. Phones play the best form they can.
| Form | What it is |
|---|---|
pattern |
Off and on times in milliseconds, starting with off: [0, 20, 40, 20] waits 0 ms, vibrates 20 ms, waits 40 ms and vibrates 20 ms. Every vibrator can play this. |
strength |
Steps of [milliseconds, strength], with strength from 0 (off) to 255 (strongest): [[20, 255], [40, 0], [20, 100]]. For vibrators that can vary their strength. |
effects |
Steps of ["effect", strength, delay in ms], with strength from 0 to 255: [["click", 255, 0], ["tick", 150, 40]]. Crisp effects for phones with a good vibration motor. |
A vibration needs pattern or strength, because every phone can play those. Without pattern,
the steps of strength with any strength make the pattern.
The effects are click, tick, low_tick, thud, spin, quick_rise, slow_rise and
quick_fall. A phone that lacks one effect of a vibration plays the strength or pattern form
instead, and many phones lack thud and spin, so click, tick, quick_rise, slow_rise and
quick_fall are the safest.
Times can be up to 5000 ms, and each form up to 64 steps. A vibration that is not well formed is left out when the theme is installed, and SandFly says why.
The Vibrations switches in Individual sounds and vibrations turn off a theme's vibrations too: the switch of the vibration a theme's vibration replaces turns it off, and plays the theme's vibration when you preview it.
- Put the theme in a GitHub repository, with
theme.jsonand the sounds at the top, and share the repository's link. Anyone can paste it into From a link, or share it to SandFly from their browser. - Or share the theme file itself, for anyone to open with SandFly.
- To make a theme file from sounds on your phone, choose them in Sounds and use Save as a
theme file. Its
theme.jsonhas the theme's settings.
- Watches have no file picker, so themes can only be installed from a link there, and single sounds can't be chosen.
- The circle menu's eight notes share one theme sound.
- Links on web pages and links in text share one vibration switch.