Both the sound theme description file and the sound data files are ini-style text files, as described in the desktop file specification. They don't have an encoding field. Instead, they must always be stored in UTF-8 encoding.
The index.theme file must start with a section called Sound Theme, with contents according to table 1 below. All lists are comma-separated.
Table 1. Standard Keys
| Key | Description | Value Type | Required |
|---|---|---|---|
| Name | Short name of the sound theme, used in e.g. lists when selecting themes. | localestring | YES |
| Comment | Longer string describing the theme | localestring | YES |
| Inherits |
The name of the theme that this theme inherits from. If a sound name is not found in the current theme, it is searched for in the inherited theme (and recursively in all the inherited themes). If no theme is specified implementations are required to add the "freedesktop" theme to the inheritance tree. An implementation may optionally add other default themes in between the last specified theme and the freedesktop theme. | strings | NO |
| Directories | List of subdirectories for this theme. For every subdirectory there must be a section in the index.theme file describing that directory. | strings | YES |
| Hidden | Whether to hide the theme in a theme selection user interface. This is used for things such as fallback-themes that are not supposed to be visible to the user. | boolean | NO |
| Example | The name of a sound that should be used as an example of how this theme sounds like. | string | NO |
Each directory specified in the Directory key has a corresponding section with the same name as the directory. The contents of this section is listed in table 2 below.
Table 2. Per-Directory Keys
| Key | Description | Value Type | Required | Type |
|---|---|---|---|---|
| Context | The context the sound is normally used in. This is in detail discussed in the section called “Context”. | string | NO | |
| OutputProfile | Define the output profile for which the sounds are made for. It can be "stereo" or "5.1", or any other output configuration. | string | NO |
In addition to these groups you may add extra groups to the index.theme file in order to extend it. These extensions must begin with "X-", and can be used to add desktop specific information to the theme file. Example group names would be "X-KDE Sound Theme" or "X-Gnome Sound Theme".
The optional file filename.sound contains a group "Sound Data", with the content listed in table 3.
Table 3. Sound Data Keys
| Key | Description | Value Type | Required |
|---|---|---|---|
| DisplayName | A translated UTF8 string that can be displayed instead of the sound by a user interface. | localestring | NO |
Extensions to filename.sound are allowed, but the keys must be begin with "X-" to avoid collisions with future standardized extensions to this format.
The context allows
the designer to group sounds on a conceptual level.
It doesn't act as a namespace in the file system, such
that sounds can have identical names, but allows
implementations to categorize and sort by it, for example.
These are the available contexts:
Alert. Sounds to alert the user of an action or event which may have a major impact on the system or their current use, such as dialog-error.
Notification. Sounds to notify the user that the system, or their current use has changed state in some way, e.g. new email arriving, new non-critical updates available...
Support. Sounds that give the user feedback on their actions. Sounds on window opening/closing for example.
Game. Sounds used for games.